General information

Thank you for purchasing an EMS Bus Gateway!
Now that you received your Gateway, it's time to integrate it into you home automation system.
On this page you can find all instructions to do so.
Keep in mind these instructions are an ongoing work in progress and there might be significant differences between firmware versions
F.i. firmware version 1.8.1b10 has added a webserver to make some initial configurations without the use of Telnet.


Compatibility

Boiler compatibility

The interface is electrically compatible with all Bosch brand boilers, heat pumps and devices that have an EMS, EMS+, EMS2, EMS Plus, Heatronic or Heatronic 3 interface. Sometimes the bus is also named f.i. 2-wire bus.
Bosch brand boilers include f.i. Bosch, Buderus, Nefit, Junkers, Sieger and Worcester.
I cannot guarantee that the interface will work with your specific boiler. Check before purchasing whether your boiler has an EMS compatible bus.

EMS bus device (thermostat) compatibility

Support for thermostats and other EMS bus device like mixer modules is firmware dependant.
Please consult Proddy's Github repository for the list. New devices are added all the time.

Connecting to the boiler

Main method - service jack

EMS Bus Gateway on boiler With the supplied jack cable you can plug in the gateway to the service jack of the boiler. This is usually located on the front.
Then stick the gateway to the metal side of the boiler. The underside of the case is magnetic.
The entire device including the Wemos is powered via this service jack. So no additional power supply needed. Just the jack cable is all you need.
It's important that you first plug in the cable to the gateway and then into the boiler. Otherwise you momentarily shortcut the bus when inserting the cable into the jack of the gateway.


Alternative method - EMS/thermostat wires

Gateway screwcon If your boiler does not have a service jack or it does but you want to mount the EMS Bus Gateway elsewhere you can use the screw terminal to connect to the two EMS bus wires. This can be in parallel with the thermostat or from inside the boiler.
In this case you can't use the buck converter. Remove it from the board. You need to power the device by plugging in a USB power supply directly to the Wemos.

To use the screw terminal remove the top of the case to access the screw terminal by unscrewing the four case screws on the bottom.
After you have connected the EMS bus wires and are sure it works properly you can screw the case top back again. Do not connect both the jack and the EMS wires via the screw terminal at the same time!

First boot -> Check the LED

Firmware version until and including 1.8.1b2
If you plug the gateway into the boiler, the on-board LED of the Wemos will start blinking. You first need to add the Gateway to your home network.
Please see 'Firmware and configuration'. If you don't see any LED, go to 'Troubleshooting'.

Firmware version above 1.8.1b2
If you plug the gateway into the boiler, the on-board LED of the Wemos will start blinking fast for the first few seconds. Then it will start to blink slow as a sign its looking for the EMS bus. As soons as it has discovered the EMS bus, it will light up solid.

If it lights up solid, then go to 'Firmware and configuration'. If you don't see any LED or it keeps blinking, go to 'Troubleshooting'.

Firmware and configuration

The Wemos comes preloaded with stable firmware from the great Proddy's Github repository so you have a working setup using MQTT.
On first boot the Wemos will create an access point on which you can login with Telnet and make the appropriate settings for your own network. So for this kit you don't need any soldering or real programming skills. You do however need to properly configure your home automation system.
The latest firmware versions (>1.8.1b2) have a built in web interface as well.

The firmware will enable communication via MQTT. The MQTT format of the messages is tailored to Home Assistant.

First boot

The setup procedure below is written for firmware version up to 1.8.1b2. For most later versions you do not need to use Telnet for the initial setup but use the webinterface on the IP address of the Gateway.

To setup the Gateway and integrate it with your home automation system, you need a laptop or other computer with a Telnet client like Putty. You can f.i. also use the app JuiceSSH on your Android phone or tablet.

If you plug in the Gateway the LED should light up solid after it has found your home network and the bus.
If it does, congratulations; the Gateway has found the EMS bus and is able to communicate with it.
It it does not, go to the troubleshooting section below first.

The Gateway sets up its own Wi-Fi network called 'ems-esp'. Connect to this network with a laptop.
Keep in mind as soon as you are connected to the ems-esp network, you cannot access the internet with the laptop.
Open Putty or your own Telnet client and start a Telnet session to IP address 192.168.1.4 (Telnet works on port 23, its NOT the same as SSL which works on port 22!).

You will now see a screen that resembles the following one:
Telnet main interface

At this point the Putty window is likely too small so resize the width to fit all information on a single line.

Settings you need to configure


