Zurück zum Inhaltsverzeichnis
Zurück zu Kapitel 4


5. BSB-LAN: Abfragen und Steuern

Da das Webinterface prinzipiell nur ‚aufgesetzt’ ist, um eine Bedienung ohne weitere Programme wie bspw. FHEM zu ermöglichen, ist ein direkter Zugriff auf die einzelnen Funktionen und Parameter mittels anderer Programme grundsätzlich möglich.


5.1 URL-Befehle

Hinweis
Bei der folgenden Aufzählung der URL-Befehle muss der jeweilige Wert oder Parameter ohne Klammern geschrieben werden.
Beispiel: URL-Befehl /<x> für die einfache Abfrage von Parameter 8700 = /8700.
URL-Befehl Auswirkung
/<x> Alle Werte von Parameter <x> abfragen
/<x>!<adr> Alle Werte von Parameter <x> für Zieladresse <adr> abfragen
/<x>/<y>/<z> Alle Werte der Parameter <x>, <y> und <z> abfragen
Hinweis: Mehrere Abfragen können miteinander verkettet werden, z.B.: http://<IP-Adresse>/K11/8000/8003/8005/8300/8301/8730-8732/8820
/<x>-<y> Alle Werte eines Parameterbereichs von <x> bis <y> abfragen
/<x>!<adr>-<y> Alle Werte eines Parameterbereichs von <x> bis <y> für Zieladresse <adr> abfragen
/A=<x>,<y>,<z> 24h-Durchschnittswertberechnung für Parameter <x>, <y>, <z> einstellen
Während der Laufzeit kann /A=[parameter1],...,[parameter20] verwendet werden, um (bis zu 20) neue Parameter zu definieren.
/A=0 24h-Durchschnittswertberechnung temporär deaktivieren.
Deaktiviert die 24-h Durchschnittswertberechnung vorübergehend bis zum nächsten Reset/Neustart des Arduino. Für eine komplette und dauerhafte Deaktivierung müssen alle als zu berechnend aufgeführten Parameter in der Datei BSB_LAN_config.h auskommentiert werden.
/B0 Zurücksetzen des Zählers der akkumulierten Brennerlaufzeiten und -zyklen
/C Konfiguration von BSB-LAN anzeigen lassen
/D oder /DD Anzeige der Logdatei
Zeigt den Inhalt der Datei datalog.txt an, die sich auf der microSD-Karte im Slot des Ethernet-Shields befindet.
/DG Grafische Anzeige der Logdatei
Wer Parameter auf SD-Karte loggt, hat neben der reinen Textform auch die Möglichkeit, einen Graphen angezeigt zu bekommen.
Hinweis: Für /DG muss bei Javascript-Blockern die Domain d3js.org freigegeben werden, da der Arduino weiterhin nur die CSV-Datei in den Browser lädt und diese dann mit dem D3-Framework grafisch aufbereitet wird.
Wird die Log-Datei via Webinterface mittels Klick auf „Anzeige Logdatei" aufgerufen, erfolgt standardmäßig zuerst die grafische Darstellung.
/DJ Anzeige des Logfiles von Telegrammen
Dieser Befehl zeigt das Logfile *journal.txt* an, das den Inhalt der empfangenen und gesendeten Telegramme anzeigt. Dieses Logging ist nützlich bei der Fehlersuche und bei der Suche nach unbekannten Parametern. Um die Funktion nutzen zu können, muss das Modul LOGGER in der Datei BSB_LAN_config.h aktiviert und das erste Element des Arrays log_parameters auf 30000 gesetzt werden.
/D0 Logfiles löschen und neuen CSV-header erstellen
Dieser Befehl löscht die Dateien datalog.txt und journal.txt und erstellt einen neuen CSV-header für datalog.txt. Dieser Befehl sollte vor dem ersten Logging ausgeführt werden.
/DD0 Logfile datalog.txt löschen
/DJ0 Logfile journal.txt löschen
/E<x> Alle ENUM-Werte für Parameter <x> auflisten
Bei diesem Befehl kommuniziert der Adapter nicht mit dem Heizungssystem. Es ist eine softwareseitige, interne Funktion. Dieser Befehl ist nur für Parameter des Typs VT_ENUM, VT_CUSTOM_ENUM, VT_BITS und VT_CUSTOM_BITS verfügbar.
/G<x> GPIO: Abfragen des GPIO-Pins <x> (GPIO wird als OUTPUT genutzt)
Gibt den momentanen Status von GPIO Pin <x> an, wobei <y>=0 LOW und <y>=1 HIGH ist.
/G<x>=<y> GPIO: Abfragen des GPIO-Pins <x> und Setzen auf <y> (GPIO wird als OUTPUT genutzt)
Setzt GPIO Pin <x> auf LOW (<y>=0) oder HIGH (<y>=1).
Reservierte Pins, die nicht gesetzt werden dürfen, können in der BSB_LAN_config.h unter dem Parameter GPIO_exclude gesperrt werden.
/G<x>,I GPIO: Abfragen des GPIO-Pins <x> (GPIO wird als INPUT genutzt)
Für die reine Abfrage eines externes Gerätes, das an einen GPIO angeschlossen ist (z.B. ein einfaches Koppelrelais), da die Pins per default auf ‚output' gesetzt sind. Der Pin bleibt nach diesem Befehl so lange auf ‚input', bis das nächste Mal mit /G<xx>=<y> ein Wert geschrieben wird - ab da ist er dann bis zum nächsten „I" wieder auf ‚output'.
/I<x>=<y> Sende eine INF-Nachricht für den Parameter <x> mit dem Wert <y>
Einige Werte können nicht direkt gesetzt werden. Das Heizungssystem wird mit einer TYPE_INF-Nachricht informiert, bspw. bei der Raumtemperatur: http://<ip-address>/I10000=19.5 → Raumtemperatur beträgt 19.5°C
/JC=<x>,<y>,<z> JSON: Abfrage der möglichen Werte der Parameter <x>,<y>,<z> für Parameter des Typs ENUM
Das Format der zurückgegeben Daten ist das gleiche wie bei dem Befehl /JK=<x>. Im Gegensatz zum Befehl /JQ werden die aktuellen Parameterwerte nicht zurückgemeldet.
/JI JSON: Konfiguration von BSB-LAN anzeigen lassen
/JK=<x> JSON: Abfrage der verfügbaren Parameter der Kategorie <x>
/JK=ALL JSON: Auflistung aller Kategorien samt zugehöriger Parameternummern
/JL JSON: Erstellt eine Liste der Konfiguration im JSON-Format
/JQ=<x>,<y>,<z> JSON: Abfrage von Parameter <x>, <y> und <z>
/JQ JSON: Abfrage von Parametern
/JR<x> JSON: Fragt den Reset-Wert für Parameter <x> ab
Im Display der integrierten Heizungssteuerung gibt es für einige Parameter eine Reset-Option. Ein Reset wird vorgenommen, indem das System nach dem Reset-Wert gefragt wird und dieser anschließend gesetzt wird.
/JS JSON: Setzen von Parametern
/JV JSON: Abfrage der JSON-API-Version. Payload: {"api_version": "major.minor"}
/JW JSON: Liest die per /JL erstellte Konfigurationsliste aus und passt die Einstellungen entsprechend an.
/K Alle Kategorien auflisten
Bei diesem Befehl kommuniziert der Adapter nicht mit dem Heizungssystem. Es ist eine softwareseitige, interne Funktion.
/K<x> Alle Parameter von Kategorie <x> abfragen
Bei diesem Befehl kommuniziert der Adapter nicht mit dem Heizungssystem. Es ist eine softwareseitige, interne Funktion.
/L=0,0 Vorübergehendes Deaktivieren des Loggens auf die microSD-Karte
Prinzipiell erfolgt das Aktivieren/Deaktivieren der Log-Funktion durch das entsprechende Definement in der Datei BSB_lan_config.h vor dem Flashen. Während des Betriebes kann das Loggen jedoch mit diesem Befehl deaktiviert werden. Zum Aktivieren werden dann wieder das Intervall und die gewünschten Parameter eingetragen. Bei einem Reset/Neustart des Arduino werden die Einstellungen aus der Datei BSB_lan_config.h verwendet - eine dauerhafte Umstellung der Logging-Parameter sollte also dort erfolgen.
/L=<x>,<y1>,<y2>,<y3> Setzen des Logging-Intervals auf <x> Sekunden mit (optional) zu loggenden Parametern <y1>,<y2>,<y3>
Setzt während der Laufzeit das Logging-Intervall auf <x> Sekunden und (optional) die Logging-Parameter auf <y1>, <y2>, <y3> etc.
Dabei sind stets alle zu loggenden Parameter anzugeben - also auch (falls gewünscht) diejenigen, die evtl. bereits in der Datei BSB_lan_config.h definiert wurden. Nach einem Neustart werden dann wieder nur die Parameter geloggt, die in der Datei BSB_lan_config.h definiert wurden.
Hinweis: Das Logging muss durch das Definement #define LOGGING in der Datei BSB_lan_config.h aktiviert werden und kann initial anhand der Variablen log_parameters und log_interval konfiguriert werden.
/LB=<x> Konfiguration des Loggens von Bus-Telegrammen: Nur Broadcasts (<x>=1) oder alle Telegramme (<x>=0)
Wenn Bus-Telegramme geloggt werden (Parameter 30000 als einzigen Parameter loggen), logge nur die Broadcasts (<x>=1) oder alle (<x>=0) Telegramme.
/LD Deaktivieren des Loggens von Bus-Telegrammen
/LE Aktivieren des Loggens von Bus-Telegrammen
/LU=<x> Konfiguration des Loggens von Bus-Telegrammen: Nur unbekannte (<x>=1) oder alle (<x>=0) Telegramme loggen
Wenn Bus-Telegramme geloggt werden (Parameter 30000 als einzigen Parameter loggen), logge nur die unbekannten Command IDs (<x>=1) oder alle (<x>=0) Telegramme.
/M<x> Aktivieren (<x> = 1) oder Deaktivieren (<x> = 0) des Bus-Monitormodus
Standardmäßig ist der Monitor-Modus deaktiviert (<x>=0).
Wenn <x> auf 1 gesetzt wird, werden alle Bytes auf dem Bus überwacht. Telegramme werden durch Umbruchzeichen als solche erkannt. Jedes Telegramm wird im Hex-Format auf der seriellen Konsole mit einem Zeitstempel in Millisekunden dargestellt. Die Ausgabe der Überwachung betrifft nur die serielle Konsole des Arduino, die html-Ausgabe bleibt unverändert.
Zum Deaktivieren des Monitor-Modus ist <x> wieder auf 0 zu setzen (URL-Befehl: /M0).
/N Reset & Neustart des Arduino (Dauer: ca. 15 Sekunden)
Hinweis: Die Funktion muss zuvor in der Datei BSB_lan_config.h aktiviert werden: #define RESET
/NE Reset & Neustart des Arduino (Dauer: ca. 15 Sekunden) und löschen des EEPROMs
Hinweis: Die Funktion muss zuvor in der Datei BSB_lan_config.h aktiviert werden: #define RESET
/P<x> Bus-Typ (BSB, LPB oder PPS) vorübergehend ändern: <x> = 0 → BSB / 1 → LPB / 2 → PPS
Wechselt zwischen BSB (<x>=0), LPB (<x>=1) und PPS (<x>=2). Nach einem Reset/Neustart des Arduino wird die Einstellung aus der Datei BSB_lan_config.h verwendet. Um den Bus-Typ dauerhaft festzulegen, sollte die Option setBusType config in der Datei BSB_lan_config.h entsprechend angepasst werden.
/P<x>,<y>,<z> Bus-Typ und zusätzlich die eigene oder die Zieladresse mittels URL-Befehl wechseln
<x> = Bus (0 = BSB, 1 = LPB, 2 = PPS),
<y> = eigene Adresse und
<z> = Zieladresse
Leerwerte bei den Adressen belassen den bisherigen Wert (= voreingestellte Adresse).
/Q Überprüfen auf nicht-freigegebene reglerspezifische Parameter
/R<x> Frage den Reset-Wert für Parameter <x> ab
Im Display der integrierten Heizungssteuerung gibt es für einige Parameter eine Reset-Option. Ein Reset wird vorgenommen, indem das System nach dem Reset-Wert gefragt wird und dieser anschließend gesetzt wird.
/S<x>=<y!z> Setze Wert <y> für den Parameter <x> mit optionaler Zieladresse <z>
Die gewünschte Gerätezieladresse ist als <z> einzufügen, wenn <!z> nicht eingegeben wird, wird die Standardzieladresse verwendet. Um einen Parameter auf 'abgeschaltet/deaktiviert' zu setzen, muss lediglich ein leerer Wert eingefügt werden: http://<ip-address>/S<x>=
/U Anzeige der in der Datei BSB_lan_custom.h benutzerdefinierten Variablen (falls verwendet)
Für die Erstellung eigener Unterprogramme in der BSB_lan_custom.h stehen zwei globale Arrays, custom_floats[] und custom_longs[], zur Verfügung, die jeweils 20 Byte groß sind. Diese können nach Bedarf verwendet werden und über das URL-Kommando /U angezeigt werden. Dies kann nützlich sein, um z.B. eigene Sensoren anzubinden, die man dann in der BSB_lan_custom.h abfragen bzw. berechnen kann und dann über /U über die Weboberfläche abfragen kann.
/V<x> Aktivieren (<x> = 1) oder Deaktivieren (<x> = 0) des Verbositätsmodus
Der voreingestellte Verbositäts-Level ist 1. Somit wird standardmäßig der Bus überwacht und alle Daten werden zusätzlich im Raw-Hex-Format dargestellt.
Soll der Modus deaktivert werden, so ist <x> auf 0 zu setzen (URL-Befehl: /V0).
Der Verbositäts-Level betrifft sowohl die serielle Konsole des Arduino als auch (optional) das Loggen der Bus-Daten auf die microSD-Karte, so dass die Speicherkarte u.U. sehr schnell voll wird! Im Fall des Loggens auf die interne microSD-Karte ist es daher empfehlenswert, den Verbostitätsmodus bereits in der Datei BSB_lan_config.h zu deaktivieren (byte verbose = 0).
Die html-Ausgabe bleibt mit /V1 unverändert.
/W Mit vorangehendem /W liefern die URL-Befehle C, S und Q Daten ohne HTML-header und -footer zurück (bspw. /WC oder /WS<x>=<y!z>); Modul WEBSERVER muss kompiliert sein!
/X Abfragen optionaler MAX!-Thermostate
Abfragen und Anzeigen der Temperaturen von optionalen MAX!-Thermostaten.
Hinweis: MAX!-Komponenten müssen zuvor in der Datei BSB_lan_config.h definiert werden!

