Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'current' into next

This commit is contained in:
Jesse Hills 2023-06-15 14:23:43 +12:00
parent e7047e6fe0 323874b76a
commit 369809d257
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
49 changed files with 588 additions and 280 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
changelog/2023.4.0.rst
View File

@ -22,7 +22,7 @@ Voice Assistant
This year is the Year of the Voice for Home Assistant, and ESPHome is charging ahead with this in mind. This year is the Year of the Voice for Home Assistant, and ESPHome is charging ahead with this in mind.
We've added a new :doc:`/components/voice_assistant` component that allows you to use ESPHome devices as an input We've added a new :doc:`/components/voice_assistant` component that allows you to use ESPHome devices as an input
for `assist <https://www.home-assistant.io/docs/assist/>`__ in Home Assistant **2023.5 or later**. for `assist <https://www.home-assistant.io/voice_control/>`__ in Home Assistant **2023.5 or later**.
With this also comes preliminary :doc:`microphone </components/microphone/index>` support, which has been built in a way that multiple With this also comes preliminary :doc:`microphone </components/microphone/index>` support, which has been built in a way that multiple
components, like ``voice_assistant`` can request start / stop of the microphone and get the data. We components, like ``voice_assistant`` can request start / stop of the microphone and get the data. We

5
changelog/2023.5.0.rst
View File

@ -80,6 +80,11 @@ Release 2023.5.4 - May 24
- fix modbus sending FP32_R values :esphomepr:`4882` by :ghuser:`ssieb` - fix modbus sending FP32_R values :esphomepr:`4882` by :ghuser:`ssieb`
- Fix esp32_rmt_led_strip color modes :esphomepr:`4886` by :ghuser:`jesserockz` - Fix esp32_rmt_led_strip color modes :esphomepr:`4886` by :ghuser:`jesserockz`
Release 2023.5.5 - May 29
-------------------------
- Fix version printing not breaking yaml parsing :esphomepr:`4904` by :ghuser:`jesserockz`
Full list of changes Full list of changes
-------------------- --------------------

2
components/captive_portal.rst
View File

@ -16,7 +16,7 @@ After 1 minute of unsuccessful WiFi connection attempts, the ESP will start a Wi
:width: 70.0% :width: 70.0%
In this web interface, you can manually override the WiFi settings of the device (please note In this web interface, you can manually override the WiFi settings of the device (please note
this will be overwritten by any subsequent upload so make sure to also update your YAML configuration). this will be overwritten by any subsequent serial upload so make sure to also update your YAML configuration).
Additionally, you can upload a new firmware file. Additionally, you can upload a new firmware file.

8
components/climate/haier.rst
View File

@ -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

4
components/climate/index.rst
View File

@ -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:

108
components/climate/pid.rst
View File

@ -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`

1
components/cover/custom.rst
View File

@ -30,6 +30,7 @@ two methods:
traits.set_is_assumed_state(false); traits.set_is_assumed_state(false);
traits.set_supports_position(true); traits.set_supports_position(true);
traits.set_supports_tilt(false); traits.set_supports_tilt(false);
traits.set_supports_stop(true);
return traits; return traits;
} }
void control(const CoverCall &call) override { void control(const CoverCall &call) override {

2
components/deep_sleep.rst
View File

@ -32,7 +32,7 @@ even Over The Air updates.
.. note:: .. note::
ESP8266 that have an onboard USB chip (e.g. D1 mini) one the chips' control lines is connected to the RST pin. This enables the flasher can reboot the ESP when required. This may interfere with deep sleep on some devices and prevent the ESP from waking when it's powered through its USB connector. Powering the ESP from a separate 3.3V source connected to the 3.3V pin and GND will solve this issue. In these cases using a USB to TTL adapter will allow you to log ESP activity. Some ESP8266s have an onboard USB chip (e.g. D1 mini) on the chips' control line that is connected to the RST pin. This enables the flasher to reboot the ESP when required. This may interfere with deep sleep on some devices and prevent the ESP from waking when it's powered through its USB connector. Powering the ESP from a separate 3.3V source connected to the 3.3V pin and GND will solve this issue. In these cases, using a USB to TTL adapter will allow you to log ESP activity.
Configuration variables: Configuration variables:
------------------------ ------------------------

4
components/display/ili9xxx.rst
View File

@ -33,7 +33,6 @@ beyond the typical SPI connections, it is better suited for use with the ESP32.
display: display:
- platform: ili9xxx - platform: ili9xxx
model: ili9341 model: ili9341
cs_pin: 14
dc_pin: 27 dc_pin: 27
reset_pin: 33 reset_pin: 33
lambda: |- lambda: |-
@ -48,7 +47,6 @@ Configuration variables:
- ``M5STACK``, ``TFT 2.4``, ``TFT 2.4R`` - ``M5STACK``, ``TFT 2.4``, ``TFT 2.4R``
- ``ILI9341``, ``ILI9342``, ``ILI9481``, ``ILI9486``, ``ILI9488``, ``ST7796`` - ``ILI9341``, ``ILI9342``, ``ILI9481``, ``ILI9486``, ``ILI9488``, ``ST7796``
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin. - **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin. - **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **rotation** (*Optional*): Set the rotation of the display. Everything drawn in the ``lambda:`` will be rotated - **rotation** (*Optional*): Set the rotation of the display. Everything drawn in the ``lambda:`` will be rotated
@ -66,6 +64,7 @@ Configuration variables:
- ``GRAYSCALE`` - ``GRAYSCALE``
- ``IMAGE_ADAPTIVE`` - ``IMAGE_ADAPTIVE``
- **color_palette_images** (*Optional*): A list of image files that will be used to generate the color pallet for the display. This should only be used in conjunction with ``-color_palette: IMAGE_ADAPTIVE`` above. The images will be analysed at compile time and a custom color pallet will be created based on the most commonly occuring colors. A typical setting would be a sample image that represented the fully populated display. This can significantly improve the quality of displayed images. Note that these images are not stored on the ESP device, just the 256byte color pallet created from them. - **color_palette_images** (*Optional*): A list of image files that will be used to generate the color pallet for the display. This should only be used in conjunction with ``-color_palette: IMAGE_ADAPTIVE`` above. The images will be analysed at compile time and a custom color pallet will be created based on the most commonly occuring colors. A typical setting would be a sample image that represented the fully populated display. This can significantly improve the quality of displayed images. Note that these images are not stored on the ESP device, just the 256byte color pallet created from them.
- **dimensions** (*Optional*): Dimensions of the screen with WIDTHxHEIGHT. Usually not needed since ``model:`` has good defaults.
Configuration examples Configuration examples
********************** **********************
@ -140,7 +139,6 @@ To configure an image adaptive color pallet to show greater than 8 bit color dep
display: display:
- platform: ili9xxx - platform: ili9xxx
model: ili9341 model: ili9341
cs_pin: 5
dc_pin: 4 dc_pin: 4
reset_pin: 22 reset_pin: 22
rotation: 90 rotation: 90

10
components/fan/binary.rst
View File

@ -14,10 +14,18 @@ The ``binary`` fan platform lets you represent any binary :ref:`output` as a fan
.. code-block:: yaml .. code-block:: yaml
# Example configuration entry # Example configuration entry
output:
- id: fan_output
platform: gpio
pin: GPIO16
fan: fan:
- platform: binary - platform: binary
output: my_output_1 output: fan_output
name: "Living Room Fan" name: "Living Room Fan"
Configuration variables: Configuration variables:
------------------------ ------------------------

6
components/light/fastled.rst
View File

@ -20,6 +20,12 @@ FastLED Light
- https://github.com/FastLED/FastLED/issues/1322 - https://github.com/FastLED/FastLED/issues/1322
- https://github.com/FastLED/FastLED/issues/1264 - https://github.com/FastLED/FastLED/issues/1264
.. warning::
FastLED does **not** work with ESP-IDF.
For addressable lights, you can use :doc:`esp32_rmt_led_strip`.
.. _fastled-clockless: .. _fastled-clockless:
Clockless Clockless

6
components/light/neopixelbus.rst
View File

@ -5,6 +5,12 @@ NeoPixelBus Light
:description: Instructions for setting up Neopixel addressable lights. :description: Instructions for setting up Neopixel addressable lights.
:image: color_lens.svg :image: color_lens.svg
.. warning::
NeoPixelBus does **not** work with ESP-IDF.
For addressable lights, you can use :doc:`esp32_rmt_led_strip`.
The ``neopixelbus`` light platform allows you to create RGB lights The ``neopixelbus`` light platform allows you to create RGB lights
in ESPHome for an individually addressable lights like NeoPixel or WS2812. in ESPHome for an individually addressable lights like NeoPixel or WS2812.

14
components/matrix_keypad.rst
View File

@ -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

8
components/mdns.rst
View File

@ -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.

2
components/media_player/i2s_audio.rst
View File

@ -1,4 +1,4 @@
I2S Audio Media Player I²S Audio Media Player
====================== ======================
.. seo:: .. seo::

2
components/output/index.rst
View File

@ -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

0
components/output/sigma_delta.rst → components/output/sigma_delta_output.rst
View File

4
components/output/slow_pwm.rst
View File

@ -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`

