Willkommen zum eBUS Adapter Shield v5!
Dies ist die Dokumentation des eBUS Adapter Shield v5, mit dessen Hilfe man mit einer eBUS-fähigen Heizungs-, Lüftungs- oder Solaranlage kommunizieren kann.
Einführung
Version 5 des eBUS Adapters ist ein Redesign der v3.1 mit einem deutlich kleineren Footprint (37x26mm), steckbarer eBUS Verbindung, WIFI on board durch Wechsel auf ESP32-C3, Unterstützung verschiedener Ethernet Module und Kompatibilität zu vielen D1 mini shields (daher der Name “eBUS Adapter Shield”).
Der Adapter erfüllt wie v3.1 und v3.0 die von der eBUS Spezifikation geforderten Zeiten bei der Arbitrierung.
Dies wird durch Einsatz eines ESP32-C3 in RISC Architektur ermöglicht, der u.a. folgende Vorteile mit sich bringt:
- minimale Zeitverzögerung durch speziell entwickelten Treiber in der Firmware
- vollständige galvanische Trennung der Signale ohne Stromaufnahme vom eBUS (Klasse 0 laut eBUS Spezifikation)
- Option für
micro-ebusddirekt auf dem Adapter, mit WIFI oder Ethernet (seit Firmware Version 2025-10-30) - flexible, konfigurierbare Verbindung zu ebusd auf einem Host:
- WIFI direkt über onboard PCB Antenne
- USB seriell über integriertes JTAG/serial interface
- Raspberry Pi über GPIO/ttyAMA0
- Ethernet mit Zusatzmodul USR-ES1 oder anderes W5500 Modul
- volle Unterstützung für ebusd enhanced protocol sowie standard protocol (für ebusd)
- über Webbrowser konfigurierbare und aktualisierbare Firmware durch OTA Update sowie direkt über das USB JTAG/serial interface
- viele weitere Möglichkeiten, z.B. Anschluss von Sensoren und/oder Displays.
Durch die Verwendung eines DC-DC Wandlers und galvanischer Trennung der Signale ist der eBUS völlig isoliert von der Stromversorgung und es wird nur marginal Strom vom eBUS ohne Schwankung entnommen (Klasse 0 laut Spezifikation Kapitel 10.7).
Somit ist die Heizungs-, Lüftungs- oder Solaranlage bestens geschützt und wird an der eigenen Stromquelle in keinster Weise belastet.
Komponenten
Hier ist eine Übersicht der einzelnen Komponenten mit ihren Verbindungen bei Verwendung von micro-ebusd:
Bei Verwendung von einem externen ebusd sieht es so aus:
Die Komponenten im Detail:
- Heizung/Lüftung/Solarthermie
wird mit dem Adapter über eine 2-Drahtleitung verbunden (die Polung spielt keine Rolle). - Adapter
- mit integriertem
micro-ebusd
interpretiert direkt das eBUS Protokoll und macht die Daten bidirektional via MQTT und HTTP verfügbar. Netwerkverbindung über - mit externem ebusd (auf einem Host),
der das eBUS Protokoll interpretiert und die Daten bidirektional via MQTT, HTTP, KNX und TCP Port verfügbar macht. Verbindung zum Adapter über- WIFI (on board),
- USB (seriell),
- GPIO (UART) des Raspberry Pi oder
- Ethernet (mit USR-ES1 oder einem anderen W5500 Modul).
- mit integriertem
- Smart Home
zur weiteren Auswertung, Monitoring oder Steuerung, z.B. Home-Assistant, KNX, Node-Red, FHEM, iobroker und weitere.
Netzwerk-/Datenverbindung
Die Verbindung über USB, WIFI und Raspberry Pi ist immer möglich. Lediglich für Ethernet wird ein zusätzliches W5500 Modul benötigt.
Über das easi> Interface (via USB oder Netzwerk) können sämtliche Parameter eingestellt werden.
Nach Auslieferung muss evtl. erst die Firmware installiert werden, siehe unter erste Schritte.
Als Protokoll zwischen ebusd und dem Adapter (wenn nicht der integrierte micro-ebusd genutzt wird) kann sowohl direkt das eBUS Protokoll (“standard protocol”), als auch das
ebusd “enhanced protocol” verwendet werden.
Sowohl der integrierte micro-ebusd als auch das enhanced protocol nutzen alle Vorteile des Adapters, indem die eBUS Arbitrierung direkt in der Firmware übernommen wird.
WIFI
Zur Nutzung des Adapters über WIFI muss dieser lediglich über die USB Buchse mit Strom versorgt werden.
Für ebusd muss die Host-Verbindung Über das easi> Interface auf WIFI gestellt werden (voreingestellt bei einem neuen oder noch nicht konfigurierten Adapter).
Im easi> Interface kann auch die WIFI Konfiguration (SSID, DHCP/feste IP-Adresse, Netzmaske, Gateway) angepasst werden.
Die initiale WLAN-Einstellung kann entweder über die Firmware-Seite erfolgen, den “EBUS” Access Point, oder via WPS mit Push Button Mode (PBC; seit Firmware Version 2024-10-27 solange der Adapter noch nicht konfiguriert wurde und der Button ein Mal gedrückt wurde, so dass die rote LED permanent an ist).
Zusätzlich zum Adapter wird lediglich ein normales USB-Kabel mit Micro-B-Stecker benötigt. Der Adapter wird bereits mit einem eingesteckten eBUS-Stecker geliefert.
Die Stromversorgung erfolgt direkt über den USB-Anschluss, kann aber auch über die Pins der Buchsenleiste W2 hergestellt werden, z.B. über ein DC Power Shield. Siehe Stromversorgung für Details.
Die “device” Konfiguration für ebusd lautet z.B. -d ens:192.168.178.2:9999,
wobei 192.168.178.2 durch die richtige IP-Adresse ersetzt werden muss.
USB
Zur Nutzung des Adapters mit externem ebusd über den USB-Anschluss muss dieser lediglich mit dem Host verbunden werden.
Alle modernen Betriebssysteme (Windows/Linux/MacOS) haben bereits den dafür notwendigen Treiber.
Der Adapter stellt zwei Interfaces über USB zur Verfügung, die sich als Produkt “USB JTAG/serial debug unit” (idProduct: 0x1001) von “Espressif” (idVendor: 0x303a) darstellen:
- Interface 0 (inkl. 1): CDC ACM (USB “communication device class” mit “abstract control model”)
die serielle Schnittstelle, erscheint unter Linux als “USB ACM device” unter/dev/ttyACM<x>und unter Windows als “USB JTAG/serial debug unit (interface 0)” oder “Serielles USB-Gerät (COM…)” - Interface 2: JTAG Debug
das Debug Interface, erscheint unter Linux nicht unter/devals Device (lsusb -tmeldet es als “If 2, Class=Vendor Specific Class” ohne Treiber) und unter Windows als “USB JTAG/serial debug unit (interface 2)” (wird nicht verwendet)
Für ebusd muss die Host-Verbindung über das easi> Interface auf USB gestellt werden.
Bei micro-ebusd lässt sich das USB Interface auch für die Kommandozeilenschnittstelle (REPL) nutzen.
Zusätzlich zum Adapter wird lediglich ein normales USB-Datenkabel mit Micro-B-Stecker benötigt. Der Adapter wird bereits mit einem eingesteckten eBUS-Stecker geliefert.
Die Stromversorgung erfolgt direkt über den USB-Anschluss, siehe Stromversorgung für Details.
Die “device” Konfiguration für ebusd lautet z.B. -d ens:/dev/ttyACM0, wobei ttyACM0 bei mehreren angeschlossenen
USB Geräten dieser Art anders lauten kann.
Raspberry Pi
Dreht man den Adapter auf den Kopf, lässt er sich auf einen
Raspberry Pi aufstecken.
Hierbei muss darauf geachtet werden, dass die näher an der Bohrung liegende Buchsenleiste des Adapters (links unten im Bild) auf Pin 2 der Raspberry Pi GPIO Leiste gesteckt wird, so dass diese Bohrung genau über der auf dem Raspberry Pi liegt und man einen Abstandshalter dazwischen setzen könnte.
Mit aufgestecktem Adapter (hier in rot zur Verdeutlichung) sieht das so aus:
Für ebusd muss die Host-Verbindung über das easi> Interface auf Raspberry Pi gestellt werden. Die Firmware erkennt das auch beim Booten und konfiguriert den Adapter bereits entsprechend.
Für Raspberry Pi 5 muss bei älteren Adaptern noch ein extra Hinweis beachtet werden.
Bei micro-ebusd ist die GPIO Verbindung zum Raspberry Pi ohne Funktion und wird lediglich zur Stromversorgung genutzt.
Zusätzlich zum Adapter wird nur evtl. ein Stacking-Header benötigt, falls die Raspberry-CPU einen Kühler hat. Der Adapter wird bereits mit einem eingesteckten eBUS-Stecker geliefert.
Die Stromversorgung erfolgt direkt über die Raspberry Pi GPIO Leiste.
Die “device” Konfiguration für ebusd lautet: -d ens:/dev/ttyAMA0 --latency=50
Details zur Einrichtung des Raspberry Pi für ebusd finden sich hier.
Ethernet
Zur Nutzung via Ethernet gibt es folgende Möglichkeiten:
- USR-ES1 Modul mit W5500 (z.B. von hier oder hier) zum Aufstecken auf W1+USRL,
- W5500 Ethernet Modul (z.B. von hier oder hier) zum geflippten Aufstecken auf USRL+W2 (so dass der 5V Pin des Moduls auf W2/9 sitzt).
Achtung: wird das W5500 Modul falsch auf den Adapter gesteckt (z.B. versetzt oder in umgekehrter Richtung), kann der Adapter dadurch beschädigt und unbrauchbar werden! Also am besten stromlos machen, Modul aufstecken und die Position kontrollieren, und erst dann wieder über den USB-Anschluss mit Strom versorgen.
Mit aufgestecktem USR-ES1 Modul sieht das so aus:
Für ebusd muss die Host-Verbindung über das easi> Interface auf Ethernet gestellt werden.
Im easi> Interface kann auch die Ethernet Konfiguration (DHCP/feste IP-Adresse, Netzmaske, Gateway) angepasst werden.
Wenn das W5500 Modul von der Firmware nicht erkannt wird, ist es möglicherweise defekt oder im Idealfall nur die Pin-Verbindung instabil. Siehe hier zur Überprüfung.
Zusätzlich zum Adapter und Ethernet-Modul wird lediglich ein normales USB-Kabel mit Micro-B-Stecker benötigt. Der Adapter wird bereits mit einem eingesteckten eBUS-Stecker geliefert.
Die Stromversorgung erfolgt direkt über den USB-Anschluss, kann aber auch über die Pins der Buchsenleiste W2 hergestellt werden, z.B. über ein DC Power Shield. Siehe Stromversorgung für Details.
Die “device” Konfiguration für ebusd lautet z.B. -d ens:192.168.178.2:9999, wobei 192.168.178.2 durch die richtige
IP-Adresse ersetzt werden muss.
Stromversorgung
Bei Verwendung von WLAN oder Ethernet erfolgt die Stromversorgung des Adapters einfach über den USB-Anschluss mit einem handelsüblichen USB-Netzteil, z.B. einem, mit dem man auch ein Handy laden kann.
Die Mindestanforderung an die Stromquelle beträgt 1 Watt. Sicherheitshalber empfehlen wir die Verwendung einer Stromquelle mit mindestens 2 Watt, also einer Leistung von 400 mA bei 5 V.
Alternativ kann der Adapter auch über die Pins an der Buchse W2 mit Strom versorgt werden, z.B. über ein DC Power Shield.
Pinleisten, Funktionen
Für den Anschluss weiterer Komponenten stehen zusätzliche Pin Header zur Verfügung. Lediglich bei Ethernet bleiben nicht viele Pins dafür übrig.
| Anschluss | Funktion | USB | WIFI | Raspberry Pi | Ethernet |
|---|---|---|---|---|---|
| USB | USB connector | USB | power | - | power |
| W1 | I/O / W5500 | I/O | I/O | I/O | W5500 |
| W2 | I/O / Raspi | I/O | I/O | Raspi | I/O |
| USRL | W5000 / Raspi | - | - | Raspi | W5500 |
| EBUS | eBUS connector | eBUS | eBUS | eBUS | eBUS |
Legende:
- - = nicht anderweitig nutzbar
Die Belegung eines Pins mit einer I/O Funktion kann über das easi> Interface vorgenommen werden.
I/O Belegung
Die ESP32-C3 I/O sind wie folgt belegt bzw. an den Buchsenleisten verfügbar:
| IO | Funktion / Leiste/Pin | Setting | USB + WIFI | Raspberry Pi | Ethernet |
|---|---|---|---|---|---|
| 0 | W1/3 | * | * | MISO | |
| 1 | W1/4 | * | * | RST | |
| 2 | W1/5, USRL/3, RPI/5 | pull-up | * | SCL | MOSI |
| 3 | W1/2, USRL/4, RPI/7 | * | GPIO4 | SCLK | |
| 4 | W2/11, RPI/8 | * | TXD | * | |
| 5 | W2/13, USRL/6, RPI/11+12 | * | GPIO17+18 | INTN | |
| 6 | W2/14, USRL/5, RPI/G | * | GND | SCNN | |
| 7 | eBUS RX | - | - | - | |
| 8 | W1/6, W2/12, RPI/10 | pull-up | * | RXD | 3.3V |
| 9 | Button, LED blue, RPI/13 | pull-up | - | (GPIO27) | - |
| 10 | eBUS TX | - | - | - | |
| 18 | USB- | USB | - | - | |
| 19 | USB+ | USB | - | - | |
| 20 | RX, LED green, W2/15, RPI/16 | LED+* | GPIO23+LED+* | LED+* | |
| 21 | TX, LED red, W2/16, RPI/18 | 500R | LED+* | GPIO24+LED+* | LED+* |
| EN | Reset, W1/1 | pull-up | Reset | Reset | Reset |
Legende:
- * = beliebige Funktionszuweisung
- - = nicht anderweitig nutzbar
LEDs
Der Adapter verfügt über 3 LEDs mit folgender Zuordnung:
- blau: Signale der Firmware
- grün: eBUS Empfang oder Firmware-Signal
- rot: eBUS Senden oder Firmware-Signal
Beim Booten dimmen alle LEDs drei Mal. Dabei hat der Button die Funktion, gespeicherte Einstellungen zu ignorieren und den WIFI Access Point mit SSID “EBUS” zu starten.
Im eBUS Modus blinkt die blaue LED alle 5 Sekunden kurz als Ping, sofern via easi> Interface konfiguriert.
Die LEDs leuchten grün und rot bei entsprechendem eBUS Traffic (grün bei Empfang, rot bei Senden), sofern der eBUS Modus aktiv ist und es so via easi> Interface konfiguriert wurde.
Button
Der Adapter hat einen Button on board, mit dem verschiedene Aktionen möglich sind:
- Drücken+Halten vor Herstellen der Stromversorgung:
Bootloader Modus - Drücken+Halten während des Bootens (solange die LEDs dimmen):
gespeicherte Einstellungen ignorieren und “EBUS” Access Point starten - Drücken nach dem Booten:
- solange der Adapter noch nicht konfiguriert ist: WPS im Push Button Mode starten (PBC, rote LED leuchtet dauerhaft bis zur erfolgreichen Verbindung)
- andernfalls: rote LED dimmt ein Mal
- Drücken+Halten nach dem Booten:
Reboot
Darüber hinaus kann der Button auch zum Prüfen der Spannungsversorgung genutzt werden, da mit Drücken des Buttons die blaue LED eingeschaltet wird (unabhängig von I/O des ESP).
Zusatzfunktionen
Viele der D1 mini Shields sind kompatibel mit dem Adapter und können einfach aufgesteckt werden. Dabei hängt der Pin links oben des aufgesteckten Moduls absichtlich “in der Luft”, das Modul muss also genau auf die 8 Pins der Buchsenleiste W2 gesteckt werden und ist deshalb um einen Pin versetzt in W1.
Folgende Typen werden vom easi> Interface unterstützt:
- OLED 0.66 Shield: erfolgreich getestet
- BMP280/BME280/BMP180: erfolgreich getestet
- 8x8 RGB Shield: erfolgreich getestet
- DC Power Shield: erfolgreich getestet
Damit kann man nahezu jedes beliebige DC Steckernetzteil mit 5,5mm Hohlstecker verwenden, um die Stromversorgung statt über USB herzustellen. - RGB LED Shield
- PIR Shield (*)
- SHT30 Shield (*)
- DHT Shield (*)
(*) geplant für eine zukünftige Firmware Version
Die Zuordnung der ESP32-C3 Pins zu den Wemos bzw. Shield Ports D0-D8 + A0 ist wie folgt:
| Wemos | IO | W1 | Adapter | W2 | IO | Wemos |
|---|---|---|---|---|---|---|
| RST | - | 16 | IO21 | TX | ||
| A0 | EN | 1 | 15 | IO20 | RX | |
| D0 | IO3 | 2 | 14 | IO6 | D1 | |
| D5 | IO0 | 3 | 13 | IO5 | D2 | |
| D6 | IO1 | 4 | 12 | IO8 | D3 | |
| D7 | IO2 | 5 | 11 | IO4 | D4 | |
| D8 | IO8 | 6 | 10 | GND | GND | |
| 3V3 | 3.3V | 7 | 9 | 5V | 5V |
Bei Verwendung von Ethernet sind durch die vielen vom W5500 Modul belegten Pins allerdings nur wenige Shields direkt nutzbar. I2C-basierte Shields und solche mit maximal 3 I/O Pins können jedoch an W2 angeschlossen werden über IO4, IO20 und IO21 (bspw. über ein Dupontkabel).
Weiterführende Links
Hier sind einige Links, die zum Thema beitragen, bzw. Basisinformationen und Grundlagen enthalten: