ebusdMQTT

Anbindung von https://github.com/john30/ebusd an Symcon.

Inhaltverzeichnis

1. Funktionsumfang
2. Voraussetzungen
3. Installation
4. Konfiguration
5. Einbindung ins Webfront
6. Schreiben von Werten
7. Funktionsreferenz
8. Anhang

1. Funktionsumfang

Das Modul dient zur Einbindung von eBUS Geräten in Symcon. eBUS ('Energie Bus') ist ein Bussystem, das von verschiedenen Herstellern von Heizungs-, Lüftungs- und Solaranlagen genutzt wird.

Die Anbindung erfolgt über den Kommunikationsdienst ebusd in Verbindung mit einem geeigneten Hardwareadapter.

Über das Modul werden die von ebusd zur Verfügung gestellten Parameter zum Auslesen und Schreiben in Symcon als Statusvariablen eingebunden. Die Auswahl der einzubindenden Parameter wird vom Anwender festgelegt.

2. Voraussetzungen

• Hardware Adapter zur Verbindung mit dem eBUS
• lauffähiger eBUS Daemon (ebusd) mit MQTT-Unterstützung und entsprechender Hardwareanbindung (siehe auch Installationskurzanleitung ebusd), erprobt mit ebusd 23.3 und 26.1
• mindestens Symcon 8.1
• MQTT Server (in Symcon enthalten)

3. Installation

Füge im "Module Control" (Kern Instanzen->Modules) die URL

https://github.com/bumaas/ebusdMQTT.git

hinzu.

Danach ist es möglich ein neues ebusd MQTT Device zu erstellen:



Falls noch keine übergeordnete MQTT Server Instanz existiert, wird automatisch eine angelegt:



Auch eine Server Socket Instanz wird automatisch angelegt, wenn noch keine existiert:

4. Konfiguration

Für jedes erkannte Gerät/Schaltkreis muss eine Instanz angelegt werden..

• Host:
  Adresse unter der der ebusd Dienst erreichbar ist. Hierbei kann es sich um eine IP Adresse oder einen Hostnamen handeln.

• Port:
  Portnummer auf dem der ebusd Dienst http-Anfragen entgegennimmt.

• Schaltkreis Name:
  Der Name des Schaltkreises, unter dem das Gerät in ebusd geführt wird ('Circuit'), z. B. bai (Gasheizung), 700 (Regler VRC700), hmu (Wärmepumpe) oder ctlv3 (Regler sensoCOMFORT). Der Button „Ermittle Schaltkreis Namen“ fragt die eingetragene Adresse ab und bietet die Schaltkreise zur Auswahl an. Werte liefern nur Schaltkreise, für die ebusd eine Konfiguration geladen hat: In ebusctl i steht bei ihnen „loaded“, nicht nur „scanned“ (siehe Installationskurzanleitung, Gefundene Geräte). Neuere Geräte kennt ebusd mitunter noch nicht; dann gibt es für sie keine Werte. Die gemeinsamen Schaltkreise Broadcast, global und scan.xx bzw. Scan.xx (Rundsendungen und Typenschilddaten) bietet die Liste nicht an.

• Aktualisierungsintervall:
  Intervall in Minuten, in dem alle Statusvariablen durch Anfragen an den eBUS aktualisiert werden (0 = keine Aktualisierung, negative Werte sind unzulässig). Je nach Anzahl der Statusvariablen kann die Abfrage den eBUS erheblich belasten. Das Intervall sollte nicht zu klein gewählt werden.

• Debug Informationen werden zusätzlich in das Logfile der IPSLibrary geschrieben:
  Schreibt die Debug-Meldungen des Moduls zusätzlich in das Logfile der IPSLibrary (IPSLogger). Nur wirksam, wenn die IPSLibrary installiert ist; sonst ohne Funktion. Für die Fehlersuche genügt in der Regel die Debug-Ausgabe der Instanz.

Nachdem die Einstellungen gespeichert wurden, kann im Aktionsbereich die Konfiguration gelesen werden und die anzulegenden Statusvariablen können ausgewählt werden. „Lese Konfiguration aus“ braucht nur die HTTP-Verbindung zu ebusd und ist deshalb auch bedienbar, wenn der MQTT Server noch nicht aktiv ist oder ebusd kein eBUS-Signal meldet; „Lese aktuelle Werte“ und „Speichere Änderungen“ erst bei aktiver Instanz.

In der Liste der Statusvariablen markiert ein (A) hinter dem Ident, dass für diese Variable die Archivierung im Query-Logger (Archive Handler) aktiv ist.

So kommen die Daten herein

Das Modul spricht auf zwei Wegen mit ebusd:

