EMS-ESP: an ESP32 bridge onto the heating bus in your boiler

The problem: your boiler's data is on a wire nobody documents

EMS-ESP is open source firmware for the Espressif ESP32 microcontroller to communicate with EMS, Energy Management System, compatible equipment from manufacturers including Bosch, Buderus, Nefit, Junkers, Worcester, Sieger, elm.leblanc and iVT.

The problem it solves is specific. A modern heating system knows a great deal about itself: boiler temperature, flow and return temperature, pump state, gas or oil consumption, solar circuit output, the curve the thermostat is using. None of that is normally exposed over a network. It sits on an internal bus between the boiler, the thermostat and the other modules, and it is undocumented from the manufacturer's point of view.

This firmware turns that bus into something a home automation stack can consume. The target user is a homeowner or installer with a compatible heating system who wants the boiler data in Home Assistant, and who is comfortable with a small piece of hardware and a bit of wiring. The topic list gives the shape of the community: boiler, bosch, buderus, ems, esp32, heatpump, home-assistant, ht3, mqtt, solar, thermostat, junkers.

The approach is hardware-plus-firmware rather than software-only, and that is the single most important thing to understand before reading further. This is not a device you can install on a Raspberry Pi next to your router. It is firmware for a microcontroller that has to be electrically connected to the bus in your heating system.

The gateway circuit is a hard requirement

The README states the requirement plainly. EMS-ESP requires a small circuit to interface with the EMS bus which can be purchased from bbqkees-electronics.nl, and these gateways are tested thoroughly and certified to work with EMS-ESP.

That sentence carries two commitments. The first is that the hardware is not optional, and not something you can improvise from an ESP32 and a level shifter. The bus is a wired connection into equipment that may sit in a boiler cupboard, and the interface circuit handles the electrical side of talking to it.

The second is that there is a tested reference hardware configuration, and the vendor of that hardware has certified compatibility with this firmware. That is a much stronger position than a project that merely says it might work on the right board.

The support section adds the boundary of that arrangement. If you are using a non-BBQKees EMS gateway, the README says you may need to contact the manufacturer for support. In other words, the compatibility guarantee is tied to specific hardware, and if you have assembled your own interface, you are outside the tested configuration and on your own.

For a reader weighing this project, the honest sequencing is: identify your bus type, confirm the hardware, then look at the firmware. Skipping the first two steps is the most common way to end up with an expensive box on the bench and a boiler that has not been touched.

Which buses and which devices are actually supported

The compatibility list is the specification of what this firmware can talk to, and it is worth reading precisely.

The bus families named are EMS, EMS+, EMS2, EMS plus, Logamatic EMS, Junkers 2-wire, Heatronic 3 and Heatronic 4. Heatronic 3 appears in the project topics as `ht3`, which suggests the Heatronic generation is the one with the most traction in the community.

The device count is the other half. The README claims support for over 120 different EMS compatible devices, and the categories it lists give a feel for the coverage: thermostats, boilers, heat pumps, mixing units, solar modules, connect modules, ventilation units and switches. That range matters because a heating system is a chain of modules, and a gateway that reads the boiler but not the solar controller or the mixing valve gives you half a picture.

The `data/` directory and the two CSV files at the repository root, `dump_entities.csv` and `dump_telegrams.csv`, are the mechanism behind that coverage. EMS devices communicate in what the project calls telegrams, and the firmware maintains a table of known entity definitions so that a raw telegram from a device can be interpreted into a named value with a unit. The `Modbus-Entity-Registers.md` file at the root is the equivalent table for the Modbus side, which is how a Modbus master reads the same values.

The feature list also mentions two extension points: the ability to add your own custom EMS entities, and the ability to expand the system with user-built external modules. So the entity table is extensible rather than fixed, which is the difference between a project that supports a set of devices and one that can be taught a new one.

A web interface, a serial console, and a scheduler

The user-facing side of the firmware has two faces, and both are described in the feature list.

The first is a multi-user, multi-language web interface to change settings and monitor incoming data. The screenshots at the root of the repository show the sections: Settings, Status, Devices, MQTT, Edit and Log. Multi-user matters in a household with more than one person, and multi-language matters because the firmware is localised in 11 languages and every device and sensor can be renamed, which is what makes the interface usable by the people in the house rather than only by the person who installed it.

The second is a console, accessible via Serial or USB or over Telnet, for advanced operations and detailed monitoring. This is the tool you reach for when the web interface does not show what you need, and Telnet access in particular is how you configure a device before it is on your network.

The automation features are the third group. There is a scheduler to automate tasks and trigger events based on data changes, and a notification service to alert you of important events. A scheduler on a heating system is more useful than it sounds, because a heating system has a physical rhythm, and being able to say that a task runs on a schedule or when a value changes is what turns a data feed into control.

The feature that stands out as a genuine piece of engineering is the simulation of remote thermostats. If the firmware can present itself to the heating system as a remote control, you can drive the boiler's target temperature from your own automation logic, rather than only reading what the boiler decided on its own. The `interface/` directory in the tree is where that kind of protocol work lives, and the `dump_telegrams.csv` file is the tool for inspecting the traffic on the bus.

Home Assistant, Domoticz, openHAB, Modbus and MQTT

The integration story is the reason most people would use this project, and the README claims native integration with Home Assistant, Domoticz, openHAB and Modbus, with MQTT underneath.