5.2 MQTT

BSB-LAN unterstützt das MQTT-Protokoll, d.h. die Werte und Einstellungen des Heizungsreglers sind per MQTT empfangbar.
Um MQTT bei BSB-LAN zu nutzen, muss zwingend das Definement “#define LOGGER” in der Datei BSB_LAN_config.h aktiviert sein. Dies ist in der Voreinstellung bereits der Fall.

Die zu sendenden (von BSB-LAN abgefragten) Parameter, das Sendeintervall (nur eines für alle Parameter möglich!) sowie die weiteren MQTT-spezifischen Einstellungen (Broker, Topic etc.) sind entweder via Webkonfiguration oder direkt in der Datei BSB_LAN_config.h einzustellen. Beachte hierzu bitte die Erklärungen in den entspr. Unterkapiteln von Kap. 5.

Beispiele für eine Einbindung von BSB-LAN findest du in den entspr. Unterkapiteln von Kap. 11.

BSB-LAN sendet über den Subtopic “status” unter dem definierten “MQTTTopicPrefix” jederzeit seinen Online-Status. Dies ist in der Voreinstellung also “BSB-LAN/status”. Über diesen Topic kann so jederzeit festgestellt werden, ob der BSB-LAN derzeit Werte sendet und Kommandos empfangen kann.
Ist BSB-LAN verfügbar, ist im Topic die Nachricht “online” zu sehen, ansonsten wird “offline” gesetzt. Die Nachricht ist per Retain-Flag dauerhaft verfügbar, der Subscriber muss also nicht zum Zeitpunkt des BSB-LAN Starts bereits den Topic abonniert haben.
Ein Neustart über die Software (z.B. per URL-Befehl /N) setzt den Topic sofort auf “offline”. Fällt BSB-LAN unkontrolliert aus (z.B. durch Stromausfall oder Flashen der Firmware) verschickt der Broker nach einem Timeout (dieser ist m.W. abhängig vom Broker) ebenfalls die Offline-Nachricht.