4
components/prometheus.rst
View File

@ -71,5 +71,9 @@ Set the ``id`` and ``name`` label values of the Prometheus metric for the sensor
See Also See Also
-------- --------
- :doc:`/components/web_server`
- :ref:`api-rest`
- :doc:`/components/http_request`
- :apiref:`prometheus/prometheus_handler.h` - :apiref:`prometheus/prometheus_handler.h`
- `Prometheus <https://prometheus.io/>`__
- :ghedit:`Edit` - :ghedit:`Edit`

4
components/remote_receiver.rst
View File

@ -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.

6
components/remote_transmitter.rst
View File

@ -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 |-

12
components/rtttl.rst
View File

@ -55,7 +55,7 @@ Plays an rtttl tone.
on_...: on_...:
then: then:
- rtttl.play: 'MissionImp:d=16,o=6,b=95:32d,32d#,32d,32d#,32d,32d#,32d,32d#,32d,32d,32d#,32e,32f,32f#,32g,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,a#,g,2d,32p,a#,g,2c#,32p,a#,g,2c,a#5,8c,2p,32p,a#5,g5,2f#,32p,a#5,g5,2f,32p,a#5,g5,2e,d#,8d' - rtttl.play: 'siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e'
Configuration options: Configuration options:
@ -101,15 +101,17 @@ This Condition returns true while playback is active.
Common beeps Common beeps
------------ ------------
You can do your own beep patterns too! Here are a few I made so you can just use right away or tweak them to your You can do your own beep patterns too! Here's a short collection so you can just use right away or tweak them to your like:
like:
.. code-block:: yaml .. code-block:: yaml
two short:d=4,o=5,b=100:16e6,16e6 two_short:d=4,o=5,b=100:16e6,16e6
long:d=1,o=5,b=100:e6 long:d=1,o=5,b=100:e6
siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e
scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b
star_wars:d=16,o=5,b=100:4e,4e,4e,8c,p,g,4e,8c,p,g,4e,4p,4b,4b,4b,8c6,p,g,4d#,8c,p,g,4e,8p
mission_imp:d=16,o=6,b=95:32d,32d#,32d,32d#,32d,32d#,32d,32d#,32d,32d,32d#,32e,32f,32f#,32g,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,a#,g,2d,32p,a#,g,2c#,32p,a#,g,2c,a#5,8c,2p,32p,a#5,g5,2f#,32p,a#5,g5,2f,32p,a#5,g5,2e,d#,8d
mario:d=4,o=5,b=100:16e6,16e6,32p,8e6,16c6,8e6,8g6,8p,8g,8p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,16p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16c7,16p,16c7,16c7,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16d#6,8p,16d6,8p,16c6
Test setup Test setup
@ -120,7 +122,7 @@ E.g. for calling ``rtttl.play`` select the service ``esphome.test_esp8266_rtttl_
.. code-block:: yaml .. code-block:: yaml
song_str: "mario:d=4,o=5,b=100:16e6,16e6,32p,8e6,16c6,8e6,8g6,8p,8g,8p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,16p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16c7,16p,16c7,16c7,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16d#6,8p,16d6,8p,16c6" song_str: 'scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b'
Sample code Sample code
*********** ***********

12
components/sensor/ads1115.rst
View File

@ -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
-------- --------

6
components/sensor/ee895.rst
View File

@ -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.

2
components/sensor/hmc5883l.rst
View File

@ -26,7 +26,7 @@ for this sensor to work.
# Example configuration entry # Example configuration entry
sensor: sensor:
- platform: hmc5883l - platform: hmc5883l
address: 0x68 address: 0x1E
field_strength_x: field_strength_x:
name: "HMC5883L Field Strength X" name: "HMC5883L Field Strength X"
field_strength_y: field_strength_y:

2
components/sensor/index.rst
View File

@ -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.

2
components/sensor/internal_temperature.rst
View File

@ -12,7 +12,7 @@ temperature sensor of the ESP32 and RP2040 chip.
.. note:: .. note::
Some ESP32 variants return a large amount of invalid temperature Some ESP32 variants return a large amount of invalid temperature
values. Invalid measurements are ignored by this component. values, including 53.3°C which equates to a raw value of 128. Invalid measurements are ignored by this component.
.. figure:: images/internal_temperature-ui.png .. figure:: images/internal_temperature-ui.png
:align: center :align: center

29
components/sensor/kuntze.rst
View File

@ -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>`.

2
components/sensor/ld2410.rst
View File

@ -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

2
components/sensor/mics_4514.rst
View File

@ -6,7 +6,7 @@ MiCS 4514 Gas Sensor
:image: mics_4514.jpg :image: mics_4514.jpg
:keywords: MiCS, 4514, MICS-4514 :keywords: MiCS, 4514, MICS-4514
This component exposes the different gas concentration sensors from the `MiCS-4514 <https://www.dfrobot.com/product-2417.html>`__. This component exposes the different gas concentration sensors from the `MiCS-4514 <https://www.dfrobot.com/product-2417.html>`__. This is a differnet sensor than the MICS-4514 being sold on AliExpress.
.. note:: .. note::

2
components/sensor/scd30.rst
View File

@ -6,7 +6,7 @@ SCD30 CO₂, Temperature and Relative Humidity Sensor
:image: scd30.jpg :image: scd30.jpg
The ``scd30`` sensor platform allows you to use your Sensirion SCD30 CO₂ The ``scd30`` sensor platform allows you to use your Sensirion SCD30 CO₂
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/9.5_CO2/Sensirion_CO2_Sensors_SCD30_Datasheet.pdf>`__) sensors with ESPHome. (`datasheet <https://sensirion.com/media/documents/4EAF6AF8/61652C3C/Sensirion_CO2_Sensors_SCD30_Datasheet.pdf>`__) sensors with ESPHome.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
.. figure:: images/scd30.jpg .. figure:: images/scd30.jpg

4
components/sensor/sdp3x.rst
View File

@ -7,8 +7,8 @@ SDP3x / SDP800 Series Differential Pressure Sensor
:keywords: SDP3x, SDP31, SDP32, SDP800 Series, SDP810, SDP810 :keywords: SDP3x, SDP31, SDP32, SDP800 Series, SDP810, SDP810
The SDP3x Differential Pressure sensor allows you to use your SDP3x The SDP3x Differential Pressure sensor allows you to use your SDP3x
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/8_Differential_Pressure/Datasheets/Sensirion_Differential_Pressure_Datasheet_SDP3x_Digital.pdf>`__, (`datasheet <https://sensirion.com/media/documents/4D045D69/6375F34F/DP_DS_SDP3x_digital_D1.pdf>`__,
`sparkfun <https://www.sparkfun.com/products/17874>`__) or SDP800 Series (`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/8_Differential_Pressure/Datasheets/Sensirion_Differential_Pressure_Datasheet_SDP8xx_Digital.pdf>`__) `sparkfun <https://www.sparkfun.com/products/17874>`__) or SDP800 Series (`datasheet <https://sensirion.com/media/documents/90500156/6167E43B/Sensirion_Differential_Pressure_Datasheet_SDP8xx_Digital.pdf>`__)
sensors with ESPHome. sensors with ESPHome.
.. figure:: images/sdp31.jpg .. figure:: images/sdp31.jpg

4
components/sensor/sht4x.rst
View File

@ -6,7 +6,7 @@ SHT4X Temperature and Humidity Sensor
:image: sht4x.jpg :image: sht4x.jpg
The ``sht4x`` sensor platform allows you to use your SHT4X temperature and humidity sensor The ``sht4x`` sensor platform allows you to use your SHT4X temperature and humidity sensor
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/2_Humidity_Sensors/Datasheets/Sensirion_Humidity_Sensors_SHT4x_Datasheet.pdf>`__, `Adafruit`_) with ESPHome. (`datasheet <https://sensirion.com/media/documents/33FD6951/63E1087C/Datasheet_SHT4x_1.pdf>`__, `Adafruit`_) with ESPHome.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
@ -58,7 +58,7 @@ The heater can be enabled by setting ``heater_max_duty`` up to a maximum duty cy
of ``5%`` (``0.05``). This runs the heater on a regular interval. While the heater of ``5%`` (``0.05``). This runs the heater on a regular interval. While the heater
is in operation the sensor disables measurements so no updates will be published. is in operation the sensor disables measurements so no updates will be published.
See the (`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/2_Humidity_Sensors/Datasheets/Sensirion_Humidity_Sensors_SHT4x_Datasheet.pdf>`__) See the (`datasheet <https://sensirion.com/media/documents/33FD6951/63E1087C/Datasheet_SHT4x_1.pdf>`__)
for more information about heater operation. for more information about heater operation.
See Also See Also

4
components/sensor/shtcx.rst
View File

