How to install EMS-ESP

What is EMS-ESP?

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

EMS-ESP requires a small additional circuit to interface between the EMS bus line an the microcontroller. This circuit is available as a pre-built module from BBQKees Electronics, or can be built from a schematic provided in the documentation.

For more information on EMS and the EMS-ESP software read the Documentation.

Flashing the firmware to your device

There are a number of ways to install the firmware on your ESP32 device:

1. Using the EMS-ESP Flash Tool. This is a native application for Windows, MacOS and Linux/Ubuntu. Your ESP32 device needs to be psychically connected to your computer via the USB or Serial port.
2. Using the EMS-ESP Web Installer which is an online installer supporting 16MB/PSRAM variants that requires the EMS-ESP device to be connected via the USB/Serial port.
3. Using EMS-ESP directly from the WebUI Settings page to automatically detect and install the latest version (v3.7 onwards).
4. Using a copy of the EMS-ESP CLI Installer command line tool. This is Unix based, so does not support Windows (unless using WSL2).
5. Building and uploading directly from the source code using PlatformIO. Follow the build instructions in the EMS-ESP documentation.

Choosing the right firmware version

There are pre-built firmware binaries for the ESP32 and ESP32-S3 chips sets. There are variations of these based on the allocated flash size (4MB, 16MB) and whether the board has additional PSRAM present. For other chip sets, such as the ESP32-C3, the firmware can be manually built from the source using PlatformIO.

You can choose either to use the current Stable or latest Development version. The Stable versions are typically updated within a few months, or patched when a critical issue is found. The Development versions (with the word dev in the filename) are updated more frequently, but may contain bugs. This is recommended for advanced users who want to test out new features. You can switch from Stable to Development at any time via the EMS-ESP Web interface.

Upgrading from versions prior to v3.7

It is always recommended to upgrade to the latest version of the firmware. If you are upgrading from a version prior to v3.7 (v3.6.4 or v3.6.5) then make a backup of your configuration settings first before upgrading in case the flash process fails. This can be done via the EMS-ESP web interface. If you run into any issues using one of the Flashing methods described above then ‘flash erase’ the EMS-ESP and start over with a fresh install, and then upload your saved settings. If you are upgrading from v3.7 or later, then you can safely upgrade without needing to backup your configuration settings.

How the firmware binary files are named

The firmware filename format used is:

EMS-ESP-<version>-<chipset>-<flashsize>[+].bin

where <chipset> is ESP32 or ESP32S3 and <flashsize> either 4MB or 16MB. The + indicates that the firmware is built to use any additional RAM (called PSRAM) if available.

Determine the correct type of your ESP32 device and download the latest stable version of the firmware using the table below. If you’re not sure which firmware to use contact us.

If using a BBQKees Electronics Gateway board, follow this guide to ensure you are select the correct firmware:

Problems installing the firmware?

Questions or Feedback?