Zurück zum Inhaltsverzeichnis
Zurück zu Kapitel 1


2. BSB-LAN: Die Software

In den folgenden Kapiteln wird auf die Installation und die Konfiguration der BSB-LAN-Software eingegangen. Eine Beschreibung des Webinterface findest du hingegen in Kap. 4, eine Beschreibung der Abfrage- und Steuermöglichkeiten in Kap 5 und eine Beschreibung der Spezialfunktionen in Kap. 6.


2.1 Installation

Die BSB-LAN-Software muss zur Installation auf den jeweils verwendeten Mikrocontroller (Arduino Due oder ESP32) geflasht werden. Dies kann bspw. mittels der “Arduino IDE” erfolgen, selbstverständlich können aber auch andere Programme wie bspw. “PlatformIO” oder “Visual Studio Code” genutzt werden.

Hinweis
In diesem Handbuch wird davon ausgegangen, dass die Arduino IDE genutzt wird. Sämtliche Beschreibungen und Bezeichnungen beziehen sich daher auf die Arduino IDE.
Solltest du Anfänger und mit der Arduino IDE noch nicht vertraut sein, so findest du eine Beschreibung zur Installation und Konfiguration der Arduino IDE in Kap. 12.

Je nach verwendeter Plattform (Arduino Due oder ESP32) unterscheiden sich die notwendigen Einstellungen der Arduino IDE. So müssen die entsprechenden Boardtypen installiert und ausgewählt sein, die Einstellungen plattformspezifisch angepasst werden etc. Auf diese Einstellungen wird im Folgenden eingegangen. Dabei wird davon ausgegangen, dass die nötigen Bibliotheken für die jeweilge Plattform bereits installiert sind. Sollte dies nicht der Fall sein, so findest du Informationen hierzu in Kap. 12.
Darüber hinaus gibt es bei der Installation auf dem ESP32 noch weitere Dinge zu beachten, die im entspr. Kapitel ebenfalls behandelt werden.


2.1.1 Installation auf dem Due

Im Folgenden wird die Installation der BSB-LAN-Software auf einem Arduino Due beschrieben. Die Beschreibung bezieht sich dabei auf die Verwendung der Arduino IDE. Mit den Voreinstellungen der BSB-LAN-Software wird für die IP-Adressvergabe DHCP genutzt. Solltest du dies nicht wünschen und eine feste IP vergeben wollen, so lies bitte Kap. 2.2.2 und passe die Datei BSB_LAN_config.h vor dem Flashen an!

Hinweis
Solltest du Windows benutzen, so ist evtl. noch eine zusätzliche Treiberinstallation nötig. Auf der Seite https://www.arduino.cc/en/Guide/ArduinoDue findest du weitere Informationen.

Führe die folgenden Schritte aus:

  1. Verbinde das Arduino-Setup mit einem USB-Kabel mit deinem Computer. Nutze dabei den ‘Programming Port’ des Due, das ist der ‘mittlere’ USB-Port, der neben der Netzteilbuchse platziert ist. Sowohl das LAN-Shield als auch der BSB-LAN-Adapter sollte zuvor bereits auf den Due gesteckt sein, dies ist jedoch nicht zwingend nötig.

    Das komplette Setup (Arduino Due + LAN-Shield + BSB-LPB-LAN-Adapter v3) inklusive der entsprechenden Kabel.

  2. Downloade die aktuelle BSB-LAN-Version und entpacke die heruntergeladene Datei BSB-LAN-master.zip.

  3. Wechsle in den Ordner “BSB-LAN-master”/”BSB_LAN” und benenne die Datei BSB_LAN_config.h.default in BSB_LAN_config.h um!

  4. Wenn du eigenen Code implementieren willst, benenne die Datei BSB_LAN_custom.h.default in BSB_LAN_custom.h um!

  5. Öffne den BSB_LAN-Sketch mittels eines Doppelklicks auf die Datei BSB_LAN.ino im BSB_LAN-Ordner. Die dazugehörigen Dateien BSB_LAN_config.h und BSB_LAN_defs.h werden automatisch mit geladen.

  6. Wähle “Arduino Due (Programming Port)” unter Tools/Board bzw. Werkzeuge/Board.

    Hinweis
    Sollte das Board nicht aufgeführt sein, so muss der Atmel SAM Core hinzugefügt werden. Informationen hierzu findest du in Kap. 12.
  7. Wähle den korrekten Seriellen Port, an dem der Due am Rechner angeschlossen ist, unter Werkzeuge/Port aus.

    Die Einstellungen für den Due in der Arduino IDE.

  8. Solltest du BSB-LAN mittels Anpassung der Datei BSB_LAN_config.h konfigurieren wollen (s. Kap. 2.2.2), so tue dies bitte jetzt.

  9. Starte den Flashvorgang und lade den Sketch mittels Klick auf “Sketch/Upload” bzw. “Sketch/Hochladen” auf den Arduino Due.

  10. Nach Beenden des Flashvorgangs starte den Seriellen Monitor der Arduino IDE und beobachte die Ausgaben, die beim Start des Arduino Due erfolgen. Dort wird u.a. auch die IP ausgegeben, die dem Setup bei Verwendung von DHCP zugeteilt wird.