@ -6,10 +6,10 @@ SHTCx Temperature+Humidity Sensors
:image: shtc3.jpg :image: shtc3.jpg
The ``shtcx`` sensor platform Temperature+Humidity sensor allows you to use your Sensirion SHTC1 The ``shtcx`` sensor platform Temperature+Humidity sensor allows you to use your Sensirion SHTC1
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/2_Humidity_Sensors/Datasheets/Sensirion_Humidity_Sensors_SHTC1_Datasheet.pdf>`__, (`datasheet <https://sensirion.com/media/documents/21BF77EA/63A5A411/Datasheet_SHTC1.pdf>`__,
`Sensirion STHC1 <https://www.sensirion.com/en/environmental-sensors/humidity-sensors/digital-humidity-sensor-for-consumer-electronics-and-iot/>`__) and `Sensirion STHC1 <https://www.sensirion.com/en/environmental-sensors/humidity-sensors/digital-humidity-sensor-for-consumer-electronics-and-iot/>`__) and
the newer SHTC3 the newer SHTC3
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/2_Humidity_Sensors/Datasheets/Sensirion_Humidity_Sensors_SHTC3_Datasheet.pdf>`__, (`datasheet <https://sensirion.com/media/documents/643F9C8E/63A5A436/Datasheet_SHTC3.pdf>`__,
`SparkFun`_ ) sensors with `SparkFun`_ ) sensors with
ESPHome. The :ref:`I²C Bus <i2c>` is ESPHome. The :ref:`I²C Bus <i2c>` is
required to be set up in your configuration for this sensor to work. required to be set up in your configuration for this sensor to work.

2
components/sensor/sps30.rst
View File

@ -6,7 +6,7 @@ SPS30 Particulate Matter Sensor
:image: sps30.jpg :image: sps30.jpg
The ``sps30`` sensor platform allows you to use your Sensirion SPS30 The ``sps30`` sensor platform allows you to use your Sensirion SPS30
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/9.6_Particulate_Matter/Datasheets/Sensirion_PM_Sensors_Datasheet_SPS30.pdf>`__) sensors with ESPHome. (`datasheet <https://sensirion.com/media/documents/8600FF88/616542B5/Sensirion_PM_Sensors_Datasheet_SPS30.pdf>`__) sensors with ESPHome.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
This sensor supports both UART and I²C communication. However, at the moment only I²C communication is implemented. This sensor supports both UART and I²C communication. However, at the moment only I²C communication is implemented.

2
components/sensor/sts3x.rst
View File

@ -6,7 +6,7 @@ STS3X Temperature Sensor
:image: sts3x.jpg :image: sts3x.jpg
The ``sts3x`` sensor platform Temperature sensor allows you to use your Sensirion STS30-DIS, STS31-DIS or STS35-DIS The ``sts3x`` sensor platform Temperature sensor allows you to use your Sensirion STS30-DIS, STS31-DIS or STS35-DIS
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/3_Temperature_Sensors/Sensirion_Temperature_Sensors_Table_Overview.pdf>`__, (`datasheet <https://sensirion.com/media/documents/1DA31AFD/61641F76/Sensirion_Temperature_Sensors_STS3x_Datasheet.pdf>`__,
`Sensirion STS3x <https://www.sensirion.com/sts3x/>`__) sensors with `Sensirion STS3x <https://www.sensirion.com/sts3x/>`__) sensors with
ESPHome. The :ref:`I²C Bus <i2c>` is ESPHome. The :ref:`I²C Bus <i2c>` is
required to be set up in your configuration for this sensor to work. required to be set up in your configuration for this sensor to work.

8
components/vbus.rst
View File

@ -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.

2
components/voice_assistant.rst
View File

@ -5,7 +5,7 @@ Voice Assistant
:description: Instructions for setting up a Voice Assistant in ESPHome. :description: Instructions for setting up a Voice Assistant in ESPHome.
:image: voice-assistant.svg :image: voice-assistant.svg
ESPHome devices with a microphone are able to stream the audio to Home Assistant and be processed there by `assist <https://www.home-assistant.io/docs/assist/>`__. ESPHome devices with a microphone are able to stream the audio to Home Assistant and be processed there by `assist <https://www.home-assistant.io/voice_control/>`__.
.. note:: .. note::

98
components/web_server.rst
View File

@ -7,27 +7,26 @@ Web Server Component
:keywords: web server, http, REST API :keywords: web server, http, REST API
The ``web_server`` component creates a simple web server on the node that can be accessed The ``web_server`` component creates a simple web server on the node that can be accessed
through any browser and a simple `REST API`_. Please note that enabling this component through any browser and a simple :ref:`api-rest`. Please note that enabling this component
will take up *a lot* of memory and can lead to problems, especially on the ESP8266. will take up *a lot* of memory and may decrease stability, especially on ESP8266.
.. figure:: /components/images/web_server.png
:align: center
:width: 86.0%
Web server version 1
.. figure:: /components/images/web_server-v2.png
:align: center
:width: 86.0%
Web server version 2
To navigate to the web server in your browser, either use the IP address of the node or To navigate to the web server in your browser, either use the IP address of the node or
use ``<node_name>.local/`` (note the trailing forward slash) via mDNS. use ``<node_name>.local/`` (note the trailing forward slash) via mDNS.
To conserve flash size, the CSS and JS files used on the root page to show a simple user
interface are hosted by esphome.io. If you want to use your own service, use the
``css_url`` and ``js_url`` options in your configuration.
.. _REST API: /web-api/index.html
.. figure:: /components/images/web_server.png
Example web server frontend (Version 1)
Version 2:
----------
.. figure:: /components/images/web_server-v2.png
Web Components (Version 2)
.. code-block:: yaml .. code-block:: yaml
@ -50,7 +49,7 @@ Configuration variables:
- **js_include** (*Optional*, local file): Path to local file to be included in web server index page. - **js_include** (*Optional*, local file): Path to local file to be included in web server index page.
Contents of this file will be served as ``/0.js`` and used as JS script by internal webserver. Contents of this file will be served as ``/0.js`` and used as JS script by internal webserver.
Useful when building device without internet access, where you want to use built-in AP and webserver. Useful when building device without internet access, where you want to use built-in AP and webserver.
- **auth** (*Optional*): Enables basic authentication with username and password. - **auth** (*Optional*): Enables a simple *Digest* authentication with username and password.
- **username** (**Required**, string): The username to use for authentication. - **username** (**Required**, string): The username to use for authentication.
- **password** (**Required**, string): The password to check for authentication. - **password** (**Required**, string): The password to check for authentication.
@ -62,52 +61,53 @@ Configuration variables:
- **local** (*Optional*, boolean): Include supporting javascript locally allowing it to work without internet access. Defaults to ``false``. - **local** (*Optional*, boolean): Include supporting javascript locally allowing it to work without internet access. Defaults to ``false``.
- **version** (*Optional*, string): ``1`` or ``2``. Version 1 displays as a table. Version 2 uses web components and has more functionality. Defaults to ``2``. - **version** (*Optional*, string): ``1`` or ``2``. Version 1 displays as a table. Version 2 uses web components and has more functionality. Defaults to ``2``.
.. note:: To conserve flash size, the CSS and JS files used on the root page to show a simple user
interface are hosted by esphome.io. If you want to use your own service, use the
``css_url`` and ``js_url`` options in your configuration.
Example web_server configuration using HTTP authentication: Example configurations:
-----------------------
.. code-block:: yaml Enabling HTTP authentication:
# Example configuration entry .. code-block:: yaml
web_server:
port: 80
auth:
username: admin
password: !secret web_server_password
Example web_server configuration using version 1 (previous behaviour): # Example configuration entry
web_server:
port: 80
auth:
username: !secret web_server_username
password: !secret web_server_password
.. code-block:: yaml Use version 1 user interface:
# Example configuration entry .. code-block:: yaml
web_server:
port: 80
version: 1
Example web_server configuration using version 2 - no internet/intranet required: # Example configuration entry
web_server:
port: 80
version: 1
.. code-block:: yaml No internet/intranet required on the clients (all assets are inlined, compressed and served from flash):
# Example configuration entry .. code-block:: yaml
web_server:
local: true # Example configuration entry
web_server:
local: true
Advanced usage
All of the assets are inlined, compressed and served from flash --------------
Here be Dragons
===============
The following assume copies of the files with local paths - which are config dependant. The following assume copies of the files with local paths - which are config dependant.
Example web_server version 1 configuration with CSS and JS included from esphome-docs. Example ``web_server`` version 1 configuration with CSS and JS included from esphome-docs.
CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface. CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface.
Force to turn off OTA function because the missing authentication. Force to turn off OTA function because the missing authentication.
.. code-block:: yaml .. code-block:: yaml
# Example configuration entry V1
web_server: web_server:
port: 80 port: 80
version: 1 version: 1
@ -117,26 +117,26 @@ Force to turn off OTA function because the missing authentication.
js_include: "../../../esphome-docs/_static/webserver-v1.min.js" js_include: "../../../esphome-docs/_static/webserver-v1.min.js"
js_url: "" js_url: ""
Example web_server version 2 configuration with JS included from a local file. Example ``web_server`` version 2 configuration with JS included from a local file.
CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface. CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface.
V2 embeds the css within the js file so is not required, however you could include your own CSS. V2 embeds the css within the js file so is not required, however you could include your own CSS.
.. code-block:: yaml .. code-block:: yaml
# Example configuration entry V2 # Example configuration entry v2
web_server: web_server:
js_include: "./v2/www.js" js_include: "./v2/www.js"
js_url: "" js_url: ""
version: 2 version: 2
Copy https://oi.esphome.io/v2/www.js to a V2 folder in your yaml folder. Copy https://oi.esphome.io/v2/www.js to a V2 folder in your yaml folder.
See Also See Also
-------- --------
- :ref:`api-event-source`
- :ref:`api-rest`
- :apiref:`web_server/web_server.h` - :apiref:`web_server/web_server.h`
- :doc:`prometheus` - :doc:`prometheus`
- :ghedit:`Edit` - :ghedit:`Edit`

