OpenTherm Gateway Hub


The opentherm_gw component is used to control the OpenTherm Gateway from Home Assistant. When enabled, this component will automatically add its climate entity to Home Assistant.

Configuration

# Example configuration.yaml entry
opentherm_gw:
  device: /dev/ttyUSB0

Configuration Variables

device

(string)(Required)Path to OpenTherm Gateway device as supported by PySerial.

climate

(map)(Optional)Settings for the opentherm_gw climate entity.

name

(string)(Optional)The name for the device within Home Assistant.

Default value: OpenTherm Gateway

precision

(float)(Optional)The desired precision for this device. Can be used to match your actual thermostat’s precision. Supported values are 0.1, 0.5 and 1.0.

Default value: 0.5 for Celsius and 1.0 for Fahrenheit.

floor_temperature

(boolean)(Optional)Some thermostats round all temperatures down to the lower value according to their precision. Default behavior for Home Assistant is to round temperatures to the nearest value. Set this to True to override Home Assistant and round to the lower value according to the configured precision.

Default value: false

monitored_variables

(list)(Optional)A list of variables to expose as sensors.

burner_hours

Boiler flame on time.

burner_starts

Number of burner starts.

ch_pump_hours

Central heating pump running time.

ch_pump_starts

Number of central heating pump starts.

ch_water_pressure

Central heating water pressure.

ch_water_temp

Central heating water temperature.

ch_water_temp_2

Central heating 2 water temperature.

control_setpoint

Central heating water target temperature.

control_setpoint_2

Central heating 2 water target temperature.

cooling_control

Cooling control signal value.

dhw_burner_hours

Hot water flame on time.

dhw_burner_starts

Number of hot water burner starts.

dhw_flow_rate

Hot water flow rate.

dhw_pump_hours

Hot water pump running time.

dhw_pump_starts

Number of hot water pump starts.

dhw_setpoint

Hot water target temperature.

dhw_temp

Hot water temperature.

dhw_temp_2

Hot water 2 temperature.

exhaust_temp

Boiler exhaust temperature.

master_ch2_enabled

Thermostat requests central heating 2 on.

master_ch_enabled

Thermostat requests central heating on.

master_cooling_enabled

Thermostat requests cooling.

master_dhw_enabled

Thermostat requests hot water to be heated.

master_memberid

Thermostat member ID.

master_ot_version

Thermostat OpenTherm protocol version.

master_otc_enabled

Thermostat is using outside temperature correction.

master_product_type

Thermostat product type.

master_product_version

Thermostat product version.

max_ch_setpoint

Boiler maximum central heating water temperature.

oem_diag

OEM diagnostic information.

otgw_about

OpenTherm Gateway firmware version.

otgw_build

OpenTherm Gateway firmware build date and time.

otgw_clockmhz

OpenTherm Gateway firmware design clock speed.

otgw_dhw_ovrd

OpenTherm Gateway hot water override status.

otgw_gpio_a

OpenTherm Gateway GPIO port A operating mode.

otgw_gpio_a_state

OpenTherm Gateway GPIO A state.

otgw_gpio_b

OpenTherm Gateway GPIO port B operating mode.

otgw_gpio_b_state

OpenTherm Gateway GPIO B state.

otgw_ignore_transitions

OpenTherm Gateway ignores ripples in the signal during high/low transitions.

otgw_led_a

OpenTherm Gateway LED A operating mode.

otgw_led_b

OpenTherm Gateway LED B operating mode.

otgw_led_c

OpenTherm Gateway LED C operating mode.

otgw_led_d

OpenTherm Gateway LED D operating mode.

otgw_led_e

OpenTherm Gateway LED E operating mode.

otgw_led_f

OpenTherm Gateway LED F operating mode.

otgw_mode

OpenTherm Gateway operating mode.

otgw_ovrd_high_byte

OpenTherm Gateway overrides high byte with message ID 100.

otgw_setback_temp

OpenTherm Gateway setback temperature for away mode.

otgw_setpoint_ovrd_mode

OpenTherm Gateway central heating setpoint override mode.

otgw_smart_pwr

OpenTherm Gateway smart power operating mode.

otgw_thermostat_detect

OpenTherm Gateway automatic thermostat detection status.

otgw_vref

OpenTherm Gateway voltage reference setting.

outside_temp

Outside temperature as reported in the OpenTherm protocol.