Herzlichen Glückwunsch - du hast BSB-LAN installiert!
Fahre nun mit dem Anschluss und der Inbetriebnahme des Setups und/oder der Konfiguration der BSB-LAN-Software fort.


2.1.2 Installation auf dem ESP32

Im Folgenden wird die Installation der BSB-LAN-Software auf einem ESP32 beschrieben. Die Beschreibung bezieht sich dabei auf die Verwendung der Arduino IDE. Mit den Voreinstellungen der BSB-LAN-Software wird für die IP-Adressvergabe DHCP genutzt. Solltest du dies nicht wünschen und eine feste IP vergeben wollen, so lies bitte Kap. 2.2.2 und passe die Datei BSB_LAN_config.h vor dem Flashen an!

Hinweis
Sollte das ESP32-Board nicht von deinem Betriebssystem erkannt werden, so ist evtl. noch eine zusätzliche Treiberinstallation für den vom Board verwendeten USB-Chip nötig.

Führe die folgenden Schritte aus:

  1. Verbinde dein ESP32-Board mit mit einem USB-Kabel mit deinem Computer. Den BSB-LAN-Adapter kannst du vorher bereits auf bzw. unter dein ESP32-Board gesteckt haben, dies ist jedoch nicht zwingend nötig.

  2. Downloade die aktuelle BSB-LAN-Version und entpacke die heruntergeladene Datei BSB-LAN-master.zip.

  3. Wechsle in den Ordner “BSB-LAN-master”/”BSB_LAN” und benenne die Datei BSB_LAN_config.h.default in BSB_LAN_config.h um!

  4. Wenn du eigenen Code implementieren willst, benenne die Datei BSB_LAN_custom.h.default in BSB_LAN_custom.h um!

  5. Entferne (oder verschiebe) die beiden Ordner “ArduinoMDNS” und “WiFiSpi” aus dem BSB-LAN-Unterordner “src” - diese dürfen nicht im “BSB-LAN”- bzw. “src”-Ordner vorhanden sein!

  6. Öffne den BSB_LAN-Sketch mittels eines Doppelklicks auf die Datei BSB_LAN.ino im BSB_LAN-Ordner. Die dazugehörigen Dateien BSB_LAN_config.h und BSB_LAN_defs.h werden automatisch mit geladen.

  7. Wähle den entspr. ESP32-Boardtyp unter Tools/Board bzw. Werkzeuge/Board aus:

    • Für den in diesem Handbuch empfohlenen “Joy-It ESP32-NodeMCU” (oder identische Clones mit einem “ESP32-WROOM”-Chip) lautet der passende Boardtyp “ESP32 Dev Module”.

    • Für das empfohlene “Olimex ESP32-EVB” wähle bitte den gleichnamigen Eintrag aus der Liste aus.

    Hinweise
    Falls das ESP32-Framework bereits installiert ist und dir die verschiedenen ESP32-Boardvarianten angezeigt werden, überprüfe bitte im “Boardverwalter” unter “Werkzeuge/Boards”, dass die Version 1.0.5 (oder höher, falls verfügbar) installiert ist.
    Sollte das Board nicht aufgeführt sein, so muss die ESP32-Plattform in der Arduino IDE hinzugefügt werden. Informationen hierzu findest du in Kap. 12.
  8. Wähle den korrekten Seriellen Port, an dem das ESP32-Board am Rechner angeschlossen ist, unter Werkzeuge/Port aus.

  9. Stelle die Übertragungsgeschwindigkeit/Baudrate auf 115200 ein (Achtung: In der Arduino IDE ist bei ESP32-Boards i.d.R. 921600 voreingestellt!).

  10. Wähle bei “Partition Scheme”

    • für den empfohlenen ESP32-NodeMCU bitte die Variante “Default 4MB with spiffs (1.2BM APP/1.5MB SPIFFS)”,

    • für das empfohlene Olimex-Board die Variante “Minimal SPIFFS (Large APPS with OTA)” aus.

      Die Einstellungen für den ESP32-NodeMCU in der Arduino IDE.

  11. Klicke nun auf den Reiter für die Datei BSB_LAN_config.h und passe zwingend die folgenden Einstellungen an:

    • Aktiviere das Definement #define WIFI in der Datei BSB_LAN_config.h!

    • Trage die Zugangsdaten für dein WLAN ein (SSID und Passwort)!

  12. Solltest du BSB-LAN mittels Anpassung der Datei BSB_LAN_config.h konfigurieren wollen (s. Kap. 2.2.2), so tue dies bitte jetzt.

  13. Starte den Flashvorgang und lade den Sketch mittels Klick auf “Sketch/Upload” bzw. “Sketch/Hochladen” auf den Arduino Due.

  14. Nach Beenden des Flashvorgangs starte den Seriellen Monitor der Arduino IDE und beobachte die Ausgaben, die beim Start des ESP32 erfolgen. Dort wird u.a. auch die IP ausgegeben, die dem Setup bei Verwendung von DHCP zugeteilt wird.