Connect the Gateway for your home network

The first thing you want to do now is to set the Wi-Fi SSID and Wi-Fi password of your own home network.
type in 'set wifi_ssid xxxx' and 'set wifi_password xxxx'. So if your Wi-Fi SSID is 'home-wifi' and the password is '123456', type in 'set wifi_ssid home-wifi' and 'set wifi_password 123456'.
Now reboot the Gateway by typing in 'reboot' or by unplugging it from the jack (and/or disconnect the UBS power) and plug it in again.
The Gateway will now try to connect to your home network. If successfull, you need to figure out the IP address it got from your home router.
Either log in to your router and look up the IP address or use f.i. the app 'Fing' on an Android phone to find the Gateway in your network.
Compare the MAC address you wrote down with any entry in the router list.
If you use Fing, the device will show as an 'Espressif' device with host name 'ems-esp'.
When you found the IP address of the Gateway you can start a new Telnet session to the Gateway.
Set a static IP address for the Gateway in your router. Sometimes this is also called a DHCP reservation.
This is necessary later on so that the home automation system will always be able to find the Gateway.


Set serial off

For most firmware versions you need to manually turn off the debug serial port, otherwise it cannot find the EMS bus. Use 'set serial off' and 'reboot'.

Set the correct MQTT host

The Gateway will communicate with your home automation system via MQTT. You need to tell the Gateway what the IP address is of the MQTT broker of your system.
Usually, but not always, this is the same IP address as your home automation system.
Use 'set mqtt_host xxxx' to set it. F.i. if you run Home Assistant on a Raspberri Pi with IP address 192.168.0.69 type in 'set mqtt_host 192.168.0.69'. Optionally use 'set mqtt_username' and 'mqtt_password' if your MQTT broker demands authentication.

If everything went well, typing in '?' will show 'MQTT is connected'. If it doesn't, go to the troubleshooting section.

Other settings

Type in 'log v' so the logging is set to verbose and you can see the communication on the bus.
Text color of the bus communication should be mostly white, green, blue and orange and some occasional red.
If you have red all the time or there is nothing at all, the Gateway has problems communicating with the bus or there is an unknown protocol on the bus.

Telnet verbose logging

If its not all red, type in 'log n' to turn off the logging and then 'system'. Make a note of the Wi-Fi MAC address that is shown and continue below.

Play around in the Telnet interface. There is a lot to see.
In any case type 'info' for EMS status information. Very informative.
Type in '?' for help, 'system' for lots of sexy system info or 'set' for all possible settings configurable via Telnet.
The firmware has more available settings but these can only be changed when you build the firmware yourself.


Configuration for Home Assistant

Home Assistant logo MQTT communication in the firmware is preconfigured for Home Assistant. Please follow the instruction in Proddy's Github repository to integrate the EMS ESP interface to Home Assistant.

Configuration for Domoticz

domoticz logo For Domoticz you need to use NodeRed see f.i. this topic and as an alternative a beta plugin is also available. This plugin will generate the thermostat control and two sensors.
The plugin will be expanded soon with new sensors etc.

Using the plugin

On the first run the plugin will create several devices and sensors in Domoticz.
The plugin then subscribes and publishes to the default MQTT topics of the Gateway.
The plugin captures the messages and updates the Domoticz devices and sensors automatically.
Currently only 3 devices are created, this will be expanded soon.

Configuration for other (home automation) systems

If your home automation system is capable of communicating via MQTT, you can always in some way integrate the Gateway into your own system.
The default MQTT format of the Gateway is described here.
Even if your system does not support MQTT natively, you can also use a stand-alone MQTT broker like Mosquitto together with NodeRed to create your own interface.

Stand alone use of the Gateway

Its also possible to use the Gateway stand alone via Telnet. You could create your own bash scripts which will retrieve data or send commands via Telnet sessions to the Gateway.

Firmware support

The firmware is not my own but a very frequently updated open source project maintained by others. Because I can't keep up with all the intricate details of the code, support by me is limited to general questions. For all technical questions and issues please refer to the repository itself.

Firmware updates

Firmware can be updated. For instructions see Proddy's Github repository.
OTA (Over The Air) upgrades are also possible, so you don't need to connect the Gateway to a pc via USB.
Keep in mind development versions of the firmware might be unstable or default settings might have changed.

Troubleshooting

Gateway plugged in to service jack but...

...no LED at all