MQTT is the transport that most of the ecosystem speaks, and the libraries section names the client, espMqttClient, alongside ArduinoJson for the JSON processing and ESPAsyncWebServer with AsyncTCP for the web server. The web UI itself is built on esp8266-react, originally by rjwats, for the core framework, heavily modified, and the console, syslog, telnet and logging are based on the uuid libraries from nomis. A project that names its dependencies this precisely, and says which of them are heavily modified, tells you where to look if something behaves unexpectedly.

The web interface sits alongside a `mock-api/` directory in the tree, which suggests the API the UI talks to is modelled and testable separately from the hardware. That matters for the same reason it matters everywhere else in this article: it means the web layer can be developed and tested without a boiler on the other end of the bus.

The project publishes a live instance of the interface, linked from the documentation, where the interface can be explored in a chosen language after entering arbitrary credentials. The README is clear about the limits of it, noting that what you see is fixed reference data so not all features are operational. Treat it as a way to look at the interface, not as evidence that the scheduler or the console work.

The `test/` directory and the `boards/` directory in the tree point at the other half of the engineering. Boards means the firmware is built for several ESP32 board variants, and the Makefile's SOURCES list shows the code split into `src/core`, `src/devices`, `src/web`, `src/test` and `lib_standalone`, with the MQTT client, ArduinoJson and the uuid libraries compiled in from the `lib/` directory. A separate `lib_standalone/` tree suggests the project also builds without the Arduino layer, which is the kind of thing you need when you want to run the core on a different platform.

Building the firmware and the two supported branches

The README does not put build instructions in the README itself. It points to a Building the firmware guide in the documentation for how to build EMS-ESP from the source code, and the installation guide is a separate page under the same site.

The repository shows what the build is made of. There is a `platformio.ini` at the root, so PlatformIO is the build system, with a local ini file for per machine overrides and a `partitions/` directory for the flash layout. There is also a GNU Makefile, and its header says GNUMakefile for EMS-ESP. The Makefile sets the target to `emsesp` and assembles the source list:

SOURCES := src/core src/devices src/web src/test lib_standalone

The Makefile also has a small piece of engineering in it that is worth noticing. It detects the platform, setting `EXTRA_CPPFLAGS` to `-D LINUX` on Linux and `-D OSX` on Darwin with a couple of warning suppressions, and it sets the parallel job count from `nproc` on Linux and `sysctl -n hw.ncpu` on macOS. A wrapper around the build is used to echo build progress, and the whole thing is written so that a single goal is passed through to a recursive make invocation.

The branches matter for what you install. The default branch is `dev`, and the release list shows a tag named `latest` carrying the title Development Build v3.9.0-dev.18 from 2026-10-11, followed by v3.8.6 from 2026-09-24 and v3.8.5 from 2026-09-22. The last push was on 2026-10-13 and the repository is not archived, so development is fast and the version numbers are dense. If you are installing rather than building, take a numbered release, and read `CHANGELOG.md` and `CHANGELOG_LATEST.md` before you do, because the difference between the `dev` branch and a release is exactly where surprises live.

The repository also carries a `factory_settings.ini` at the root, which is the file that defines the device tree, the defaults for each entity and the sensors, and a `recovery/` directory that suggests there is a documented way back if a firmware write goes wrong.

Two licences, and a project run by volunteers

There is an inconsistency in the licensing information that is worth resolving before you build on this.

The licence field in the project metadata says LGPL-3.0, while the README's own License section states that the program is licensed under GPL-3.0, and the badge in the README points at the LICENSE file. Those are different obligations, and a downstream project that relies on the weaker of the two would be making a mistake. The practical step is to read the LICENSE file in the repository, and to ask the maintainers if the README and the metadata disagree in substance rather than in wording.

What is clear from the README is the character of the project. EMS-ESP was originally created by proddy and is maintained by the ems-esp community, described as an open source project maintained by volunteers whose support is greatly appreciated. Support comes through a Discord server and a Getting Support section in the documentation, and the project also carries a `CONTRIBUTING.md`, a `SECURITY.md` and a `CODEOWNERS`-style ownership structure in the `.github/` directory.

There are also two honest limits to set before you commit. The first is scope: this is a heating bus gateway, and if your system does not speak one of the listed EMS variants, the firmware has nothing to talk to. The second is risk of installation. Connecting a device to a boiler's bus is a physical intervention in equipment that heats your house, and the failure mode of a mistake there is not a broken web page.

The alternative approach, for comparison, is a commercially supported heating gateway with cloud connectivity and a mobile app. The difference in approach is where the control and the data live. This project keeps everything local, publishes the data over MQTT and Modbus to your own automation stack, and needs no vendor account, which is the appeal for a Home Assistant user. The commercial route gives you a supported installation and a warranty, and it gives the vendor a view of your heating data. Which one is right depends on how much of your house's heating system you are willing to own.

Editorial conclusion

Adopt EMS-ESP if you own an EMS or Heatronic compatible heating system, you want its data in Home Assistant or openHAB, and you are prepared to solder a gateway circuit onto the bus, since the firmware covers over 120 device types, simulates a remote thermostat, and ships a scheduler and notification service. Do not adopt it if your boiler does not speak EMS, if you need a commercial support contract, or if you are unwilling to own the wiring. Verify three things first: that your gateway is one of the tested BBQKees circuits, because the README says other gateways may need the manufacturer for support, that your bus variant is in the supported list including EMS2, EMS plus, Logamatic EMS, Junkers 2-wire and Heatronic 3 and 4, and which licence you are actually bound by, because the repository metadata says LGPL-3.0 while the README says GPL-3.0.

Frequently asked questions

Official sources

1. emsesp/EMS-ESP32 on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases