ESPHome Altherma

A native ESPHome custom component for monitoring Daikin Altherma 3 heat pumps via the X10A connector. It exposes temperatures, voltages, currents, and other operational data directly to Home Assistant. No MQTT, no manual config, just plug and play.

🌐 Web Installer · 💬 HA Community · 🗨️ Discussions · 📖 Emoncms Setup Guide

M5Stack Basic running ESPHome Altherma

ESPHome Altherma with real-time data in Home Assistant

ESPHome Altherma + Emoncms and My Heatpump App

Quick Start

Open the Web Installer in Chrome/Edge
Connect your ESP32 via USB and click Connect
Flash the firmware and configure Wi-Fi
The device appears automatically in Home Assistant 🎉

No command line needed. See Installation for more options.

Features

Real-time sensor data - temperatures, voltages, currents, flow rates, pressures, fan speeds, and more
Model-specific configuration via modular YAML files for different Altherma units
Multiple board support - ESP32, ESP32-S3, and M5Stack AtomS3 Lite
Browser-based installation via ESP Web Tools (no command line needed)
OTA updates with automatic update checking via GitHub releases
Mock UART mode for development and testing without hardware

Supported Boards

Board	YAML Config	UART RX Pin	UART TX Pin
ESP32 DevKit	`esphome-altherma-esp32.yaml`	GPIO 16	GPIO 17
ESP32-S3 DevKit	`esphome-altherma-esp32-s3.yaml`	GPIO 2	GPIO 1
M5Stack AtomS3 Lite	`esphome-altherma-atoms3.yaml`	GPIO 2 (G1)	GPIO 1 (G2)

Hardware Requirements

ESP32 development board (ESP8266 may also work)
Daikin Altherma heat pump with X10A connector
5-pin JST EH 2.5 mm connector or 4 Dupont M-F wires

Wiring

Connect the ESP32 to the Altherma unit using the X10A connector:

X10A Pin	Signal	ESP32 DevKit	M5Stack AtomS3 Lite / ESP32-S3
1	5V	5V / VIN	5V
2	TX (pump → ESP)	RX pin (GPIO 16)	RX pin (GPIO 2)
3	RX (ESP → pump)	TX pin (GPIO 17)	TX pin (GPIO 1)
4	NC	Not connected	Not connected
5	GND	GND	GND

Note: The heat pump's TX connects to the ESP's RX, and vice versa (crossover).

Refer to the ESPAltherma wiring guide for additional details and photos.

Successful Installs

Board	Heat Pump	User	Additional info
Generic esp32dev board	ERGA08DAV3 / EHVH08S23DA6V	@jjohnsen	This repo ;)
M5-Stack Basic	ERGA08DAV3 / EHVH08S23DA6V	@jjohnsen	This repo ;)
M5Stack AtomS3 Lite	DAIKIN Altherma 3 R Ech2o / EHSXB08P30EF	@maromme	#4
DOIT ESP32 DEVKIT V1	EHVX08S26CB9W	@MaBeniu	#5
esp32dev	ERLQ011CAV3 / EHBX11CB9W		Detailed setup guide in French
ESP32-C6-WROOM-1	EHBH16C9W	@AndriesMuylaert	Includes relay + onboard sensors - #11

Installation

⚠️ Note: This repo currently includes sensor mappings for the ERGA-D EHV/EHB/EHVZ DA series (04-08kW) and the ERLA D EBSH-X 16P30-50 D series 11-16kW-ECH2O. Contributions for other models are welcome!

Option 1: Browser Install (ESP Web Tools)

The easiest way to get started - no tools to install.

Open https://jjohnsen.github.io/esphome-altherma/ and click Connect
Follow the guided process to:
- Flash the firmware
- Connect to Wi-Fi
- Add the device to Home Assistant

OTA Updates are available within Home Assistant:

Option 2: Command Line (ESPHome CLI)

Install ESPHome

Clone this repository:

git clone https://github.com/jjohnsen/esphome-altherma.git
cd esphome-altherma

Configure Wi-Fi credentials in secrets.yaml:

wifi_ssid: "YourWiFiSSID"
wifi_password: "YourWiFiPassword"

Connect your ESP32 via USB and flash:
```
esphome run esphome-altherma-esp32.yaml
```
After the initial flash, subsequent updates can be done wirelessly (OTA)

Configuration

Model Files (`confs/*.yaml`)

Model files define the available sensors for specific Altherma units. Each sensor entry specifies the UART register, byte offset, data size, and converter ID used to decode the value.

Available models:

erga_eh_da_04_08.yaml - ERGA-D EHV/EHB/EHVZ DA series (04-08kW)
erla_d_ebsh_11_16_ech2o.yaml - EBSXB16P50DF / ERLA D EBSH-X 16P30-50 D series 11-16kW-ECH2O

Community-contributed models:

EHVX configs by @MaBeniu

Board-Specific Files

Choose the YAML file matching your board:

esphome-altherma-esp32.yaml - Generic ESP32
esphome-altherma-esp32-s3.yaml - ESP32-S3 DevKit
esphome-altherma-atoms3.yaml - M5Stack AtomS3 Lite

Each includes base.yaml (shared component setup) and the model config from confs/.

Guides