relative_mod_level

Relative modulation level.

remote_rw_dhw

Boiler supports writing hot water setpoint.

remote_rw_max_ch

Boiler supports writing maximum central heating setpoint.

remote_transfer_dhw

Boiler supports reading hot water setpoint.

remote_transfer_max_ch

Boiler supports reading maximum central heating setpoint.

return_water_temp

Boiler return water temperature.

room_setpoint

Room target temperature.

room_setpoint_2

Room 2 target temperature.

room_setpoint_ovrd

Room target temperature override value.

room_temp

Current room temperature.

rovrd_auto_prio

Programmed room setpoint change takes priority over remote override setting.

rovrd_man_prio

Manual room setpoint change takes priority over remote override setting.

slave_air_pressure_fault

Boiler reports air pressure fault.

slave_ch2_active

Boiler reports central heating 2 active.

slave_ch2_present

Boiler has a central heating 2 circuit.

slave_ch_active

Boiler reports central heating active.

slave_ch_max_setp

Maximum boiler supported central heating water target temperature.

slave_ch_min_setp

Minimum boiler supported central heating water target temperature.

slave_control_type

Boiler control type (‘off’ is modulating, ‘on’ is on/off).

slave_cooling_active

Boiler reports cooling active.

slave_cooling_supported

Boiler supports cooling.

slave_dhw_active

Boiler reports hot water active.

slave_dhw_config

Boiler hot water mode (‘off’ is instantaneous or unspecified, ‘on’ is storage tank).

slave_dhw_max_setp

Maximum boiler supported hot water target temperature.

slave_dhw_min_setp

Minimum boiler supported hot water target temperature.

slave_dhw_present

Boiler reports hot water present.

slave_diagnostic_indication

Boiler diagnostic indication.

slave_fault_indication

Boiler fault indication.

slave_flame_on

Boiler reports flame on.

slave_gas_fault

Boiler reports gas fault.

slave_low_water_pressure

Boiler reports low water pressure.

slave_master_low_off_pump

Boiler supports low-off and pump control commands (this sensor is inverted, ‘on’ is not supported, ‘off’ is supported)

slave_max_capacity

Maximum boiler capacity.

slave_max_relative_modulation

Maximum boiler supported relative modulation.

slave_memberid

Boiler member ID.

slave_min_mod_level

Minimum boiler supported modulation level.

slave_oem_fault

Boiler OEM fault indication.

slave_ot_version

Boiler OpenTherm protocol version.

slave_product_type

Boiler product type.

slave_product_version

Boiler product version.

slave_remote_reset

Boiler reports ‘lockout-reset’ supported.

slave_service_required

Boiler reports service required.

slave_water_overtemp

Boiler reports water overtemperature.

solar_coll_temp

Solar collector temperature.

solar_storage_temp

Solar storage unit temperature.

Supported Variables

The list above contains all supported variables. Note that not all boilers and thermostats properly support all variables, so the fact that a variable is listed here and published by your system does not necessarily mean that you will get useful data out of it. To see which variables are published in your situation, enable debug logging for the opentherm_gw component and look for the status updates.

Services

Service opentherm_gw.reset_gateway

Reset the OpenTherm Gateway.

This service takes no parameters.

Service opentherm_gw.set_clock

Provide the time and day of week to the OpenTherm Gateway. The value provided here will be forwarded to the thermostat on the next date/time request from the thermostat. The OpenTherm Gateway does not have the ability to accurately keep track of time, so it will only retain the information provided here for a maximum of about 61 seconds.

Service data attribute Optional Default Description
date yes Today’s date Date from which the day of week will be extracted. Format: YYYY-MM-DD.
time yes Current time Time in 24h format.

Service opentherm_gw.set_control_setpoint

Improper use of this service may continuously keep your central heating system active, resulting in an overheated house and a significant increase in gas and/or electricity consumption.

Set the central heating control setpoint override on the OpenTherm Gateway. In a normal situation, the thermostat will calculate and control the central heating setpoint on the boiler. Setting this to any value other than 0 will enable the override and allow the OpenTherm Gateway to control this setting. While the override is active, the OpenTherm Gateway will also request your boiler to activate the central heating circuit. For your boiler’s actual maximum and minimum supported setpoint value, please see the slave_ch_max_setp and slave_ch_min_setp variables. Due to the potential consequences of leaving this setting enabled for prolonged periods, the override will be disabled when Home Assistant is shut down or restarted. You will only need this if you are writing your own software thermostat.