Weg	wofür	Einstellung
HTTP	Schaltkreise ermitteln, Konfiguration lesen, „Lese aktuelle Werte“, Verbindungsprüfung	Host und Port der Instanz, bei ebusd --httpport
MQTT	alle laufenden Werte: Anfragen des Aktualisierungsintervalls und die Antworten darauf, Poll-Prioritäten, Schreiben von Werten	MQTT Server Instanz in Symcon, bei ebusd --mqtthost, --mqttport, --mqttuser, --mqttpass

Erreicht ebusd den MQTT Server in Symcon nicht, zeigt „Lese aktuelle Werte“ die Werte trotzdem an, denn das läuft über HTTP. Die Variablen bekommen dann aber keine. Das erkennt das Modul selbst. Solange ebusd mit dem MQTT Server verbunden ist, meldet es sich dort alle 15 Sekunden (ebusd/global/uptime). Kommt zwei Minuten lang nichts, geht die Instanz auf Status 209. Ohne diese Meldung, etwa bei einem eigenen Topic ohne %name, wartet das Modul zwei Aktualisierungsintervalle. Die Poll-Priorität hilft dabei nicht, auch sie läuft über MQTT.

Ob eine Variable Werte bekommt, zeigt ihre letzte Aktualisierung, die bei jeder Antwort von ebusd vorrückt. Die letzte Änderung bleibt dagegen stehen, solange der Wert gleich bleibt, etwa bei einer abgeschalteten Heizung im Sommer.

Das Modul prüft zudem jede Minute die Verbindung zu ebusd und dessen globales Signal, bei einer Störung zunächst öfter. Jede Störung hat einen eigenen Instanzstatus:

Status	Bedeutung	Was tun
104	Der MQTT Server (übergeordnete Instanz) ist nicht aktiv	MQTT-Server-Instanz prüfen
202	Port ungültig	Port korrigieren (1 bis 65535)
203	Schaltkreis ungültig oder bei ebusd nicht vorhanden	mit „Ermittle Schaltkreis Namen“ neu auswählen
204	Host ungültig	Host korrigieren
205	ebusd ist nicht erreichbar	Host, Port und HTTP-Port von ebusd (--httpport) prüfen
206	ebusd meldet kein eBUS-Signal (z. B. Adapter getrennt)	eBUS-Adapter und Verbindung zum Bus prüfen
207	Kein Schaltkreis ausgewählt	Schaltkreis auswählen
208	Aktualisierungsintervall ungültig (negativ)	0 (aus) oder eine Anzahl Minuten eintragen
209	ebusd antwortet per HTTP, sendet aber nichts per MQTT	MQTT-Optionen von ebusd mit Server Socket und MQTT Server Instanz abgleichen

Jeder Wechsel in eine Störung steht einmal als Warnung mit Ursache und nächstem Schritt im Meldungsprotokoll, die Behebung einer Betriebsstörung (104, 203, 205, 206, 209) einmal als Meldung. Nach dem Korrigieren einer Einstellung (202, 204, 207, 208) erscheint keine solche Meldung. Eine anhaltende Störung wiederholt sich dort nicht.

Bei Bedarf kann für eine Statusvariable eine Poll Priorität angegeben werden, die von ebusd verwendet werden soll. Die Poll Prioriät besagt, in welchem Intervallzyklus eine Meldung von ebusd gepollt werden soll. Meldungen mit Priorität 1 werden in jedem Pollzyklus abgefragt, Meldungen mit Priorität 2 werden in jedem zweiten Zyklus abgefragt usw.. Die Pollpriorität kann gesetzt werden, wenn das Abfrageintervall, das im Minutenbereich liegt, für einzelne Meldungen nicht fein genug ist.

Wechsel der ebusd-Konfiguration

Seit ebusd 24.1 lädt --scanconfig die Standardkonfiguration von ebus.github.io. Darin heißen viele Meldungen anders als in der früheren Konfiguration. Beim Regler ändert sich meist nur die Schreibweise (z1DayTemp wird Z1DayTemp, hwcTimer.Monday wird HwcTimer_Monday), bei der Wärmepumpe liest ebusd viele Werte über andere Meldungen. Nach „Lese Konfiguration aus“ sind die neuen Meldungen noch nicht aktiv, und wer sie aktiviert, bekommt neue Variablen. Die alten bleiben mit ihrem Archiv stehen, bekommen aber keine Werte mehr. Der Selbsttest nennt sie unter „Variablen ohne Meldung“.

Wer die Archive weiterführen will, gibt den alten Variablen vor dem Aktivieren den Ident der neuen Meldung (IPS_SetIdent). Das Modul übernimmt die Variable dann samt Archiv, Name und eigener Darstellung. Den Ident einer Meldung zeigt EBM_FindMessages. Ändert sich dabei der Typ, etwa von ganzzahlig auf Kommazahl, darf man nicht umbenennen: Das Modul löscht eine Variable mit falschem Typ und legt sie neu an, ihr Archiv ist dann nicht mehr erreichbar. In diesem Fall die neue Meldung unter ihrem eigenen Ident aktivieren und das Archiv der alten Variable mit AC_ChangeVariableID übertragen, bevor die neue selbst archiviert wird.

