Add documentation for uponor_smatrix component (#3381)

This commit is contained in:
Stefan Rado 2024-02-22 04:03:17 +01:00 committed by GitHub
parent 46790fd346
commit ce7d691779
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 143 additions and 0 deletions

View File

@ -0,0 +1,138 @@
Uponor Smatrix Base Pulse Underfloor Heating
============================================
.. seo::
:description: Instructions for setting up an Uponor Smatrix Base Pulse underfloor heating control system in ESPHome.
:keywords: Uponor Smatrix, HCS, Thermostat
The Uponor Smatrix component allows you to integrate an Uponor Smatrix Base Pulse underfloor heating control system in ESPHome without the need for an Smatrix Pulse Com R-208 communication module.
It directly communicates with the controller and thermostats via the RS485 thermostat bus.
Connecting to the bus
---------------------
This component is able to communicate directly with the RS485 thermostat bus. For that, you will need to connect an RS485 to TTL converter to a UART bus of your ESPHome device.
The RS485 side of the converter can either be connected to one of the A/B terminals on the controller or on one of the thermostats.
The +/- terminals provide 5 volts and can be used to power your ESPHome device.
The :ref:`UART Component <uart>` must be configured with a baud rate of 19200, 8 data bits, no parity, 1 stop bit.
.. _uponor-gettingstarted:
Getting started
---------------
The controller and the thermostats have unique addresses used for communication that are not displayed anywhere but can only be found when scanning the bus.
Start with a basic configuration that just contains the UART and Uponor hub components. Make sure that the UART pins are configured according to your wiring and the baud rate is set to 19200.
.. code-block:: yaml
uponor_smatrix:
When you upload this configuration to your ESPHome device and connect it to the Uponor Smatrix bus, it will print a list of detected addresses to the log output.
.. code-block:: text
[00:00:00][C][uponor_smatrix:019]: Uponor Smatrix
[00:00:00][C][uponor_smatrix:020]: System address: 0x110B
[00:00:00][C][uponor_smatrix:031]: Detected unknown device addresses:
[00:00:00][C][uponor_smatrix:033]: 0xDE62
[00:00:00][C][uponor_smatrix:033]: 0xDDFF
[00:00:00][C][uponor_smatrix:033]: 0xDE72
[00:00:00][C][uponor_smatrix:033]: 0xDE4A
[00:00:00][C][uponor_smatrix:033]: 0xDE13
With that you can then add ``climate`` or ``sensor`` components for the detected devices. Optionally, you can also statically add the detected system address to your ``uponor_smatrix`` configuration.
.. code-block:: yaml
uponor_smatrix:
address: 0x110B
climate:
- platform: uponor_smatrix
address: 0xDE13
name: Thermostat Living Room
Controller/Hub component
------------------------
The main ``uponor_smatrix`` component is responsible for the communication with the controller and thermostats and distributes data to the climate and sensor components described below.
It is also able to synchronize the date and time of the thermostats with a time source in case your system has thermostats that can be programmed with a time schedule.
.. code-block:: yaml
uponor_smatrix:
address: 0x110B
uart_id: my_uart
time_id: my_time
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **address** (*Optional*, int): The 16 bit system/controller address. This will be automatically detected from the bus if not specified. See :ref:`uponor-gettingstarted` on how to find the address.
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want to use multiple UART buses.
- **time_id** (*Optional*, :ref:`config-id`): Specify the ID of the :doc:`Time Component <time/index>` to use as the time source if you want ESPHome to automatically synchronize the date and time of the thermostats.
- **time_device_address** (*Optional*, int): The 16 bit device address of the thermostat that keeps the system time. This will be automatically detected from the bus if not specified.
It needs to be the device address of the first thermostat that was paired to the controller, and the one where you can manually change the date and time via the buttons on the thermostat.
.. note::
The system address and the address of the thermostat keeping the time will be automatically detected from the bus if not specified in the configuration!
You can safely leave out those parameters in almost all cases.
Climate component
------------------
.. code-block:: yaml
climate:
- platform: uponor_smatrix
address: 0xDE13
name: Thermostat Living Room
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **address** (*Required*, int): The 16 bit device address of the thermostat. See :ref:`uponor-gettingstarted` on how to find the address.
- **uponor_smatrix_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the ``uponor_smatrix`` hub component if you want to use multiple hub components on one ESPHome device.
- All options from :ref:`Climate <config-climate>`.
Sensor component
----------------
.. code-block:: yaml
sensor:
- platform: uponor_smatrix
address: 0xDE13
humidity:
name: Humidity Living Room
temperature:
name: Temperature Living Room
external_temperature:
name: Floor Temperature Living Room
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **address** (*Required*, int): The 16 bit device address of the thermostat. See :ref:`uponor-gettingstarted` on how to find the address.
- **uponor_smatrix_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the ``uponor_smatrix`` hub component if you want to use multiple hub components on one ESPHome device.
- **humidity** (*Optional*): A sensor reading the current humidity the thermostat reports.
All options from :ref:`Sensor <config-sensor>`.
- **temperature** (*Optional*): A sensor reading the current temperature the thermostat reports.
All options from :ref:`Sensor <config-sensor>`.
- **external_temperature** (*Optional*): A sensor reading the current external temperature the thermostat reports.
This comes from an optionally attached external temperature sensor that can measure the floor or outdoor temperature.
All options from :ref:`Sensor <config-sensor>`.
See Also
--------
- `Protocol Analysis <https://github.com/kroimon/uponor-smatrix-analysis>`__
- :apiref:`uponor_smatrix/uponor_smatrix.h`
- :ghedit:`Edit`

4
images/uponor.svg Normal file
View File

@ -0,0 +1,4 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" version="1.0" width="105" height="27" viewBox="-0.561 -0.624 105 27" id="svg2217" xml:space="preserve">
<g id="g2241"><path d="M 26.743,0 C 22.23,0 18.574,3.659 18.574,8.171 L 18.574,11.094 L 18.572,11.094 L 18.572,23.803 C 18.572,24.807 19.387,25.62 20.387,25.62 L 22.201,25.62 C 23.206,25.62 24.02,24.807 24.02,23.803 L 24.02,19.707 C 24.871,20.009 25.786,20.172 26.742,20.172 C 31.256,20.172 34.913,16.514 34.913,12.002 L 34.913,8.171 C 34.914,3.659 31.257,0 26.743,0 M 29.467,13.818 C 29.467,15.322 28.246,16.541 26.743,16.541 C 25.239,16.541 24.021,15.322 24.021,13.818 L 24.021,6.357 C 24.021,4.852 25.239,3.631 26.743,3.631 C 28.246,3.631 29.467,4.852 29.467,6.357 L 29.467,13.818 z " style="fill: rgb(0, 116, 190); fill-rule: evenodd;" id="path2221"/><path d="M 14.522,0 L 12.707,0 C 11.704,0 10.893,0.813 10.893,1.816 L 10.893,13.818 C 10.893,15.322 9.673,16.541 8.168,16.541 C 6.665,16.541 5.445,15.322 5.445,13.818 L 5.445,1.816 C 5.445,0.813 4.633,0 3.63,0 L 1.815,0 C 0.813,0 0,0.813 0,1.816 L 0,12.002 C 0,16.514 3.657,20.172 8.168,20.172 C 12.68,20.172 16.338,16.514 16.338,12.002 L 16.338,1.816 C 16.338,0.813 15.524,0 14.522,0" style="fill: rgb(0, 116, 190); fill-rule: evenodd;" id="path2223"/><path d="M 101.95,0 L 101.041,0 C 96.528,0 92.873,3.659 92.873,8.171 L 92.873,18.357 C 92.873,19.359 93.683,20.172 94.687,20.172 L 96.503,20.172 C 97.504,20.172 98.315,19.359 98.315,18.357 L 98.315,6.357 C 98.315,4.852 99.536,3.631 101.041,3.631 L 101.95,3.631 C 102.952,3.631 103.764,2.819 103.764,1.816 C 103.764,0.813 102.952,0 101.95,0" style="fill: rgb(0, 116, 190); fill-rule: evenodd;" id="path2225"/><path d="M 82.467,0 C 77.956,0 74.296,3.659 74.296,8.171 L 74.296,12.002 C 74.296,16.514 77.956,20.172 82.467,20.172 C 86.978,20.172 90.638,16.514 90.638,12.002 L 90.638,8.171 C 90.638,3.659 86.978,0 82.467,0 M 85.188,13.818 C 85.188,15.322 83.97,16.541 82.466,16.541 C 80.961,16.541 79.742,15.322 79.742,13.818 L 79.742,6.357 C 79.742,4.852 80.961,3.631 82.466,3.631 C 83.97,3.631 85.188,4.852 85.188,6.357 L 85.188,13.818 z " style="fill: rgb(0, 116, 190); fill-rule: evenodd;" id="path2227"/><path d="M 63.892,0 C 59.379,0 55.722,3.659 55.722,8.171 L 55.722,18.357 C 55.722,19.359 56.535,20.172 57.539,20.172 L 59.353,20.172 C 60.356,20.172 61.169,19.359 61.169,18.357 L 61.169,6.357 C 61.169,4.852 62.388,3.631 63.891,3.631 C 65.395,3.631 66.616,4.852 66.616,6.357 L 66.616,18.357 C 66.616,19.359 67.429,20.172 68.43,20.172 L 70.245,20.172 C 71.251,20.172 72.062,19.359 72.062,18.357 L 72.062,8.171 C 72.063,3.659 68.405,0 63.892,0" style="fill: rgb(0, 116, 190); fill-rule: evenodd;" id="path2231"/><path d="M 45.317,0 C 40.806,0 37.149,3.659 37.149,8.171 L 37.149,12.002 C 37.149,16.514 40.806,20.172 45.317,20.172 C 49.831,20.172 53.488,16.514 53.488,12.002 L 53.488,8.171 C 53.488,3.659 49.831,0 45.317,0 M 48.041,13.818 C 48.041,15.322 46.821,16.541 45.317,16.541 C 43.814,16.541 42.593,15.322 42.593,13.818 L 42.593,6.357 C 42.593,4.852 43.814,3.631 45.317,3.631 C 46.821,3.631 48.041,4.852 48.041,6.357 L 48.041,13.818 z " style="fill: rgb(0, 116, 190); fill-rule: evenodd;" id="path2233"/></g>
</svg>

After

Width:  |  Height:  |  Size: 3.2 KiB

View File

@ -749,6 +749,7 @@ Climate Components
Anova Cooker, components/climate/anova, anova.png
BedJet Climate System, components/climate/bedjet, bedjet.png
Haier Climate, components/climate/haier, haier.svg
Uponor Smatrix Base Pulse Underfloor Heating, components/uponor_smatrix, uponor.svg
Number Components
-----------------