Service data attribute Optional Description
temperature no The central heating setpoint. Values between 0.0 and 90.0 are accepted, but your boiler may not support the full range. Set to 0 to disable the override.

Please read this information from the designer of the OpenTherm Gateway before considering to write your own software thermostat.

Service opentherm_gw.set_gpio_mode

Configure the GPIO behavior on the OpenTherm Gateway. For an explanation of the possible modes, see GPIO modes

Service data attribute Optional Description
id no The GPIO ID, A or B.
mode no The GPIO mode to be set.

Service opentherm_gw.set_led_mode

Configure the function of the LEDs on the OpenTherm Gateway. For a list of possible modes with explanation, see LED modes

Service data attribute Optional Description
id no The LED ID, accepted values are A through F.
mode no The LED mode to be set.

Service opentherm_gw.set_max_modulation

Improper use of this service may impair the performance of your central heating system.

Set the maximum modulation level override on the OpenTherm Gateway. In a normal situation, the thermostat will control the maximum modulation level on the boiler. Setting this to any value other than -1 will enable the override and allow the OpenTherm Gateway to control this setting. Due to the potential consequences of leaving this setting enabled, the override will be disabled when Home Assistant is shut down or restarted. You will only need this if you are writing your own software thermostat.

Service data attribute Optional Description
level no The maximum modulation level. Accepted values are -1 through 100. Set to -1 to disable the override.

Please read this information from the designer of the OpenTherm Gateway before considering to write your own software thermostat.

Service opentherm_gw.set_outside_temperature

Provide the outside temperature to the thermostat. If your thermostat is unable to display an outside temperature and does not support OTC (Outside Temperature Correction), this has no effect. Note that not all thermostats are able to display the full supported range.

Service data attribute Optional Description
temperature no The outside temperature to provide to the thermostat. Accepted values are -40.0 through 64.0. Any value above 64.0 will clear a previously configured value (suggestion: 99).

Service opentherm_gw.set_setback_temperature

Configure the setback temperature on the OpenTherm Gateway. The value you provide here will be used with the GPIO home (5) and away (6) modes.

Service data attribute Optional Description
temperature no The setback temperature. Accepted values are 0.0 through 30.0.

GPIO modes

Possible modes and their meaning for the GPIO pins are listed here:

  • 1. No function, default for both ports on a freshly flashed chip.
  • 2. Ground - A permanently low output (0V). Could be used for a power LED.
  • 3. Vcc - A permanently high output (5V). Can be used as a short-proof power supply for some external circuitry used by the other GPIO port.
  • 4. LED E - An additional LED if you want to present more than 4 LED functions.
  • 5. LED F - An additional LED if you want to present more than 5 LED functions.
  • 6. Home - Set thermostat to setback temperature when pulled low.
  • 7. Away - Set thermostat to setback temperature when pulled high.
  • 8. DS1820 (GPIO port B only) - Data line for a DS18S20 or DS18B20 temperature sensor used to measure the outside temperature. A 4k7 resistor should be connected between GPIO port B and Vcc.

LED modes

Possible LED modes and their meaning are listed here:

  • R. Receiving an Opentherm message from the thermostat or boiler.
  • X. Transmitting an Opentherm message to the thermostat or boiler.
  • T. Transmitting or receiving a message on the thermostat interface.
  • B. Transmitting or receiving a message on the boiler interface.
  • O. Remote setpoint override is active.
  • F. Flame is on.
  • H. Central heating is on.
  • W. Hot water is on.
  • C. Comfort mode (Domestic Hot Water Enable) is on.
  • X. Transmission error has been detected.
  • M. Boiler requires maintenance.
  • P. Raised power mode active on thermostat interface.

The OpenTherm protocol is based on polling. The thermostat sends requests to the boiler at specific intervals. As a result, it may take some time for changes to propagate between Home Assistant and the thermostat.

Example

A full configuration example with the OpenTherm Gateway connected to a remote host running ser2net looks like the one below.

# Full example configuration.yaml entry
opentherm_gw:
  device: socket://otgw.example.org:2345
  climate:
    name: Thermostat
    precision: 0.5
    floor_temperature: True
  monitored_variables:
    - room_setpoint
    - room_temp
    - otgw_about