Ereignisse

Die lokale Logik im IOZER basic ist ereignisorientiert aufgebaut. Ein Programm wird nicht dauerhaft in einer Schleife abgearbeitet, sondern reagiert auf konkrete Auslöser.

Ein Ereignis beschreibt immer:

wodurch die Logik gestartet wird
für welche Quelle das Ereignis gilt
welcher Code ausgeführt wird
welche Kontextdaten dem Code zur Verfügung stehen

Grundprinzip

Das Modell folgt dem Muster:

Auslöser -> Kontext -> Aktion

Ein Datenpunkt wird aktualisiert, ein Zeitplan wird fällig, das Programm startet oder eine Schnittstelle meldet einen Fehler. Die Firmware erzeugt daraus ein Ereignis und übergibt passende Kontextdaten an den hinterlegten Blockly- oder JavaScript-Code.

Der Code läuft nur, wenn das Ereignis tatsächlich ausgelöst wird. Dadurch bleibt die Logik übersichtlich und ressourcenschonend.

Treten mehrere Ereignisse gleichzeitig oder kurz hintereinander auf, werden sie in der Reihenfolge ihres Auftretens abgearbeitet. Die Ausführung erfolgt sequenziell: Ein Ereignis wird vollständig ausgeführt, bevor das nächste Ereignis startet.

Ereignisprogramm

Ein IOZER-Programm besteht aus mehreren Ereignissen. Jedes Ereignis besitzt eine eigene Konfiguration:

Eigenschaft	Bedeutung
Aktiv	Legt fest, ob das Ereignis ausgeführt wird
Name und Beschreibung	Dokumentation innerhalb der Programmierung
Auslöser	Typ des Ereignisses, z. B. Datenpunkt, Zeitplan, Programm oder Fehler
Quelle	Konkreter Datenpunkt, Zeitplan, Fehlerquelle oder manueller Parameter
Script-Typ	Blockly oder JavaScript
Code	Auszuführende Logik
Kontext	Laufzeitinformationen zum Auslöser

Blockly eignet sich für visuelle Logik. JavaScript eignet sich für kompaktere oder komplexere Abläufe.

Ereignis hinzufügen

Neue Ereignisse werden im Programmbereich über Ereignis hinzufügen angelegt. Der Dialog gruppiert die verfügbaren Auslöser nach Funktionsbereich.

Wählen Sie zuerst die passende Gruppe, zum Beispiel Datenpunkt, Zeitplan, Benutzerdefiniert oder Fehler. Anschließend wählen Sie den konkreten Ereignistyp.

Bei Datenpunkten stehen typischerweise folgende Auslöser zur Verfügung:

Wert geändert: Wird ausgelöst, sobald sich der Wert gegenüber dem vorherigen gültigen Wert ändert.
Wert aktualisiert: Wird bei jedem neu gesetzten oder empfangenen Wert ausgelöst, auch wenn der Wert unverändert ist.
Status geändert: Wird ausgelöst, sobald sich der Status eines Datenpunkts ändert.
Fehler: Wird ausgelöst, wenn ein Datenpunkt einen Fehlerzustand meldet.

Nach dem Hinzufügen wird das Ereignis in der Ereignisliste angezeigt und kann dort benannt, aktiviert, einer Quelle zugeordnet und mit Blockly oder JavaScript programmiert werden.

Auslöser

Die Firmware unterscheidet mehrere Ereignisgruppen.

Gruppe	Typische Auslöser
Programm	Programmstart, Programmstopp
Datenpunkte	Wertänderung, Wertaktualisierung, Statusänderung, Fehler
Zeitplan	Cron-Ausdruck
Manuell	Benutzerdefiniertes Ereignis
Fehler	1-Wire-Fehler, Modbus-Fehler, MQTT-Fehler

Digitale Eingänge, digitale Ausgänge, 1-Wire-Werte, Modbus-Werte und MQTT-Werte besitzen keine eigenen Ereignisgruppen. Sie werden über Datenpunkte abgebildet. Die lokale Logik reagiert daher auf den jeweiligen Datenpunkt, nicht direkt auf die Hardware- oder Protokollquelle.

Ereignis und Quelle

Viele Ereignisse können auf eine bestimmte Quelle eingeschränkt werden.

Beispiele:

Datenpunkt taster_flur wechselt von false auf true
Datenpunkt licht_flur ändert seinen Zustand
Datenpunkt raumtemperatur wird durch einen 1-Wire-Sensor aktualisiert
Datenpunkt zaehlerleistung wird aus einem Modbus-Register aktualisiert
Datenpunkt sollwert_mqtt wird über MQTT beschrieben
Fehlerquelle 1-Wire meldet einen Bus- oder Sensorfehler

Wenn keine einzelne Quelle ausgewählt ist, kann ein Ereignis allgemeiner reagieren, abhängig vom jeweiligen Ereignistyp.

Kontextdaten

Beim Ausführen stellt die Firmware Kontextdaten bereit. In JavaScript sind diese als ioz_event und ioz_event_context verfügbar.

Allgemeine Felder:

Feld	Bedeutung
`event_id`	ID des ausgelösten Ereignisses
`trigger_code`	Interner Ereignistyp
`source_no`	Nummer der Quelle
`timestamp`	Zeitstempel der Ausführung

Je nach Ereignisgruppe kommen weitere Felder hinzu.

Ereignisgruppe	Kontextfelder
Programm	Programmzustand und Zeitstempel
Datenpunkte	`datapoint_id`, `datapoint_name`, `value`, `last_value`, `valid`, `last_valid`, `state`, `last_state`, `unit`, `classification`
Zeitplan	`cron_expression`
Manuell	`param1` bis `param4`
Fehler	`interface`, `error_code`, `error_message`

Eingänge, Ausgänge und Schnittstellenwerte stehen der Logik über die Kontextfelder des zugehörigen Datenpunkts zur Verfügung. Fehlerereignisse für 1-Wire, Modbus und MQTT liefern dagegen Fehlerkontext zur betroffenen Schnittstelle.

Aktionen im Code

Lokale JavaScript-Programme können über globale Objekte mit dem Gerät interagieren.

Objekt	Zweck
`system`	Warten oder Neustart auslösen
`mqtt`	MQTT-Nachrichten veröffentlichen
`dp`	Datenpunkte lesen, schreiben, schalten oder Status abfragen
`event`	Manuelle Ereignisse auslösen, stoppen oder Status abfragen
`log`	Meldungen in Debug-, Info-, Warn- oder Fehlerstufe schreiben

Beispiel:

if(ioz_event.datapoint_name = "taster_flur" && ioz_event.value = true) {
  dp.set("licht_flur", true);
  log.info("Flurlicht eingeschaltet");
}

Datenpunkte als zentrale Ebene

Datenpunkte sind die empfohlene Ebene für Logik, die mehr als eine Schnittstelle berührt.

Ausführlich beschrieben unter: Datenpunkte.

Ein Datenpunkt kann zum Beispiel:

von einem digitalen Eingang gelesen werden
einen digitalen Ausgang schreiben
per MQTT veröffentlicht werden
per Modbus abgebildet werden
in JavaScript verarbeitet werden

Dadurch muss die Logik nicht wissen, ob ein Wert ursprünglich aus Hardware, MQTT, Modbus oder 1-Wire stammt. Sie arbeitet mit einer stabilen logischen Bezeichnung.

Manuelle Ereignisse

Manuelle Ereignisse können aus anderer Logik heraus gestartet werden. Dafür steht in JavaScript das Objekt event zur Verfügung.

Manuelle Ereignisse können bis zu vier Parameter erhalten. Diese stehen im Zielereignis als param1 bis param4 zur Verfügung.

Typische Anwendungen:

wiederverwendbare Teilabläufe
verzögerte Aktionen
zentrale Fehlerbehandlung
Szenen oder Betriebsarten

Zeitpläne

Zeitbasierte Ereignisse verwenden Cron-Ausdrücke. Damit lassen sich zyklische oder kalenderbasierte Aktionen abbilden.

Beispiele:

jeden Tag zu einer bestimmten Uhrzeit
alle fünf Minuten
nur an bestimmten Wochentagen

Beim Ausführen steht der verwendete Ausdruck als cron_expression im Kontext.

Gute Praxis

Verwenden Sie Datenpunkte als stabile Schnittstelle zwischen Logik, Hardware und Protokollen.
Reagieren Sie auf Wertänderungen, wenn eine Aktion nur bei echten Änderungen ausgeführt werden soll.
Reagieren Sie auf Wertaktualisierungen, wenn auch gleiche Werte verarbeitet werden sollen.
Halten Sie einzelne Ereignisse klein und klar benannt.
Nutzen Sie manuelle Ereignisse für wiederkehrende Abläufe.
Vermeiden Sie lange blockierende Abläufe in einem Ereignis.
Dokumentieren Sie wichtige Ereignisse mit Beschreibungstexten.

Beispielablauf

Ein typischer Ablauf für eine einfache Lichtsteuerung:

Ein digitaler Eingang schreibt den Datenpunkt taster_flur.
Der Datenpunkt taster_flur löst bei Wertänderung ein Ereignis aus.
Die Logik prüft den Datenpunktwert.
Der Datenpunkt licht_flur wird gesetzt.
Der Datenpunkt licht_flur schreibt den digitalen Ausgang.
Optional wird der neue Zustand über MQTT veröffentlicht.

So bleibt die Logik lokal auf dem Gerät, kann aber trotzdem mit MQTT, Modbus, 1-Wire und der Weboberfläche zusammenarbeiten.