If the LED is always off, there either is no power or the Wemos firmware is wrong, corrupt or has a wrong setting.

  • No power on the Service jack -> Plug in a USB power adapter to the Wemos directly. The LED should start blinking now.
  • Buck missing or broken -> Plug in a USB power adapter to the Wemos directly. The LED should start blinking now.
  • You are shortcutting the bus or the jack. -> unplug the Gateway and wait 2 min before plugging it back in.
  • You are drawing too much current from the bus. -> Unplug the Gateway, remove all external components and and wait 2 min before plugging it back in.
  • No firmware or firmware update error -> Reload a stable firmware image.
  • LED is turned off in the firmware settings -> Log in with Telnet and turn it on.

...LED keeps blinking forever

If the LED keeps blinking forever this means it cannot find the EMS bus.

  • Boiler with no EMS bus -> The Gateway is only compatible with the EMS bus.
  • EMS wires not connected or faulty -> Reconnect the jack cable or otherwise connect the screw terminal of the Gateway to the thermostat wires.
  • The board is running in Serial mode -> This will be shown in the telnet session and you can use 'set serial off' to disable it.

...LED turns solid but start blinking again after a while.

In this case the EMS bus was found at some point, but due to either intermittency problems the communication was lost.

  • Bus wires not connected properly -> Reconnect the EMS bus wires.
  • Perhaps the Wemos is not getting enough power and is rebooting. -> Remove external components and try again.


...LED is blinking or is solid but cannot connect with Telnet.

This is likely caused by network communication issues.

  • You are not Telnetting to the right IP or not on port 23 -> Change to the IP address of the Gateway and to port 23.
  • Your laptop with Telnet is not on the same network as the Gateway -> The Gateway should be on either your home network or it is in access point mode. In the latter case connect your laptop to the 'ems-esp' Wi-Fi network.
  • You are trying to visit the IP of the Gateway via a browser -> The Gateways with firmware up to V1.8.0 have no web interface. This won't work. Use Telnet.


Gateway connects to home network but MQTT is not connected

There can be a range of issues.

  • Wrong IP -> Set the correct IP of your MQTT broker. This is not always the same IP address as your home automation system.
  • Wrong user/password -> Make sure the MQTT authentication is set right or not at all.
  • Wrong port -> the MQTT port is 1883 by default. If you need to change this you have to build the firmware yourself.
  • MQTT broker is not running -> Make sure the broker is running on the target machine.
  • MQTT broker is not installed -> Install a MQTT broker like Mosquitto on the target machine.


MQTT is connected but seemingly no response

  • You are listening or publishing to the wrong MQTT topics.


Modular design

To provide maximal flexibility and serviceability both the buck power converter and the Wemos are mounted on a header so they can be easily removed or exchanged in case of failure or upgrade.

EMS ESP kit
EMS Bus Gateway full kit with opened case
EMS ESP kit main components
EMS Bus Gateway main components

Wemos D1 mini connector

On the right side of the board you can find the header used for Wemos D1 Mini. Included is the Wemos D1 Mini V2. You can use other pin-compatible Wemos or ESP8266 devices if needed like the Wemos D1 Mini V3 or the Wemos D1 Mini Pro V1.1.

Also if you need to improve the WiFi reception you can replace the existing Wemos with a Wemos D1 Mini Pro V1.1 together with an external antenna. On this Pro you need to move the 000 resistor to the side of the external antenna, otherwise the internal antenna will be used.

Buck power converter

In the middle of the board connector J13 is the header for a buck power converter. If you buy a complete kit a suitable stress tested buck is already installed.
This buck will step down the 8 to 12 Volts on the service jack to 5 Volt as the source for the Wemos board. The internal voltage regulator of the Wemos will then deliver 3.3V for the entire board.

The pinout of the header is 5V output, GND, VIN from the jack and the most right pin is not connected to anything. So if you have a standard 3 or 4 pin buck it will fit.
Because almost all buck converters have the same pinout you can exchange the existing buck for another one.
The board has f.i. also been tested with several Polulu bucks.
Although the supplied buck will work just fine in most cases, for critical setups you could replace the buck with a Pololu D24V22F5 or D24V5F5.

Board headers

EMS ESP kit headers

EMS ESP kit headers

Connecting external DS18B20 sensors

JST connector pinout On the right side of the board below the Wemos you can find a 3-pin 2.5mm pitch JST XH connector.
This connector is intended for adding Dallas type DS18B20 1-wire temperature sensors.
The Dallas sensors supported are DS1822, DS18S20, DS18B20, DS1825 including their parasite varieties.
If you purchased a complete kit a JST cable is included. If you need to source this cable yourself then look for RC car battery cables. These are usually the same ones.

