Welcome to eBUS Adapter Shield v5!

This is the documentation of the eBUS Adapter Shield v5, which can be used to communicate with an eBUS enabled heating, ventilation or solar system.

You can reserve the current adapter here and it will then be sent in sequence as soon as the next batch is available.

Introduction

Version 5 of the eBUS adapter is a redesign of v3.1 with a significantly smaller footprint (37x26mm), pluggable eBUS connection, on-board WIFI due to changing to ESP32-C3, support for different Ethernet modules, and compatibility with many D1 mini shields (therefore the name “eBUS Adapter Shield”).

The adapter fulfils the arbitration times required by the eBUS specification just like v3.1 and v3.0.
This is made possible by the use of an ESP32-C in RISC architecture which, among other things, brings the following advantages:

By using a DC-DC converter and galvanic isolation of the signals the eBUS is completely isolated from the host and only marginal current is drawn from the eBUS without any fluctuation (class 0 according to specification chapter 10.7).

This way, the heating, ventilation or solar system is perfectly protected and is not burdened in any way on its own power source.

Connections

This is an overview of the individual components and their connections:
schema

Host connection

Connecting via USB, WIFI, and Raspberry Pi is always possible. Only the Ethernet connection requires an additional W5500 module.

By using the easi> interface (via USB or network) all parameters can be adjusted.

Upon delivery, the firmware might need to be installed first, see under first steps.

The protocol between ebusd and the adapter is either the eBUS protocol directly (“standard protocol”) or the ebusd “enhanced protocol”. The enhanced protocol uses all advantages of the adapter by handling the eBUS arbitration directly from the ESP32 firmware.

USB

USB
To use the adapter via USB, it just needs to be connected with the host using the USB connector.
All modern operating systems (Windows/Linux/MacOS) already have the necessary driver for that.

The adapter provides two interfaces on USB, that are presented as product “USB JTAG/serial debug unit” (idProduct: 0x1001) of “Espressif” (idVendor: 0x303a):

By using the easi> interface, the host connection is set to USB.

In addition to the adapter, only a regular USB data cable with a Micro-B plug is needed. The adapter comes with an eBUS connector already plugged in.

The power is supplied directly via the USB connector.

The ebusd device configuration is e.g. -d ens:/dev/ttyACM0, where ttyACM0 might be different when several USB devices of this kind are connected.

WIFI

WIFI
To use the adapter via WIFI, it just needs to be connected to a power source using the USB connector.

By using the easi> interface, the host connection is set to WIFI. It can also be used to adjust the WIFI configuration (SSID, DHCP/fix IP address, network mask, gateway).

In addition to the adapter, only a regular USB cable with a Micro-B plug is needed. The adapter comes with an eBUS connector already plugged in.

The power is supplied directly via the USB connector, but it can also be powered via the pins on the socket W2, e.g. by using a DC Power Shield. See power source for details.

The ebusd device configuration is e.g. -d ens:192.168.178.2:9999, where 192.168.178.2 has to be replaced with the right IP address.

Raspberry Pi

RPI
When flipping the adapter upside down, it can be plugged onto a Raspberry Pi.
Care must be taken here, that the socket closer to the hole (on the bottom left in the picture) is plugged into pin 2 of the Raspberry Pi GPIO headers, so that the hole is exactly above the one of the Raspberry Pi and a spacer could be placed in between.

When the adapter is plugged in (shown in red here for better visibility), it looks like this:
RPI+Adapter Front

By using the easi> interface, the host connection is set to Raspberry Pi. The firmware also detects this itself when booting and already configures the adapter accordingly.

For Raspberry Pi 5, an additional note must be taken into account for older adapters.

In addition to the adapter, only a stacking header might be needed in case the Raspberry CPU has a cooler on it. The adapter comes with an eBUS connector already plugged in.

The power is supplied directly via the Raspberry Pi GPIO socket.

The ebusd device configuration is: -d ens:/dev/ttyAMA0 --latency=50

Details on setting up the Raspberry Pi can be found here.

Ethernet

Ethernet
To use the adapter via Ethernet, the following options are available:

Attention: when the W5500 module is not correctly plugged onto the adapter (e.g. shifted or in the wrong direction), the adapter can be damaged and become unusable! So the best way it to disconnect power, plug in the module, and check the position. After that, power can be reconnected.

When a USR-ES1 modules is plugged in, it looks like this:
Ethernet Front Ethernet Side

By using the easi> interface, the host connection is set to Ethernet. It can also be used to adjust the Ethernet configuration (DHCP/fix IP address, network mask, gateway).

If the W5500 module cannot be detected by the firmware, it might be broken or ideally only the pin connection is not stable. See here for checking this.

In addition to the adapter and the Ethernet module, only a regular USB cable with a Micro-B plug is needed. The adapter comes with an eBUS connector already plugged in.

The power is supplied directly via the USB connector, but it can also be powered via the pins on the socket W2, e.g. by using a DC Power Shield. See power source for details.

The ebusd device configuration is e.g. -d ens:192.168.178.2:9999, where 192.168.178.2 has to be replaced with the right IP address.

Power Source

When using Ethernet or WIFI as the host connection, the adapter is simply powered via the USB connector using a standard USB power adapter, e.g. one that can also be used to charge a cell phone.

The minimum requirement for the power source is 1 Watt. To be on the safe side, we recommend using a power source with at least 2 Watts, i.e. capable of supplying 400mA at 5V.

Alternatively, the adapter can also be powered via the pins on the socket W2, e.g. by using a DC Power Shield.

Pin headers, functions

Additional pin headers are available for connecting further components. With Ethernet only a small number of pins are available for that.

Connector Function 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 3 I/O
USRL W5000 / Raspi - - Raspi W5500
EBUS eBUS connector eBUS eBUS eBUS eBUS

Legend:

Pins

The easi> interface can be used to associate a pin with an I/O function.

I/O pinout

The ESP32-C3 I/O pins are associated and available on headers as follows:

IO Function / Header/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, 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

Legend:

LEDs

The adapter has 3 LEDs with the following assignment:

During boot all LEDs fade 3 times. In that phase, pressing the button allows to ignore all saved settings and start the WIFI access point with SSID “EBUS”.

In eBUS mode, the blue LED blinks shortly every 5 seconds as a ping, when configured like that via easi> interface.

The green and red LEDs light up on the corresponding eBUS traffic, when eBUS mode is on and configured like that via easi> interface.

Button

The adapter has a button on board allowing several actions:

In general, the button can be used to check the power supply as well, as pressing it will power on the blue LED independant of the ESP I/O.

Additional functions

Many of the D1 mini Shields are compatible with the adapter and can simply be plugged in. The pin on the top left of such a module is intentionally left out and will “hang out”, so the module needs to sit exactly on the 8 pins of the header W2 and is thus shifted by one pin on W1.

The following shields are usable:

(*) planned for a future firmware version

The association of the ESP32-C3 pins with the Wemos / shield ports D0-D8 + A0 is this:

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

Due to the many pins occupied by the W5500 module, with Ethernet onlya some shields are usable directly. I2C-based shields and those with at most 3 I/O pins can be connected to W2 via IO4, IO20, and IO21 (e.g. via Dupont cable).

Here are some links that contribute to the topic or contain basic information: