mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-03-01 03:51:36 +01:00
Documentation for new OpenTherm component (#3800)
Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
This commit is contained in:
parent
29f917d90d
commit
2e6381a9d5
BIN
components/images/opentherm-shield.png
Normal file
BIN
components/images/opentherm-shield.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 292 KiB |
437
components/opentherm.rst
Normal file
437
components/opentherm.rst
Normal file
@ -0,0 +1,437 @@
|
||||
OpenTherm
|
||||
=========
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up OpenTherm bridge in ESPHome.
|
||||
:image: ../components/images/opentherm-shield.png
|
||||
:keywords: OpenTherm
|
||||
|
||||
OpenTherm (OT) is a standard communications protocol used in central heating systems for the communication between
|
||||
central heating appliances and a thermostatic controller. As a standard, OpenTherm is independent of any single
|
||||
manufacturer. A controller from manufacturer A can in principle be used to control a boiler from manufacturer B.
|
||||
|
||||
Since OpenTherm doesn't operate in a standard voltage range, special hardware is required. You can choose from several
|
||||
ready-made adapters or roll your own:
|
||||
|
||||
- `DIYLESS Master OpenTherm Shield <https://diyless.com/product/master-opentherm-shield>`__
|
||||
- `Ihor Melnyk's OpenTherm Adapter <http://ihormelnyk.com/opentherm_adapter>`__
|
||||
- `Jiří Praus' OpenTherm Gateway Arduino Shield <https://www.tindie.com/products/jiripraus/opentherm-gateway-arduino-shield/>`__
|
||||
|
||||
.. figure:: images/opentherm-shield.png
|
||||
:align: center
|
||||
:width: 50.0%
|
||||
|
||||
DIYLESS Master OpenTherm Shield.
|
||||
|
||||
.. note::
|
||||
|
||||
This component acts only as an OpenTherm master (for example, a thermostat or controller) and not as a slave or
|
||||
gateway. Your existing thermostat is not usable while you use ESPHome with this component to control your boiler.
|
||||
|
||||
Quick glossary
|
||||
--------------
|
||||
|
||||
- CH: Central Heating
|
||||
- DHW: Domestic Hot Water
|
||||
|
||||
Hub
|
||||
---
|
||||
|
||||
First, you need to define the OpenTherm hub in your configuration. Note that most OpenTherm adapters label ``in`` and
|
||||
``out`` pins relative to themselves; this component labels its ``in`` and ``out`` pins relative to the microcontroller
|
||||
ESPHome runs on. As such, your bridge's ``in`` pin becomes the hub's ``out`` pin and vice-versa.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
opentherm:
|
||||
in_pin: GPIOXX
|
||||
out_pin: GPIOXX
|
||||
|
||||
Configuration variables:
|
||||
************************
|
||||
|
||||
- **in_pin** (**Required**, number): The pin of the OpenTherm hardware bridge which is usually labeled ``out`` on the
|
||||
board.
|
||||
- **out_pin** (**Required**, number): The pin of the OpenTherm hardware bridge which is usually labeled ``in`` on the
|
||||
board.
|
||||
- **sync_mode** (**Optional**, boolean, default **false**): Synchronous communication mode prevents other components
|
||||
from disabling interrupts while we are talking to the boiler. Enable if you experience a lot of random intermittent
|
||||
invalid response errors (very likely to happen while using Dallas temperature sensors).
|
||||
- **opentherm_version** (**Optional**, float): OpenTherm version that is required for some boilers to work (message
|
||||
id 124). You don't need to specify this if everything works.
|
||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Required if you have
|
||||
multiple busses.
|
||||
|
||||
Note abut sync mode
|
||||
*******************
|
||||
|
||||
The use of some components (like Dallas temperature sensors) may result in lost frames and protocol warnings from
|
||||
OpenTherm. Since OpenTherm is resilient by design and transmits its messages in a constant loop, these dropped frames
|
||||
don't usually cause any problems. Still, if you want to decrease the number of protocol warnings in your logs, you can
|
||||
enable ``sync_mode`` which will block ESPHome's main application loop until a single conversation with the boiler is
|
||||
complete. This can greatly reduce the number of dropped frames, but usually won't eliminate them entirely. With
|
||||
``sync_mode`` enabled, in some cases, ESPHome's main application loop may be blocked for longer than is recommended,
|
||||
resulting in warnings in the logs. If this bothers you, you can adjust ESPHome's log level by adding the following to
|
||||
your configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
logger:
|
||||
logs:
|
||||
component: ERROR
|
||||
|
||||
Usage as a thermostat
|
||||
---------------------
|
||||
|
||||
The most important function for a thermostat is to set the boiler temperature setpoint. This component has three ways
|
||||
to provide this input: using a Home Assistant sensor from which the setpoint can be read, using a
|
||||
:doc:`/components/number/index`, or defining an output to which other components can write. For most users, the last
|
||||
option is the most useful one, as it can be combined with the :doc:`/components/climate/pid` component to create a
|
||||
thermostat that works as you would expect a thermostat to work. See :ref:`thermostat-pid-basic` for an example.
|
||||
|
||||
Numerical values
|
||||
****************
|
||||
|
||||
There are three ways to set a numerical value:
|
||||
|
||||
- As an input sensor, defined in the hub configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
opentherm:
|
||||
t_set: setpoint_sensor
|
||||
|
||||
sensor:
|
||||
- platform: homeassistant
|
||||
id: setpoint_sensor
|
||||
entity_id: sensor.boiler_setpoint
|
||||
|
||||
This can be useful if you have an external thermostat-like device that provides the setpoint as a sensor.
|
||||
|
||||
- As a number:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
number:
|
||||
- platform: opentherm
|
||||
t_set:
|
||||
name: Boiler Setpoint
|
||||
|
||||
This is useful if you want full control over your boiler and want to manually set all values.
|
||||
|
||||
- As an output:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
output:
|
||||
- platform: opentherm
|
||||
t_set:
|
||||
id: setpoint
|
||||
|
||||
This is especially useful in combination with the PID Climate component:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
climate:
|
||||
- platform: pid
|
||||
heat_output: setpoint
|
||||
# ...
|
||||
|
||||
For the output and number variants, there are four more properties you can configure beyond those included in the
|
||||
output and number components by default:
|
||||
|
||||
- ``min_value`` (float): The minimum value. For a number this is the minimum value you are allowed to input. For an
|
||||
output this is the number that will be sent to the boiler when the output is at 0%.
|
||||
- ``max_value`` (float): The maximum value. For a number this is the maximum value you are allowed to input. For an
|
||||
output this is the number that will be sent to the boiler when the output is at 100%.
|
||||
- ``auto_max_value`` (boolean): Automatically configure the maximum value to a value reported by the boiler. Not
|
||||
available for all inputs.
|
||||
- ``auto_min_value`` (boolean): Automatically configure the minimum value to a value reported by the boiler. Not
|
||||
available for all inputs.
|
||||
|
||||
The following numerical values are available:
|
||||
|
||||
- ``t_set``: Control setpoint: temperature setpoint for the boiler's supply water (°C)
|
||||
|
||||
* Default ``min_value``: 0
|
||||
* Default ``max_value``: 100
|
||||
* Supports ``auto_max_value``
|
||||
- ``t_set_ch2``: Control setpoint 2: temperature setpoint for the boiler's supply water on the second heating circuit
|
||||
(°C)
|
||||
|
||||
* Default ``min_value``: 0
|
||||
* Default ``max_value``: 100
|
||||
* Supports ``auto_max_value``
|
||||
- ``cooling_control``: Cooling control signal (%)
|
||||
|
||||
* Default ``min_value``: 0
|
||||
* Default ``max_value``: 100
|
||||
- ``t_dhw_set``: Domestic hot water temperature setpoint (°C)
|
||||
|
||||
* Default ``min_value``: 0
|
||||
* Default ``max_value``: 127
|
||||
* Supports ``auto_min_value``
|
||||
* Supports ``auto_max_value``
|
||||
- ``max_t_set``: Maximum allowable CH water setpoint (°C)
|
||||
|
||||
* Default ``min_value``: 0
|
||||
* Default ``max_value``: 127
|
||||
* Supports ``auto_min_value``
|
||||
* Supports ``auto_max_value``
|
||||
- ``t_room_set``: Current room temperature setpoint (informational) (°C)
|
||||
|
||||
* Default ``min_value``: -40
|
||||
* Default ``max_value``: 127
|
||||
- ``t_room_set_ch2``: Current room temperature setpoint on CH2 (informational) (°C)
|
||||
|
||||
* Default ``min_value``: -40
|
||||
* Default ``max_value``: 127
|
||||
- ``t_room``: Current sensed room temperature (informational) (°C)
|
||||
|
||||
* Default ``min_value``: -40
|
||||
* Default ``max_value``: 127
|
||||
- ``max_rel_mod_level``: Maximum relative modulation level (%)
|
||||
|
||||
* Default ``min_value``: 0
|
||||
* Default ``max_value``: 100
|
||||
* Supports ``auto_min_value``
|
||||
- ``otc_hc_ratio``: OTC heat curve ratio (°C)
|
||||
|
||||
* Default ``min_value``: 0
|
||||
* Default ``max_value``: 127
|
||||
* Supports ``auto_min_value``
|
||||
* Supports ``auto_max_value``
|
||||
|
||||
Switch
|
||||
******
|
||||
|
||||
|
||||
Switches are available to allow manual toggling of any of the following seven status codes:
|
||||
|
||||
- ``ch_enable``: Central Heating enabled
|
||||
- ``dhw_enable``: Domestic Hot Water enabled
|
||||
- ``cooling_enable``: Cooling enabled
|
||||
- ``otc_active``: Outside temperature compensation active
|
||||
- ``ch2_active``: Central Heating 2 active
|
||||
- ``summer_mode_active``: Summer mode active
|
||||
- ``dhw_block``: Block DHW
|
||||
|
||||
If you do not wish to have switches, the same values can be permanently set in the hub configuration, like so:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
opentherm:
|
||||
ch_enable: true
|
||||
dhw_enable: true
|
||||
|
||||
This is useful when you'd never want to toggle it after the initial configuration.
|
||||
|
||||
The default values for these configuration variables are listed below.
|
||||
|
||||
To enable central heating and cooling, the flag is only sent to the boiler if the following conditions are met:
|
||||
|
||||
- the flag is set to true in the hub configuration,
|
||||
- the switch is on (if configured),
|
||||
- the setpoint or cooling control value is not 0 (if configured)
|
||||
|
||||
For domestic hot water and outside temperature compensation, only the first two conditions are necessary.
|
||||
|
||||
The last point ensures that central heating is not enabled if no heating is requested as indicated by a setpoint of 0.
|
||||
If you use a number as the setpoint input and use a minimum value higher than 0, you **must** use the ``ch_enable``
|
||||
switch to turn off your central heating. In such a case, the flag will be set to true in the hub configuration and the
|
||||
setpoint is always larger than 0, so including a switch is the only way you can turn off central heating. (This also
|
||||
holds for cooling and CH2.)
|
||||
|
||||
Binary sensor
|
||||
*************
|
||||
|
||||
The component can report boiler status on several binary sensors. The *Status* sensors are updated in each message
|
||||
cycle, while the others are only set during initialization, as they are unlikely to change without restarting the
|
||||
boiler.
|
||||
|
||||
- ``fault_indication``: Status: Fault indication
|
||||
- ``ch_active``: Status: Central Heating active
|
||||
- ``dhw_active``: Status: Domestic Hot Water active
|
||||
- ``flame_on``: Status: Flame on
|
||||
- ``cooling_active``: Status: Cooling active
|
||||
- ``ch2_active``: Status: Central Heating 2 active
|
||||
- ``diagnostic_indication``: Status: Diagnostic event
|
||||
- ``electricity_production``: Status: Electricity production
|
||||
- ``dhw_present``: Configuration: DHW present
|
||||
- ``control_type_on_off``: Configuration: Control type is on/off
|
||||
- ``cooling_supported``: Configuration: Cooling supported
|
||||
- ``dhw_storage_tank``: Configuration: DHW storage tank
|
||||
- ``controller_pump_control_allowed``: Configuration: Controller pump control allowed
|
||||
- ``ch2_present``: Configuration: CH2 present
|
||||
- ``water_filling``: Configuration: Remote water filling
|
||||
- ``heat_mode``: Configuration: Heating or cooling
|
||||
- ``dhw_setpoint_transfer_enabled``: Remote boiler parameters: DHW setpoint transfer enabled
|
||||
- ``max_ch_setpoint_transfer_enabled``: Remote boiler parameters: CH maximum setpoint transfer enabled
|
||||
- ``dhw_setpoint_rw``: Remote boiler parameters: DHW setpoint read/write
|
||||
- ``max_ch_setpoint_rw``: Remote boiler parameters: CH maximum setpoint read/write
|
||||
- ``service_request``: Service required
|
||||
- ``lockout_reset``: Lockout Reset
|
||||
- ``low_water_pressure``: Low water pressure fault
|
||||
- ``flame_fault``: Flame fault
|
||||
- ``air_pressure_fault``: Air pressure fault
|
||||
- ``water_over_temp``: Water overtemperature
|
||||
|
||||
Sensor
|
||||
******
|
||||
|
||||
The boiler can also report several numerical values, which are available through sensors. Your boiler may not support
|
||||
all of these values, in which case there won't be any value published to that sensor. The following sensors are
|
||||
available:
|
||||
|
||||
- ``rel_mod_level``: Relative modulation level (%)
|
||||
- ``ch_pressure``: Water pressure in CH circuit (bar)
|
||||
- ``dhw_flow_rate``: Water flow rate in DHW circuit (l/min)
|
||||
- ``t_boiler``: Boiler water temperature (°C)
|
||||
- ``t_dhw``: DHW temperature (°C)
|
||||
- ``t_outside``: Outside temperature (°C)
|
||||
- ``t_ret``: Return water temperature (°C)
|
||||
- ``t_storage``: Solar storage temperature (°C)
|
||||
- ``t_collector``: Solar collector temperature (°C)
|
||||
- ``t_flow_ch2``: Flow water temperature CH2 circuit (°C)
|
||||
- ``t_dhw2``: Domestic hot water temperature 2 (°C)
|
||||
- ``t_exhaust``: Boiler exhaust temperature (°C)
|
||||
- ``fan_speed``: Boiler fan speed (RPM)
|
||||
- ``fan_speed_setpoint``: Boiler fan speed setpoint (RPM)
|
||||
- ``flame_current``: Boiler flame current (µA)
|
||||
- ``burner_starts``: Number of starts burner
|
||||
- ``ch_pump_starts``: Number of starts CH pump
|
||||
- ``dhw_pump_valve_starts``: Number of starts DHW pump/valve
|
||||
- ``dhw_burner_starts``: Number of starts burner during DHW mode
|
||||
- ``burner_operation_hours``: Number of hours that burner is in operation
|
||||
- ``ch_pump_operation_hours``: Number of hours that CH pump has been running
|
||||
- ``dhw_pump_valve_operation_hours``: Number of hours that DHW pump has been running or DHW valve has been opened
|
||||
- ``dhw_burner_operation_hours``: Number of hours that burner is in operation during DHW mode
|
||||
- ``t_dhw_set_ub``: Upper bound for adjustment of DHW setpoint (°C)
|
||||
- ``t_dhw_set_lb``: Lower bound for adjustment of DHW setpoint (°C)
|
||||
- ``max_t_set_ub``: Upper bound for adjustment of max CH setpoint (°C)
|
||||
- ``max_t_set_lb``: Lower bound for adjustment of max CH setpoint (°C)
|
||||
- ``t_dhw_set``: Domestic hot water temperature setpoint (°C)
|
||||
- ``max_t_set``: Maximum allowable CH water setpoint (°C)
|
||||
- ``opentherm_version_device``: Version of OpenTherm implemented by device
|
||||
- ``device_type``: Device product type
|
||||
- ``device_version``: Device product version
|
||||
- ``device_id``: Device ID code
|
||||
- ``otc_hc_ratio_ub``: OTC heat curve ratio upper bound
|
||||
- ``otc_hc_ratio_lb``: OTC heat curve ratio lower bound
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
Minimal example with numeric input
|
||||
**********************************
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# An extremely minimal configuration which only enables you to set the boiler's
|
||||
# water temperature setpoint as a number.
|
||||
|
||||
opentherm:
|
||||
in_pin: GPIOXX
|
||||
out_pin: GPIOXX
|
||||
ch_enable: true
|
||||
|
||||
number:
|
||||
- platform: opentherm
|
||||
t_set:
|
||||
name: "Boiler Control setpoint"
|
||||
|
||||
.. _thermostat-pid-basic:
|
||||
|
||||
Basic PID thermostat
|
||||
********************
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# A basic thremostat for a boiler with a single central heating circuit and
|
||||
# domestic hot water. It reports the flame, CH and DHW status, similar to what
|
||||
# you would expect to see on a thermostat and also reports the internal boiler
|
||||
# temperatures and the current modulation level. The temperature is regulated
|
||||
# through a PID Climate controller and the current room temperature is retrieved
|
||||
# from a sensor in Home Asisstant.
|
||||
|
||||
# This configuration should meet most needs and is the recommended starting
|
||||
# point if you just want a thermostat with an external temperature sensor.
|
||||
|
||||
opentherm:
|
||||
in_pin: GPIOXX
|
||||
out_pin: GPIOXX
|
||||
dhw_enable: true # Note that when we specify an input in hub config with a static value, it can't be
|
||||
# changed without uploading new firmware. If you want to be able to turn things on or off,
|
||||
# use a switch (see the ch_enable switch below).
|
||||
# Also note that when we define an input as a switch (or use other platform), we don't need
|
||||
# to set it at hub level.
|
||||
|
||||
output:
|
||||
- platform: opentherm
|
||||
t_set:
|
||||
id: t_set
|
||||
min_value: 20
|
||||
max_value: 65
|
||||
zero_means_zero: true
|
||||
|
||||
sensor:
|
||||
- platform: opentherm
|
||||
rel_mod_level:
|
||||
name: "Boiler Relative modulation level"
|
||||
t_boiler:
|
||||
name: "Boiler water temperature"
|
||||
t_ret:
|
||||
name: "Boiler Return water temperature"
|
||||
|
||||
- platform: homeassistant
|
||||
id: ch_room_temperature
|
||||
entity_id: sensor.temperature
|
||||
filters:
|
||||
# Push room temperature every second to update PID parameters
|
||||
- heartbeat: 1s
|
||||
|
||||
binary_sensor:
|
||||
- platform: opentherm
|
||||
ch_active:
|
||||
name: "Boiler Central Heating active"
|
||||
dhw_active:
|
||||
name: "Boiler Domestic Hot Water active"
|
||||
flame_on:
|
||||
name: "Boiler Flame on"
|
||||
fault_indication:
|
||||
name: "Boiler Fault indication"
|
||||
entity_category: diagnostic
|
||||
diagnostic_indication:
|
||||
name: "Boiler Diagnostic event"
|
||||
entity_category: diagnostic
|
||||
|
||||
switch:
|
||||
- platform: opentherm
|
||||
ch_enable:
|
||||
name: "Boiler Central Heating enabled"
|
||||
restore_mode: RESTORE_DEFAULT_ON
|
||||
|
||||
climate:
|
||||
- platform: pid
|
||||
name: "Central heating"
|
||||
heat_output: t_set
|
||||
default_target_temperature: 20
|
||||
sensor: ch_room_temperature
|
||||
control_parameters:
|
||||
kp: 0.4
|
||||
ki: 0.004
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :apiref:`API Reference: OpenthermHub <opentherm/hub.h>`
|
||||
- :apiref:`API Reference: OpenthermInput <opentherm/input.h>`
|
||||
- :apiref:`API Reference: OpenthermNumber <opentherm/number/number.h>`
|
||||
- :apiref:`API Reference: OpenthermOutput <opentherm/output/output.h>`
|
||||
- :apiref:`API Reference: OpenthermSwitch <opentherm/switch/switch.h>`
|
||||
- `OpenTherm thermostat with ESPHome and Home Assistant <https://olegtarasov.me/opentherm-thermostat-esphome/>`__ —
|
||||
real-world use case for this component.
|
||||
- `Development repository <https://github.com/olegtarasov/esphome-opentherm>`__ — new features will be tested here
|
||||
before proposing them to ESPHome core.
|
||||
- :ghedit:`Edit`
|
BIN
images/opentherm.png
Normal file
BIN
images/opentherm.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 13 KiB |
@ -258,12 +258,13 @@ Hardware Peripheral Interfaces/Busses
|
||||
|
||||
.. imgtable::
|
||||
|
||||
1-Wire, components/one_wire, one-wire.svg
|
||||
CAN Bus, components/canbus/index, canbus.svg
|
||||
I²C Bus, components/i2c, i2c.svg
|
||||
I²S Audio, components/i2s_audio, i2s_audio.svg
|
||||
OpenTherm, components/opentherm, opentherm.png
|
||||
SPI Bus, components/spi, spi.svg
|
||||
UART, components/uart, uart.svg
|
||||
1-Wire, components/one_wire, one-wire.svg
|
||||
|
||||
I/O Expanders/Multiplexers
|
||||
--------------------------
|
||||
|
Loading…
Reference in New Issue
Block a user