OpenTherm Gateway with ESP32 and Home Assistant

If your boiler supports OpenTherm, an ESP32 can do far more than switch heating on and off with a relay. OpenTherm is a two-wire digital control bus that allows a thermostat or controller to exchange operating data with a compatible boiler.

That can include the requested central-heating water temperature, flame state, burner modulation, boiler flow temperature, return temperature, domestic-hot-water status, system pressure and fault information.

Room temperature / Home Assistant
             │
             ▼
          ESP32
             │
      OpenTherm interface
             │
             ▼
           Boiler

Possible data:
- requested CH water temperature
- burner modulation %
- flame on/off
- CH / DHW active
- boiler flow temperature
- return temperature
- pressure
- faults / diagnostics

The result is much closer to a real modulating thermostat than a simple dry-contact relay.

First: OpenTherm Master and OpenTherm Gateway Are Not the Same Thing

This is the most important distinction in the entire project.

Mode	Connection	Existing thermostat	ESP32 role
OpenTherm master/controller	ESP32 ↔ boiler	Disconnected	ESP32 becomes the thermostat/controller
Inline OpenTherm gateway	Thermostat ↔ ESP32 ↔ boiler	Stays connected	ESP32 monitors/forwards/intercepts traffic

ESPHome now includes an official OpenTherm component, but that built-in component operates as an OpenTherm master. It does not emulate both sides of the bus and therefore does not act as a transparent inline gateway.

If you use the native ESPHome component, the ESP32 replaces the original OpenTherm thermostat.

Native ESPHome OpenTherm:

Home Assistant / room sensor
          │
          ▼
        ESP32
   OpenTherm MASTER
          │
          ▼
        Boiler
   OpenTherm SLAVE

A real inline gateway needs two OpenTherm interfaces or gateway hardware so it can act as a slave toward the thermostat and a master toward the boiler.

True inline gateway:

Existing thermostat
   OpenTherm MASTER
          │
          ▼
        ESP32
   gateway / MITM
          │
          ▼
        Boiler
   OpenTherm SLAVE

Why OpenTherm Is Better Than Simple On/Off Control

A conventional relay thermostat usually gives the boiler one bit of information: heat requested or heat not requested.

Relay thermostat:

0 = stop heating
1 = heat

OpenTherm can instead request a particular central-heating flow temperature.

OpenTherm:

Room nearly at target
→ request 35 °C water

Room moderately cold
→ request 45 °C water

Large heating demand
→ request 60 °C water

A compatible modulating boiler can then reduce burner output rather than repeatedly cycling between full fire and off. The exact behaviour depends on the boiler, but this is the fundamental advantage of a modulating control bus.

Lower flow temperatures can improve condensing-boiler efficiency.
Longer burner runs can reduce unnecessary cycling.
Room temperature can approach the target more smoothly.
Home Assistant can expose useful boiler telemetry instead of only an on/off state.
Faults and operating states can often be monitored directly.

Check That Your Boiler Really Supports OpenTherm

Do not assume a pair of thermostat terminals is OpenTherm just because there are two wires.

Check the boiler installation manual for OpenTherm, OT or the OpenTherm logo.
Do not connect an OpenTherm adapter to a proprietary manufacturer bus.
Do not connect it to a 230 V switched-live thermostat input.
Some boilers provide both dry-contact and OpenTherm terminals; use the correct pair.
Some manufacturers support OpenTherm only on certain models, firmware versions or optional interface boards.

If the documentation calls the connection eBUS, EMS, KM-BUS, EMS2, proprietary digital thermostat or another named bus, treat it as a different protocol until proven otherwise.

OpenTherm Is Not a 3.3 V Logic Bus

Never connect the boiler’s OpenTherm terminals directly to ESP32 GPIO.

The OpenTherm physical layer uses current and voltage signalling on the two-wire boiler/thermostat loop. It is not UART, I²C, RS-485 or a normal 3.3 V digital signal.

Use a proper OpenTherm interface designed to translate the bus into safe microcontroller logic. ESPHome’s own documentation points to interfaces such as the DIYLESS Master OpenTherm Shield, Ihor Melnyk’s OpenTherm Adapter and Jiří Praus’ OpenTherm hardware.

Boiler-side safety isolation belongs in the boiler/interface design. Do not improvise the physical layer on a permanently installed gas-heating appliance unless you fully understand the isolation and electrical requirements.

Recommended Architecture for Most Home Assistant Users