Hinweise
Wenn der ESP32 sich nicht mit dem konfigurierten WLAN verbinden kann, richtet er seinen eigenen Accesspoint “BSB-LAN” mit dem Passwort “BSB-LPB-PPS-LAN” für 30 Minuten ein. Danach wird er neu starten und erneut versuchen, eine Verbindung zum eingerichteten WLAN-Netzwerk herzustellen.
Obwohl die Logging-Funktion auch mit dem ESP32 funktioniert, ist es nicht empfehlenswert, diese Funktion aufgrund des Verschleißes des Flash-Speichers übermäßig zu nutzen. Sollte das Olimex-Board zum Einsatz kommen, so kann anstelle des SPIFF-Flashspeichers eine microSD-Karte genutzt werden. Die Verwendung ist in der Datei “BSB_LAN_config.h” zu aktivieren.

Herzlichen Glückwunsch - du hast BSB-LAN installiert!
Fahre nun mit dem Anschluss und der Inbetriebnahme des Setups und/oder der Konfiguration der BSB-LAN-Software fort.


2.1.3 Updates

Ein Updaten der BSB-LAN-Software erfolgt durch das gewohnte Flashen der neuen Version (Download als ZIP-File, per git o.ä.), wie es in den vorherigen Installationskapiteln beschrieben ist.