ESPHome Altherma + Emoncms Setup Guide
Long-term heat pump performance monitoring with the MyHeatpump dashboard in Home Assistant. Covers Emoncms installation, input/feed setup, and COP tracking.

Register Discovery (Experimental)

⚠️ This is an experimental feature, use at your own risk.

The component exposes a query_register Home Assistant action (service) that lets you query any register directly. This is useful for exploring what data your specific heat pump model supports, which you can then turn into proper sensor definitions.

Action Parameters

Parameter	Type	Description
`register`	string	Register address as a hex (`0x60`) string
`offset`	int	Byte offset within the register payload (0-based)
`convid`	int	Converter ID from `converters.h`, determines how bytes are decoded
`datasize`	int	Number of bytes to read for decoding

The result is published to the Manual Query Registry Result text sensor and also appears in the ESPHome device logs.

Example: Home Assistant action call

action: esphome.esphome_altherma_query_register
data:
   register: "0x60"
   offset: 11
   convid: 105
   datasize: 1

Interpreting the result

The Manual Query Registry Result sensor updates after every call and shows one of:

Manual query accepted reg=0x.. offset=.. convid=.. datasize=..: query queued
Manual query result reg=0x.. value=.. buffer=..: success, with decoded value and full raw frame as hex
Manual query failed reg=0x..: <reason>: failure with cause (timeout, CRC invalid, out-of-bounds, etc.)
Manual query rejected: <reason>: invalid parameters, not sent to device

Development

Setting Up a Dev Environment

python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install esphome
esphome compile esphome-altherma-esp32.yaml

Mock UART Mode

For development without physical hardware, enable mock UART mode by adding the build flag:

esphome:
  platformio_options:
    build_flags:
      - -DUSE_MOCK_UART

This provides simulated register responses so you can test the component logic without an actual Altherma connection.

Project Structure

base.yaml                          # Shared ESPHome config (logger, API, OTA, UART, hub)
esphome-altherma-esp32.yaml        # Board config: ESP32 DevKit
esphome-altherma-esp32-s3.yaml     # Board config: ESP32-S3
esphome-altherma-atoms3.yaml       # Board config: M5Stack AtomS3 Lite
confs/
  erga_eh_da_04_08.yaml            # Sensor definitions for ERGA-D series
  erla_d_ebsh_11_16_ech2o.yaml     # Sensor definitions for ERLA D EBSH-X 11-16kW-ECH2O
components/altherma_hub/
  __init__.py                      # ESPHome component definition (Python)
  altherma_hub.cpp                 # Hub implementation (C++)
  altherma_hub.h                   # Hub header
  sensor.py                        # Sensor platform
  binary_sensor.py                 # Binary sensor platform
  text_sensor.py                   # Text sensor platform
  mock_uart.h                      # Mock UART for testing
  lib/
    converters.h                   # Vendored from ESPAltherma
    labeldef.h                     # Vendored from ESPAltherma

Vendored ESPAltherma Files

This project vendors selected files from ESPAltherma:

Source File	Local Path
`include/converters.h`	`components/altherma_hub/lib/converters.h`
`include/labeldef.h`	`components/altherma_hub/lib/labeldef.h`

To update vendored files from upstream:

# Add ESPAltherma as a remote (one-time setup)
git remote add espaltherma https://github.com/raomin/ESPAltherma.git

git fetch espaltherma
git checkout espaltherma/main -- include/converters.h
git checkout espaltherma/main -- include/labeldef.h

git mv -f include/converters.h components/altherma_hub/lib/converters.h
git mv -f include/labeldef.h components/altherma_hub/lib/labeldef.h

git commit -m "Update ESPAltherma vendored files"
rmdir include

Contributing

Contributions are welcome! In particular:

Sensor mappings for other Altherma models - add a new file under confs/ with the register definitions for your unit
Bug reports and fixes - open an issue or pull request

If you have a successful install with a model not listed above, please share it in the Discussions.

License

This project is provided as-is for educational and personal use.

Please respect the licenses of the dependencies:

ESPAltherma files are subject to their original license
ESPHome is licensed under the MIT License

Credits

Based on ESPAltherma by raomin
Built with ESPHome
Integrates with Home Assistant

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ESPHome Altherma

Quick Start

Features

Supported Boards

Hardware Requirements

Wiring

Successful Installs

Installation

Option 1: Browser Install (ESP Web Tools)

Option 2: Command Line (ESPHome CLI)

Configuration

Model Files (`confs/*.yaml`)

Board-Specific Files

Guides

Register Discovery (Experimental)

Action Parameters

Example: Home Assistant action call

Interpreting the result

Development

Setting Up a Dev Environment

Mock UART Mode

Project Structure

Vendored ESPAltherma Files

Contributing

License

Credits

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

ESPHome Altherma

Quick Start

Features

Supported Boards

Hardware Requirements

Wiring

Successful Installs

Installation

Option 1: Browser Install (ESP Web Tools)

Option 2: Command Line (ESPHome CLI)

Configuration

Model Files (confs/*.yaml)

Board-Specific Files

Guides

Register Discovery (Experimental)

Action Parameters

Example: Home Assistant action call

Interpreting the result

Development

Setting Up a Dev Environment

Mock UART Mode

Project Structure

Vendored ESPAltherma Files

Contributing

License

Credits

Model Files (`confs/*.yaml`)