(as External component, by Reproduktor)
I have two main requirements to solve:
For some time, I've been using this Opentherm Arduino shield from Jiří Praus. I had it connected with an ESP8266-based board and using Jiří's Arduino library I added some MQTT communication to report the values and show them in my Home Assistant. I added OTA, so it was a practically usable solution. Once I was able to read the values, I let the project sleep and did not get to extend it for overriding the values.
When the time finally came, I wished I could somehow port this to ESPHome. The ecosystem gives you lots for free, native Home Assistant API support is seamless. And here goes this project. It is still only in its beginning, please create an Issue if you observe a problem, or want the functionality extended. If you get me a coffee, I may be more willing to do something about it 😊
A code cleanup is needed - noted.
Ihor Myealnik's Opentherm library is used by this component.
The gateway is an ESPHome external component. To use it, you only need to include it in your configuration file:
external_components:
- source: github://Reproduktor/esphome-openthermgw
components: [ openthermgw ]
You need to configure the pins, on which the Opentherm gateway is connected. Please note - master
is the thermostat end, slave
is the boiler end.
openthermgw:
master_in_pin: 19
master_out_pin: 17
slave_in_pin: 18
slave_out_pin: 16
I was trying to achieve such a configurability, that the component code does not need to be changed to just observe another message, or find out the details about the request and response messages. As a result, you are able to expose any message as a sensor, using the type decoding you specify. The same message ID can be used in multiple sensors, thus you can expose a sensor with different encoding (e.g., HB and LB as two different sensors). Binary sensors are handled separately, as they create a different kind of sensor - binary sensor.
For the numeric sensors, you can create a list like this:
acme_opentherm_sensor_list:
- name: "ACME Control setpoint"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 1
value_on_request: false
value_type: 2
- name: "ACME Control setpoint 2"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 8
value_on_request: false
value_type: 2
- name: "ACME Room setpoint"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 16
value_on_request: false
value_type: 2
- name: "ACME Relative modulation level"
device_class: "signal_strength"
accuracy_decimals: 0
unit_of_measurement: "%"
message_id: 17
value_on_request: false
value_type: 2
Sensor variables are inherited from ESPHome Sensor component, plus:
False
): Only False
is supported at the moment. True
does not have any effect. If false
, the value is read from the slave (boiler) response message. If true
, the value is read from the master (thermostat) request message.Binary sensors are added like this:
acme_opentherm_binary_sensors:
- name: "ACME Boiler fault"
message_id: 0
value_on_request: false
bitindex: 1
- name: "ACME Boiler CH mode"
message_id: 0
value_on_request: false
bitindex: 2
- name: "ACME Boiler DHW mode"
message_id: 0
value_on_request: false
bitindex: 3
- name: "ACME Boiler flame status"
message_id: 0
value_on_request: false
bitindex: 4
Sensor variables are inherited from ESPHome Binary sensor component, plus:
False
): Only False
is supported at the moment. True
does not have any effect. If false
, the value is read from the slave (boiler) response message. If true
, the value is read from the master (thermostat) request message.You can add an override switch like this:
acme_opentherm_override_binary_switches:
- name: "OT override DHW circulating pump"
message_id: 129
value_on_request: true
bitindex: 4
acme_opentherm_override_binary_value:
name: "OT override DHW circulating pump with"
This example creates two switches: OT override DHW circulating pump
is the switch which controls, if the value in the given message is overriden, and the OT override DHW circulating pump with
switch specifies the value to override the data with. (Note that this example is for Geminox THRi boiler, the message ID is proprietary and not according to Opentherm standard.)
For every message yyou wish to override, configure an independent switch to control, if the overriding is on or off. Switch variables are inherited from ESPHome Switch component, plus:
True
): Only True
is supported at the moment. False
does not have any effect. If false
, the value is overriden in the slave (boiler) response message. If true
, the value is overriden in the master (thermostat) request message.external_components:
- source: github://Reproduktor/esphome-openthermgw
components: [ openthermgw ]
openthermgw:
master_in_pin: 19
master_out_pin: 17
slave_in_pin: 18
slave_out_pin: 16
acme_opentherm_sensor_list:
- name: "ACME Control setpoint"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 1
value_on_request: false
value_type: 2
- name: "ACME ASF flags / OEM Fault code"
message_id: 5
value_on_request: false
value_type: 0
- name: "ACME ASF flags / OEM Fault code response"
message_id: 5
value_on_request: false
value_type: 7
- name: "ACME Control setpoint 2"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 8
value_on_request: false
value_type: 2
- name: "ACME OEM diagnostic code"
message_id: 115
value_on_request: false
value_type: 0
- name: "ACME OEM diagnostic code response"
message_id: 115
value_on_request: false
value_type: 7
- name: "ACME Room setpoint"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 16
value_on_request: false
value_type: 2
- name: "ACME Relative modulation level"
device_class: "signal_strength"
accuracy_decimals: 0
unit_of_measurement: "%"
message_id: 17
value_on_request: false
value_type: 2
- name: "ACME CH water pressure"
device_class: "pressure"
accuracy_decimals: 2
unit_of_measurement: "bar"
message_id: 18
value_on_request: false
value_type: 2
- name: "ACME Room setpoint CH2"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 23
value_on_request: false
value_type: 2
- name: "ACME Room temperature"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 24
value_on_request: false
value_type: 2
- name: "ACME Boiler water temperature"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 25
value_on_request: false
value_type: 2
- name: "ACME DHW temperature"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 26
value_on_request: false
value_type: 2
- name: "ACME Outside temperature"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 27
value_on_request: false
value_type: 2
- name: "ACME Return water temperature"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 28
value_on_request: false
value_type: 2
- name: "ACME Flow temperature CH2"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 31
value_on_request: false
value_type: 2
- name: "ACME Exhaust temperature"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 33
value_on_request: false
value_type: 1
- name: "ACME DHW setpoint"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 56
value_on_request: false
value_type: 2
- name: "ACME Max CH water setpoint"
device_class: "temperature"
accuracy_decimals: 1
unit_of_measurement: "°C"
message_id: 57
value_on_request: false
value_type: 2
acme_opentherm_binary_sensors:
- name: "ACME Boiler fault"
message_id: 0
value_on_request: false
bitindex: 1
- name: "ACME Boiler CH mode"
message_id: 0
value_on_request: false
bitindex: 2
- name: "ACME Boiler DHW mode"
message_id: 0
value_on_request: false
bitindex: 3
- name: "ACME Boiler flame status"
message_id: 0
value_on_request: false
bitindex: 4
- name: "ACME Boiler CH2 mode"
message_id: 0
value_on_request: false
bitindex: 6
- name: "ACME Boiler diagnostic indication"
message_id: 0
value_on_request: false
bitindex: 7
- name: "ACME Control CH enable"
message_id: 0
value_on_request: false
bitindex: 9
- name: "ACME Control DHW enable"
message_id: 0
value_on_request: false
bitindex: 10
- name: "ACME Control CH2 enable"
message_id: 0
value_on_request: false
bitindex: 13
acme_opentherm_override_binary_switches:
- name: "OT override DHW circulating pump"
message_id: 129
value_on_request: true
bitindex: 4
acme_opentherm_override_binary_value:
name: "OT override DHW circulating pump with"