Hinweise
Solltest du in der Datei BSB_LAN_config.h bestimmte Änderungen bei der neu zu flashenden Version vorgenommen haben, wie bspw. die Zugangsdaten für dein WLAN oder eine fest vergebene IP, die dann nach dem Flashen offenbar nicht übernommen wurden, so liegt dies i.d.R. daran, dass die alten Einstellungen aus dem EEPROM gelesen wurden.
Um die neuen Einstellungen wirksam werden zu lassen, stelle in der Webkonfiguration die Einstellung “Konfiguration aus EEPROM lesen” einmal auf “Aus”, speichere die Änderung und flashe nochmal neu.
Danach sollten die neuen Einstellungen wirksam geworden sein, weil BSB-LAN diese nun aus der Datei BSB_LAN_config.h und nicht aus dem EEPROM eingelesen hat.
Nach erfolgreicher Überprüfung stelle “Konfiguration aus EEPROM lesen” wieder auf “Ein”.
Die bestehende und ggf. angepasste Datei BSB_LAN_config.h kann in der Regel bei einem Update auf eine neuere Version zwar übernommen werden, es jedoch ratsam, auch hier die jeweils aktuelle Datei BSB_LAN_config.h.default anstelle der bestehenden Datei BSB_LAN_config.h zu verwenden. Dazu muss die .default-Datei wie gehabt umbenannt und ggf. den vorherigen Einstellungen entspr. angepasst werden. So kann man sicher gehen, dass man ein komplettes Update der BSB-LAN-Software vorgenommen hat.
Wenn der Adapter an den Bus des Heizungsreglers angeschlossen ist, so kann er angeschlossen bleiben, wenn der Due/ESP32 erneut geflasht werden soll. Es besteht keine Notwendigkeit den Adapter vom Regler abzuklemmen, wenn man BSB-LAN updaten möchte.

2.2 Konfiguration

Die BSB-LAN-Software kann den individuellen Ansprüchen entsprechend konfiguriert werden. Die Konfiguration kann dabei auf zwei Arten erfolgen: Mittels Anpassen der Datei BSB_LAN_config.h sowie mittels Webinterface. Im Folgenden werden die Konfigurationsmöglichkeiten eingehender erklärt. Die Beschreibungen in Kap. 2.2.2 sind i.d.R. ausführlicher, daher ist es sinnvoll, beide Kapitel eingehend zu studieren.


2.2.1 Konfiguration mittels Webinterface

Die Einstellungsübersicht bzw. die Webkonfigurationsoberfläche ist zwar im Prinzip selbsterklärend, trotzdem seien die einzelnen Punkte hier nochmals mit einer kurzen Erklärung aufgeführt.
Für eine u.U. ausführlichere Erklärung zu den einzelnen Funktionen sieh bitte im Kap. 2.2.2 nach.

Die Übersicht der Webkonfiguration gliedert sich in drei Spalten:

Wichtig
Zum Übernehmen geänderter Einstellungen muss schließlich unten auf den Button “Parameter speichern” geklickt werden!

Im Folgenden nun die tabellarische Übersicht der Funktionen mit den (Vor-)Einstellungen und den entspr. Erklärungen (auf die Nennung der linken Spalte “Kategorie” muss an dieser Stelle aus Platz- und Darstellungsgründen leider verzichtet werden):