If you are happy to replace the existing thermostat, use the native ESPHome OpenTherm master. It is the cleanest software path and does not depend on a third-party external component.

Room temperature sensor
       │
       ▼
Home Assistant or local ESP32 sensor
       │
       ▼
ESPHome PID climate
       │
       ▼
OpenTherm water-temperature setpoint
       │
       ▼
Boiler modulation

For a self-contained controller, place the room-temperature sensor on the same ESP32 or use another reliable local sensor. ESPHome can also import a room-temperature entity from Home Assistant, but the heating loop then depends on Home Assistant being available.

Native ESPHome OpenTherm Hardware Wiring

The exact pin labels vary by adapter. ESPHome names the pins relative to the ESP32, while some adapter boards label them relative to the adapter. This can make IN/OUT appear reversed.

Example:

ESP32 GPIO21  ← adapter logic OUT
ESP32 GPIO22  → adapter logic IN

Adapter OT terminals
        ↕
Boiler OpenTherm terminals

With ESPHome, in_pin is the signal entering the ESP32 from the bridge, and out_pin is the signal leaving the ESP32 toward the bridge.

Minimal ESPHome OpenTherm Configuration

esphome:
  name: opentherm-boiler
  friendly_name: OpenTherm Boiler

esp32:
  board: esp32dev
  framework:
    type: esp-idf

logger:

api:

ota:
  - platform: esphome

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

opentherm:
  in_pin: GPIO21
  out_pin: GPIO22
  ch_enable: true

number:
  - platform: opentherm
    t_set:
      name: "Boiler CH Water Setpoint"
      min_value: 20
      max_value: 65

This is the simplest useful test: Home Assistant gets a number entity that writes the requested central-heating water temperature to the boiler.

Start conservatively and respect the boiler manufacturer’s allowed operating range. The values above are only an example, not a universal boiler specification.

Add Boiler Telemetry

The OpenTherm component can expose many useful values, but support varies by boiler. A valid OpenTherm boiler is not required to implement every optional data item.

sensor:
  - platform: opentherm
    rel_mod_level:
      name: "Boiler Relative Modulation"
    ch_pressure:
      name: "CH Water Pressure"
    t_boiler:
      name: "Boiler Flow Temperature"
    t_ret:
      name: "Boiler Return Temperature"
    t_dhw:
      name: "Domestic Hot Water Temperature"
    dhw_flow_rate:
      name: "DHW Flow Rate"

binary_sensor:
  - platform: opentherm
    ch_active:
      name: "Central Heating Active"
    dhw_active:
      name: "Domestic Hot Water Active"
    flame_on:
      name: "Boiler Flame"
    fault_indication:
      name: "Boiler Fault"
      entity_category: diagnostic
    diagnostic_indication:
      name: "Boiler Diagnostic Event"
      entity_category: diagnostic

If one of these stays unavailable, that does not necessarily mean the ESP32 or adapter is faulty. The boiler may simply not provide that OpenTherm data ID.

What the Most Useful OpenTherm Sensors Mean

Entity	Meaning	Why it is useful
rel_mod_level	Relative burner modulation %	Shows whether the boiler is firing hard or gently
t_boiler	CH flow/water temperature	Compare requested vs actual flow temperature
t_ret	Return-water temperature	Useful for delta-T and condensing-system analysis
ch_pressure	Heating circuit pressure	Trend pressure loss if the boiler exposes it
t_dhw	Domestic hot-water temperature	Monitor DHW performance
dhw_flow_rate	DHW flow rate	Useful during hot-water draw
flame_on	Burner flame state	Confirms firing rather than only heat demand
fault_indication	Boiler fault flag	Allows Home Assistant alerts

Using ESPHome PID to Modulate the Boiler

The most interesting native ESPHome design uses a PID climate controller. Instead of toggling a relay, the PID output becomes the requested OpenTherm water-temperature setpoint.

output:
  - platform: opentherm
    t_set:
      id: boiler_setpoint
      min_value: 20
      max_value: 65
      zero_means_zero: true

sensor:
  - platform: homeassistant
    id: room_temperature
    entity_id: sensor.living_room_temperature
    filters:
      - heartbeat: 1s

climate:
  - platform: pid
    name: "Central Heating"
    sensor: room_temperature
    heat_output: boiler_setpoint
    default_target_temperature: 20.5

    control_parameters:
      kp: 0.4
      ki: 0.004

The gains above are the current ESPHome documentation example, not universal PID tuning values. Every building, radiator system and boiler responds differently, so treat PID tuning as a commissioning exercise rather than copying numbers blindly.

The important architecture is what matters:

Room error
(target - actual)
      │
      ▼
PID controller
      │
      ▼
requested boiler flow temperature
      │
      ▼
OpenTherm boiler

Enable and Disable Central Heating from Home Assistant

switch:
  - platform: opentherm
    ch_enable:
      name: "Boiler Central Heating Enabled"
      restore_mode: RESTORE_DEFAULT_ON

This controls the OpenTherm central-heating enable request. It is not a substitute for the boiler’s own safety controls.

Domestic Hot Water

Combination boilers commonly manage domestic hot water internally, but OpenTherm can expose DHW state and may allow DHW enable or setpoint functions depending on the boiler.

Do not assume every appliance allows remote DHW setpoint changes. OpenTherm contains optional capabilities, and the boiler decides which functions it actually supports.

ESPHome sync_mode and Communication Errors

OpenTherm timing is sensitive. ESPHome provides sync_mode for installations that suffer intermittent invalid responses because other components temporarily interfere with timing.

opentherm:
  in_pin: GPIO21
  out_pin: GPIO22
  sync_mode: true

Do not enable it as a ritual. Use it when logs show random response errors and you have ruled out wiring and interface problems. ESPHome notes that synchronous mode can block the main application loop for longer periods.

Common Problem: Boiler Does Not Respond

Confirm the selected terminals are really OpenTherm.
Confirm the OpenTherm adapter is powered and wired correctly.
Check whether adapter IN/OUT labels are reversed relative to ESPHome’s pin naming.
Disconnect the old OpenTherm thermostat when using ESPHome’s native master component.
Check GPIO assignment and board pinout.
Review ESPHome logs for timeout, parity or invalid-frame errors.
Confirm the boiler is configured to accept an OpenTherm controller if the manufacturer requires a setup change.

Common Problem: Existing Thermostat Stops Working

That is expected with the built-in ESPHome OpenTherm component.

The native component is a master/controller, not an inline gateway. The boiler should have one active OpenTherm master on that connection.

If preserving the original thermostat is a requirement, use a genuine inline gateway design instead.

True Inline Gateway: Keep the Existing Thermostat

A transparent gateway sits between the thermostat and boiler and forwards OpenTherm traffic while observing or modifying selected messages.

Existing thermostat
        │
        ▼
  OpenTherm interface
        │
        ▼
      ESP32
        │
        ▼
  OpenTherm interface
        │
        ▼
      Boiler

This requires two logical OpenTherm sides:

A slave-side interface facing the thermostat.
A master-side interface facing the boiler.
Firmware that forwards requests and responses with correct OpenTherm timing.
A clear failure strategy if the ESP32 reboots or loses power.

ESPHome External Gateway Components

There are community ESPHome external components that implement true gateway mode on ESP32/ESP8266 hardware. One actively visible project uses four GPIO signals: master-side IN/OUT toward the boiler and slave-side IN/OUT toward the thermostat.

Gateway concept:

opentherm:
  id: opentherm_gateway

  # Boiler side: ESP acts as master
  in_pin: GPIOXX
  out_pin: GPIOXX

  # Thermostat side: ESP acts as slave
  slave_in_pin: GPIOXX
  slave_out_pin: GPIOXX

Because this is an external component rather than ESPHome core, verify the repository version, supported ESPHome release and hardware before installing it on a heating system. External-component APIs can change independently of ESPHome.

Gateway Mode Advantages

The existing wall thermostat keeps its normal user interface.
Home Assistant gains boiler telemetry.
Selected temperature requests can be monitored or overridden.
If designed correctly, the thermostat remains the primary controller.
You can observe what the commercial thermostat is actually requesting from the boiler.

For users who already have a good modulating thermostat, this can be more attractive than replacing it with a DIY controller.

Gateway Mode Risks

The gateway becomes part of the live control path between thermostat and boiler.
A firmware bug can affect both directions of communication.
A reboot can interrupt heating control unless the hardware/firmware has a suitable fail strategy.
Message overrides can produce confusing behaviour if both Home Assistant and the thermostat are trying to control the same parameter.
Third-party gateway components need more maintenance than the native ESPHome master component.

Home Assistant’s OpenTherm Gateway Integration Is a Different Route

Home Assistant also has a dedicated OpenTherm Gateway integration. That integration targets OpenTherm Gateway devices that speak the classic OTGW command/interface protocol.