Fehlersuche

Die Stationen der Reihe nach, vom Bus bis zur Variable:

Symptom	Ursache	Prüfen
Status 206, die Weboberfläche des Adapters zeigt „ebusd connected: no“	ebusd findet den Adapter nicht	Adresse hinter -d in /etc/default/ebusd mit dem „ebusd device string“ des Adapters vergleichen, danach systemctl restart ebusd
Status 206, der Adapter zeigt „eBUS signal“ nicht als „acquired“	der Adapter hört den Bus nicht	Verkabelung zum eBUS
Status 205	ebusd antwortet nicht per HTTP	läuft ebusd (systemctl status ebusd)? Ist --httpport gesetzt und als Port in der Instanz eingetragen?
„Ermittle Schaltkreis Namen“ bietet das Gerät nicht an	ebusd hat für das Gerät keine Konfiguration geladen	ebusctl i nach dem Ende des Scans: steht „loaded“ beim Gerät?
Status 209	ebusd erreicht den MQTT Server nicht	grep mqtt /var/log/ebusd.log | tail muss connection established zeigen; --mqtthost, --mqttport, --mqttuser, --mqttpass mit Server Socket und MQTT Server Instanz abgleichen
Eine Variable zeigt eine alte letzte Änderung	der Wert hat sich seitdem nicht geändert, das ist kein Fehler	die letzte Aktualisierung der Variable ansehen, sie rückt bei jeder Antwort von ebusd vor
Status 104	der MQTT Server in Symcon ist nicht aktiv	MQTT Server Instanz und ihren Server Socket
Einem Feld fehlt die Variable, im Log steht „… hat den eBUS-Typ …, den dieses Modul nicht kennt“	die ebusd-Konfiguration verwendet einen Datentyp, den das Modul noch nicht kennt; die übrigen Felder der Meldung werden trotzdem angelegt und aktualisiert	Modul aktualisieren; kennt auch die neueste Version den Typ nicht, ihn im Forum melden

Den aktuellen Stand fasst der Selbsttest zusammen (EBM_RunSelfTest, siehe Funktionsreferenz). Zeilen wie „received unknown MS cmd“ im ebusd-Log sind dagegen normal, siehe Installationskurzanleitung, Überprüfen.

5. Einbindung ins Webfront

Alle Statusvariablen sind für eine Anzeige und (sofern vom ebusd ein Schreiben unterstützt wird) zum Ändern im Webfront vorbereitet. Sie haben alle eine Darstellung, die der ebusd Definition entspricht. Zur Verwendung in der Visu sollten sie jedoch überprüft werden. ebusd liefert keine fachlichen Grenzen, nur den technischen Bereich des eBUS-Datentyps. Schreibbare Zahlen bekommen deshalb nur dann einen Schieberegler, wenn dieser Bereich überschaubar ist (höchstens 1000 Schritte, z. B. 0 bis 100 %). Sonst gibt es ein Eingabefeld mit Einheit, etwa bei Temperaturen im Typ EXP mit ±3·10³⁸. Wer einen Schieberegler mit anlagenspezifischen Grenzen möchte, legt dafür eine eigene Darstellung an; das Modul überschreibt sie nicht.

Der Selbsttest (EBM_RunSelfTest) nennt außerdem Variablen, zu denen es in der ebusd-Konfiguration keine Meldung mehr gibt (vermutlich veraltet), und gleich benannte Variablen, denn ebusd beschreibt manche Werte in zwei Meldungen gleich. Das Modul benennt dabei nichts um und löscht nichts.

Besonderheit:

Schreibbare Mehrfachfelder können nicht direkt aus der Visu heraus geändert werden. Sie lassen sich aber über EBM_publish schreiben.

Beispiel (Meldungsname wie in der Konfiguration von ebusd, in der früheren Konfiguration hwcTimer.Monday):

EBM_publish(47111, 'ebusd/700/HwcTimer_Monday/set', '07:00;22:00;00:00;00:00;00:00;00:00');

6. Schreiben von Werten

Sofern die Statusvariablen ein Schreiben zulassen, können die Werte direkt über das Webfront oder per Skript über RequestAction verändert werden.

Schaltbar sind nur Variablen, deren Meldung ebusd schreiben lässt und die aus einem einzigen Feld besteht. Ein Schreibwunsch wird vor dem Senden geprüft und sonst mit einer Fehlermeldung abgelehnt, die Grund und nächsten Schritt nennt. Auf den eBUS geht dann nichts. Abgelehnt werden:

• Wert außerhalb der Wertetabelle oder des Wertebereichs (die erlaubten Werte stehen in der Meldung),
• nur lesbare Meldung,
• Feld einer Meldung mit mehreren Feldern (diese schreibt man als Ganzes mit EBM_publish),
• unbekannter Ident,
• MQTT Server (übergeordnete Instanz) nicht aktiv.

7. Funktionsreferenz

Alles, was im Formular über Knöpfe geht, geht auch per Skript. Fehlschläge kommen als Warnung mit Grund und nächstem Schritt.

EBM_RunSelfTest(int $InstanceID): string

Prüft ohne jede Wirkung auf die Instanz, ob alles funktioniert: MQTT Server aktiv, ebusd erreichbar, eBUS-Signal, Antworten von ebusd per MQTT, Schaltkreis vorhanden, Konfiguration eingelesen, aktive Meldungen, letzte Aktualisierung. Liefert einen Text, jede Störung mit dem nächsten Schritt.

EBM_FindMessages(int $InstanceID, string $search): string

Liefert die Meldungen des Schaltkreises als JSON, also dieselbe Information wie die Liste im Formular: Meldung, lesbar, schreibbar, aktiv, Poll-Priorität und je Feld Ident, Bezeichnung, Typ, Einheit, erlaubte Werte (values) bzw. Bereich (min/max, nur wo er sinnvoll ist) und die ID der Variable, falls sie schon angelegt ist. $search filtert nach Meldungsname oder Bezeichnung (Groß-/Kleinschreibung egal), '' liefert alle.

EBM_UpdateConfiguration(int $InstanceID): string

Liest die Konfiguration des Schaltkreises von ebusd und speichert sie (wie der Knopf „Lese Konfiguration aus“). Liefert die Anzahl der gelesenen Meldungen.

EBM_SetMessageActive(int $InstanceID, string $messageName, bool $active, int $pollPriority): string

Bindet eine Meldung ein (true: Variablen anlegen, Auswahl speichern, aktuellen Wert gleich bei ebusd anfordern) oder aus (false), wie das Häkchen „Aktiv“ plus „Variablen anlegen/aktualisieren“. Ausgeschaltet bleiben die Variablen samt Archivdaten erhalten; das Modul fragt sie nur nicht mehr ab. $pollPriority 0 bis 9 (0 = keine eigene Poll-Priorität) wird an ebusd gesendet, wenn sie sich ändert.

EBM_ReadMessageValues(int $InstanceID, string $search): string

Liest die aktuellen Werte der lesbaren Meldungen, die zu $search passen, bei ebusd (wie der Knopf „Lese aktuelle Werte“) und liefert sie als JSON: Meldung → value (Werte durch „/“ getrennt, null = kein Wert) und lastUpdate (Zeitpunkt der letzten Aktualisierung bei ebusd, null = nie). Weil ebusd dafür den Bus abfragen kann, höchstens 20 Meldungen je Aufruf. Antwortet ebusd nicht, bricht die Funktion bei der ersten Meldung mit einer Warnung ab, die die abgefragte URL nennt, und liefert einen leeren Text; ebenso der Knopf „Lese aktuelle Werte“, der dann die Liste unverändert lässt.

Beispiel: Vorlauftemperatur einbinden

$id = 12345; // Instanz-ID des „ebusd MQTT Device“
echo EBM_FindMessages($id, 'Vorlauf');           // Meldungsnamen suchen, z. B. Hc1FlowTemp
echo EBM_ReadMessageValues($id, 'Hc1FlowTemp');  // aktuellen Wert ansehen
echo EBM_SetMessageActive($id, 'Hc1FlowTemp', true, 0);

EBM_publish(int $InstanceID, string $topic, string $payload): void

Published den Wert $payload zum $topic. Kann für "Sonderthemen" genutzt werden, siehe MQTT client Beschreibung. Ein Beispiel zum Schreiben eines Topics:

// der Wert des Parameters 'FlowsetHCMax' des Schaltkreises 'bai' wird auf 75 gesetzt

$InstanceID = 12345;                                  // die Instanz ID des "ebusd MQTT Device"
$topic      = 'ebusd/<Schaltkreis>/<Parameter>/set';  // <Schaltkreis> und <Parameter> sind entsprechend zu ersetzen ('ebusd/bai/FlowsetHCMax')
$payload    = '75';                                   // der Wert ist als String zu übergeben

EBM_publish($InstanceID, $topic, $payload);

8. Anhang

GUIDs der Module

Modul	Typ	GUID
ebusd MQTT Device	Device	{0A243F27-C31D-A389-5357-B8D000901D78}

Spenden

Die Nutzung des Moduls ist kostenfrei. Niemand sollte sich verpflichtet fühlen, aber wenn das Modul gefällt, dann freue ich mich über eine Spende.