Neben dem (brokerseitigen) reinen Empfangen ist es auch möglich, via MQTT vom Broker aus sowohl Abfragen als auch Steuerbefehle (URL-Befehle /S und /I) an BSB-LAN zu senden. Selbstverständlich muss BSB-LAN für das Umsetzen von Steuerbefehlen Schreibzugriff auf den Regler gewährt werden.

Die Befehlssyntax lautet:

set <MQTT-Server> publish <Topic> <Befehl>

Nachfolgend schickt BSB-LAN eine Empfangsbestätigung zurück (“ACK_<Befehl>”).

Beispiel
Der Befehl set mqtt2Server publish BSB-LAN /S700=1 sendet vom MQTT-Broker namens “mqtt2Server” den Befehl “/S700=1” mit dem Topic “BSB-LAN” und bewirkt eine Betriebsartumschaltung in den Automatikmodus.
Der Befehl set mqtt2Server publish BSB-LAN /700 sendet vom MQTT-Broker namens “mqtt2Server” den Befehl “/700” mit dem Topic “BSB-LAN” und bewirkt eine Abfrage von Parameter 700.

5.3 JSON


User “hacki11” hat eine ausführliche und interaktive API-Dokumentation zum Abfragen und Steuern via JSON erstellt.
Vielen Dank!

Hinweis für Entwickler
Die API lässt sich mittels Postman am eigenen System testen. Dazu muss man die URL https://raw.githubusercontent.com/fredlcore/bsb_lan/master/openapi.yaml in File/Import/Link hinzufügen und ggf. die spezifischen Angaben wie bspw. Adresse und Zugangsdaten anpassen.

Neben den Beschreibungen samt Beispielen zu den einzelnen Befehlen sind ebenfalls sämtliche Informationen zu den Typen, Formaten, möglichen Werten etc. aufgeführt.

Hinweise
JSON-Befehle lassen sich auch per Linux-Kommandozeile oder „Curl for Windows“ nutzen. Bei der o.g. interaktiven API-Dokumentation können die entspr. Curl-Befehle generiert und danach zur weiteren Nutzung kopiert werden (die IP ist bei der weiteren Verwendung stets anzupassen). Dazu ist wie folgt vorzugehen:
1. Klicke auf die gewünschte Operation, bspw. “/JQ={parameterIds}”.
2. Bei dem aufklappenden Fenster klicke rechts auf “Try it out”.
3. Trage den/die gewünschten Parameter ein (im unten gezeigten Beispiel: 700,8300).
4. Klicke auf “Execute”.
Im Feld “Responses” werden dann die URL- und Curl-Befehle angezeigt, die man kopieren kann.
Achtung: Die Zeichenkombination %2C bei der Auflistung mehrerer Parameter wird von Swagger anstelle des Kommas eingefügt. Solltest du die URL-/Curl-Befehle kopieren und nutzen wollen, so ersetze bitte jedes %2C durch ein , (Komma)!

Die Ausgabe des URL-/Curl-Befehls.


Weiter zu Kapitel 6
Zurück zum Inhaltsverzeichnis