It should not be confused with ESPHome’s native OpenTherm component. An ESPHome device normally appears in Home Assistant through the ESPHome integration, while a classic OTGW device uses the OpenTherm Gateway integration.

Hardware / firmware	Home Assistant integration
ESP32 + native ESPHome OpenTherm	ESPHome
ESP32 + ESPHome external inline gateway	Usually ESPHome
Classic OpenTherm Gateway / OTGW protocol device	OpenTherm Gateway integration

Modulation: What to Look for in Home Assistant

The most useful graph combines room temperature, requested water temperature, actual boiler flow temperature and relative modulation.

Home Assistant history:

Room temperature          20.1 → 20.4 → 20.5 °C
Requested CH water temp   48   → 40   → 30 °C
Boiler flow temperature   46   → 39   → 31 °C
Relative modulation       65%  → 35%  → 15%

A well-behaved modulating system should normally reduce demand as the room approaches target instead of repeatedly demanding maximum temperature until the thermostat abruptly stops.

Flow and Return Temperature

If the boiler exposes both t_boiler and t_ret, Home Assistant can calculate heating-system delta-T.

ΔT = flow temperature - return temperature

Example:
Flow   = 52 °C
Return = 42 °C
ΔT     = 10 °C

Do not chase one universal ‘correct’ delta-T. The desirable value depends on boiler design, emitter sizing, pump speed, hydraulic balancing and operating load. The trend is still valuable for diagnosing changes in system behaviour.

Condensing Boilers and Lower Flow Temperatures

OpenTherm is especially useful with condensing boilers because it can request lower central-heating water temperatures during light load.

Lower water temperatures often produce lower return temperatures, which can help a condensing boiler spend more time in its efficient condensing operating region. How much benefit you get depends on the actual heating system and boiler.

Do Not Use Home Assistant as the Only Safety Layer

Home Assistant can provide schedules, weather compensation, occupancy logic and dashboards, but it should not replace boiler safety systems.

Leave over-temperature protection to the appliance.
Leave flame supervision to the appliance.
Leave pressure and combustion safeties intact.
Do not use OpenTherm commands to defeat lockouts or manufacturer interlocks.
Treat remote lockout-reset functions cautiously.
Keep any frost-protection strategy robust against network or Home Assistant failure.

When a Simple Relay Is Still Better

OpenTherm is not automatically the right choice for every project.

Situation	Better approach
Boiler has only dry-contact thermostat input	ESP32 relay / contactor interface
Boiler supports OpenTherm and you want modulation	OpenTherm master/controller
You want to keep an existing OpenTherm thermostat	True inline gateway
You only need on/off hot-water scheduling	Relay may be simpler
You want detailed boiler telemetry	OpenTherm is usually more useful

Recommended Build Sequence

Verify the exact boiler model and OpenTherm terminals from the manual.
Use a proven OpenTherm interface board.
Start with the native ESPHome master component if you do not need the original thermostat.
Expose only boiler flow temperature, flame state and a manual CH setpoint first.
Confirm stable communication for several heating cycles.
Add return temperature, pressure and modulation telemetry.
Only then add PID or automated setpoint control.
Move to inline gateway firmware only if keeping the original thermostat is a real requirement.

This progression keeps protocol debugging separate from thermostat-control tuning.

Final Recommendation

For a new Home Assistant boiler controller, the native ESPHome OpenTherm component is the best starting point. It is built into ESPHome, exposes the important OpenTherm inputs and telemetry, and can directly drive a PID climate controller.

Use a true inline gateway only when preserving the existing OpenTherm thermostat matters. In that design, the ESP32 must sit between thermostat and boiler and implement both sides of the protocol; the normal ESPHome OpenTherm component alone cannot do that.

The biggest improvement over relay control is not simply ‘more data.’ It is the ability to request an appropriate heating-water temperature and let a compatible boiler modulate instead of treating every heating demand as full-on/full-off.

Related ESP32 Guides

Official Documentation and Project References

External framework and project references are collected here so the main article keeps the implementation path clear.

ESPHome OpenTherm component — current native master/controller configuration, sensors, switches, outputs and PID example.
Home Assistant OpenTherm Gateway integration — integration for classic OTGW-compatible gateways.
ESPHome OpenTherm Gateway external component — community inline master/slave gateway implementation.
OpenTherm Protocol Specification v2.2 — physical-layer and protocol reference.