Gateways < V1.0: When seen from the front the left pin is GND, the middle pin goes to D5 of the Wemos and the right pin is 3V3.
Gateways > V1.0: When seen from the front the left pin is D5, the middle pin goes to GND of the Wemos and the right pin is 3V3.
A 4k7 pull up resistor is already on the board.
For Gateways < V1.0: If you use the supplied JST cable, please be advised the 3 wires do not color match general waterproof DS18B20 sensor wires!

For most cases the pull-up on the board is sufficient.
However, if you connect too many sensors or the wires are very long, the pull-up resistor value will be to high. You need to add a through hole resistor on position R20 (also below the Wemos). This optional through hole resistor is routed in parallel to the 4k7 resistor.
Recommended in that case is to use a 4k7 resistor, so the final resistor value will be 2k3.
If you don't have the equipment or skills to solder the resistor, you can also insert the resistor in a screw connector like below.
You can solder one or more DS18B20 sensors to the JST cable or use f.i. a screw terminal.
Please be advised (waterproof) DS18B20 sensors from AliExpress etc are often fake and will have an offset of sometimes 2 degrees Celcius.

Additional non-populated internal connectors

Headers J15 and J16

For Gateways < V1.0: J15 is a single pin connected to GND and J16 is a two pin header connected to 5V and GND.
These pins can be used to add f.i. a 19mm supercap.
For Gateways > V1.0: J16 is a three pin header and is connected to the EMS+ line via diode D7 and the other pins are connected to 5V and GND.
The diode is not mounted. This pin is intended for doing measurements on EMS+ directly, or f.i. to draw power from the bus itself.
If you want to do measurements on EMS+, solder a wire or an 0805 000 (zero Ohm) resistor on D7.
If you want to draw power from the bus then solder a diode on D7. Footprint is for MiniMELF diodes.

Headers J20 and J18

J20 is a single pin connected to 3V3 and the adjacent connector J18 is connected to GND, Wemos TX, Wemos RX, Wemos D2 and Wemos D3.

Header J19

J19 is a three pin connected to GND, Wemos D0 and Wemos A0.

Header J21

Only on Gateways > V1.0: J21 is a two pin connected to GND.

On board LED footprints

Below the Wemos there is an additional parallel footprint for either a 0805 SMD or a 3mm throughhole LED.
These footprints are both connected in series with the same resistor R18 to pin D1 of the Wemos so you can use either the SMD or the through hole footprint.
For Gateways < V1.0: One side is connected to GND. Be advised the ESP can only source 12 mA on I/O pins.
For Gateways > V1.0: One side is connected to 3V3. Be advised the ESP can only sink 20 mA on I/O pins.

Available power and voltages on the board

Power flow

If you connect the board via the service jack, the power for the board is sourced from the jack itself. For most boilers the output voltage is 8V, but for some it can be around 12V.
This 8V is fed into the buck power converter. The buck converter can handle between 6,5V and 24V input to provide a 5V output.
The 5V output from the buck is fed to the Wemos 5V input. It is also available on header J16.
The on-board LDO voltage regulator of the Wemos will then down convert the 5V to 3.3V.
This 3.3V is used to power the entire board.
The 3.3V is also available on header J20 and on the JST connector for the temperature sensors.


Maximum power draw

When powered from the jack, the current eventually flows back via a polyfuse to the EMS- line.
This polyfuse is rated for a continuous current of 200mA and they trip at 400mA.
Other components in the circuit are also rated for a 200mA continuous current. As the Wemos is also power hungry by itself, there is not much power available for external components. So while it is possible to add external components to the 5V and 3.3V pins, make sure it does not exceed the design limitations of the board.
If you want to measure the total current yourself, add a current meter between the GND pin of the buck and the header it sits on.

Raspberry Pi / Arduino mod

If at some point you want to interface with a Raspberry Pi / Arduino etc instead of the on board Wemos this is possible.
You can still use the jack connector or the screw connector, but the buck converter will lose its function. So remove it.
Now remove the Wemos and connect 4 wires like below:

RPi modRPi mod
You can still use the enclosure and route the wires through the hole in front of the JST connector. Now the JST connector has no function anymore.

Ordering information and availability

You can buy several versions of the EMS Bus Gateway on the ordering page here.
Availability of the new design is spotty at the moment as I need to soure more components from different suppliers and assemble by hand and test everything.