Funktion (Vor-)Einstellung Erklärung
Konfiguration aus EEPROM lesen Ein Liest die gespeicherte Konfiguration aus dem EEPROM beim Start des Due aus (Aus/Ein).
Diese Einstellungen können von den Voreinstellungen abweichen, die in der Datei BSB_LAN_config.h hinterglegt wurden.
Sollen die im EEPROM gespeicherten Einstellungen bspw. bei einem Update überschrieben werden, so ist vor dem Flashen auf “Aus” zu stellen und die Einstellung zu speichern!
Wenn die Einstellung auf „Aus“ ist, werden Änderungen nur bis zum Neustart des Due aktiv bleiben.
Schreibzugriff (Ebene) Aus Schreibzugriff des Adapters auf den Heizungsregler (Aus/Standard/Komplett).
Soll Schreibzugriff auf den Heizungsregler gewährt werden, so ist es empfehlenswert, die Einstellung ‘Standard’ zu wählen, hierbei sind nahezu alle verfügbaren Parameter schreibbar. Im Unterschied zu ‘Komplett’ sind jedoch einige funktionskritische Parameter nicht veränderbar, die reglerintern nochmals geschützt vorliegen.
Die Einstellung ‘Komplett’ sollte daher nur in Ausnahmefällen und mit Bedacht sowie einem sehr guten Kenntnisstand über die Reglerfunktionalität gewählt werden!
Auf Updates überprüfen Aus Automatisches Überprüfen auf Updates von BSB-LAN (Aus/Ein)
Typ BSB Verwendeter Bustyp (BSB/LPB/PPS)
Eigene Adresse 66 Eigene Adresse des Adapters
Zieladresse 0 Zieladresse für die Abfragen
PPS: PPS-Modus Passiv Nur PPS: Benutzer, die den Adapter an der PPS-Schnittstelle verwenden, müssen zwei Einstellungen vornehmen: Zum einen muss der Modus ausgewählt werden, in dem auf den Bus zugegriffen werden soll (Passiv/Als Raumgerät). Bei Verwendung eines QAA-Raumgerätes muss hier „passiv“ ausgewählt werden. Dann werden nur die Werte, die über den Bus gehen, in der Weboberfläche angezeigt, ein Schreiben von Werten ist dann nicht möglich.
Wenn hier „als Raumgerät“ ausgewählt wird, können über die Weboberfläche auch Werte an die Heizung gesendet werden. Zum anderen ist dann noch der Typ des zu emulierenden Raumgerätes auszuwählen (s.u.). Es sollte dann kein weiteres Raumgerät am Bus hängen, da sonst beide Sender ihre jeweils eigenen Werte an den Heizungsregler schicken, so dass kein konsistenter Betrieb möglich ist.
PPS: QAA Modell QAA70 Nur PPS: Modell des zu imitierenden Raumgerätes (QAA50/QAA70).
URL Passkey -keine Voreinstellung- Optionale Sicherheitsfunktion: “URL Passkey”
HTTP-Authentifizierung -keine Voreinstellung- Optionale Sicherheitsfunktion: “User-Pass” (Basic HTTP Auth)
DHCP verwenden Ein DHCP verwenden (= automatische IP-Adressvergabe durch Router) (Aus/Ein)
Statische IP-Adresse 192.168.178.88 Manuelle Netzwerkkonfiguration: Feste IP-Adresse
Subnetzmaske 255.255.255.0 Manuelle Netzwerkkonfiguration: Subnetz
Gateway 192.168.178.1 Manuelle Netzwerkkonfiguration: IP-Adresse des Gateways
DNS Server 192.168.178.1 Manuelle Netzwerkkonfiguration: IP-Adresse des DNS-Servers
TCP Port 80 TCP-Port des Setups
MAC-Adresse 00:80:41:19:69:90 (Voreingestellte) MAC-Adresse des LAN-Shields oder MAC-Adresse des ESP
Vertrauenswürdige IP-Adresse 0.0.0.0 Optionale Sicherheitsfunktion: “Trusted IP”, Zugriff nur von dieser IP möglich
Vertrauenswürdige IP-Adresse 0.0.0.0 Optionale Sicherheitsfunktion: “Trusted IP”, Zugriff nur von dieser IP möglich
WLAN SSID -keine Voreinstellung- SSID des WLAN bei Verwendung der WiFi-ESP-Lösung
WLAN Passwort -keine Voreinstellung- Passwort des WLAN bei Verwendung der WiFi-ESP-Lösung
Verwenden Aus MQTT-Funktion verwenden (Aus/Ein)
IP-Adresse Broker 192.168.178.20 IP-Adresse des MQTT-Brokers
Username User MQTT: Username bei Verwendung von Username/Passwort
Passwort Pass MQTT: Passwort bei Verwendung von Username/Passwort
Geräte ID MyHeater Gerätename (Header in JSON-Payload)
Topic prefix BSB-LAN Topic prefix der MQTT-Nachrichten
Berechnung Aus Berechnung von 24h-Durchschnittswerten ausgewählter Parameter (Aus/Ein)
Parameter 8700,8326 Parameter für die 24h-Durchschnittswertberechnung
Bustelegramme Aus Loggen von Bustelegrammen aktivieren (Aus/-diverse Optionen-), die gewünschte Einstellung ist der jeweiligen Optionsbeschreibung entspr. vorzunehmen.
Auf SD Karte Aus Zu loggende Werte auf der microSD-Karte speichern (Aus/Ein)
Logintervall (Sekunden) 3600 Logintervall in Sekunden
Parameter 8700,8743,8314 Zu loggende Parameter
Pins 7 Verwendete(r) Pin(s) für OneWire-Sensoren (DS18B20)
Pins 2,3 Verwendete(r) Pin(s) für DHT22-Sensoren
TWW-Push Taste: Pin 0 Raumgerät-Emulation: Verwendeter Pin für den TWW-Push Taster.
RGT1 Temperatursensor Parameter -keine Voreinstellung- Raumgerät 1 Emulation: Trage hier die spezifische(n) Parameternummer(n) für den (die) Raumtemperatur-Sensor(en) ein. Bis zu fünf Sensoren können verwendet werden, die Aufzählung der Parameternummern ist lediglich durch ein Komma zu separieren. Wenn mehr als ein Sensor verwendet werden, wird automatisch der Mittelwert gebildet.
RGT1 Präsenztaste: Pin 0 Raumgerät 1 Emulation: Verwendeter Pin für die HK1-Präsenztaste.
RGT2 Temperatursensor Parameter -keine Voreinstellung- Raumgerät 2 Emulation: Trage hier die spezifische(n) Parameternummer(n) für den (die) Raumtemperatur-Sensor(en) ein. Bis zu fünf Sensoren können verwendet werden, die Aufzählung der Parameternummern ist lediglich durch ein Komma zu separieren. Wenn mehr als ein Sensor verwendet werden, wird automatisch der Mittelwert gebildet.
RGT2 Präsenztaste: Pin 0 Raumgerät 2 Emulation: Verwendeter Pin für die HK2-Präsenztaste.
RGT3 Temperatursensor Parameter -keine Voreinstellung- Raumgerät 3 Emulation: Trage hier die spezifische(n) Parameternummer(n) für den (die) Raumtemperatur-Sensor(en) ein. Bis zu fünf Sensoren können verwendet werden, die Aufzählung der Parameternummern ist lediglich durch ein Komma zu separieren. Wenn mehr als ein Sensor verwendet werden, wird automatisch der Mittelwert gebildet.
RGT3 Präsenztaste: Pin 0 Raumgerät 3 Emulation: Verwendeter Pin für die HK3-Präsenztaste.
Verwenden Aus MAX!-Geräte verwenden (Aus/Ein)
IP-Adresse Cube 192.168.178.5 IP-Adresse des CUNO/CUNX/modifizierten MAX!Cube
Geräte KEQ0502326,KEQ0505080 Seriennummern der zu verwendenden MAX!-Geräte
Verwenden Aus IPWE-Erweiterung verwenden (URL/ipwe.cgi) (Aus/Ein)
Parameter 8700,8743,8314 Darzustellende Parameter in der IPWE-Erweiterung
Verwenden Serial Debugging-Funktion verwenden (Aus/Serial/Telnet)
Verbositätsmodus Ein Verbositätsmodus aktiviert (Aus/Ein)
Monitor Modus Aus Monitor Modus aktiviert (Aus/Ein)