121
cookbook/http_request_sensor.rst Normal file
View File

@ -0,0 +1,121 @@
Share data directly between ESPHome nodes
=========================================
In certain special cases it might be desired to avoid placing any middleware like an MQTT or a home automation server just to transfer small bits of data from one node to another. Direct data polling is possibvle using HTTP, but beware that the involved components are resource hungry and may be less stable on long term. The webserver embedded in the node is not designed to constantly serve a large amount of requests.
The primary node holding the data we need to retrieve from will be the server, and the others polling for it will be the clients (can be multiple).
Server part
-----------
Setting up a webserver using the :doc:`/components/web_server` on the primary node will make available the required sensor data through a :ref:`api-rest` interface.
.. code-block:: yaml
web_server:
port: 80
Client part
-----------
On the client nodes we need an :doc:`/components/http_request` with an ``id`` set, and a :doc:`/components/sensor/template` to make it accessible locally.
.. code-block:: yaml
http_request:
useragent: esphome/device
id: http_request_id
sensor:
- platform: template
name: "Template sensor on client"
id: template_sensor_id
Pulling the data
****************
To automate the request for data, we use an :ref:`interval` requesting the URL pointing to the sensor id for which the state is needed. See :ref:`api-rest` on how to build up the URL for your sensors.
In the example below we request the value of a sensor from the server node, and after parsing the resulted JSON string we publish it to the local template sensor:
.. code-block:: yaml
interval:
- interval: 60s
then:
- http_request.get:
url: http://ip or nodename.local/sensor/ID_of_the_sensor
on_response:
then:
- lambda: |-
json::parse_json(id(http_request_id).get_string(), [](JsonObject root) {
id(template_sensor_id).publish_state(root["value"]);
});
Result
------
.. figure:: images/server.png
:align: center
:width: 95.0%
Server side real sensor
.. figure:: images/clients.png
:align: center
:width: 95.0%
Client side template sensor
Increasing security
-------------------
For security reasons, it's always recommended to protect the web interface of the nodes with authentication, even if you're using them on your local network.
Server part
***********
Add authentication to the ``web_server`` component on the primary node:
.. code-block:: yaml
web_server:
port: 80
auth:
username: !secret admin
password: !secret web_server_password
Client part
***********
Add an ``Authorization`` header to your ``http_request.get`` action. The simplest way to determine a working authorization header is to visit the password-protected REST URL of the primary node using a browser while watching the network traffic in the browser's developer tools. If you look at the headers of the request sent by the browser, you'll find the ``Authorization`` header it sends to the node, and you can copy it for your own replay:
.. code-block:: yaml
interval:
- interval: 60s
then:
- http_request.get:
url: http://ip or nodename.local/sensor/ID_of_the_sensor
headers:
Authorization: 'Digest username="admin", realm="asyncesp", nonce="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", uri="/sensor/ID_of_the_sensor", response="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", opaque="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", qop=auth, nc=xxxxxxxx, cnonce="xxxxxxxxxxxxxxxx"'
on_response:
then:
- lambda: |-
json::parse_json(id(http_request_id).get_string(), [](JsonObject root) {
id(template_sensor_id).publish_state(root["value"]);
});
See Also
--------
- :doc:`/components/web_server`
- :doc:`/components/http_request`
- :doc:`/components/sensor/template`
- :ref:`interval`
- :ref:`api-rest`
- :ghedit:`Edit`

BIN
cookbook/images/clients.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
cookbook/images/server.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

58
custom/i2c.rst
View File

@ -29,6 +29,64 @@ them publish values.
} }
}; };
I²C Write
---------
It may be useful to write to a register via I²C using a numerical input. For example, the following yaml code snippet captures a user-supplied numerical input in the range 1--255 from the dashboard:
.. code-block:: yaml
number:
- platform: template
name: "Input 1"
optimistic: true
min_value: 1
max_value: 255
initial_value: 20
step: 1
mode: box
id: input_1
icon: "mdi:counter"
We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I²C. The Arduino-based looping code shown above is modified following the guidance in :doc:`Custom Sensor Component </components/sensor/custom>`.
.. code-block:: cpp
#include "esphome.h"
const uint16_t I2C_ADDRESS = 0x21;
const uint16_t REGISTER_ADDRESS = 0x78;
const uint16_t POLLING_PERIOD = 15000; //milliseconds
char temp = 20; //Initial value of the register
class MyCustomComponent : public PollingComponent {
public:
MyCustomComponent() : PollingComponent(POLLING_PERIOD) {}
float get_setup_priority() const override { return esphome::setup_priority::BUS; } //Access I2C bus
void setup() override {
//Add code here as needed
Wire.begin();
}
void update() override {
char register_value = id(input_1).state; //Read the number set on the dashboard
//Did the user change the input?
if(register_value != temp){
Wire.beginTransmission(I2C_ADDRESS);
Wire.write(REGISTER_ADDRESS);
Wire.write(register_value);
Wire.endTransmission();
temp = register_value; //Swap in the new value
}
}
};
The ``Component`` class has been replaced with ``PollingComponent`` and the free-running ``loop()`` is changed to the ``update()`` method with period set by ``POLLING_PERIOD``. The numerical value from the dashboard is accessed with its ``id`` tag and its state is set to the byte variable that we call ``register_value``. To prevent an I²C write on every iteration, the contents of the register are stored in ``temp`` and checked for a change. Configuring the hardware with ``get_setup_priority()`` is explained in :doc:`Step 1 </components/sensor/custom>`.
See Also See Also
-------- --------

70
guides/configuration-types.rst
View File

@ -451,6 +451,76 @@ them locally with their own subsitution value.
# shorthand form github://username/repository/[folder/]file-path.yml[@branch-or-tag] # shorthand form github://username/repository/[folder/]file-path.yml[@branch-or-tag]
remote_package_three: github://esphome/non-existant-repo/file1.yml@main remote_package_three: github://esphome/non-existant-repo/file1.yml@main
Packages as Templates
*********************
Since packages are incorporated using the ``!include`` system,
variables can be provided to them. This means that packages can be
used as `templates`, allowing complex or repetitive configurations to
be stored in a package file and then incorporated into the
configuration more than once.
As an example, if the configuration needed to support three garage
doors using the ``gpio`` switch platform and the ``time_based`` cover
platform, it could be constructed like this:
.. code-block:: yaml
# In config.yaml
packages:
left_garage_door: !include
file: garage-door.yaml
vars:
door_name: Left
door_location: left
open_switch_gpio: 25
close_switch_gpio: 26
middle_garage_door: !include
file: garage-door.yaml
vars:
door_name: Middle
door_location: middle
open_switch_gpio: 27
close_switch_gpio: 29
right_garage_door: !include
file: garage-door.yaml
vars:
door_name: Right
door_location: right
open_switch_gpio: 15
close_switch_gpio: 18
.. code-block:: yaml
# In garage-door.yaml
switch:
- id: open_${door_location}_door_switch
name: ${door_name} Garage Door Open Switch
platform: gpio
pin: ${open_switch_gpio}
- id: close_${door_location}_door_switch
name: ${door_name} Garage Door Close Switch
platform: gpio
pin: ${close_switch_gpio}
cover:
- platform: time_based
name: ${door_name} Garage Door
open_action:
- switch.turn_on: open_${door_location}_door_switch
open_duration: 2.1min
close_action:
- switch.turn_on: close_${door_location}_door_switch
close_duration: 2min
stop_action:
- switch.turn_off: open_${door_location}_door_switch
- switch.turn_off: close_${door_location}_door_switch
See Also See Also
-------- --------

6
guides/getting_started_command_line.rst
View File

@ -40,6 +40,12 @@ If you want to use `docker-compose` instead, here's a sample file:
privileged: true privileged: true
network_mode: host network_mode: host
.. note::
If you are using NFS share to back your container's config volume, you may
need to mount the volume with the `nolock` option, otherwise platformio may
freeze on container startup as per `platformIO-core Issue 3089 <https://github.com/platformio/platformio-core/issues/3089>`__
The project provides multiple docker tags; please pick the one that suits you The project provides multiple docker tags; please pick the one that suits you
better: better:

59
guides/supporters.rst
View File

