Current-gen-schema (#2887)
* fix enum docs style * schema fixes updates for 2023.2 * support multi key prop * format fixes * Format fixes * set typed * fix code quotes * add platforms --------- Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
This commit is contained in:
parent
12f9aefeed
commit
0b041128a6
|
@ -5,7 +5,7 @@ Haier Climate
|
||||||
:description: Instructions for setting up a Haier climate devices.
|
:description: Instructions for setting up a Haier climate devices.
|
||||||
:image: air-conditioner.svg
|
:image: air-conditioner.svg
|
||||||
|
|
||||||
The `haier` climate platform creates a Haier climate device.
|
The ``haier`` climate platform creates a Haier climate device.
|
||||||
The component can be used as a replacement of a Haier proprietary WiFi modules such as KZW-W001 and KZW-W002.
|
The component can be used as a replacement of a Haier proprietary WiFi modules such as KZW-W001 and KZW-W002.
|
||||||
|
|
||||||
This component requires a :ref:`uart` to be setup.
|
This component requires a :ref:`uart` to be setup.
|
||||||
|
@ -33,7 +33,7 @@ Configuration variables:
|
||||||
|
|
||||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||||
- **name** (**Required**, string): The name of the climate device.
|
- **name** (**Required**, string): The name of the climate device.
|
||||||
- **update_interval** (*Optional*, :ref:`config-time`): How often device will be polled for status. Defaults to `5s`.
|
- **update_interval** (*Optional*, :ref:`config-time`): How often device will be polled for status. Defaults to ``5s``.
|
||||||
- **supported_swing_modes** (*Optional*, list): List of supported swing modes. Possible values are: ``VERTICAL``, ``HORIZONTAL``, ``BOTH``.
|
- **supported_swing_modes** (*Optional*, list): List of supported swing modes. Possible values are: ``VERTICAL``, ``HORIZONTAL``, ``BOTH``.
|
||||||
- All other options from :ref:`Climate <config-climate>`.
|
- All other options from :ref:`Climate <config-climate>`.
|
||||||
|
|
||||||
|
@ -42,10 +42,10 @@ Hardware setup
|
||||||
|
|
||||||
Most units will have a dedicated USB-A port for Haier WiFi module.
|
Most units will have a dedicated USB-A port for Haier WiFi module.
|
||||||
The physical USB port is in fact UART and does not "speak" USB protocol.
|
The physical USB port is in fact UART and does not "speak" USB protocol.
|
||||||
It uses four USB pins as 5V, GND, RX, TX.
|
It uses four USB pins as 5V, GND, RX, TX.
|
||||||
You can use spare male USB cable to connect esphome device directly to the climate appliance.
|
You can use spare male USB cable to connect esphome device directly to the climate appliance.
|
||||||
|
|
||||||
Other units will not have USB ports, but will still probably have UART exposed somewhere on the main board.
|
Other units will not have USB ports, but will still probably have UART exposed somewhere on the main board.
|
||||||
|
|
||||||
.. list-table:: Haier UART pinout
|
.. list-table:: Haier UART pinout
|
||||||
:header-rows: 1
|
:header-rows: 1
|
||||||
|
|
|
@ -52,8 +52,8 @@ Configuration variables:
|
||||||
- **temperature_step** (*Optional*, float): The granularity with which the target temperature
|
- **temperature_step** (*Optional*, float): The granularity with which the target temperature
|
||||||
can be controlled. Can be a single number, or split as below:
|
can be controlled. Can be a single number, or split as below:
|
||||||
|
|
||||||
- **target_temperature** (**Required**, float)
|
- **target_temperature** (**Required**, float): The granularity for target temperature
|
||||||
- **current_temperature** (**Required**, float)
|
- **current_temperature** (**Required**, float): The granularity for current temperature
|
||||||
|
|
||||||
Advanced options:
|
Advanced options:
|
||||||
|
|
||||||
|
|
|
@ -15,12 +15,12 @@ temperature to a user-specified setpoint.
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
PID is like cruise control in the cars: it keeps the car's speed constant by continuously
|
PID is like cruise control in the cars: it keeps the car's speed constant by continuously
|
||||||
adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill,
|
adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill,
|
||||||
the system notices the load increase thus immediately gives more fuel to the engine; and when it
|
the system notices the load increase thus immediately gives more fuel to the engine; and when it
|
||||||
goes down on the other side of the hill, it notices the load decrease thus reduces or cuts off fuel
|
goes down on the other side of the hill, it notices the load decrease thus reduces or cuts off fuel
|
||||||
completely so that car speed remains as constant as possible. The calculation takes in consideration
|
completely so that car speed remains as constant as possible. The calculation takes in consideration
|
||||||
constants like car weight, wind resistance etc.
|
constants like car weight, wind resistance etc.
|
||||||
|
|
||||||
This kind of math can be used for a heating or cooling system too, and an auto-tuning algorithm can help
|
This kind of math can be used for a heating or cooling system too, and an auto-tuning algorithm can help
|
||||||
determining such constants, which mainly describe the heat loss of the room or building. Goal is to
|
determining such constants, which mainly describe the heat loss of the room or building. Goal is to
|
||||||
keep the temperature as constant as possible, and smooth out oscillations otherwise produced by
|
keep the temperature as constant as possible, and smooth out oscillations otherwise produced by
|
||||||
|
@ -47,12 +47,12 @@ but there's a nice article explaining the function principle `here <https://blog
|
||||||
deadband_parameters:
|
deadband_parameters:
|
||||||
threshold_high: 0.5°C # deadband within +/-0.5°C of target_temperature
|
threshold_high: 0.5°C # deadband within +/-0.5°C of target_temperature
|
||||||
threshold_low: -0.5°C
|
threshold_low: -0.5°C
|
||||||
|
|
||||||
Configuration variables:
|
Configuration variables:
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current
|
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current
|
||||||
temperature.
|
temperature.
|
||||||
- **default_target_temperature** (**Required**, float): The default target temperature (setpoint)
|
- **default_target_temperature** (**Required**, float): The default target temperature (setpoint)
|
||||||
for the control algorithm. This can be dynamically set in the frontend later.
|
for the control algorithm. This can be dynamically set in the frontend later.
|
||||||
- **heat_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output <config-output>`
|
- **heat_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output <config-output>`
|
||||||
|
@ -72,37 +72,35 @@ Configuration variables:
|
||||||
``ki`` to prevent windup. Defaults to ``-1``.
|
``ki`` to prevent windup. Defaults to ``-1``.
|
||||||
- **max_integral** (*Optional*, float): The minimum value of the integral term multiplied by
|
- **max_integral** (*Optional*, float): The minimum value of the integral term multiplied by
|
||||||
``ki`` to prevent windup. Defaults to ``1``.
|
``ki`` to prevent windup. Defaults to ``1``.
|
||||||
- **starting_integral_term** (*Optional*, float): Set the initial output, by priming the integral
|
- **starting_integral_term** (*Optional*, float): Set the initial output, by priming the integral
|
||||||
term. This is useful for when your system is rebooted and you don't want to wait
|
term. This is useful for when your system is rebooted and you don't want to wait
|
||||||
for it to get back equilibrium.
|
for it to get back equilibrium.
|
||||||
|
|
||||||
- **output_averaging_samples** (*Optional*, int): average the output over this many samples. PID controllers
|
- **output_averaging_samples** (*Optional*, int): average the output over this many samples. PID controllers
|
||||||
can be quite sensitive to small changes on the input sensor. By averaging the last X output samples,
|
can be quite sensitive to small changes on the input sensor. By averaging the last X output samples,
|
||||||
the temperature can be more stable. However, the larger the sampling window, the less responsive the
|
the temperature can be more stable. However, the larger the sampling window, the less responsive the
|
||||||
PID controller. Defaults to ``1`` which is no sampling/averaging.
|
PID controller. Defaults to ``1`` which is no sampling/averaging.
|
||||||
|
|
||||||
- **derivative_averaging_samples** (*Optional*, int): average the derivative term over this many samples. Many
|
- **derivative_averaging_samples** (*Optional*, int): average the derivative term over this many samples. Many
|
||||||
controllers don't use the derivative term because it is sensitive to slight changes in the input sensor.
|
controllers don't use the derivative term because it is sensitive to slight changes in the input sensor.
|
||||||
By taking an average of the derivative term it might become more useful for you. Most PID controllers call
|
By taking an average of the derivative term it might become more useful for you. Most PID controllers call
|
||||||
this derivative filtering. The derivative term is used to pre-act so don't filter too much. Defaults to ``1``
|
this derivative filtering. The derivative term is used to pre-act so don't filter too much. Defaults to ``1``
|
||||||
which is no sampling/averaging.
|
which is no sampling/averaging.
|
||||||
|
|
||||||
- **deadband_parameters** (*Optional*): Enables a deadband to stabilise and minimise changes in the
|
- **deadband_parameters** (*Optional*): Enables a deadband to stabilise and minimise changes in the
|
||||||
output when the temperature is close to the target temperature. See `Deadband Setup`_.
|
output when the temperature is close to the target temperature. See `Deadband Setup`_.
|
||||||
|
|
||||||
- **threshold_low/threshold_high** (**Required**, float): Specifies a high/low
|
- **threshold_high/threshold_low** (**Required**, float): Specifies a high/low
|
||||||
threshold defining the deadband
|
threshold defining the deadband around the target temperature. For instance with
|
||||||
around the target temperature. For instance with `default_target_temperature` of ``21°C`` and
|
``default_target_temperature`` of ``21°C`` and thresholds of ``+/-0.5°C``, the deadband will be
|
||||||
thresholds of ``+/-0.5°C``, the deadband will be
|
|
||||||
between ``20.5°C - 21.5°C``. The PID controller will limit output changes within the deadband.
|
between ``20.5°C - 21.5°C``. The PID controller will limit output changes within the deadband.
|
||||||
|
- **kp_multiplier** (*Optional*, float): Set the ``kp`` gain when inside the deadband. Defaults to ``0``.
|
||||||
|
- **ki_multiplier** (*Optional*, float): Set the ``ki`` gain when inside the deadband. Defaults to ``0``.
|
||||||
|
- **kd_multiplier** (*Optional*, float): Set the ``kd`` gain when inside the deadband. Recommended this
|
||||||
|
is set to ``0``. Defaults to ``0``.
|
||||||
|
|
||||||
- **kp_multiplier** (**Optional**, float): Set the ``kp`` gain when inside the deadband. Defaults to ``0``.
|
- **deadband_output_averaging_samples** (*Optional*, int): Typically when inside the deadband the PID Controller has
|
||||||
- **ki_multiplier** (**Optional**, float): Set the ``ki`` gain when inside the deadband. Defaults to ``0``.
|
reached a state of equilibrium, so it advantageous to use a higher number of output samples
|
||||||
- **kd_multiplier** (**Optional**, float): Set the ``kd`` gain when inside the deadband. Recommended this
|
|
||||||
is set to 0. Defaults to ``0``.
|
|
||||||
|
|
||||||
- **deadband_output_averaging_samples** (**Optional**, int): Typically when inside the deadband the PID Controller has
|
|
||||||
reached a state of equilibrium, so it advantageous to use a higher number of output samples
|
|
||||||
like 10-30 samples. Defaults to ``1`` which is no sampling/averaging.
|
like 10-30 samples. Defaults to ``1`` which is no sampling/averaging.
|
||||||
|
|
||||||
- All other options from :ref:`Climate <config-climate>`.
|
- All other options from :ref:`Climate <config-climate>`.
|
||||||
|
@ -116,7 +114,7 @@ To set up a PID climate controller, you need a couple of components:
|
||||||
|
|
||||||
- A :ref:`Sensor <config-sensor>` to read the current temperature (``sensor``).
|
- A :ref:`Sensor <config-sensor>` to read the current temperature (``sensor``).
|
||||||
- At least one :ref:`float output <config-output>` to drive for heating or cooling (or both).
|
- At least one :ref:`float output <config-output>` to drive for heating or cooling (or both).
|
||||||
This could for example be a PWM output via :doc:`/components/output/sigma_delta` or :doc:`/components/output/slow_pwm` that drives a heating unit.
|
This could for example be a PWM output via :doc:`/components/output/sigma_delta_output` or :doc:`/components/output/slow_pwm` that drives a heating unit.
|
||||||
|
|
||||||
Please note the output *must* be controllable with continuous value (not only ON/OFF, but any state
|
Please note the output *must* be controllable with continuous value (not only ON/OFF, but any state
|
||||||
in between for example 50% heating power).
|
in between for example 50% heating power).
|
||||||
|
@ -126,22 +124,22 @@ To set up a PID climate controller, you need a couple of components:
|
||||||
The sensor should have a short update interval. The PID update frequency is tied to the update
|
The sensor should have a short update interval. The PID update frequency is tied to the update
|
||||||
interval of the sensor. Set a short ``update_interval`` like ``5s`` on the sensor.
|
interval of the sensor. Set a short ``update_interval`` like ``5s`` on the sensor.
|
||||||
|
|
||||||
We recommend putting a filter on the sensor (see filters in :doc:`/components/sensor/index`) and
|
We recommend putting a filter on the sensor (see filters in :doc:`/components/sensor/index`) and
|
||||||
using ``output_averaging_samples`` to calm the PID sensor from a noisy input sensor.
|
using ``output_averaging_samples`` to calm the PID sensor from a noisy input sensor.
|
||||||
|
|
||||||
Deadband Setup
|
Deadband Setup
|
||||||
--------------
|
--------------
|
||||||
A deadband is used to prevent the PID controller from further adjusting the power
|
A deadband is used to prevent the PID controller from further adjusting the power
|
||||||
once the temperature has settled within a range of the target temperature.
|
once the temperature has settled within a range of the target temperature.
|
||||||
|
|
||||||
We do this by specifying a high/low threshold of the target temperature.
|
We do this by specifying a high/low threshold of the target temperature.
|
||||||
|
|
||||||
To understand the benefit, consider a heating/cooling HVAC which is constantly
|
To understand the benefit, consider a heating/cooling HVAC which is constantly
|
||||||
oscillating between heating and cooling as the thermostat records very minor
|
oscillating between heating and cooling as the thermostat records very minor
|
||||||
changes from +0.1º to -0.1º. Clearly this is undesirable and will cause wear
|
changes from +0.1º to -0.1º. Clearly this is undesirable and will cause wear
|
||||||
and tear as the HVAC oscillates. With a deadband in place the heater won't
|
and tear as the HVAC oscillates. With a deadband in place the heater won't
|
||||||
activate until the thermostat breaches the low_threshold and the cooler won't activate
|
activate until the thermostat breaches the low_threshold and the cooler won't activate
|
||||||
until the thermostat breaches the high_threshold.
|
until the thermostat breaches the high_threshold.
|
||||||
|
|
||||||
The most basic setup specifies the threshold around the target temperature as follows:
|
The most basic setup specifies the threshold around the target temperature as follows:
|
||||||
|
|
||||||
|
@ -153,7 +151,7 @@ The most basic setup specifies the threshold around the target temperature as fo
|
||||||
threshold_high: 0.5°C
|
threshold_high: 0.5°C
|
||||||
threshold_low: -1.0°C
|
threshold_low: -1.0°C
|
||||||
|
|
||||||
In this example the deadband is between ``20.0°C - 21.5°C``. The PID controller will limit any output
|
In this example the deadband is between ``20.0°C - 21.5°C``. The PID controller will limit any output
|
||||||
variation inside this deadband. How it limits depends on how you set the `Deadband Multipliers`_.
|
variation inside this deadband. How it limits depends on how you set the `Deadband Multipliers`_.
|
||||||
|
|
||||||
.. figure:: images/deadband1.png
|
.. figure:: images/deadband1.png
|
||||||
|
@ -161,19 +159,19 @@ variation inside this deadband. How it limits depends on how you set the `Deadba
|
||||||
Deadband Multipliers
|
Deadband Multipliers
|
||||||
********************
|
********************
|
||||||
|
|
||||||
Deadband Multipliers tell the controller how to operate when inside of the deadband.
|
Deadband Multipliers tell the controller how to operate when inside of the deadband.
|
||||||
|
|
||||||
Each of the p,i and d terms can be controlled using the kp, ki and kd multipliers. For instance, if the kp_multiplier
|
Each of the p,i and d terms can be controlled using the kp, ki and kd multipliers. For instance, if the kp_multiplier
|
||||||
is set to 0.05 then the final proportional term will be set to 5% of its normal value within the deadband.
|
is set to 0.05 then the final proportional term will be set to 5% of its normal value within the deadband.
|
||||||
|
|
||||||
If all of the multipliers are set to 0, then the controller will not adjust power at all within the
|
If all of the multipliers are set to 0, then the controller will not adjust power at all within the
|
||||||
deadband. This is the default behavior.
|
deadband. This is the default behavior.
|
||||||
|
|
||||||
Most deadband implementations set kp and ki multipliers to a small gain like ``0.05`` and set
|
Most deadband implementations set kp and ki multipliers to a small gain like ``0.05`` and set
|
||||||
derivative to 0. This means that the PID output will calmly make minor adjustments over a 20x longer
|
derivative to 0. This means that the PID output will calmly make minor adjustments over a 20x longer
|
||||||
timeframe to stay within the deadband zone.
|
timeframe to stay within the deadband zone.
|
||||||
|
|
||||||
To start with we recommend just setting the ``ki_multiplier`` to ``0.05`` (5%). Then
|
To start with we recommend just setting the ``ki_multiplier`` to ``0.05`` (5%). Then
|
||||||
set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the deadband too often.
|
set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the deadband too often.
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
@ -184,7 +182,7 @@ set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the d
|
||||||
threshold_high: 0.5°C
|
threshold_high: 0.5°C
|
||||||
threshold_low: -1.0°C
|
threshold_low: -1.0°C
|
||||||
kp_multiplier: 0.0 # proportional gain turned off inside deadband
|
kp_multiplier: 0.0 # proportional gain turned off inside deadband
|
||||||
ki_multiplier: 0.05 # integral accumulates at only 5% of normal ki
|
ki_multiplier: 0.05 # integral accumulates at only 5% of normal ki
|
||||||
kd_multiplier: 0.0 # derviative is turned off inside deadband
|
kd_multiplier: 0.0 # derviative is turned off inside deadband
|
||||||
deadband_output_averaging_samples: 15 # average the output over 15 samples within the deadband
|
deadband_output_averaging_samples: 15 # average the output over 15 samples within the deadband
|
||||||
|
|
||||||
|
@ -192,8 +190,8 @@ set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the d
|
||||||
|
|
||||||
Deadband Output Averaging Samples
|
Deadband Output Averaging Samples
|
||||||
*********************************
|
*********************************
|
||||||
Since we expect the PID Controller to be at equilibrium while inside the deadband, we can
|
Since we expect the PID Controller to be at equilibrium while inside the deadband, we can
|
||||||
average the output over a longer range of samples, like 15 samples. This helps even further
|
average the output over a longer range of samples, like 15 samples. This helps even further
|
||||||
with temperature and controller stability.
|
with temperature and controller stability.
|
||||||
|
|
||||||
.. _pid-autotune:
|
.. _pid-autotune:
|
||||||
|
@ -249,7 +247,7 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat
|
||||||
device can reach. For example if the temperature of a room is to be controlled, the setpoint needs
|
device can reach. For example if the temperature of a room is to be controlled, the setpoint needs
|
||||||
to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the
|
to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the
|
||||||
climate device should be set to at least ~24°C so that an oscillation can be induced.
|
climate device should be set to at least ~24°C so that an oscillation can be induced.
|
||||||
|
|
||||||
Also take care of external influences, like for example when room temperature is severely affected by
|
Also take care of external influences, like for example when room temperature is severely affected by
|
||||||
outdoor weather like sun, if it starts to warm up the room in parallel with the heating
|
outdoor weather like sun, if it starts to warm up the room in parallel with the heating
|
||||||
autotune will likely fail or give false results.
|
autotune will likely fail or give false results.
|
||||||
|
@ -273,10 +271,10 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
In the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C.
|
In the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C.
|
||||||
|
|
||||||
This will continue for some time until data for 3 phases (6 crossings of the setpoint; or a bit more, depending on
|
This will continue for some time until data for 3 phases (6 crossings of the setpoint; or a bit more, depending on
|
||||||
the data quality) have been acquired.
|
the data quality) have been acquired.
|
||||||
|
|
||||||
The autotune algorithm may take a long time to complete, it depends on the time needed to reproduce the
|
The autotune algorithm may take a long time to complete, it depends on the time needed to reproduce the
|
||||||
heating up and cooling down oscillations the required number of times.
|
heating up and cooling down oscillations the required number of times.
|
||||||
|
|
||||||
|
@ -298,7 +296,7 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat
|
||||||
|
|
||||||
As soon as the the autotune procedure finishes, the climate starts to work with the calculated parameters
|
As soon as the the autotune procedure finishes, the climate starts to work with the calculated parameters
|
||||||
so that expected operation can be immediately verified.
|
so that expected operation can be immediately verified.
|
||||||
|
|
||||||
If satisfied, copy the values in ``control_parameters`` into your configuration:
|
If satisfied, copy the values in ``control_parameters`` into your configuration:
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
@ -349,7 +347,7 @@ Configuration variables:
|
||||||
Defaults to ``-1.0``.
|
Defaults to ``-1.0``.
|
||||||
|
|
||||||
The ``positive_output`` and ``negative_output`` parameters can be used to compensate the heating or the
|
The ``positive_output`` and ``negative_output`` parameters can be used to compensate the heating or the
|
||||||
cooling process during the autotune, in the cases when they are not changing the temperature at the
|
cooling process during the autotune, in the cases when they are not changing the temperature at the
|
||||||
same rate, resulting in a not symmetrical oscillation. The autotune result will print a message when
|
same rate, resulting in a not symmetrical oscillation. The autotune result will print a message when
|
||||||
it's recommended to repeat the entire procedure with such parameters configured.
|
it's recommended to repeat the entire procedure with such parameters configured.
|
||||||
|
|
||||||
|
@ -435,7 +433,7 @@ See Also
|
||||||
- Åström, K. J. and T. Hägglund (1984a), 'Automatic tuning of simple regulators',
|
- Åström, K. J. and T. Hägglund (1984a), 'Automatic tuning of simple regulators',
|
||||||
Proceedings of IFAC 9th World Congress, Budapest, 1867-1872
|
Proceedings of IFAC 9th World Congress, Budapest, 1867-1872
|
||||||
- :doc:`/components/climate/index`
|
- :doc:`/components/climate/index`
|
||||||
- :doc:`/components/output/sigma_delta`
|
- :doc:`/components/output/sigma_delta_output`
|
||||||
- :doc:`/components/output/slow_pwm`
|
- :doc:`/components/output/slow_pwm`
|
||||||
- `Principles of PID <https://blog.opticontrols.com/archives/344>`__
|
- `Principles of PID <https://blog.opticontrols.com/archives/344>`__
|
||||||
- :apiref:`pid/pid_climate.h`
|
- :apiref:`pid/pid_climate.h`
|
||||||
|
|
|
@ -7,8 +7,8 @@ Matrix keypad
|
||||||
:description: Matrix key input panel
|
:description: Matrix key input panel
|
||||||
|
|
||||||
The ``matrix_keypad`` component allows you to integrate pads which
|
The ``matrix_keypad`` component allows you to integrate pads which
|
||||||
have the keys connected at the intersection points of the rows and columns
|
have the keys connected at the intersection points of the rows and columns
|
||||||
of a matrix.
|
of a matrix.
|
||||||
|
|
||||||
.. figure:: ../images/matrix_keypad.jpg
|
.. figure:: ../images/matrix_keypad.jpg
|
||||||
:align: center
|
:align: center
|
||||||
|
@ -44,14 +44,14 @@ Configuration variables:
|
||||||
- **columns** (**Required**, list): A list of :ref:`pins <config-pin_schema>` where the vertical
|
- **columns** (**Required**, list): A list of :ref:`pins <config-pin_schema>` where the vertical
|
||||||
matrix lines are connected, in order from left to right. These pins need to be input capable
|
matrix lines are connected, in order from left to right. These pins need to be input capable
|
||||||
with pullups enabled. If there is no internal pullup, then an external one is required.
|
with pullups enabled. If there is no internal pullup, then an external one is required.
|
||||||
- **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right,
|
- **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right,
|
||||||
row by row. Required for ``key_collector`` and ``binary_sensor`` (if using key selection).
|
row by row. Required for ``key_collector`` and ``binary_sensor`` (if using key selection).
|
||||||
- **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are
|
- **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are
|
||||||
connected with diodes. Defaults to ``false``.
|
connected with diodes. Defaults to ``false``.
|
||||||
|
|
||||||
|
|
||||||
Binary Sensors
|
Binary Sensor
|
||||||
--------------
|
-------------
|
||||||
|
|
||||||
Individual keys can be added independently to ESPHome as ``binary_sensor``:
|
Individual keys can be added independently to ESPHome as ``binary_sensor``:
|
||||||
|
|
||||||
|
@ -82,7 +82,7 @@ Either the ``row`` and ``col`` parameters, or the ``key`` parameter has to be pr
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Automatic handling of multiple keys (e.g. PIN code entry) is possible with the
|
Automatic handling of multiple keys (e.g. PIN code entry) is possible with the
|
||||||
the :ref:`Key Collector <key_collector>` component.
|
the :ref:`Key Collector <key_collector>` component.
|
||||||
|
|
||||||
See Also
|
See Also
|
||||||
|
|
|
@ -48,7 +48,7 @@ Configuration variables:
|
||||||
- **disabled** (*Optional*, boolean): Set to true to disable mDNS usage. Defaults to false.
|
- **disabled** (*Optional*, boolean): Set to true to disable mDNS usage. Defaults to false.
|
||||||
- **services** (*Optional*, list): List of additional services to expose.
|
- **services** (*Optional*, list): List of additional services to expose.
|
||||||
|
|
||||||
- **service** (*Required*, string): Name of extra service
|
- **service** (**Required**, string): Name of extra service.
|
||||||
- **protocol** (*Required*, string): Protocol of service (_udp or _tcp)
|
- **protocol** (**Required**, string): Protocol of service (_udp or _tcp).
|
||||||
- **port** (*Optional*, int): Port number of extra service
|
- **port** (*Optional*, int): Port number of extra service.
|
||||||
- **txt** (*Optional*, mapping): Additional text records to add to service
|
- **txt** (*Optional*, mapping): Additional text records to add to service.
|
||||||
|
|
|
@ -98,7 +98,7 @@ This action turns the output with the given ID off when executed.
|
||||||
***************************
|
***************************
|
||||||
|
|
||||||
This action sets the float output to the given level when executed. Note: This only
|
This action sets the float output to the given level when executed. Note: This only
|
||||||
works with floating point outputs like :doc:`/components/output/esp8266_pwm`, :doc:`/components/output/ledc`, :doc:`/components/output/sigma_delta`, :doc:`/components/output/slow_pwm`.
|
works with floating point outputs like :doc:`/components/output/esp8266_pwm`, :doc:`/components/output/ledc`, :doc:`/components/output/sigma_delta_output`, :doc:`/components/output/slow_pwm`.
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
|
|
@ -70,7 +70,7 @@ Example:
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
If the duty cycle is not constrained to a maximum value, the
|
If the duty cycle is not constrained to a maximum value, the
|
||||||
:doc:`/components/output/sigma_delta` component offers faster updates and
|
:doc:`/components/output/sigma_delta_output` component offers faster updates and
|
||||||
greater control over the switching frequency. This is better for loads that
|
greater control over the switching frequency. This is better for loads that
|
||||||
need some time to fully change between on and off, like eletric thermal
|
need some time to fully change between on and off, like eletric thermal
|
||||||
actuator heads or fans.
|
actuator heads or fans.
|
||||||
|
@ -81,7 +81,7 @@ See Also
|
||||||
- :doc:`/components/output/index`
|
- :doc:`/components/output/index`
|
||||||
- :doc:`/components/output/esp8266_pwm`
|
- :doc:`/components/output/esp8266_pwm`
|
||||||
- :doc:`/components/output/ledc`
|
- :doc:`/components/output/ledc`
|
||||||
- :doc:`/components/output/sigma_delta`
|
- :doc:`/components/output/sigma_delta_output`
|
||||||
- :doc:`/components/light/monochromatic`
|
- :doc:`/components/light/monochromatic`
|
||||||
- :doc:`/components/fan/speed`
|
- :doc:`/components/fan/speed`
|
||||||
- :doc:`/components/power_supply`
|
- :doc:`/components/power_supply`
|
||||||
|
|
|
@ -204,13 +204,13 @@ Remote code selection (exactly one of these has to be included):
|
||||||
- **canalsat**: Trigger on a decoded CanalSat remote code with the given data.
|
- **canalsat**: Trigger on a decoded CanalSat remote code with the given data.
|
||||||
|
|
||||||
- **device** (**Required**, int): The device to trigger on, see dumper output for more info.
|
- **device** (**Required**, int): The device to trigger on, see dumper output for more info.
|
||||||
- **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0``
|
- **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0``
|
||||||
- **command** (**Required**, int): The command to listen for.
|
- **command** (**Required**, int): The command to listen for.
|
||||||
|
|
||||||
- **canalsatld**: Trigger on a decoded CanalSatLD remote code with the given data.
|
- **canalsatld**: Trigger on a decoded CanalSatLD remote code with the given data.
|
||||||
|
|
||||||
- **device** (**Required**, int): The device to trigger on, see dumper output for more info.
|
- **device** (**Required**, int): The device to trigger on, see dumper output for more info.
|
||||||
- **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0``
|
- **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0``
|
||||||
- **command** (**Required**, int): The command to listen for.
|
- **command** (**Required**, int): The command to listen for.
|
||||||
|
|
||||||
- **coolix**: Trigger on a decoded Coolix remote code with the given data.
|
- **coolix**: Trigger on a decoded Coolix remote code with the given data.
|
||||||
|
|
|
@ -122,7 +122,7 @@ This :ref:`action <config-action>` sends a CanalSat infrared remote code to a re
|
||||||
Configuration variables:
|
Configuration variables:
|
||||||
|
|
||||||
- **device** (**Required**, int): The device to send to, see dumper output for more details.
|
- **device** (**Required**, int): The device to send to, see dumper output for more details.
|
||||||
- **address** (**Optional**, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0``
|
- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0``
|
||||||
- **command** (**Required**, int): The command to send.
|
- **command** (**Required**, int): The command to send.
|
||||||
- All other options from :ref:`remote_transmitter-transmit_action`.
|
- All other options from :ref:`remote_transmitter-transmit_action`.
|
||||||
|
|
||||||
|
@ -149,7 +149,7 @@ This :ref:`action <config-action>` sends a CanalSatLD infrared remote code to a
|
||||||
Configuration variables:
|
Configuration variables:
|
||||||
|
|
||||||
- **device** (**Required**, int): The device to send to, see dumper output for more details.
|
- **device** (**Required**, int): The device to send to, see dumper output for more details.
|
||||||
- **address** (**Optional**, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0``
|
- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0``
|
||||||
- **command** (**Required**, int): The command to send.
|
- **command** (**Required**, int): The command to send.
|
||||||
- All other options from :ref:`remote_transmitter-transmit_action`.
|
- All other options from :ref:`remote_transmitter-transmit_action`.
|
||||||
|
|
||||||
|
@ -283,7 +283,7 @@ This :ref:`action <config-action>` sends a 40-bit Midea code to a remote transmi
|
||||||
on_...:
|
on_...:
|
||||||
- remote_transmitter.transmit_midea:
|
- remote_transmitter.transmit_midea:
|
||||||
code: [0xA2, 0x08, 0xFF, 0xFF, 0xFF]
|
code: [0xA2, 0x08, 0xFF, 0xFF, 0xFF]
|
||||||
|
|
||||||
on_...:
|
on_...:
|
||||||
- remote_transmitter.transmit_midea:
|
- remote_transmitter.transmit_midea:
|
||||||
code: !lambda |-
|
code: !lambda |-
|
||||||
|
|
|
@ -96,8 +96,8 @@ Configuration variables:
|
||||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||||
- **resolution** (*Optional*, string): the resolution of this sensor. Defaults to ``16 bits``.
|
- **resolution** (*Optional*, string): the resolution of this sensor. Defaults to ``16 bits``.
|
||||||
|
|
||||||
- **16 bits**
|
- ``16 bits``
|
||||||
- **12 bits**
|
- ``12 bits``
|
||||||
|
|
||||||
|
|
||||||
Multiplexer and Gain
|
Multiplexer and Gain
|
||||||
|
@ -105,10 +105,10 @@ Multiplexer and Gain
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
As per (`datasheet <http://www.ti.com/lit/ds/symlink/ads1115.pdf>`__, `Adafruit`_) Section 7.3 Note 2:
|
As per (`datasheet <http://www.ti.com/lit/ds/symlink/ads1115.pdf>`__, `Adafruit`_) Section 7.3 Note 2:
|
||||||
"No more than VDD + 0.3V must be applied to the analog inputs of the device."
|
"No more than VDD + 0.3V must be applied to the analog inputs of the device."
|
||||||
This means if you power the device with 3.3V, take care not to supply the 4 AIN pins with more than 3.6V.
|
This means if you power the device with 3.3V, take care not to supply the 4 AIN pins with more than 3.6V.
|
||||||
|
|
||||||
The ADS1115 has a multiplexer that can be configured to measure voltage between several pin configurations. These are:
|
The ADS1115 has a multiplexer that can be configured to measure voltage between several pin configurations. These are:
|
||||||
|
|
||||||
- ``A0_A1`` (between Pin 0 and Pin 1)
|
- ``A0_A1`` (between Pin 0 and Pin 1)
|
||||||
|
@ -128,11 +128,11 @@ Additionally, the ADS1115 has a Programmable Gain Amplifier (PGA) that can help
|
||||||
- ``1.024`` (measures up to 1.024V)
|
- ``1.024`` (measures up to 1.024V)
|
||||||
- ``0.512`` (measures up to 0.512V)
|
- ``0.512`` (measures up to 0.512V)
|
||||||
- ``0.256`` (measures up to 0.256V)
|
- ``0.256`` (measures up to 0.256V)
|
||||||
|
|
||||||
The ADS1115 can be used with defaults settings.
|
The ADS1115 can be used with defaults settings.
|
||||||
When using an ADS1015, the resolution has to be specified and should be defined to ``12_BITS``
|
When using an ADS1015, the resolution has to be specified and should be defined to ``12_BITS``
|
||||||
(or equivalent notations like ``12 BITS`` or ``12 bits``).
|
(or equivalent notations like ``12 BITS`` or ``12 bits``).
|
||||||
|
|
||||||
See Also
|
See Also
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|
|
@ -36,19 +36,19 @@ The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for thi
|
||||||
Configuration variables:
|
Configuration variables:
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
- **temperature** (*Required*): The information for the Temperature sensor.
|
- **temperature** (**Required**): The information for the Temperature sensor.
|
||||||
|
|
||||||
- **name** (**Required**, string): The name for the temperature sensor.
|
- **name** (**Required**, string): The name for the temperature sensor.
|
||||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||||
- All other options from :ref:`Sensor <config-sensor>`.
|
- All other options from :ref:`Sensor <config-sensor>`.
|
||||||
|
|
||||||
- **co2** (*Required*): The information for the CO₂ sensor.
|
- **co2** (**Required**): The information for the CO₂ sensor.
|
||||||
|
|
||||||
- **name** (**Required**, string): The name for the CO₂eq sensor.
|
- **name** (**Required**, string): The name for the CO₂eq sensor.
|
||||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||||
- All other options from :ref:`Sensor <config-sensor>`.
|
- All other options from :ref:`Sensor <config-sensor>`.
|
||||||
|
|
||||||
- **Pressure** (*Required*): The information for the Pressure sensor.
|
- **pressure** (**Required**): The information for the Pressure sensor.
|
||||||
|
|
||||||
- **name** (**Required**, string): The name for the Pressure sensor.
|
- **name** (**Required**, string): The name for the Pressure sensor.
|
||||||
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
|
||||||
|
|
|
@ -415,7 +415,7 @@ Configuration variables:
|
||||||
``skip_initial``
|
``skip_initial``
|
||||||
****************
|
****************
|
||||||
|
|
||||||
A simple skip filter; `skip_initial: N` skips the first `N` sensor readings and passes on the
|
A simple skip filter; ``skip_initial: N`` skips the first ``N`` sensor readings and passes on the
|
||||||
rest. This can be used when the sensor needs a few readings to 'warm up'. After the initial
|
rest. This can be used when the sensor needs a few readings to 'warm up'. After the initial
|
||||||
readings have been skipped, this filter does nothing.
|
readings have been skipped, this filter does nothing.
|
||||||
|
|
||||||
|
|
|
@ -5,7 +5,7 @@ Kuntze pool monitor
|
||||||
:description: Instructions for setting up Kuntze pool monitor in ESPHome.
|
:description: Instructions for setting up Kuntze pool monitor in ESPHome.
|
||||||
:image: kuntze.jpg
|
:image: kuntze.jpg
|
||||||
|
|
||||||
The ``kuntze`` component allows you to integrate the Kuntze water measurement
|
The ``kuntze`` component allows you to integrate the Kuntze water measurement
|
||||||
instrument in ESPHome. It uses :ref:`UART <uart>` (ModBUS) for communication.
|
instrument in ESPHome. It uses :ref:`UART <uart>` (ModBUS) for communication.
|
||||||
|
|
||||||
Once configured you can use sensors as described below for your projects.
|
Once configured you can use sensors as described below for your projects.
|
||||||
|
@ -19,25 +19,25 @@ Once configured you can use sensors as described below for your projects.
|
||||||
Overview
|
Overview
|
||||||
--------
|
--------
|
||||||
|
|
||||||
Kuntze devices have an RS485 (ModBUS RTU) communication port. Please see the
|
Kuntze devices have an RS485 (ModBUS RTU) communication port. Please see the
|
||||||
Kuntze papers for the pinout of the RS485 connector on your unit. ModBUS line
|
Kuntze papers for the pinout of the RS485 connector on your unit. ModBUS line
|
||||||
has to be terminated properly (with a ``120Ω`` resistor), and since this is likely
|
has to be terminated properly (with a ``120Ω`` resistor), and since this is likely
|
||||||
your only unit connected to ESPHome, you should activate bus termination in the
|
your only unit connected to ESPHome, you should activate bus termination in the
|
||||||
Network menu (this component doesn't support multiple Kuntze devices on the same
|
Network menu (this component doesn't support multiple Kuntze devices on the same
|
||||||
bus). ModBUS address should remain at factory default value.
|
bus). ModBUS address should remain at factory default value.
|
||||||
|
|
||||||
The device communicates at ``19200`` baud ``8E1``. To connect to ESPHome, an RS485
|
The device communicates at ``19200`` baud ``8E1``. To connect to ESPHome, an RS485
|
||||||
transceiver is needed. Choose a type which does not need a trigger to send and
|
transceiver is needed. Choose a type which does not need a trigger to send and
|
||||||
receive data, for example:
|
receive data, for example:
|
||||||
|
|
||||||
.. figure:: ../../images/rs485.jpg
|
.. figure:: ../../images/rs485.jpg
|
||||||
|
|
||||||
The controller connects to the UART of the MCU. For ESP32 GPIO `16` to `TXD` and `17`
|
The controller connects to the UART of the MCU. For ESP32 GPIO `16` to `TXD` and `17`
|
||||||
to RXD are the default ones but any other pins can be used as well. 3.3V to VCC and GND to GND.
|
to RXD are the default ones but any other pins can be used as well. 3.3V to VCC and GND to GND.
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
If you are using the :ref:`logger` make sure you are not using the same pins for it or otherwise disable the UART
|
If you are using the :ref:`logger` make sure you are not using the same pins for it or otherwise disable the UART
|
||||||
logging with the ``baud_rate: 0`` option.
|
logging with the ``baud_rate: 0`` option.
|
||||||
|
|
||||||
Component
|
Component
|
||||||
|
@ -66,14 +66,13 @@ A configured modbus component is optional. It will be automatically created.
|
||||||
|
|
||||||
Configuration variables:
|
Configuration variables:
|
||||||
|
|
||||||
- **ph**: Measured pH value
|
- **ph** (*Optional*): Measured pH value.
|
||||||
- **temperature**: Measured temperature value
|
- **temperature** (*Optional*): Measured temperature value.
|
||||||
- **dis1**: Measured DIS 1 value
|
- **dis1** (*Optional*): Measured DIS 1 value.
|
||||||
- **dis2**: Measured DIS 2 value
|
- **dis2** (*Optional*): Measured DIS 2 value.
|
||||||
- **redox**: Measured Redox value
|
- **redox** (*Optional*): Measured Redox value.
|
||||||
- **ec**: Measured EC value
|
- **ec** (*Optional*): Measured EC value.
|
||||||
- **oci**: Measured OCI value
|
- **oci** (*Optional*): Measured OCI value.
|
||||||
|
|
||||||
|
|
||||||
All sensors are *Optional* and support all other options from :ref:`Sensor <config-sensor>`.
|
All sensors are *Optional* and support all other options from :ref:`Sensor <config-sensor>`.
|
||||||
|
|
||||||
|
|
|
@ -75,7 +75,7 @@ and binary sensors.
|
||||||
Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``.
|
Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``.
|
||||||
- **gX_move_threshold** (*Optional*, int): Threshold for the Xth gate for motion detection (X => 0 to 8).
|
- **gX_move_threshold** (*Optional*, int): Threshold for the Xth gate for motion detection (X => 0 to 8).
|
||||||
Above this level for the considered gate (distance), movement detection will be triggered. Defaults to ``see table below``.
|
Above this level for the considered gate (distance), movement detection will be triggered. Defaults to ``see table below``.
|
||||||
- **gX _still_threshold** (*Optional*, int): Threshold for the Xth gate for still detection. (X => 0 to 8).
|
- **gX_still_threshold** (*Optional*, int): Threshold for the Xth gate for still detection. (X => 0 to 8).
|
||||||
Above this level for the considered gate (distance), still detection will be triggered. Defaults to ``see table below``.
|
Above this level for the considered gate (distance), still detection will be triggered. Defaults to ``see table below``.
|
||||||
|
|
||||||
.. list-table:: Default values for gate threshold
|
.. list-table:: Default values for gate threshold
|
||||||
|
|
|
@ -176,8 +176,8 @@ All binary sensors are *Optional* and support all other options from :ref:`Binar
|
||||||
``Custom`` VBus sensors
|
``Custom`` VBus sensors
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
Devices on a VBus are identified with a source address. There can be multiple devices on the same bus,
|
Devices on a VBus are identified with a source address. There can be multiple devices on the same bus,
|
||||||
each device type has a different address.
|
each device type has a different address.
|
||||||
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
@ -203,7 +203,7 @@ Configuration variables:
|
||||||
- **sensors** (**Required**): A list of :ref:`Sensor <config-sensor>` definitions that include a ``lambda`` to do the decoding and return a ``float`` value.
|
- **sensors** (**Required**): A list of :ref:`Sensor <config-sensor>` definitions that include a ``lambda`` to do the decoding and return a ``float`` value.
|
||||||
|
|
||||||
- **lambda** (**Required**, :ref:`lambda <config-lambda>`): Code to parse a value from the incoming data packets and return it.
|
- **lambda** (**Required**, :ref:`lambda <config-lambda>`): Code to parse a value from the incoming data packets and return it.
|
||||||
The data packet is in a `std::vector<uint8_t>` called `x`.
|
The data packet is in a ``std::vector<uint8_t>`` called ``x``.
|
||||||
|
|
||||||
|
|
||||||
``custom`` VBus binary sensors
|
``custom`` VBus binary sensors
|
||||||
|
@ -218,7 +218,7 @@ Configuration variables:
|
||||||
- **binary_sensors** (**Required**): A list of :ref:`Binary Sensor <config-binary_sensor>` definitions that include a ``lambda`` to do the decoding and return a ``bool`` value.
|
- **binary_sensors** (**Required**): A list of :ref:`Binary Sensor <config-binary_sensor>` definitions that include a ``lambda`` to do the decoding and return a ``bool`` value.
|
||||||
|
|
||||||
- **lambda** (**Required**, :ref:`lambda <config-lambda>`): Code to parse a value from the incoming data packets and return it.
|
- **lambda** (**Required**, :ref:`lambda <config-lambda>`): Code to parse a value from the incoming data packets and return it.
|
||||||
The data packet is in a `std::vector<uint8_t>` called `x`.
|
The data packet is in a ``std::vector<uint8_t>`` called ``x``.
|
||||||
|
|
||||||
To determine the correct values for the parameters above, visit `packet definitions list <http://danielwippermann.github.io/resol-vbus/#/vsf>`__. In the search field of the **Packets** table, enter the name of your device.
|
To determine the correct values for the parameters above, visit `packet definitions list <http://danielwippermann.github.io/resol-vbus/#/vsf>`__. In the search field of the **Packets** table, enter the name of your device.
|
||||||
|
|
||||||
|
|
|
@ -499,7 +499,7 @@ Output Components
|
||||||
BLE Binary Output, components/output/ble_client, bluetooth.svg
|
BLE Binary Output, components/output/ble_client, bluetooth.svg
|
||||||
Modbus Output, components/output/modbus_controller, modbus.png
|
Modbus Output, components/output/modbus_controller, modbus.png
|
||||||
Custom Output, components/output/custom, language-cpp.svg
|
Custom Output, components/output/custom, language-cpp.svg
|
||||||
Sigma-Delta Output, components/output/sigma_delta, sigma-delta.svg
|
Sigma-Delta Output, components/output/sigma_delta_output, sigma-delta.svg
|
||||||
Template Output, components/output/template, description.svg
|
Template Output, components/output/template, description.svg
|
||||||
BP1658CJ, components/output/bp1658cj, bp1658cj.svg
|
BP1658CJ, components/output/bp1658cj, bp1658cj.svg
|
||||||
BP5758D, components/output/bp5758d, bp5758d.svg
|
BP5758D, components/output/bp5758d, bp5758d.svg
|
||||||
|
|
142
schema_doc.py
142
schema_doc.py
|
@ -81,6 +81,8 @@ PLATFORMS_TITLES = {
|
||||||
"Stepper": "stepper",
|
"Stepper": "stepper",
|
||||||
"Switch": "switch",
|
"Switch": "switch",
|
||||||
"I²C": "i2c",
|
"I²C": "i2c",
|
||||||
|
"Media Player": "media_player",
|
||||||
|
"Microphone": "microphone",
|
||||||
}
|
}
|
||||||
|
|
||||||
CUSTOM_DOCS = {
|
CUSTOM_DOCS = {
|
||||||
|
@ -196,6 +198,8 @@ CUSTOM_DOCS = {
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
|
|
||||||
|
REQUIRED_OPTIONAL_TYPE_REGEX = r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s"
|
||||||
|
|
||||||
|
|
||||||
def get_node_title(node):
|
def get_node_title(node):
|
||||||
return list(node.traverse(nodes.title))[0].astext()
|
return list(node.traverse(nodes.title))[0].astext()
|
||||||
|
@ -250,7 +254,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
]
|
]
|
||||||
|
|
||||||
else: # sub component, e.g. output/esp8266_pwm
|
else: # sub component, e.g. output/esp8266_pwm
|
||||||
|
|
||||||
# components here might have a core / hub, eg. dallas, ads1115
|
# components here might have a core / hub, eg. dallas, ads1115
|
||||||
# and then they can be a binary_sensor, sensor, etc.
|
# and then they can be a binary_sensor, sensor, etc.
|
||||||
self.platform = self.path[1]
|
self.platform = self.path[1]
|
||||||
|
@ -775,7 +778,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
and (self.props or self.multi_component)
|
and (self.props or self.multi_component)
|
||||||
and self.bullet_list_level > 1
|
and self.bullet_list_level > 1
|
||||||
):
|
):
|
||||||
|
|
||||||
self.prop_stack.append((self.current_prop, node))
|
self.prop_stack.append((self.current_prop, node))
|
||||||
self.accept_props = True
|
self.accept_props = True
|
||||||
return
|
return
|
||||||
|
@ -844,7 +846,7 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
try:
|
try:
|
||||||
name_type = markdown[: markdown.index(": ") + 2]
|
name_type = markdown[: markdown.index(": ") + 2]
|
||||||
ntr = re.search(
|
ntr = re.search(
|
||||||
r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s",
|
REQUIRED_OPTIONAL_TYPE_REGEX,
|
||||||
name_type,
|
name_type,
|
||||||
re.IGNORECASE,
|
re.IGNORECASE,
|
||||||
)
|
)
|
||||||
|
@ -875,7 +877,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
return markdown
|
return markdown
|
||||||
|
|
||||||
def update_prop(self, node, props):
|
def update_prop(self, node, props):
|
||||||
|
|
||||||
prop_name = None
|
prop_name = None
|
||||||
|
|
||||||
for s_prop, n in self.prop_stack:
|
for s_prop, n in self.prop_stack:
|
||||||
|
@ -901,10 +902,10 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
found = True
|
found = True
|
||||||
if enum_docs:
|
if enum_docs:
|
||||||
enum_docs = enum_docs.strip()
|
enum_docs = enum_docs.strip()
|
||||||
if "values_docs" not in inner:
|
if inner["values"][name] is None:
|
||||||
inner["values_docs"] = {name: enum_docs}
|
inner["values"][name] = {"docs": enum_docs}
|
||||||
else:
|
else:
|
||||||
inner["values_docs"][name] = enum_docs
|
inner["values"][name]["docs"] = enum_docs
|
||||||
statistics.props_documented += 1
|
statistics.props_documented += 1
|
||||||
statistics.enums_good += 1
|
statistics.enums_good += 1
|
||||||
if not found:
|
if not found:
|
||||||
|
@ -941,12 +942,19 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
return prop_name, False
|
return prop_name, False
|
||||||
|
|
||||||
# Example properties formats are:
|
# Example properties formats are:
|
||||||
# **name** (**Required**, string): Long Description...
|
# **prop_name** (**Required**, string): Long Description...
|
||||||
# **name** (*Optional*, string): Long Description... Defaults to ``value``.
|
# **prop_name** (*Optional*, string): Long Description... Defaults to ``value``.
|
||||||
# **name** (*Optional*): Long Description... Defaults to ``value``.
|
# **prop_name** (*Optional*): Long Description... Defaults to ``value``.
|
||||||
|
# **prop_name** can be a list of names separated by / e.g. **name1/name2** (*Optional*) see climate/pid/ threshold_low/threshold_high
|
||||||
|
|
||||||
|
PROP_NAME_REGEX = r"\*\*(\w*(?:/\w*)*)\*\*"
|
||||||
|
|
||||||
|
FULL_ITEM_PROP_NAME_TYPE_REGEX = (
|
||||||
|
r"\* " + PROP_NAME_REGEX + r"\s" + REQUIRED_OPTIONAL_TYPE_REGEX
|
||||||
|
)
|
||||||
|
|
||||||
ntr = re.search(
|
ntr = re.search(
|
||||||
r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s",
|
FULL_ITEM_PROP_NAME_TYPE_REGEX,
|
||||||
name_type,
|
name_type,
|
||||||
re.IGNORECASE,
|
re.IGNORECASE,
|
||||||
)
|
)
|
||||||
|
@ -956,14 +964,14 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
param_type = ntr.group(7)
|
param_type = ntr.group(7)
|
||||||
else:
|
else:
|
||||||
s2 = re.search(
|
s2 = re.search(
|
||||||
r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s",
|
FULL_ITEM_PROP_NAME_TYPE_REGEX,
|
||||||
markdown,
|
markdown,
|
||||||
re.IGNORECASE,
|
re.IGNORECASE,
|
||||||
)
|
)
|
||||||
if s2:
|
if s2:
|
||||||
# this is e.g. when a property has a list inside, and the list inside are the options.
|
# this is e.g. when a property has a list inside, and the list inside are the options.
|
||||||
# just validate **prop_name**
|
# just validate **prop_name**
|
||||||
s3 = re.search(r"\* \*\*(\w*)\*\*:\s", name_type)
|
s3 = re.search(r"\* " + PROP_NAME_REGEX + r"*:\s", name_type)
|
||||||
if s3 is not None:
|
if s3 is not None:
|
||||||
prop_name = s3.group(1)
|
prop_name = s3.group(1)
|
||||||
else:
|
else:
|
||||||
|
@ -977,61 +985,61 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
)
|
)
|
||||||
return prop_name, False
|
return prop_name, False
|
||||||
|
|
||||||
k = str(prop_name)
|
prop_names = str(prop_name)
|
||||||
|
for k in prop_names.split("/"):
|
||||||
|
config_var = props.get(k)
|
||||||
|
|
||||||
config_var = props.get(k)
|
if not config_var:
|
||||||
|
# Create docs for common properties when descriptions are overridden
|
||||||
|
# in the most specific component.
|
||||||
|
|
||||||
if not config_var:
|
if k in [
|
||||||
# Create docs for common properties when descriptions are overridden
|
"id",
|
||||||
# in the most specific component.
|
"name",
|
||||||
|
"internal",
|
||||||
if k in [
|
# i2c
|
||||||
"id",
|
"address",
|
||||||
"name",
|
"i2c_id",
|
||||||
"internal",
|
# polling component
|
||||||
# i2c
|
"update_interval",
|
||||||
"address",
|
# uart
|
||||||
"i2c_id",
|
"uart_id",
|
||||||
# polling component
|
# light
|
||||||
"update_interval",
|
"effects",
|
||||||
# uart
|
"gamma_correct",
|
||||||
"uart_id",
|
"default_transition_length",
|
||||||
# light
|
"flash_transition_length",
|
||||||
"effects",
|
"color_correct",
|
||||||
"gamma_correct",
|
# display
|
||||||
"default_transition_length",
|
"lambda",
|
||||||
"flash_transition_length",
|
"pages",
|
||||||
"color_correct",
|
"rotation",
|
||||||
# display
|
# spi
|
||||||
"lambda",
|
"spi_id",
|
||||||
"pages",
|
"cs_pin",
|
||||||
"rotation",
|
# output (binary/float output)
|
||||||
# spi
|
"inverted",
|
||||||
"spi_id",
|
"power_supply",
|
||||||
"cs_pin",
|
# climate
|
||||||
# output (binary/float output)
|
"receiver_id",
|
||||||
"inverted",
|
|
||||||
"power_supply",
|
|
||||||
# climate
|
|
||||||
"receiver_id",
|
|
||||||
]:
|
|
||||||
config_var = props[k] = {}
|
|
||||||
else:
|
|
||||||
if self.path[1] == "esphome" and k in [
|
|
||||||
# deprecated esphome
|
|
||||||
"platform",
|
|
||||||
"board",
|
|
||||||
"arduino_version",
|
|
||||||
"esp8266_restore_from_flash",
|
|
||||||
]:
|
]:
|
||||||
return prop_name, True
|
config_var = props[k] = {}
|
||||||
return prop_name, False
|
else:
|
||||||
|
if self.path[1] == "esphome" and k in [
|
||||||
|
# deprecated esphome
|
||||||
|
"platform",
|
||||||
|
"board",
|
||||||
|
"arduino_version",
|
||||||
|
"esp8266_restore_from_flash",
|
||||||
|
]:
|
||||||
|
return prop_name, True
|
||||||
|
return prop_name, False
|
||||||
|
|
||||||
desc = markdown[markdown.index(": ") + 2 :].strip()
|
desc = markdown[markdown.index(": ") + 2 :].strip()
|
||||||
if param_type:
|
if param_type:
|
||||||
desc = "**" + param_type + "**: " + desc
|
desc = "**" + param_type + "**: " + desc
|
||||||
|
|
||||||
config_var["docs"] = desc
|
config_var["docs"] = desc
|
||||||
|
|
||||||
statistics.props_documented += 1
|
statistics.props_documented += 1
|
||||||
|
|
||||||
|
@ -1084,7 +1092,11 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
|
|
||||||
def _find_extended(self, component, key):
|
def _find_extended(self, component, key):
|
||||||
for extended in component.get("extends", []):
|
for extended in component.get("extends", []):
|
||||||
schema = self.visitor.get_component_schema(extended).get("schema", {})
|
c = self.visitor.get_component_schema(extended)
|
||||||
|
if c.get("type") == "typed":
|
||||||
|
p = self.visitor.Props(self.visitor, c)
|
||||||
|
return p[key]
|
||||||
|
schema = c.get("schema", {})
|
||||||
for k, cv in schema.get("config_vars", {}).items():
|
for k, cv in schema.get("config_vars", {}).items():
|
||||||
if k == key:
|
if k == key:
|
||||||
return SetObservable(
|
return SetObservable(
|
||||||
|
@ -1124,7 +1136,7 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
|
||||||
)
|
)
|
||||||
|
|
||||||
def _set_typed(self, inner_key, original_dict, key, value):
|
def _set_typed(self, inner_key, original_dict, key, value):
|
||||||
if inner_key == self.component.get("typed_key"):
|
if inner_key == self.component.get("typed_key", "type"):
|
||||||
self.component[key] = value
|
self.component[key] = value
|
||||||
else:
|
else:
|
||||||
for tk, tv in self.component["types"].items():
|
for tk, tv in self.component["types"].items():
|
||||||
|
|
Loading…
Reference in New Issue