2.2.2 Konfiguration durch Anpassen der Datei BSB_LAN_config.h

Die Konfiguration der BSB-LAN-Software kann außerdem erfolgen, indem die Einstellungen in der Datei BSB_LAN_config.h angepasst werden. Hierzu werden nachfolgend sämtliche Einstellmöglichkeiten analog zu der Reihenfolge in der Datei BSB_LAN_config.h aufgeführt. Es ist daher ratsam, die Einstellungen Punkt für Punkt abzuarbeiten.

Hinweis
Wenn ein Definement deaktiviert ist oder werden soll, dann sind vor dem Hashtag zwei Slashes hinzuzufügen (“auskommentieren”):
//#define XYZ = Definement XYZ ist deaktiviert.
Wenn ein Definement aktiviert werden soll, dann sind die beiden Slashes vor dem Hashtag zu entfernen:
#define XYZ = Definement XYZ ist aktiv.



Netzwerkeinstellungen:





Sicherheitsfunktionen:


Einstellungen für optionale Sensoren:








Buseinstellungen (Pins und Typ):









#define JSONCONFIG



Für Nutzer des veralteten Setups auf Basis des Arduino Mega 2560:
Nachfolgende Einstellmöglichkeiten dienen der Möglichkeit, Speicher einzusparen, so dass auch auf einen Mega 2560 geflasht werden kann.


Weiter zu Kapitel 3
Zurück zum Inhaltsverzeichnis