@ -64,7 +64,7 @@ Contributors
- `Alexandre Danault (@AlexDanault) <https://github.com/AlexDanault>`__ - `Alexandre Danault (@AlexDanault) <https://github.com/AlexDanault>`__
- `Alex Iribarren (@alexiri) <https://github.com/alexiri>`__ - `Alex Iribarren (@alexiri) <https://github.com/alexiri>`__
- `Alex Mekkering (@AlexMekkering) <https://github.com/AlexMekkering>`__ - `Alex Mekkering (@AlexMekkering) <https://github.com/AlexMekkering>`__
- `Alex Yao (@alexyao2015) <https://github.com/alexyao2015>`__ - `Alex (@alexyao2015) <https://github.com/alexyao2015>`__
- `Alfredo (@alfredopironti) <https://github.com/alfredopironti>`__ - `Alfredo (@alfredopironti) <https://github.com/alfredopironti>`__
- `Andreas Mandel (@amandel) <https://github.com/amandel>`__ - `Andreas Mandel (@amandel) <https://github.com/amandel>`__
- `Amish Vishwakarma (@amishv) <https://github.com/amishv>`__ - `Amish Vishwakarma (@amishv) <https://github.com/amishv>`__
@ -80,12 +80,12 @@ Contributors
- `Andreas Hergert (@andreashergert1984) <https://github.com/andreashergert1984>`__ - `Andreas Hergert (@andreashergert1984) <https://github.com/andreashergert1984>`__
- `Andrew J.Swan (@andrewjswan) <https://github.com/andrewjswan>`__ - `Andrew J.Swan (@andrewjswan) <https://github.com/andrewjswan>`__
- `andrewpc (@andrewpc) <https://github.com/andrewpc>`__ - `andrewpc (@andrewpc) <https://github.com/andrewpc>`__
- `Andrew Y. (@andrey-yantsen) <https://github.com/andrey-yantsen>`__ - `Andrey Yantsen (@andrey-yantsen) <https://github.com/andrey-yantsen>`__
- `Andrzej (@andriej) <https://github.com/andriej>`__ - `Andrzej (@andriej) <https://github.com/andriej>`__
- `Andreas (@anduchs) <https://github.com/anduchs>`__ - `Andreas (@anduchs) <https://github.com/anduchs>`__
- `Andy2No (@Andy2No) <https://github.com/Andy2No>`__ - `Andy2No (@Andy2No) <https://github.com/Andy2No>`__
- `AndyRPH (@AndyRPH) <https://github.com/AndyRPH>`__ - `AndyRPH (@AndyRPH) <https://github.com/AndyRPH>`__
- `Angel Nunez Mencias (@angelnu) <https://github.com/angelnu>`__ - `Vegetto (@angelnu) <https://github.com/angelnu>`__
- `Sergey Anisimov (@anisimovsergey) <https://github.com/anisimovsergey>`__ - `Sergey Anisimov (@anisimovsergey) <https://github.com/anisimovsergey>`__
- `Nikolay Vasilchuk (@Anonym-tsk) <https://github.com/Anonym-tsk>`__ - `Nikolay Vasilchuk (@Anonym-tsk) <https://github.com/Anonym-tsk>`__
- `Anthony Keane (@anthonykeane) <https://github.com/anthonykeane>`__ - `Anthony Keane (@anthonykeane) <https://github.com/anthonykeane>`__
@ -111,12 +111,12 @@ Contributors
- `Alexander Turlov (@aturlov) <https://github.com/aturlov>`__ - `Alexander Turlov (@aturlov) <https://github.com/aturlov>`__
- `aus (@aus) <https://github.com/aus>`__ - `aus (@aus) <https://github.com/aus>`__
- `AustinMorris (@AustinMorris) <https://github.com/AustinMorris>`__ - `AustinMorris (@AustinMorris) <https://github.com/AustinMorris>`__
- `Denis Demchenko (@Avirsaam) <https://github.com/Avirsaam>`__ - `Avirsaam (@Avirsaam) <https://github.com/Avirsaam>`__
- `Arsène von Wyss (@avonwyss) <https://github.com/avonwyss>`__ - `Arsène von Wyss (@avonwyss) <https://github.com/avonwyss>`__
- `Andrew Weddle (@aweddle2) <https://github.com/aweddle2>`__ - `Andrew Weddle (@aweddle2) <https://github.com/aweddle2>`__
- `Achilleas Pipinellis (@axilleas) <https://github.com/axilleas>`__ - `Achilleas Pipinellis (@axilleas) <https://github.com/axilleas>`__
- `Kamil Trzciński (@ayufan) <https://github.com/ayufan>`__ - `Kamil Trzciński (@ayufan) <https://github.com/ayufan>`__
- `Azimath (@Azimath) <https://github.com/Azimath>`__ - `Nicholas Peters (@Azimath) <https://github.com/Azimath>`__
- `Daniel (@azrael783) <https://github.com/azrael783>`__ - `Daniel (@azrael783) <https://github.com/azrael783>`__
- `B48D81EFCC (@B48D81EFCC) <https://github.com/B48D81EFCC>`__ - `B48D81EFCC (@B48D81EFCC) <https://github.com/B48D81EFCC>`__
- `Florian Mösch (@badbadc0ffee) <https://github.com/badbadc0ffee>`__ - `Florian Mösch (@badbadc0ffee) <https://github.com/badbadc0ffee>`__
@ -131,7 +131,7 @@ Contributors
- `Bascht74 (@Bascht74) <https://github.com/Bascht74>`__ - `Bascht74 (@Bascht74) <https://github.com/Bascht74>`__
- `Viktr (@BbIKTOP) <https://github.com/BbIKTOP>`__ - `Viktr (@BbIKTOP) <https://github.com/BbIKTOP>`__
- `J. Nick Koston (@bdraco) <https://github.com/bdraco>`__ - `J. Nick Koston (@bdraco) <https://github.com/bdraco>`__
- `Maxym Ocheretianko (@bearpawmaxim) <https://github.com/bearpawmaxim>`__ - `Maxim Ocheretianko (@bearpawmaxim) <https://github.com/bearpawmaxim>`__
- `beaudeanadams (@beaudeanadams) <https://github.com/beaudeanadams>`__ - `beaudeanadams (@beaudeanadams) <https://github.com/beaudeanadams>`__
- `Benjamin Freeman (@Beetix) <https://github.com/Beetix>`__ - `Benjamin Freeman (@Beetix) <https://github.com/Beetix>`__
- `beikeland (@beikeland) <https://github.com/beikeland>`__ - `beikeland (@beikeland) <https://github.com/beikeland>`__
@ -151,7 +151,7 @@ Contributors
- `Ivan Bessarabov (@bessarabov) <https://github.com/bessarabov>`__ - `Ivan Bessarabov (@bessarabov) <https://github.com/bessarabov>`__
- `Brandon (@bgulla) <https://github.com/bgulla>`__ - `Brandon (@bgulla) <https://github.com/bgulla>`__
- `Benedikt Hübschen (@bhuebschen) <https://github.com/bhuebschen>`__ - `Benedikt Hübschen (@bhuebschen) <https://github.com/bhuebschen>`__
- `Stef (@Bierchermuesli) <https://github.com/Bierchermuesli>`__ - `Bierchermuesli (@Bierchermuesli) <https://github.com/Bierchermuesli>`__
- `Bill Church (@billchurch) <https://github.com/billchurch>`__ - `Bill Church (@billchurch) <https://github.com/billchurch>`__
- `Brian Kaufman (@bkaufx) <https://github.com/bkaufx>`__ - `Brian Kaufman (@bkaufx) <https://github.com/bkaufx>`__
- `JDavid (@blackhack) <https://github.com/blackhack>`__ - `JDavid (@blackhack) <https://github.com/blackhack>`__
@ -169,7 +169,7 @@ Contributors
- `Mauricio Bonani (@bonanitech) <https://github.com/bonanitech>`__ - `Mauricio Bonani (@bonanitech) <https://github.com/bonanitech>`__
- `Casey Olson (@bookcasey) <https://github.com/bookcasey>`__ - `Casey Olson (@bookcasey) <https://github.com/bookcasey>`__
- `Borja Burgos (@borjaburgos) <https://github.com/borjaburgos>`__ - `Borja Burgos (@borjaburgos) <https://github.com/borjaburgos>`__
- `bouhaa (@BoukeHaarsma23) <https://github.com/BoukeHaarsma23>`__ - `BoukeHaarsma23 (@BoukeHaarsma23) <https://github.com/BoukeHaarsma23>`__
- `brambo123 (@brambo123) <https://github.com/brambo123>`__ - `brambo123 (@brambo123) <https://github.com/brambo123>`__
- `Bram Kragten (@bramkragten) <https://github.com/bramkragten>`__ - `Bram Kragten (@bramkragten) <https://github.com/bramkragten>`__
- `Brandan Cotton (@Brando47) <https://github.com/Brando47>`__ - `Brandan Cotton (@Brando47) <https://github.com/Brando47>`__
@ -288,7 +288,7 @@ Contributors
- `Daniel Correa Lobato (@dclobato) <https://github.com/dclobato>`__ - `Daniel Correa Lobato (@dclobato) <https://github.com/dclobato>`__
- `DeadEnd (@DeadEnded) <https://github.com/DeadEnded>`__ - `DeadEnd (@DeadEnded) <https://github.com/DeadEnded>`__
- `Debashish Sahu (@debsahu) <https://github.com/debsahu>`__ - `Debashish Sahu (@debsahu) <https://github.com/debsahu>`__
- `Dek Shanaghy (@declanshanaghy) <https://github.com/declanshanaghy>`__ - `declanshanaghy (@declanshanaghy) <https://github.com/declanshanaghy>`__
- `Maximilian (@DeerMaximum) <https://github.com/DeerMaximum>`__ - `Maximilian (@DeerMaximum) <https://github.com/DeerMaximum>`__
- `definitio (@definitio) <https://github.com/definitio>`__ - `definitio (@definitio) <https://github.com/definitio>`__
- `Christiaan Blom (@Deinara) <https://github.com/Deinara>`__ - `Christiaan Blom (@Deinara) <https://github.com/Deinara>`__
@ -335,7 +335,7 @@ Contributors
- `Tom Soer (@dtx3k) <https://github.com/dtx3k>`__ - `Tom Soer (@dtx3k) <https://github.com/dtx3k>`__
- `dubit0 (@dubit0) <https://github.com/dubit0>`__ - `dubit0 (@dubit0) <https://github.com/dubit0>`__
- `Mikkel Jeppesen (@Duckle29) <https://github.com/Duckle29>`__ - `Mikkel Jeppesen (@Duckle29) <https://github.com/Duckle29>`__
- `Sergey Dudanov (@dudanov) <https://github.com/dudanov>`__ - `Sergey V. DUDANOV (@dudanov) <https://github.com/dudanov>`__
- `David Girón (@duhow) <https://github.com/duhow>`__ - `David Girón (@duhow) <https://github.com/duhow>`__
- `Duncan Findlay (@duncf) <https://github.com/duncf>`__ - `Duncan Findlay (@duncf) <https://github.com/duncf>`__
- `Jannick (@DutchDeffy) <https://github.com/DutchDeffy>`__ - `Jannick (@DutchDeffy) <https://github.com/DutchDeffy>`__
@ -489,7 +489,7 @@ Contributors
- `Héctor Giménez (@hectorgimenez) <https://github.com/hectorgimenez>`__ - `Héctor Giménez (@hectorgimenez) <https://github.com/hectorgimenez>`__
- `Jimmy Hedman (@HeMan) <https://github.com/HeMan>`__ - `Jimmy Hedman (@HeMan) <https://github.com/HeMan>`__
- `Hemi03 (@Hemi03) <https://github.com/Hemi03>`__ - `Hemi03 (@Hemi03) <https://github.com/Hemi03>`__
- `Andrei Solodovnikov (@HepoH3) <https://github.com/HepoH3>`__ - `HepoH3 (@HepoH3) <https://github.com/HepoH3>`__
- `Hermann Kraus (@herm) <https://github.com/herm>`__ - `Hermann Kraus (@herm) <https://github.com/herm>`__
- `Herr Frei (@herrfrei) <https://github.com/herrfrei>`__ - `Herr Frei (@herrfrei) <https://github.com/herrfrei>`__
- `highground88 (@highground88) <https://github.com/highground88>`__ - `highground88 (@highground88) <https://github.com/highground88>`__
@ -510,7 +510,7 @@ Contributors
- `Adrián Panella (@ianchi) <https://github.com/ianchi>`__ - `Adrián Panella (@ianchi) <https://github.com/ianchi>`__
- `Ian Anderson (@ianderso) <https://github.com/ianderso>`__ - `Ian Anderson (@ianderso) <https://github.com/ianderso>`__
- `Ian Leeder (@ianleeder) <https://github.com/ianleeder>`__ - `Ian Leeder (@ianleeder) <https://github.com/ianleeder>`__
- `Honza Pobořil (@iBobik) <https://github.com/iBobik>`__ - `Jan Pobořil (@iBobik) <https://github.com/iBobik>`__
- `igg (@igg) <https://github.com/igg>`__ - `igg (@igg) <https://github.com/igg>`__
- `Ignacio Hernandez-Ros (@IgnacioHR) <https://github.com/IgnacioHR>`__ - `Ignacio Hernandez-Ros (@IgnacioHR) <https://github.com/IgnacioHR>`__
- `ikatkov (@ikatkov) <https://github.com/ikatkov>`__ - `ikatkov (@ikatkov) <https://github.com/ikatkov>`__
@ -606,13 +606,13 @@ Contributors
- `Jonathan Treffler (@JonathanTreffler) <https://github.com/JonathanTreffler>`__ - `Jonathan Treffler (@JonathanTreffler) <https://github.com/JonathanTreffler>`__
- `JonnyaiR (@jonnyair) <https://github.com/jonnyair>`__ - `JonnyaiR (@jonnyair) <https://github.com/jonnyair>`__
- `Jonathan V (@jonofmac) <https://github.com/jonofmac>`__ - `Jonathan V (@jonofmac) <https://github.com/jonofmac>`__
- `Joppy Furr (@JoppyFurr) <https://github.com/JoppyFurr>`__ - `Joppy (@JoppyFurr) <https://github.com/JoppyFurr>`__
- `Jared Sanson (@jorticus) <https://github.com/jorticus>`__ - `Jared Sanson (@jorticus) <https://github.com/jorticus>`__
- `Joshua Spence (@joshuaspence) <https://github.com/joshuaspence>`__ - `Joshua Spence (@joshuaspence) <https://github.com/joshuaspence>`__
- `joskfg (@joskfg) <https://github.com/joskfg>`__ - `joskfg (@joskfg) <https://github.com/joskfg>`__
- `Joscha Wagner (@jowgn) <https://github.com/jowgn>`__ - `Joscha Wagner (@jowgn) <https://github.com/jowgn>`__
- `Javier Peletier (@jpeletier) <https://github.com/jpeletier>`__ - `Javier Peletier (@jpeletier) <https://github.com/jpeletier>`__
- `Jos Suanet (@jsuanet) <https://github.com/jsuanet>`__ - `jsuanet (@jsuanet) <https://github.com/jsuanet>`__
- `James Szalay (@jtszalay) <https://github.com/jtszalay>`__ - `James Szalay (@jtszalay) <https://github.com/jtszalay>`__
- `Jules-R (@Jules-R) <https://github.com/Jules-R>`__ - `Jules-R (@Jules-R) <https://github.com/Jules-R>`__
- `Julie Koubová (@juliekoubova) <https://github.com/juliekoubova>`__ - `Julie Koubová (@juliekoubova) <https://github.com/juliekoubova>`__
@ -621,7 +621,7 @@ Contributors
- `Justin Gerhardt (@justin-gerhardt) <https://github.com/justin-gerhardt>`__ - `Justin Gerhardt (@justin-gerhardt) <https://github.com/justin-gerhardt>`__
- `Justyn Shull (@justyns) <https://github.com/justyns>`__ - `Justyn Shull (@justyns) <https://github.com/justyns>`__
- `Jasper van der Neut - Stulen (@jvanderneutstulen) <https://github.com/jvanderneutstulen>`__ - `Jasper van der Neut - Stulen (@jvanderneutstulen) <https://github.com/jvanderneutstulen>`__
- `João Vitor Miranda Roma (@jvmr1) <https://github.com/jvmr1>`__ - `João Vitor M. Roma (@jvmr1) <https://github.com/jvmr1>`__
- `Jack Wozny (@jwozny) <https://github.com/jwozny>`__ - `Jack Wozny (@jwozny) <https://github.com/jwozny>`__
- `Jozef Zuzelka (@jzlka) <https://github.com/jzlka>`__ - `Jozef Zuzelka (@jzlka) <https://github.com/jzlka>`__
- `Kris (@K-r-i-s-t-i-a-n) <https://github.com/K-r-i-s-t-i-a-n>`__ - `Kris (@K-r-i-s-t-i-a-n) <https://github.com/K-r-i-s-t-i-a-n>`__
@ -656,7 +656,7 @@ Contributors
- `Karl Q. (@kquinsland) <https://github.com/kquinsland>`__ - `Karl Q. (@kquinsland) <https://github.com/kquinsland>`__
- `Kodey Converse (@krconv) <https://github.com/krconv>`__ - `Kodey Converse (@krconv) <https://github.com/krconv>`__
- `KristopherMackowiak (@KristopherMackowiak) <https://github.com/KristopherMackowiak>`__ - `KristopherMackowiak (@KristopherMackowiak) <https://github.com/KristopherMackowiak>`__
- `Stefan Rado (@kroimon) <https://github.com/kroimon>`__ - `kroimon (@kroimon) <https://github.com/kroimon>`__
- `krunkel (@krunkel) <https://github.com/krunkel>`__ - `krunkel (@krunkel) <https://github.com/krunkel>`__
- `kryptonitecb3 (@kryptonitecb3) <https://github.com/kryptonitecb3>`__ - `kryptonitecb3 (@kryptonitecb3) <https://github.com/kryptonitecb3>`__
- `Kendell R (@KTibow) <https://github.com/KTibow>`__ - `Kendell R (@KTibow) <https://github.com/KTibow>`__
@ -672,7 +672,7 @@ Contributors
- `Lawrie George (@lawriege) <https://github.com/lawriege>`__ - `Lawrie George (@lawriege) <https://github.com/lawriege>`__
- `Laszlo Gazdag (@lazlyhu) <https://github.com/lazlyhu>`__ - `Laszlo Gazdag (@lazlyhu) <https://github.com/lazlyhu>`__
- `Ludovic BOUÉ (@lboue) <https://github.com/lboue>`__ - `Ludovic BOUÉ (@lboue) <https://github.com/lboue>`__
- `Luca Cavalli (@lcavalli) <https://github.com/lcavalli>`__ - `lcavalli (@lcavalli) <https://github.com/lcavalli>`__
- `Craig Fletcher (@leakypixel) <https://github.com/leakypixel>`__ - `Craig Fletcher (@leakypixel) <https://github.com/leakypixel>`__
- `Dominik Wagenknecht (@LeDominik) <https://github.com/LeDominik>`__ - `Dominik Wagenknecht (@LeDominik) <https://github.com/LeDominik>`__
- `Benny de Leeuw (@leeuwte) <https://github.com/leeuwte>`__ - `Benny de Leeuw (@leeuwte) <https://github.com/leeuwte>`__
@ -681,7 +681,7 @@ Contributors
- `Leon Loopik (@Lewn) <https://github.com/Lewn>`__ - `Leon Loopik (@Lewn) <https://github.com/Lewn>`__
- `Luca Gugelmann (@lgugelmann) <https://github.com/lgugelmann>`__ - `Luca Gugelmann (@lgugelmann) <https://github.com/lgugelmann>`__
- `Lubos Horacek (@lhoracek) <https://github.com/lhoracek>`__ - `Lubos Horacek (@lhoracek) <https://github.com/lhoracek>`__
- `LiJu09 (@LiJu09) <https://github.com/LiJu09>`__ - `Juraj Liso (@LiJu09) <https://github.com/LiJu09>`__
- `lillborje71 (@lillborje71) <https://github.com/lillborje71>`__ - `lillborje71 (@lillborje71) <https://github.com/lillborje71>`__
- `lingex (@lingex) <https://github.com/lingex>`__ - `lingex (@lingex) <https://github.com/lingex>`__
- `Markus (@Links2004) <https://github.com/Links2004>`__ - `Markus (@Links2004) <https://github.com/Links2004>`__
@ -704,7 +704,7 @@ Contributors
- `Ohad Lutzky (@lutzky) <https://github.com/lutzky>`__ - `Ohad Lutzky (@lutzky) <https://github.com/lutzky>`__
- `Luke Fitzgerald (@lwfitzgerald) <https://github.com/lwfitzgerald>`__ - `Luke Fitzgerald (@lwfitzgerald) <https://github.com/lwfitzgerald>`__
- `Alex Peters (@Lx) <https://github.com/Lx>`__ - `Alex Peters (@Lx) <https://github.com/Lx>`__
- `Marius Dinu (@M95D) <https://github.com/M95D>`__ - `M95D (@M95D) <https://github.com/M95D>`__
- `maaadc (@maaadc) <https://github.com/maaadc>`__ - `maaadc (@maaadc) <https://github.com/maaadc>`__
- `Marc-Antoine Courteau (@macourteau) <https://github.com/macourteau>`__ - `Marc-Antoine Courteau (@macourteau) <https://github.com/macourteau>`__
- `Massimiliano Ravelli (@madron) <https://github.com/madron>`__ - `Massimiliano Ravelli (@madron) <https://github.com/madron>`__
@ -856,7 +856,7 @@ Contributors
- `obrain17 (@obrain17) <https://github.com/obrain17>`__ - `obrain17 (@obrain17) <https://github.com/obrain17>`__
- `Ockert Marais (@OckertM) <https://github.com/OckertM>`__ - `Ockert Marais (@OckertM) <https://github.com/OckertM>`__
- `Dave Walker (@oddsockmachine) <https://github.com/oddsockmachine>`__ - `Dave Walker (@oddsockmachine) <https://github.com/oddsockmachine>`__
- `Andrii Ganzevych (@odya) <https://github.com/odya>`__ - `Andrey Ganzevich (@odya) <https://github.com/odya>`__
- `ogatatsu (@ogatatsu) <https://github.com/ogatatsu>`__ - `ogatatsu (@ogatatsu) <https://github.com/ogatatsu>`__
- `Oğuzhan Başer (@oguzhanbaser) <https://github.com/oguzhanbaser>`__ - `Oğuzhan Başer (@oguzhanbaser) <https://github.com/oguzhanbaser>`__
- `OkhammahkO (@OkhammahkO) <https://github.com/OkhammahkO>`__ - `OkhammahkO (@OkhammahkO) <https://github.com/OkhammahkO>`__
@ -864,7 +864,7 @@ Contributors
- `Ömer Şiar Baysal (@omersiar) <https://github.com/omersiar>`__ - `Ömer Şiar Baysal (@omersiar) <https://github.com/omersiar>`__
- `optimusprimespace (@optimusprimespace) <https://github.com/optimusprimespace>`__ - `optimusprimespace (@optimusprimespace) <https://github.com/optimusprimespace>`__
- `Oscar Bolmsten (@oscar-b) <https://github.com/oscar-b>`__ - `Oscar Bolmsten (@oscar-b) <https://github.com/oscar-b>`__
- `Mauri (@Otamay) <https://github.com/Otamay>`__ - `Otamay (@Otamay) <https://github.com/Otamay>`__
- `Otto Winter (@OttoWinter) <https://github.com/OttoWinter>`__ - `Otto Winter (@OttoWinter) <https://github.com/OttoWinter>`__
- `Maxime Dufour (@outscale-mdr) <https://github.com/outscale-mdr>`__ - `Maxime Dufour (@outscale-mdr) <https://github.com/outscale-mdr>`__
- `Ben Owen (@owenb321) <https://github.com/owenb321>`__ - `Ben Owen (@owenb321) <https://github.com/owenb321>`__
@ -935,7 +935,7 @@ Contributors
- `Robert Gabrielson (@rgabrielson11) <https://github.com/rgabrielson11>`__ - `Robert Gabrielson (@rgabrielson11) <https://github.com/rgabrielson11>`__
- `Rafael Goes (@rgriffogoes) <https://github.com/rgriffogoes>`__ - `Rafael Goes (@rgriffogoes) <https://github.com/rgriffogoes>`__
- `rheinz (@rheinz) <https://github.com/rheinz>`__ - `rheinz (@rheinz) <https://github.com/rheinz>`__
- `Richard Hopton (@richardhopton) <https://github.com/richardhopton>`__ - `richardhopton (@richardhopton) <https://github.com/richardhopton>`__
- `Richard Klingler (@richardklingler) <https://github.com/richardklingler>`__ - `Richard Klingler (@richardklingler) <https://github.com/richardklingler>`__
- `Richard Lewis (@richrd) <https://github.com/richrd>`__ - `Richard Lewis (@richrd) <https://github.com/richrd>`__
- `Andre Borie (@Rjevski) <https://github.com/Rjevski>`__ - `Andre Borie (@Rjevski) <https://github.com/Rjevski>`__
@ -964,6 +964,7 @@ Contributors
- `rwilson131 (@rwilson131) <https://github.com/rwilson131>`__ - `rwilson131 (@rwilson131) <https://github.com/rwilson131>`__
- `Ryan Lang (@ryan-lang) <https://github.com/ryan-lang>`__ - `Ryan Lang (@ryan-lang) <https://github.com/ryan-lang>`__
- `ryanalden (@ryanalden) <https://github.com/ryanalden>`__ - `ryanalden (@ryanalden) <https://github.com/ryanalden>`__
- `ryansmigley (@ryansmigley) <https://github.com/ryansmigley>`__
- `Lukas Bachschwell (@s00500) <https://github.com/s00500>`__ - `Lukas Bachschwell (@s00500) <https://github.com/s00500>`__
- `Sabesto (@Sabesto) <https://github.com/Sabesto>`__ - `Sabesto (@Sabesto) <https://github.com/Sabesto>`__
- `Jan Čermák (@sairon) <https://github.com/sairon>`__ - `Jan Čermák (@sairon) <https://github.com/sairon>`__
@ -1024,7 +1025,7 @@ Contributors
- `sticilface (@sticilface) <https://github.com/sticilface>`__ - `sticilface (@sticilface) <https://github.com/sticilface>`__
- `Stijn Tintel (@stintel) <https://github.com/stintel>`__ - `Stijn Tintel (@stintel) <https://github.com/stintel>`__
- `Mathias Stock (@Stock-M) <https://github.com/Stock-M>`__ - `Mathias Stock (@Stock-M) <https://github.com/Stock-M>`__
- `Daniel Jönsson (@Strixx76) <https://github.com/Strixx76>`__ - `Strixx76 (@Strixx76) <https://github.com/Strixx76>`__
- `stubs12 (@stubs12) <https://github.com/stubs12>`__ - `stubs12 (@stubs12) <https://github.com/stubs12>`__
- `Jordan Vohwinkel (@sublime93) <https://github.com/sublime93>`__ - `Jordan Vohwinkel (@sublime93) <https://github.com/sublime93>`__
- `sud33p (@sud33p) <https://github.com/sud33p>`__ - `sud33p (@sud33p) <https://github.com/sud33p>`__
@ -1068,7 +1069,7 @@ Contributors
- `Thomas Langewouters (@thouters) <https://github.com/thouters>`__ - `Thomas Langewouters (@thouters) <https://github.com/thouters>`__
- `Transylvania High Tech (@thtro) <https://github.com/thtro>`__ - `Transylvania High Tech (@thtro) <https://github.com/thtro>`__
- `Thunderbiscuits (@Thunderbiscuits) <https://github.com/Thunderbiscuits>`__ - `Thunderbiscuits (@Thunderbiscuits) <https://github.com/Thunderbiscuits>`__
- `Tiago Freire (@tiagofreire-pt) <https://github.com/tiagofreire-pt>`__ - `tiagofreire-pt (@tiagofreire-pt) <https://github.com/tiagofreire-pt>`__
- `Tijs-B (@Tijs-B) <https://github.com/Tijs-B>`__ - `Tijs-B (@Tijs-B) <https://github.com/Tijs-B>`__
- `Tim Laurence (@timdaman) <https://github.com/timdaman>`__ - `Tim Laurence (@timdaman) <https://github.com/timdaman>`__
- `Aidan Timson (@timmo001) <https://github.com/timmo001>`__ - `Aidan Timson (@timmo001) <https://github.com/timmo001>`__
@ -1077,7 +1078,7 @@ Contributors
- `Tinkerfish (@tinkerfish) <https://github.com/tinkerfish>`__ - `Tinkerfish (@tinkerfish) <https://github.com/tinkerfish>`__
- `TJ Horner (@tjhorner) <https://github.com/tjhorner>`__ - `TJ Horner (@tjhorner) <https://github.com/tjhorner>`__
- `Christian (@Tntdruid) <https://github.com/Tntdruid>`__ - `Christian (@Tntdruid) <https://github.com/Tntdruid>`__
- `Philipp Riederer (@toelke) <https://github.com/toelke>`__ - `Philipp Tölke (@toelke) <https://github.com/toelke>`__
- `tomaszduda23 (@tomaszduda23) <https://github.com/tomaszduda23>`__ - `tomaszduda23 (@tomaszduda23) <https://github.com/tomaszduda23>`__
- `Tom Brien (@TomBrien) <https://github.com/TomBrien>`__ - `Tom Brien (@TomBrien) <https://github.com/TomBrien>`__
- `Tom Hartogs (@TomHartogs) <https://github.com/TomHartogs>`__ - `Tom Hartogs (@TomHartogs) <https://github.com/TomHartogs>`__
@ -1086,7 +1087,7 @@ Contributors
- `Tom Price (@tomtom5152) <https://github.com/tomtom5152>`__ - `Tom Price (@tomtom5152) <https://github.com/tomtom5152>`__
- `David Kiliani (@torfbolt) <https://github.com/torfbolt>`__ - `David Kiliani (@torfbolt) <https://github.com/torfbolt>`__
- `tracestep (@tracestep) <https://github.com/tracestep>`__ - `tracestep (@tracestep) <https://github.com/tracestep>`__
- `Felix E (@tribut) <https://github.com/tribut>`__ - `Felix Eckhofer (@tribut) <https://github.com/tribut>`__
- `Trick van Staveren (@trickv) <https://github.com/trickv>`__ - `Trick van Staveren (@trickv) <https://github.com/trickv>`__
- `TripitakaBC (@TripitakaBC) <https://github.com/TripitakaBC>`__ - `TripitakaBC (@TripitakaBC) <https://github.com/TripitakaBC>`__
- `Tobias (@tripplet) <https://github.com/tripplet>`__ - `Tobias (@tripplet) <https://github.com/tripplet>`__
@ -1128,7 +1129,7 @@ Contributors
- `Ian Wells (@wellsi) <https://github.com/wellsi>`__ - `Ian Wells (@wellsi) <https://github.com/wellsi>`__
- `wifwucite (@wifwucite) <https://github.com/wifwucite>`__ - `wifwucite (@wifwucite) <https://github.com/wifwucite>`__
- `wilberforce (@wilberforce) <https://github.com/wilberforce>`__ - `wilberforce (@wilberforce) <https://github.com/wilberforce>`__
- `Willem Vooijs (@wildekek) <https://github.com/wildekek>`__ - `wildekek (@wildekek) <https://github.com/wildekek>`__
- `Wingman3434 (@Wingman3434) <https://github.com/Wingman3434>`__ - `Wingman3434 (@Wingman3434) <https://github.com/Wingman3434>`__
- `Emil Hesslow (@WizKid) <https://github.com/WizKid>`__ - `Emil Hesslow (@WizKid) <https://github.com/WizKid>`__
- `WJCarpenter (@wjcarpenter) <https://github.com/wjcarpenter>`__ - `WJCarpenter (@wjcarpenter) <https://github.com/wjcarpenter>`__
@ -1143,7 +1144,7 @@ Contributors
- `Mike Brown (@xenoxaos) <https://github.com/xenoxaos>`__ - `Mike Brown (@xenoxaos) <https://github.com/xenoxaos>`__
- `Xose Pérez (@xoseperez) <https://github.com/xoseperez>`__ - `Xose Pérez (@xoseperez) <https://github.com/xoseperez>`__
- `WitchKing (@xvil) <https://github.com/xvil>`__ - `WitchKing (@xvil) <https://github.com/xvil>`__
- `Yaroslav Heriatovych (@Yarikx) <https://github.com/Yarikx>`__ - `Yaroslav (@Yarikx) <https://github.com/Yarikx>`__
- `Marcin Jaworski (@yawor) <https://github.com/yawor>`__ - `Marcin Jaworski (@yawor) <https://github.com/yawor>`__
- `Yuval Aboulafia (@yuvalabou) <https://github.com/yuvalabou>`__ - `Yuval Aboulafia (@yuvalabou) <https://github.com/yuvalabou>`__
- `Björn Stenberg (@zagor) <https://github.com/zagor>`__ - `Björn Stenberg (@zagor) <https://github.com/zagor>`__
@ -1158,4 +1159,4 @@ Contributors
- `Zack Barett (@zsarnett) <https://github.com/zsarnett>`__ - `Zack Barett (@zsarnett) <https://github.com/zsarnett>`__
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__ - `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
*This page was last updated May 24, 2023.* *This page was last updated May 29, 2023.*

3
index.rst
View File

@ -500,7 +500,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
@ -848,6 +848,7 @@ Cookbook
Sonoff Fishpond Pump, cookbook/sonoff-fishpond-pump, cookbook-sonoff-fishpond-pump.jpg Sonoff Fishpond Pump, cookbook/sonoff-fishpond-pump, cookbook-sonoff-fishpond-pump.jpg
Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg
EHMTX a matrix status/text display, cookbook/ehmtx, ehmtx.jpg EHMTX a matrix status/text display, cookbook/ehmtx, ehmtx.jpg
Share data directly between ESPHome nodes, cookbook/http_request_sensor, connection.svg
Do you have other awesome automations or cool setups? Please feel free to add them to the Do you have other awesome automations or cool setups? Please feel free to add them to the
documentation for others to copy. See :doc:`Contributing </guides/contributing>`. documentation for others to copy. See :doc:`Contributing </guides/contributing>`.

142
schema_doc.py
View File

@ -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():

12
web-api/index.rst
View File

@ -24,6 +24,8 @@ While it's currently recommended to use ESPHome directly through Home Assistant,
to integrate ESPHome with an external or self-built application you can use two available to integrate ESPHome with an external or self-built application you can use two available
APIs: the real-time event source API and REST API. APIs: the real-time event source API and REST API.
.. _api-event-source:
Event Source API Event Source API
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@ -56,6 +58,8 @@ states so that the client can catch up with reality.
The payloads of these state events are also the same as the payloads of the REST API GET calls. The payloads of these state events are also the same as the payloads of the REST API GET calls.
I would recommend just opening the network debug panel of your web browser to see what's sent. I would recommend just opening the network debug panel of your web browser to see what's sent.
.. _api-rest:
REST API REST API
-------- --------
@ -297,3 +301,11 @@ method is ``set``. The following parameter can be used:
minimum and maximum range of the number otherwise it will be ignored. minimum and maximum range of the number otherwise it will be ignored.
For example POST ``/number/desired_delay/set?value=24`` will set the number to 24. For example POST ``/number/desired_delay/set?value=24`` will set the number to 24.
See Also
--------
- :doc:`/components/web_server`
- :doc:`/components/prometheus`
- :doc:`/components/http_request`
- :ghedit:`Edit`