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

Docs cleanup for schema gen (#1973)

This commit is contained in:
Guillermo Ruffino 2022-04-03 04:30:25 -03:00 committed by GitHub
parent 48256f265d
commit 53d1abd7a8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
63 changed files with 1130 additions and 913 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
changelog/2021.12.0.rst
View File

@ -71,7 +71,7 @@ NEC remote protocol
-------------------
In this version, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC standard.
Therefore, if the the configuration file has come from an earlier version of ESPhome, it is necessary to reverse
Therefore, if the configuration file has come from an earlier version of ESPhome, it is necessary to reverse
the order of the address and command bits when moving to 2021.12 or above.
For example, address: ``0x84ED``, command: ``0x13EC`` becomes ``0xB721`` and ``0x37C8`` respectively.

2
changelog/v1.14.0.rst
View File

@ -306,7 +306,7 @@ Notable Changes & New Features
- Add configurable ignore bits to rc_switch_raw codes (:esphomepr:`650` by :ghuser:`mtl010957`,
:doc:`docs </components/remote_receiver>`).
- New ``restore`` option has been added to :doc:`servos </components/servo>` (:esphomepr:`829`).
- Add IR receiver support for coolix climate devices (:esphomepr:`645` by :ghuser:`glmnet`, :doc:`docs </components/climate/ir_climate>`).
- Add IR receiver support for coolix climate devices (:esphomepr:`645` by :ghuser:`glmnet`, :doc:`docs </components/climate/climate_ir>`).
- Add :ref:`calibrate_polynomial <sensor-calibrate_polynomial>` sensor filter (:esphomepr:`642`).
- Allow setting the initial mode of HLW8012 sensors (:esphomepr:`611` by :ghuser:`brandond`, :doc:`docs </components/sensor/hlw8012>`).
- Add tilt actions to :doc:`template cover </components/cover/template>` (:esphomepr:`577` by :ghuser:`mtl010957`).

20
components/binary_sensor/analog_threshold.rst
View File

@ -5,19 +5,19 @@ Analog Threshold Binary Sensor
:description: Instructions for setting up an analog threshold binary sensors.
:image: analog_threshold.svg
The ``analog_threshold`` binary sensor platform allows you to convert analog values
(i.e. :doc:`sensor </components/sensor/index>` readings)
into boolean values, using a threshold as a reference.
When the signal is above or equal to the threshold the binary sensor is `true`
(this behavior can be changed adding and `invert` filter).
The ``analog_threshold`` binary sensor platform allows you to convert analog values
(i.e. :doc:`sensor </components/sensor/index>` readings)
into boolean values, using a threshold as a reference.
When the signal is above or equal to the threshold the binary sensor is ``true``
(this behavior can be changed adding and ``invert`` filter).
It provides an *hysteresis* option to reduce instability when the source signal is noisy
using different limits depending on the current state.
Additionally a :ref:`delay filter <binary_sensor-filters>` could be used to only change
using different limits depending on the current state.
Additionally a :ref:`delay filter <binary_sensor-filters>` could be used to only change
after a new state has been kept a minimum time.
If the source sensor is uninitialized at the moment of component creation, the initial
state of the binary sensor wil be `false`, if later it has some reading errors, those
state of the binary sensor wil be ``false``, if later it has some reading errors, those
invalid source updates will be ignored, and the binary sensor will keep it´s last state.
For example, below configuration would turn the readings of current sensor into
@ -39,8 +39,8 @@ Configuration variables
- **name** (**Required**, string): The name of the binary sensor.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **sensor_id** (**Required**, :ref:`config-id`): The ID of the source sensor.
- **threshold** (**Required**, float or mapping): Configures the reference for comparison. Accepts either a shorthand
float number that will be used as both upper/lower threshold, or a mapping to define different values for each (to
- **threshold** (**Required**, float or mapping): Configures the reference for comparison. Accepts either a shorthand
float number that will be used as both upper/lower threshold, or a mapping to define different values for each (to
use hysteresis).
- **upper** (**Required**, float): Upper threshold, that needs to be crossed to transition from ``low`` to ``high`` states.

2
components/binary_sensor/cap1188.rst
View File

@ -49,10 +49,12 @@ The configuration is made up of two parts: The central component, and individual
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor.
- **reset_pin** (*Optional*, :ref:`config-pin`): Set the pin that is used to reset the CAP1188 board on boot.
- **touch_threshold** (*Optional*, int): The touch threshold for all channels. This defines the sensitivity for touch detection.
- ``0x01``: Maximum sensitivity - Most sensitive to touch
- ``0x20``: Default sensitivity
- ``0x40``: Medium sensitivity (I used this sensitivity when being used through a 3mm sheet of plastic)
- ``0x80``: Minimum sensitivity - Least sensitive to touch
- **allow_multiple_touches** (*Optional*, boolean): Whether to allow multitouch. Defaults to off.
Binary Sensor

59
components/binary_sensor/modbus_controller.rst
View File

@ -1,5 +1,5 @@
Modbus Binary Sensor
====================
Modbus Controller Binary Sensor
===============================
.. seo::
:description: Instructions for setting up a modbus_controller device binary sensor.
@ -14,31 +14,39 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the sensor.
- **modbus_functioncode** (**Required**): type of the modbus register.
- "read_coils": Function 01 (01hex) Read Coils - Reads the ON/OFF status of discrete coils in the device.
- "read_discrete_inputs": Function 02(02hex) - Reads the ON/OFF status of discrete inputs in the device.
- "read_holding_registers": Function 03 (03hex) Read Holding Registers - Read the binary contents of holding registers in the device.
- "read_input_registers": Function 04 (04hex) Read Input Registers - Read the binary contents of input registers in the device.
- **register_type** (**Required**): type of the modbus register.
- **address**: (**Required**, int): start address of the first register in a range
- **bitmask** : some values are packed in a response. The bitmask is used to determined if the result is true or false
- **skip_updates**: (*Optional*, int): By default all sensors of of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
- **register_count**: (*Optional*, int): only required for uncommon response encodings or to :ref:`optimize modbus communications<modbus_register_count>`
The number of registers this data point spans. Overrides the defaults determined by ``value_type``.
If no value for ``register_count`` is provided, it is calculated based on the register type.
- ``coil``: Function 01 (01hex) Read Coils - Reads the ON/OFF status of discrete coils in the device.
- ``discrete_input``: Function 02(02hex) - Reads the ON/OFF status of discrete inputs in the device.
- ``holding``: Function 03 (03hex) Read Holding Registers - Read the binary contents of holding registers in the device.
- ``read``: Function 04 (04hex) Read Input Registers - Read the binary contents of input registers in the device.
The default size for 1 register is 16 bits (1 Word). Some devices are not adhering to this convention and have registers larger than 16 bits. In this case ``register_count`` and ``response_size`` must be set. For example, if your modbus device uses 1 registers for a FP32 value instead the default of two set ``register_count: 1`` and ``response_size: 4``.
- **response_size**: (*Optional*, int): Size of the response for the register in bytes. Defaults to register_count*2.
- **force_new_range**: (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting ``force_new_range: true`` enforces the start of a new range at that address.
- **custom_data** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_data`` is used ``address`` and ``register_type`` can't be used.
- **address** (**Required**, int): start address of the first register in a range
- **bitmask** (*Optional*, int): Some values are packed in a response. The bitmask is used to determined if the result is true or false
- **skip_updates** (*Optional*, int): By default all sensors of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
- **response_size** (*Optional*, int): Size of the response for the register in bytes. Defaults to register_count*2.
- **force_new_range** (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting ``force_new_range: true`` enforces the start of a new range at that address.
- **custom_command** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_command`` is used ``address`` and ``register_type`` can't be used.
custom data must contain all required bytes including the modbus device address. The crc is automatically calculated and appended to the command.
See :ref:`modbus_custom_data` how to use ``custom_command``
See :ref:`modbus_custom_command` how to use ``custom_command``
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated every update interval to get the new value of the sensor
- **offset**: (*Optional*, int): not required for most cases
Parameters
- **x** (bool): The parsed float value of the modbus data
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
- **item** (const pointer to a ModbusBinarySensor object): The sensor object itself.
Possible return values for the lambda:
- ``return true/false;`` the new value for the sensor.
- **offset** (*Optional*, int): not required for most cases
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
The value for offset depends on the register type. If a binary_sensor is created from an input register the offset is in bytes. For coil and discrete input resisters the LSB of the first data byte contains the coil addressed in the request. The other coils follow toward the high-order end of this byte and from low order to high order in subsequent bytes. For the registers offset is the position of the relevant bit.
To get the value of the coil register 2 can be retrived using address: 2 / offset: 0 or address: 0 / offset 2
To get the value of the coil register 2 can be retrieved using address: 2 / offset: 0 or address: 0 / offset 2
Example
@ -55,17 +63,6 @@ Example
bitmask: 0x80 #(bit 8)
Parameters passed into the lambda
- **x** (bool): The parsed float value of the modbus data
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
- **item** (const pointer to a ModbusBinarySensor object): The sensor object itself.
Possible return values for the lambda:
- ``return true/false;`` the new value for the sensor.
See Also
--------
- :apiclass:`:modbus_controller::ModbusBinarySensor`

39
components/canbus.rst
View File

@ -62,24 +62,23 @@ Configuration variables:
- **use_extended_id** (*Optional*, boolean): default *false* identifies the type of *can_id*:
*false*: Standard 11 bits IDs, *true*: Extended 29 bits ID
- **bit_rate** (*Optional*, enum): One of the supported bitrates. Defaults to ``125KBPS``.
Bitrates marked with * are not supported by the internal ESP32 CAN controller.
- 5KBPS *
- 10KBPS *
- 20KBPS *
- 31K25BPS *
- 33KBPS *
- 40KBPS *
- 50KBPS
- 80KBPS *
- 83K3BPS *
- 95KBPS *
- 100KBPS
- 125KBPS
- 200KBPS *
- 250KBPS
- 500KBPS
- 1000KBPS
- ``5KBPS`` - Not supported by ``esp32_can``
- ``10KBPS`` - Not supported by ``esp32_can``
- ``20KBPS`` - Not supported by ``esp32_can``
- ``31K25BPS`` - Not supported by ``esp32_can``
- ``33KBPS`` - Not supported by ``esp32_can``
- ``40KBPS`` - Not supported by ``esp32_can``
- ``50KBPS``
- ``80KBPS`` - Not supported by ``esp32_can``
- ``83K3BPS`` - Not supported by ``esp32_can``
- ``95KBPS`` - Not supported by ``esp32_can``
- ``100KBPS``
- ``125KBPS`` - (Default)
- ``200KBPS`` - Not supported by ``esp32_can``
- ``250KBPS``
- ``500KBPS``
- ``1000KBPS``
Automations:
------------
@ -229,9 +228,9 @@ Configuration variables:
Defaults to ``8MHZ``.
- **mode** (*Optional*): Operation mode. Default to ``NORMAL``
- NORMAL: Normal operation
- LOOPBACK: Loopback mode can be used to just test you spi connections to the device
- LISTENONLY: only receive data
- ``NORMAL``: Normal operation
- ``LOOPBACK``: Loopback mode can be used to just test you spi connections to the device
- ``LISTENONLY``: only receive data
- All other options from :ref:`Canbus <config-canbus>`.

0
components/climate/ir_climate.rst → components/climate/climate_ir.rst
View File

2
components/cover/time_based.rst
View File

@ -1,4 +1,4 @@
Time-Based Cover
Time Based Cover
================
.. seo::

2
components/deep_sleep.rst
View File

@ -127,7 +127,7 @@ Useful for keeping the ESP active during data transfer or OTA updating (See note
it will no longer enter deep sleep mode and you can upload your OTA update.
Remember to turn "OTA mode" off again after the OTA update by sending a MQTT message with the payload
``OFF``. To enter the the deep sleep again after the OTA update send a message on the topic ``livingroom/sleep_mode``
``OFF``. To enter the deep sleep again after the OTA update send a message on the topic ``livingroom/sleep_mode``
with payload ``ON``. Deep sleep will start immediately. Don't forget to delete the payload before the node
wakes up again.

24
components/display/index.rst
View File

@ -374,8 +374,8 @@ RGB displays use red, green, and blue, while grayscale displays may use white.
.. _display-graphs:
Graphs
******
Graph Component
***************
You can display a graph of a sensor value(s) using this component. Examples:
@ -482,8 +482,8 @@ And then later in code:
- Axis labels are currently not possible without manually placing them.
- The grid and border color is set with it.graph(), while the traces are defined separately.
QR Codes
********
QR Code Component
*****************
Use this component to generate a QR-code containing a string on the device, which can then be drawn on compatible displays.
@ -500,10 +500,10 @@ Configuration variables:
- **value** (**Required**, string): The string which you want to encode in the QR-code.
- **ecc** (*Optional*, string): The error correction code level you want to use. Defaults to ``LOW``. You can use one of the following values:
- ``LOW`` - The QR Code can tolerate about 7% erroneous codewords
- ``MEDIUM`` - The QR Code can tolerate about 15% erroneous codewords
- ``QUARTILE`` - The QR Code can tolerate about 25% erroneous codewords
- ``HIGH`` - The QR Code can tolerate about 30% erroneous codewords
- ``LOW``: The QR Code can tolerate about 7% erroneous codewords
- ``MEDIUM``: The QR Code can tolerate about 15% erroneous codewords
- ``QUARTILE``: The QR Code can tolerate about 25% erroneous codewords
- ``HIGH``: The QR Code can tolerate about 30% erroneous codewords
To draw the QR-code, call the ``it.qr_code`` function from your render lambda:
@ -641,14 +641,6 @@ Configuration variables:
- ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
- ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
- **dither** (*Optional*): Specifies which dither method used to process each frame, only used in GRAYSCALE and BINARY type image.
Defaults to ``NONE``. You can read more about it `here <https://pillow.readthedocs.io/en/stable/reference/Image.html?highlight=Dither#PIL.Image.Image.convert>`__
and `here <https://en.wikipedia.org/wiki/Dither>`__.
- ``NONE``: Every pixel convert to its nearest color.
- ``FLOYDSTEINBERG``: Uses Floyd-Steinberg dither to approximate the original image luminosity levels.
.. _display-pages:
Display Pages

4
components/display/ssd1306.rst
View File

@ -12,7 +12,7 @@ Over I²C
The ``ssd1306_i2c`` display platform allows you to use
SSD1306 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf>`__,
`Adafruit <https://www.adafruit.com/product/326>`__), SSD1305 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1305.pdf>`__)
`Adafruit <https://www.adafruit.com/product/326>`__), SSD1305 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1305.pdf>`__)
and SH1106 (`datasheet <https://www.elecrow.com/download/SH1106%20datasheet.pdf>`__,
`electrodragon <https://www.electrodragon.com/product/1-3-12864-blue-oled-display-iicspi/>`__)
displays with ESPHome. Note that this component is for displays that are connected via the :ref:`I²C Bus <i2c>`.
@ -48,7 +48,7 @@ Configuration variables:
- **model** (**Required**): The model of the display. Options are:
- ``SSD1306 128x32`` (SSD1306 with 128 columns and 32 rows)
- ``SSD1306 128x32`` - SSD1306 with 128 columns and 32 rows
- ``SSD1306 128x64``
- ``SSD1306 96x16``
- ``SSD1306 64x48``

2
components/display/ssd1325.rst
View File

@ -49,7 +49,7 @@ Configuration variables:
- **model** (**Required**): The model of the display. Options are:
- ``SSD1325 128x32`` (SSD1325 with 128 columns and 32 rows)
- ``SSD1325 128x32`` - SSD1325 with 128 columns and 32 rows
- ``SSD1325 128x64``
- ``SSD1325 96x16``
- ``SSD1325 64x48``

4
components/display/ssd1351.rst
View File

@ -48,8 +48,8 @@ Configuration variables:
- **model** (**Required**): The model of the display. Options are:
- ``SSD1351 128x128`` (SSD1351 with 128 columns and 128 rows)
- ``SSD1351 128x96`` (SSD1351 with 128 columns and 96 rows)
- ``SSD1351 128x128`` - SSD1351 with 128 columns and 128 rows
- ``SSD1351 128x96`` - SSD1351 with 128 columns and 96 rows
- **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin on the ESP that that the CS line is connected to.

2
components/display/tm1637.rst
View File

@ -39,7 +39,7 @@ Configuration variables:
- **intensity** (*Optional*, int): The intensity with which the TM1637 should drive the outputs. Range is from
0 (least intense) to 7 (the default).
- **inverted** (*Optional*, bool): Invert character rendering to the TM1637 so you can physically flip the display around.
- **length** (*Optional*, int): The amount of digits your TM1637 is driving. Only required when `inverted: true`
- **length** (*Optional*, int): The amount of digits your TM1637 is driving. Only used when ``inverted: true``
Range is from 1 to 6 (the default).
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the TM1637.
See :ref:`display-tm1637_lambda` for more information.

26
components/display/waveshare_epaper.rst
View File

@ -78,24 +78,24 @@ Configuration variables:
- ``1.54in``
- ``1.54inv2``
- ``2.13in`` (not tested)
- ``2.13in-ttgo`` (T5_V2.3 tested. Also works for Wemos D1 Mini ePaper Shield 2.13 1.0.0 "LOLIN")
- ``2.13in-ttgo-b73`` (T5_V2.3 with B73 display tested)
- ``2.13in-ttgo-b74`` (T5_V2.3.1 with B74 display tested)
- ``2.13in-ttgo-b1`` (T5_V2.3 with B1 display tested)
- ``2.13in-ttgo-dke`` (T5_V2.3 with DKE group display (DEPG0213BN) tested)
- ``2.70in`` (currently not working with the HAT Rev 2.1 version)
- ``2.13in`` - not tested
- ``2.13in-ttgo`` - T5_V2.3 tested. Also works for Wemos D1 Mini ePaper Shield 2.13 1.0.0 "LOLIN"
- ``2.13in-ttgo-b73`` - T5_V2.3 with B73 display tested
- ``2.13in-ttgo-b74`` - T5_V2.3.1 with B74 display tested
- ``2.13in-ttgo-b1`` - T5_V2.3 with B1 display tested
- ``2.13in-ttgo-dke`` - T5_V2.3 with DKE group display (DEPG0213BN) tested
- ``2.70in`` - currently not working with the HAT Rev 2.1 version
- ``2.90in``
- ``2.90inv2``
- ``2.90in-b`` (B/W rendering only)
- ``2.90in-b`` - B/W rendering only
- ``4.20in``
- ``4.20in-bV2`` (B/W rendering only)
- ``4.20in-bV2`` - B/W rendering only
- ``5.83in``
- ``7.50in``
- ``7.50in-bV2`` (also supports v3, B/W rendering only)
- ``7.50in-bc`` (display with version sticker '(C)' on the back, B/W rendering only)
- ``7.50inV2`` (Can't use with an ESP8266 as it runs out of RAM)
- ``7.50in-hd-b`` (Can't use with an ESP8266 as it runs out of RAM)
- ``7.50in-bV2`` - also supports v3, B/W rendering only
- ``7.50in-bc`` - display with version sticker '(C)' on the back, B/W rendering only
- ``7.50inV2`` - Can't use with an ESP8266 as it runs out of RAM
- ``7.50in-hd-b`` - Can't use with an ESP8266 as it runs out of RAM
- **busy_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The BUSY pin. Defaults to not connected.
- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin. Defaults to not connected.

8
components/esp32.rst
View File

@ -23,7 +23,7 @@ Configuration variables:
choose a generic board from Espressif such as ``esp32dev``.
- **framework** (*Optional*): Options for the underlying framework used by ESPHome.
See :ref:`esp32-arduino_framework` and :ref:`esp32-espidf_framework`.
- **variant** (*Optional*, boolean): The variant of the ESP32 that is used on this board. One of ``esp32``,
- **variant** (*Optional*, boolean): The variant of the ESP32 that is used on this board. One of ``esp32``,
``esp32s2``, ``esp32s3``, ``esp32c3`` and ``esp32h2``. Defaults to the variant that is detected from the board, if
a board that's unknown to ESPHome is used, this option is mandatory.
@ -43,6 +43,9 @@ This is the default framework for ESP32 chips at the moment.
type: arduino
version: 2.0.0
Configuration variables:
------------------------
- **version** (*Optional*, string): The base framework version number to use, from
`ESP32 arduino releases <https://github.com/espressif/arduino-esp32/releases>`__. Defaults to ``recommended``. Additional values are:
@ -76,6 +79,9 @@ of the ESP32 like ESP32S2, ESP32S3, ESP32C3 and single-core ESP32 chips.
advanced:
ignore_efuse_mac_crc: false
Configuration variables:
------------------------
- **version** (*Optional*, string): The base framework version number to use, from
`ESP32 ESP-IDF releases <https://github.com/espressif/esp-idf/releases>`__. Defaults to ``recommended``. Additional values are:

3
components/ethernet.rst
View File

@ -54,7 +54,6 @@ Configuration variables:
- **dns1** (*Optional*, IPv4 address): The main DNS server to use.
- **dns2** (*Optional*, IPv4 address): The backup DNS server to use.
- **enable_mdns** (*Optional*, boolean): Controls if your node should advertise its presence and services using mDNS. When set to ``false`` you won't be able to access your node using its hostname which can break certain functionalities. Please see :ref:`notes on disabling mDNS <faq-notes_on_disabling_mdns>`. Defaults to ``true``.
- **use_address** (*Optional*, string): Manually override what address to use to connect
to the ESP. Defaults to auto-generated value. For example, if you have changed your
static IP and want to flash OTA to the previously configured IP address.
@ -69,7 +68,7 @@ Configuration variables:
If your ethernet board is not designed with an ESP32 built in, chances are that you are going
to use flying leads, dupont wires, etc. to connect the ethernet to the ESP32. This is
probably to fail as the ethernet interface uses a high frequency clock signal. For more
information and wiring details refer to the the link in the *See also* section.
information and wiring details refer to the link in the *See also* section.
Configuration for wESP32 board
------------------------------

4
components/fan/hbridge.rst
View File

@ -5,7 +5,7 @@ H-bridge Fan
:description: Instructions for setting up hbridge controlled fans (or motors).
:image: fan.svg
The ``hbridge`` fan platform allows you to use a compatible `h-bridge` (L298N, DRV8871, MX1508, BTS7960, L9110S, DRV8833, TB6612, etc.) to control a fan (or motor/solenoid).
The ``hbridge`` fan platform allows you to use a compatible *h-bridge* (L298N, DRV8871, MX1508, BTS7960, L9110S, DRV8833, TB6612, etc.) to control a fan (or motor/solenoid).
.. figure:: images/L298N_module.jpg
:align: center
@ -30,7 +30,7 @@ The ``hbridge`` fan platform allows you to use a compatible `h-bridge` (L298N, D
- platform: ...
id: motor_reverse_pin
pin: GPIO4
fan:
- platform: hbridge
id: my_fan

2
components/light/cwww.rst
View File

@ -29,7 +29,7 @@ Mixing
The two channels of this light can be controlled individually by using the ``cold_white`` and ``warm_white`` options of
the :ref:`light control actions <light-turn_on_action>`.
If the color temperature of both lights is supplied, it is also possible to control the the two channels together by
If the color temperature of both lights is supplied, it is also possible to control the two channels together by
setting a color temperature, using the ``white`` (interpreted as brightness) and ``color_temperature`` options. This
calculation assumes that both lights have the same illuminance, which might not always be accurate.

4
components/light/tuya.rst
View File

@ -63,7 +63,7 @@ Configuration variables:
maximum of 255, but dimmers with a maximum of 1000 can also be found. Try what works best.
Defaults to 255.
- **color_temperature_max_value** (*Optional*, int): The highest color temperature
value allowed. Some ceiling fans have a value of 100 (also for `max_value`). Defaults to 255.
value allowed. Some ceiling fans have a value of 100 (also for ``max_value``). Defaults to 255.
- **color_temperature_invert** (*Optional*, boolean): Control how color temperature values are
sent to the MCU. If this is set to true ESPHome will treat 0 as warm white and
**color_temperature_max_value** as cool white when setting **color_temperature_datapoint**.
@ -79,7 +79,7 @@ Configuration variables:
.. note::
The MCU on the Tuya dimmer handles transitions and gamma correction on its own.
Therefore the ``gamma_correct`` setting default is ``1.0`` and the the
Therefore the ``gamma_correct`` setting default is ``1.0`` and the
``default_transition_length`` parameter is ``0s`` by default.
See Also

4
components/lock/template.rst
View File

@ -37,7 +37,7 @@ Possible return values for the optional lambda:
- ``return LOCK_STATE_LOCKING;`` if the lock should be reported as LOCKING.
- ``return LOCK_STATE_UNLOCKING;`` if the lock should be reported as UNLOCKING.
- ``return {};`` if the last state should be repeated.
.. note::
Only ``LOCK_STATE_LOCKED`` and ``LOCK_STATE_UNLOCKED`` are supported by the MQTT component in Home Assistant
@ -52,8 +52,6 @@ Configuration variables:
be performed when the remote (like Home Assistant's frontend) requests the lock to be locked.
- **unlock_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote (like Home Assistant's frontend) requests the lock to be unlocked.
- **restore_state** (*Optional*, boolean): Sets whether ESPHome should attempt to restore the
state on boot-up and call the lock/unlock actions with the recovered values. Defaults to ``no``.
- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
any command sent to the template lock will immediately update the reported state.
Defaults to ``false``.

10
components/modbus.rst
View File

@ -24,13 +24,13 @@ Configuration variables:
------------------------
- **flow_control_pin** (*Optional*, :ref:`config-pin`): The pin used to switch flow control.
This is useful for RS485 transeivers that do not have automatic flow control switching,
like the common MAX485.
This is useful for RS485 transceivers that do not have automatic flow control switching,
like the common MAX485.
- **send_wait_time** (*Optional*, :ref:`config-time`): Time in milliseconds before a new modbus command is sent if an answer from a previous command is pending. Defaults to 250 ms.
If multiple modbus devices are attached increasing this value can help avoiding to to overlapping reads.
When 2 devices are sending a command at the same the the response read from uart can't be assigend to the proper design.
This value defines the maximumm queuing time for a command before it is send anyways.
If multiple modbus devices are attached increasing this value can help avoiding to to overlapping reads.
When 2 devices are sending a command at the same the response read from uart can't be assigned to the proper design.
This value defines the maximum queuing time for a command before it is send anyways.
See Also

12
components/mqtt.rst
View File

@ -58,6 +58,12 @@ Configuration variables:
``<APP_NAME>``.
- **log_topic** (*Optional*, :ref:`mqtt-message`): The topic to send MQTT log
messages to.
The ``log_topic`` has an additional configuration option:
- **level** (*Optional*, string): The log level to use for MQTT logs. See
:ref:`logger-log_levels` for options.
- **birth_message** (*Optional*, :ref:`mqtt-message`): The message to send when
a connection to the broker is established. See :ref:`mqtt-last_will_birth` for more information.
- **will_message** (*Optional*, :ref:`mqtt-message`): The message to send when
@ -113,12 +119,6 @@ Configuration options:
- **retain** (*Optional*, boolean): If the published message should
have a retain flag on or not. Defaults to ``true``.
The ``log_topic`` has an additional configuration option:
- **level** (*Optional*, string): The log level to use for MQTT logs. See
:ref:`logger-log_levels` for options.
.. _mqtt-using_with_home_assistant:
Using with Home Assistant

106
components/number/modbus_controller.rst
View File

@ -12,77 +12,71 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the sensor.
- **address**: (**Required**, int): start address of the first register in a range
- **value_type**: (**Required**): datatype of the mod_bus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first)
- U_WORD (unsigned 16 bit integer from 1 register = 16bit)
- S_WORD (signed 16 bit integer from 1 register = 16bit)
- U_DWORD (unsigned 32 bit integer from 2 registers = 32bit)
- S_DWORD (signed 32 bit integer from 2 registers = 32bit)
- U_DWORD_R (unsigned 32 bit integer from 2 registers low word first)
- S_DWORD_R (signed 32 bit integer from 2 registers low word first)
- U_QWORD (unsigned 64 bit integer from 4 registers = 64bit)
- S_QWORD (unsigned 64 bit integer from 4 registers = 64bit)
- U_QWORD_R (unsigned 64 bit integer from 4 registers low word first)
- U_QWORD_R signed 64 bit integer from 4 registers low word first)
- FP32 (32 bit IEEE 754 floating point from 2 registers)
- FP32_R (32 bit IEEE 754 floating point - same as FP32 but low word first)
- **address** (**Required**, int): start address of the first register in a range
- **value_type** (**Required**): datatype of the mod_bus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first)
- **skip_updates**: (*Optional*, int): By default all sensors of of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
Note: The modbus_controller groups component by address ranges to reduce number of transactions. All compoents with the same address will be updated in one request. skip_updates applies for all components in the same range.
- **register_count**: (*Optional*): only required for uncommon response encodings or to :ref:`optimize modbus communications<modbus_register_count>`
The number of registers this data point spans. Overrides the defaults determined by ``value_type``.
If no value for ``register_count`` is provided, it is calculated based on the register type.
- ``U_WORD`` (unsigned 16 bit integer from 1 register = 16bit)
- ``S_WORD`` (signed 16 bit integer from 1 register = 16bit)
- ``U_DWORD`` (unsigned 32 bit integer from 2 registers = 32bit)
- ``S_DWORD`` (signed 32 bit integer from 2 registers = 32bit)
- ``U_DWORD_R`` (unsigned 32 bit integer from 2 registers low word first)
- ``S_DWORD_R`` (signed 32 bit integer from 2 registers low word first)
- ``U_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit)
- ``S_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit)
- ``U_QWORD_R`` (unsigned 64 bit integer from 4 registers low word first)
- ``U_QWORD_R`` signed 64 bit integer from 4 registers low word first)
- ``FP32`` (32 bit IEEE 754 floating point from 2 registers)
- ``FP32_R`` (32 bit IEEE 754 floating point - same as FP32 but low word first)
The default size for 1 register is 16 bits (1 Word). Some devices are not adhering to this convention and have registers larger than 16 bits. In this case ``register_count`` and ``response_size`` must be set. For example, if your modbus device uses 1 registers for a FP32 value instead the default of two set ``register_count: 1`` and ``response_size: 4``.
- **response_size**: (*Optional*): Size of the response for the register in bytes. Defaults to register_count*2.
- **force_new_range**: (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting ``force_new_range: true`` enforces the start of a new range at that address.
- **offset**: (*Optional*, int): only required for uncommon response encodings
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
- **skip_updates** (*Optional*, int): By default all sensors of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
Note: The modbus_controller groups component by address ranges to reduce number of transactions. All components with the same address will be updated in one request. skip_updates applies for all components in the same range.
- **response_size** (*Optional*): Size of the response for the register in bytes. Defaults to register_count*2.
- **force_new_range** (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting ``force_new_range: true`` enforces the start of a new range at that address.
- **offset** (*Optional*, int): only required for uncommon response encodings offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
- **min_value** (*Optional*, float): The minimum value this number can be.
- **max_value** (*Optional*, float): The maximum value this number can be.
- **step** (*Optional*, float): The granularity with which the number can be set. Defaults to 1
- **custom_data** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_data`` is used ``address`` and ``register_type`` can't be used.
- **custom_command** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_command`` is used ``address`` and ``register_type`` can't be used.
custom data must contain all required bytes including the modbus device address. The crc is automatically calculated and appended to the command.
See :ref:`modbus_custom_data` how to use ``custom_command``
See :ref:`modbus_custom_command` how to use ``custom_command``
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated every update interval to get the new value of the sensor.
Parameters passed into the lambda
- **x** (float): The parsed float value of the modbus data
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
*note:* because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER>;`` the new value for the sensor.
- ``return NAN;`` if the state should be considered invalid to indicate an error (advanced).
- **write_lambda** (*Optional*, :ref:`lambda <config-lambda>`): Lambda called before send.
Lambda is evaluated before the modbus write command is created.
Parameters passed into the lambda
- **x** (float): The float value to be sent to the modbus device
- **payload** (``std::vector<uint16_t>&payload``): empty vector for the payload. The lambda can add 16 bit raw modbus register words.
*note:* because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER>;`` the new value for the sensor.
- ``return <anything>; and fill payload with data`` if the payload is added from the lambda then these 16 bit words will be sent
- ``return {};`` if you don't want write the command to the device (or do it from the lambda).
- **multiply** (*Optional*, float): multiply the new value with this factor before sending the requests. Ignored if lambda is defined.
- **use_write_multiple**: (*Optional*, boolean): By default the modbus command ``Preset Single Registers`` (function code 6) is used for setting the holding register if only 1 register is set. If your device only supports ``Preset Multiple Registers`` (function code 16) set this option to true.
- **use_write_multiple** (*Optional*, boolean): By default the modbus command ``Preset Single Registers`` (function code 6) is used for setting the holding register if only 1 register is set. If your device only supports ``Preset Multiple Registers`` (function code 16) set this option to true.
All other options from :ref:`Number <config-number>`.
Parameters passed into the lambda
- **x** (float): The parsed float value of the modbus data
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
note: because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER>;`` the new value for the sensor.
- ``return NAN;`` if the state should be considered invalid to indicate an error (advanced).
**Parameters passed into write_lambda**
- **x** (float): The float value to be sent to the modbus device
- **payload** (`std::vector<uint16_t>&payload`): empty vector for the payload. The lamdba can add 16 bit raw modbus register words.
note: because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER>;`` the new value for the sensor.
- ``return <anything>; and fill payload with data`` if the payload is added from the lambda then these 16 bit words will be sent
- ``return {};`` if you don't want write the command to the device (or do it from the lambda).
**Example**
.. code-block:: yaml

2
components/output/ac_dimmer.rst
View File

@ -56,7 +56,7 @@ Configuration variables:
detector, in such case duplicate the ``zero_cross_pin`` config on each output.
- **method** (*Optional*): Set the method for dimming, can be:
- ``leading pulse`` (default): a short pulse to trigger a triac.
- ``leading pulse``: (default) a short pulse to trigger a triac.
- ``leading``: gate pin driven high until the zero cross is detected
- ``trailing``: gate pin driven high from zero cross until dim period, this method
is suitable for mosfet dimmers only.

2
components/output/mcp4725.rst
View File

@ -46,7 +46,7 @@ Usage with voltages higher than 3.3v
In order to drive analog modules with voltages higher than 3.3v, use a `TTL bi-directionnal level
converter <https://learn.sparkfun.com/tutorials/bi-directional-logic-level-converter-hookup-guide/all>`__
Be careful about what converter you use, some of of them have channels labeled with `RX` and `TX`,
Be careful about what converter you use, some of them have channels labeled with `RX` and `TX`,
in this case only `TX` channels are bi-directional (so you must use 2 `TX` channels for I2C to work).
See Also

14
components/output/mcp4728.rst
View File

@ -1,5 +1,5 @@
MCP4728 Output
==============
MCP4728 Component
=================
.. seo::
:description: Instructions for setting up MCP4728 outputs on the ESP.
@ -34,8 +34,8 @@ Configuration variables:
the DAC. Defaults to ``0x60``.
- **store_in_eeprom** (*Optional*, boolean): Use SEQ_WRITE mode to also write to EEPROM sequentially. Defaults to ``false``.
Output
******
MCP4728 Output
**************
The MCP4728 output component exposes 4 MCP4728 channels of a global :ref:`MCP4728 <mcp4728-component>` as float outputs.
@ -84,9 +84,9 @@ Configuration variables:
Use this if you have multiple MCP4728 chains you want to use at the same time.
- **channel** (**Required**, string): Chose the channel of the MCP4728 chain of
this output component. One of ``A``, ``B``, ``C`` or ``D``.
- **vref** (**Optional**, string): Chose the VREF source. One of ``vdd`` or ``internal``. Defaults to ``vdd``.
- **gain** (**Optional**, string): Chose the GAIN multiplier for internal VREF. One of ``X1`` or ``X2``. Only useful when ``vdd=internal``. Defaults to ``X1``.
- **power_down** (**Optional**, string): Chose the power down mode. In power down mode (value different from ``normal``) the output pin will be connected to GND using a resistor (1kOhm, 100kOhm or 500kOhm). One of ``normal``, ``gnd_1k``, ``gnd_100k`` or ``gnd_500k``. Defaults to ``normal``.
- **vref** (*Optional*, string): Chose the VREF source. One of ``vdd`` or ``internal``. Defaults to ``vdd``.
- **gain** (*Optional*, string): Chose the GAIN multiplier for internal VREF. One of ``X1`` or ``X2``. Only useful when ``vdd=internal``. Defaults to ``X1``.
- **power_down** (*Optional*, string): Chose the power down mode. In power down mode (value different from ``normal``) the output pin will be connected to GND using a resistor (1kOhm, 100kOhm or 500kOhm). One of ``normal``, ``gnd_1k``, ``gnd_100k`` or ``gnd_500k``. Defaults to ``normal``.
- All other options from :ref:`Output <config-output>`.
Output voltage range will be different depending on the ``vref`` source and ``gain``.

77
components/output/modbus_controller.rst
View File

@ -11,54 +11,53 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the sensor.
- **address**: (**Required**, int): start address of the first register in a range
- **value_type**: (**Required**): datatype of the mod_bus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first)
- U_WORD (unsigned 16 bit integer from 1 register = 16bit)
- S_WORD (signed 16 bit integer from 1 register = 16bit)
- U_DWORD (unsigned 32 bit integer from 2 registers = 32bit)
- S_DWORD (signed 32 bit integer from 2 registers = 32bit)
- U_DWORD_R (unsigned 32 bit integer from 2 registers low word first)
- S_DWORD_R (signed 32 bit integer from 2 registers low word first)
- U_QWORD (unsigned 64 bit integer from 4 registers = 64bit)
- S_QWORD (unsigned 64 bit integer from 4 registers = 64bit)
- U_QWORD_R (unsigned 64 bit integer from 4 registers low word first)
- U_QWORD_R signed 64 bit integer from 4 registers low word first)
- FP32 (32 bit IEEE 754 floating point from 2 registers)
- FP32_R (32 bit IEEE 754 floating point - same as FP32 but low word first)
- **register_count**: (*Optional*): only required for uncommon response encodings
The number of registers this data point spans. Default is 1
- **address** (**Required**, int): start address of the first register in a range
- **value_type** (**Required**): datatype of the modbus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first)
- ``U_WORD`` (unsigned 16 bit integer from 1 register = 16bit)
- ``S_WORD`` (signed 16 bit integer from 1 register = 16bit)
- ``U_DWORD`` (unsigned 32 bit integer from 2 registers = 32bit)
- ``S_DWORD`` (signed 32 bit integer from 2 registers = 32bit)
- ``U_DWORD_R`` (unsigned 32 bit integer from 2 registers low word first)
- ``S_DWORD_R`` (signed 32 bit integer from 2 registers low word first)
- ``U_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit)
- ``S_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit)
- ``U_QWORD_R`` (unsigned 64 bit integer from 4 registers low word first)
- ``U_QWORD_R`` signed 64 bit integer from 4 registers low word first)
- ``FP32`` (32 bit IEEE 754 floating point from 2 registers)
- ``FP32_R`` (32 bit IEEE 754 floating point - same as FP32 but low word first)
- **write_lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda is evaluated before the modbus write command is created. The value is passed in as ``float x`` and an empty vector is passed in as ``std::vector<uint16_t>&payload``.
You can directly define the payload by adding data to payload then the return value is ignored and the content of payload is used.
Parameters passed into the lambda
- **x** (float): The float value to be sent to the modbus device for ``register_type: holding``
- **x** (bool): The boolean value to be sent to the modbus device for ``register_type: coil``
- **payload** (```std::vector<uint16_t>&payload```):
- for ``register_type: holding``: empty vector for the payload. The lamdba can add 16 bit raw modbus register words.
- for ``register_type: coil``: empty vector for the payload. If payload is set in the lambda it is sent as a custom command and must include all required bytes for a modbus request
note: because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER / BOOL>;`` the new value for the sensor.
- ``return <anything>; and fill payload with data`` if the payload is added from the lambda then these 16 bit words will be sent
- ``return {};`` if you don't want write the command to the device (or do it from the lambda).
- **register_type** (*Optional*): ``coil`` to create a binary outout or ``holding`` to create a float output.
- **multiply** (*Optional*, float): multiply the new value with this factor before sending the requests. Ignored if lambda is defined. Only valid for ``register_type: holding``.
- **offset**: (*Optional*, int): only required for uncommon response encodings
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
- **use_write_multiple**: (*Optional*, boolean): By default the modbus command ``Preset Single Registers`` (function code 6) is used for setting the holding register if only 1 register is set. If your device only supports ``Preset Multiple Registers`` (function code 16) set this option to true.
- **offset** (*Optional*, int): only required for uncommon response encodings
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
- **use_write_multiple** (*Optional*, boolean): By default the modbus command ``Preset Single Registers`` (function code 6) is used for setting the holding register if only 1 register is set. If your device only supports ``Preset Multiple Registers`` (function code 16) set this option to true.
All other options from :ref:`Output <config-output>`.
**Parameters passed into the lambda**
- **x** (float): The float value to be sent to the modbus device for ``register_type: holding``
- **x** (bool): The boolean value to be sent to the modbus device for ``register_type: coil``
- **payload** (`std::vector<uint16_t>&payload`):
- for ``register_type: holding``: empty vector for the payload. The lamdba can add 16 bit raw modbus register words.
- for ``register_type: coil``: empty vector for the payload. If payload is set in the lambda it is sent as a custom command and must include all required bytes for a modbus request
note: because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER / BOOL>;`` the new value for the sensor.
- ``return <anything>; and fill payload with data`` if the payload is added from the lambda then these 16 bit words will be sent
- ``return {};`` if you don't want write the command to the device (or do it from the lambda).
**Example**
.. code-block:: yaml

4
components/output/pca9685.rst
View File

@ -45,8 +45,8 @@ Configuration variables:
.. _pca9685-output:
PWM Output
----------
PCA9685 Output
--------------
The PCA9685 output component exposes a PCA9685 PWM channel of a global
:ref:`PCA9685 hub <pca9685-component>` as a float

6
components/output/slow_pwm.rst
View File

@ -34,12 +34,12 @@ Configuration variables:
- **period** (**Required**, :ref:`config-time`): The duration of each cycle. (i.e. a 10s
period at 50% duty would result in the pin being turned on for 5s, then off for 5s)
- **pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin to pulse.
- **state_change_action** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is switched. If a lambda is used the boolean ``state`` parameter holds the new status.
- **turn_on_action** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is turned on. Can be used to control for example a switch or output component.
- **state_change_action** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is switched. If a lambda is used the boolean ``state`` parameter holds the new status.
- **turn_on_action** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is turned on. Can be used to control for example a switch or output component.
- **turn_off_action** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is turned off. ``turn_on_action`` and ``turn_off_action`` must be configured together.
- **restart_cycle_on_state_change** (*Optional*, boolean): Restart a timer of a cycle
when new state is set. Defaults to ``false``.
- All other options from :ref:`Output <config-output>`.

10
components/output/tlc59208f.rst
View File

@ -8,8 +8,8 @@ TLC59208F
.. _tlc59208f-component:
Component
---------
Component/Hub
-------------
The TLC59208F component represents a Texas Instruments TLC59208F 8-bit PWM driver
(`datasheet <http://www.ti.com/lit/gpn/tlc59208f>`__,
@ -43,8 +43,8 @@ Configuration variables:
.. _tlc59208f-output:
PWM Output
----------
TLC59208F Output
----------------
The TLC59208F output component exposes a TLC59208F PWM channel of a global
:ref:`TLC59208F chip <tlc59208f-component>` as a float
@ -86,7 +86,7 @@ output.
id: 'tlc59208f_3_ch7'
channel: 7
tlc59208f_id: 'tlc59208f_3'
# Sample use as a RGB light
light:
- platform: rgb

57
components/pipsolar.rst
View File

@ -5,14 +5,14 @@ PipSolar PV Inverter
:description: Instructions for setting up PipSolar Compatible PV Inverter in ESPHome.
:image: pipsolar.jpg
The PipSolar component allows you to integrate PIP-compatible Inverters in ESPHome.
The PipSolar component allows you to integrate PIP-compatible Inverters in ESPHome.
It uses :ref:`UART <uart>` for communication.
Once configured, you can use sensors, binary sensors, switches and outputs as described below for your projects.
.. warning::
All functionality is working fine on esp8266 and esp32 chips.
All functionality is working fine on esp8266 and esp32 chips.
If you configure a lot of the possible sensors etc. from below it could be that you run out of memory (on esp8266).
If you configure more than one if this devices with nearly all sensors etc. you run in a stack-size issue. In this case you have to increase stack size.
@ -54,8 +54,8 @@ Configuration variables:
- **id** (**Required**, :ref:`config-id`): The id to use for this pipsolar component.
- **uart_id** (*Optional*): The uart Bus ID
Sensors
-------
Sensor
------
.. code-block:: yaml
# Example configuration entry
@ -121,15 +121,13 @@ All sensors are normal sensors... so all sensor variables are working to.
- **pv_input_voltage** (*Optional*): pv input voltage
- **battery_voltage_scc** (*Optional*): battery voltage from scc
- **battery_discharge_current** (*Optional*): battery discharge current
- **add_sbu_priority_version** (*Optional*): add sbu priority status
- **configuration_status** (*Optional*): configuration status
- **scc_firmware_version** (*Optional*): scc firmware version
- **battery_voltage_offset_for_fans_on** (*Optional*): battery voltage offset for fans on
- **eeprom_version** (*Optional*): eeprom version
- **pv_charging_power** (*Optional*): pc charging power
Binary Sensors
--------------
Binary Sensor
-------------
.. code-block:: yaml
# Example configuration entry
@ -205,8 +203,9 @@ All sensors are normal binary sensors... so all binary sensor variables are work
- **warning_high_ac_input_during_bus_soft_start** (*Optional*): warning high ac input during bus soft start
- **warning_battery_equalization** (*Optional*): warning battery equalization
Text Sensors
------------
Text Sensor
-----------
.. code-block:: yaml
# Example configuration entry
@ -234,9 +233,10 @@ All sensors are normal text sensors... so all text sensor variables are working
- **last_qt** (*Optional*): last qt reponse
- **last_qmn** (*Optional*): last qmn reponse
Switches
--------
Not all possible switches are exposed as they lead to the possibility to make serious damage. They should only be set at the physical device itself.
Switch
------
Not all possible switches are exposed as they lead to the possibility to make serious damage. They should only be set at the physical device itself.
.. code-block:: yaml
@ -265,12 +265,13 @@ All sensors are normal text sensors... so all text sensor variables are working
- **output_source_priority_solar** (*Optional*): output source priority solar
- **output_source_priority_battery** (*Optional*): output source priority battery
- **input_voltage_range** (*Optional*): input voltage range
- **pv_ok_condition_for_parallel** (*Optional*): pv ok condition for parallel
- **pv_ok_condition_for_parallel** (*Optional*): pv ok condition for parallel
- **pv_power_balance** (*Optional*): pv power balance
Outputs
--------------
Not all possible outputs are exposed as they lead to the possibility to make serious damage. They should only be set at the physical device itself.
Output
------
Not all possible outputs are exposed as they lead to the possibility to make serious damage. They should only be set at the physical device itself.
.. code-block:: yaml
@ -287,31 +288,31 @@ All sensors are normal text sensors... so all text sensor variables are working
- **battery_recharge_voltage** (*Optional*): battery recharge voltage;
- **possible_values** (*Optional*,list): a list of possible values default: 44.0,45.0,46.0,47.0,48.0,49.0,50.0,51.0
- **possible_values** (*Optional*, list): a list of possible values default: 44.0,45.0,46.0,47.0,48.0,49.0,50.0,51.0
- **battery_under_voltage** (*Optional*): battery under voltage;
- **possible_values** (*Optional*,list): a list of possible values default: 40.0,40.1,42,43,44,45,46,47,48.0
- **possible_values** (*Optional*, list): a list of possible values default: 40.0,40.1,42,43,44,45,46,47,48.0
- **battery_float_voltage** (*Optional*): battery float voltage;
- **possible_values** (*Optional*,list): a list of possible values default: 48.0,49.0,50.0,51.0
- **possible_values** (*Optional*, list): a list of possible values default: 48.0,49.0,50.0,51.0
- **battery_type** (*Optional*): battery type;
- **possible_values** (*Optional*,list): a list of possible values default: 0,1,2
- **possible_values** (*Optional*, list): a list of possible values default: 0,1,2
- **current_max_ac_charging_current** (*Optional*): current max ac charging current;
- **possible_values** (*Optional*,list): a list of possible values default: 2,10,20
- **possible_values** (*Optional*, list): a list of possible values default: 2,10,20
- **current_max_charging_current** (*Optional*): current max charging current;
- **possible_values** (*Optional*,list): a list of possible values default: 10,20,30,40
- **possible_values** (*Optional*, list): a list of possible values default: 10,20,30,40
- **output_source_priority** (*Optional*): output source priority;
- **possible_values** (*Optional*,list): a list of possible values default: 0,1,2
- **possible_values** (*Optional*, list): a list of possible values default: 0,1,2
- **charger_source_priority** (*Optional*): charger source priority;
- **possible_values** (*Optional*,list): a list of possible values default: 0,1,2,3
- **possible_values** (*Optional*, list): a list of possible values default: 0,1,2,3
- **battery_redischarge_voltage** (*Optional*): battery redischarge voltage;
- **possible_values** (*Optional*,list): a list of possible values default: 00.0,48.0,49,50.0,51.0,52,53,54,55,56,57,58
- **possible_values** (*Optional*, list): a list of possible values default: 00.0,48.0,49,50.0,51.0,52,53,54,55,56,57,58
.. _pipsolaroutput_set_level_action:
@ -333,7 +334,7 @@ target level of the output.
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the output.
- **level** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The target level.
- **value** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The target level.
See Also

4
components/remote_receiver.rst
View File

@ -89,7 +89,7 @@ Automations:
.. note::
In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC standard.
Therefore, if the the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above.
Therefore, if the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above.
For example, address: 0x84ED, command: 0x13EC becomes 0xB721 and 0x37C8 respectively.
- **on_nexa** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
@ -190,7 +190,7 @@ Remote code selection (exactly one of these has to be included):
.. note::
In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC standard.
Therefore, if the the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above.
Therefore, if the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above.
For example, address: 0x84ED, command: 0x13EC becomes 0xB721 and 0x37C8 respectively.
- **address** (**Required**, int): The address to trigger on, see dumper output for more info.

10
components/remote_transmitter.rst
View File

@ -159,7 +159,7 @@ Configuration variables:
``remote_transmitter.transmit_magiquest`` Action
************************************************
This :ref:`action <config-action>` sends a MagiQuest wand code to a remote transmitter.
This :ref:`action <config-action>` sends a MagiQuest wand code to a remote transmitter.
.. code-block:: yaml
@ -200,7 +200,7 @@ This :ref:`action <config-action>` sends an NEC infrared remote code to a remote
.. note::
In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC standard.
Therefore, if the the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above.
Therefore, if the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above.
For example, address: 0x84ED, command: 0x13EC becomes 0xB721 and 0x37C8 respectively.
.. code-block:: yaml
@ -576,6 +576,10 @@ Configuration variables:
This :ref:`action <config-action>` sends a Toshiba AC infrared remote code to a remote transmitter.
.. note::
This action transmits codes using the new(er) Toshiba AC protocol and likely will not work with older units.
.. code-block:: yaml
on_...:
@ -588,7 +592,7 @@ Configuration variables:
- **rc_code_1** (**Required**, int): The remote control code to send, see dumper output for more details.
- **rc_code_2** (*Optional*, int): The secondary remote control code to send; some codes are sent in
two parts.
- **Note:** this action transmits codes using the new(er) Toshiba AC protocol and likely will not work with older units.
- All other options from :ref:`remote_transmitter-transmit_action`.

2
components/rtttl.rst
View File

@ -59,7 +59,7 @@ Plays an rtttl tone.
Configuration options:
- **play** (**Required**, string, :ref:`templatable <config-templatable>`): The rtttl string.
- **rtttl** (**Required**, string, :ref:`templatable <config-templatable>`): The rtttl string.
You can find many rtttl strings online on the web, they must start with a name, then a colon: ``:`` symbol
and more codes of the song itself. Tip: you can try playing with the values of d=16,o=6,b=95 and make the

48
components/select/modbus_controller.rst
View File

@ -26,12 +26,13 @@ Configuration variables:
------------------------
- **name** (**Required**, string): The name of the Select.
- **address**: (**Required**, int): The start address of the first or only register
- **address** (**Required**, int): The start address of the first or only register
of the Select.
- **optionsmap**: (**Required**, Map[str, int]): Provide a mapping from options (str) of
- **optionsmap** (**Required**, Map[str, int]): Provide a mapping from options (str) of
this Select to values (int) of the modbus register and vice versa. All options and
all values have to be unique.
- **value_type**: (*Optional*): The datatype of the modbus data. Defaults to ``U_WORD``.
- **value_type** (*Optional*): The datatype of the modbus data. Defaults to ``U_WORD``.
- ``U_WORD`` (unsigned 16 bit integer from 1 register = 16bit)
- ``S_WORD`` (signed 16 bit integer from 1 register = 16bit)
- ``U_DWORD`` (unsigned 32 bit integer from 2 registers = 32bit)
@ -42,24 +43,39 @@ Configuration variables:
- ``S_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit)
- ``U_QWORD_R`` (unsigned 64 bit integer from 4 registers low word first)
- ``U_QWORD_R`` (signed 64 bit integer from 4 registers low word first)
- **register_count**: (*Optional*): The number of registers which are used for this Select. Only
required for uncommon response encodings or to
:ref:`optimize modbus communications<modbus_register_count>`. Overrides the defaults determined
- **register_count** (*Optional*): The number of registers which are used for this Select. Only
required for uncommon response encodings or to
:ref:`optimize modbus communications<modbus_register_count>`. Overrides the defaults determined
by ``value_type``.
- **skip_updates**: (*Optional*, int): By default all sensors of of a modbus_controller are
- **skip_updates** (*Optional*, int): By default all sensors of a modbus_controller are
updated together. For data points that don't change very frequently updates can be skipped. A
value of 5 would only update this sensor range in every 5th update cycle. Defaults to ``0``.
Note: The modbus_controller merges several registers into groups which are updated together. For
each group the smallest update cycle is used.
- **force_new_range**: (*Optional*, boolean): If possible sensors with sequential addresses are
grouped together and requested in one range. Setting this to ``true`` enforces the start of a new
- **force_new_range** (*Optional*, boolean): If possible sensors with sequential addresses are
grouped together and requested in one range. Setting this to ``true`` enforces the start of a new
range at that address.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): Lambda to be evaluated every update interval
to get the current option of the select.
Parameters passed into lambda
- **x** (``int64_t``): The parsed integer value of the modbus data.
- **data** (``const std::vector<uint8_t>&``): vector containing the complete raw modbus response bytes for this
sensor. Note: because the response contains data for all registers in the same range you have to
use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (``ModbusSelect*const``): The sensor object itself.
Possible return values for the lambda:
- ``return <std::string>;`` The new option for this Select.
- ``return {};`` Use default mapping (see ``optionsmap``).
- **write_lambda** (*Optional*, :ref:`lambda <config-lambda>`): Lambda to be evaluated on every update
of the Sensor, before the new value is written to the modbus registers.
- **use_write_multiple**: (*Optional*, boolean): By default the modbus command ``Preset Single Registers``
- **use_write_multiple** (*Optional*, boolean): By default the modbus command ``Preset Single Registers``
(function code 6) is used for setting the holding register if only 1 register is set. If your device only supports *Preset Multiple Registers* (function code 16) set this option to ``true``. Defaults
to ``false``.
- **optimistic**: (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
@ -68,19 +84,7 @@ Configuration variables:
- All other options from :ref:`Select <config-select>`.
Parameters passed into ``lambda``
---------------------------------
- **x** (``int64_t``): The parsed integer value of the modbus data.
- **data** (``const std::vector<uint8_t>&``): vector containing the complete raw modbus response bytes for this
sensor. Note: because the response contains data for all registers in the same range you have to
use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (``ModbusSelect*const``): The sensor object itself.
Possible return values for the lambda:
- ``return <std::string>;`` The new option for this Select.
- ``return {};`` Use default mapping (see ``optionsmap``).
.. code-block:: yaml

12
components/sensor/airthings_ble.rst
View File

@ -1,5 +1,5 @@
AirThings BLE Sensors
========================
=====================
.. seo::
:description: Instructions for setting up AirThings bluetooth-based sensors in ESPHome.
@ -28,7 +28,7 @@ The device will then listen for nearby devices, and display a message like this
.. code-block:: text
[D][airthings_ble:019]:
[D][airthings_ble:019]:
Found AirThings device Serial: 123456789 (MAC: 01:02:03:04:05:06)
Once the device is found, remove the ``airthings_ble`` device tracker from your configuration and take note of the device MAC address, and use it when configuring a sensor below.
@ -36,8 +36,8 @@ Once the device is found, remove the ``airthings_ble`` device tracker from your
Supported Devices
-----------------
Wave Plus
*********
Airthings Wave Plus Sensor
**************************
AirThings Wave Plus tracks radon (24h and long term), airborne chemicals, CO2, temperature, atmospheric pressure and humidity.
@ -76,8 +76,8 @@ Configuration example:
esp32_ble_tracker:
Wave Mini
*********
Airthings Wave Mini Sensor
**************************
AirThings Wave Mini tracks airborne chemicals, temperature, pressure and humidity.

18
components/sensor/apds9960.rst
View File

@ -66,11 +66,11 @@ Configuration variables:
- **name** (**Required**, string): The name for the sensor.
- **type** (**Required**, string): The type of sensor measurement. One of
- **CLEAR**
- **RED**
- **GREEN**
- **BLUE**
- **PROXIMITY**
- ``CLEAR``
- ``RED``
- ``GREEN``
- ``BLUE``
- ``PROXIMITY``
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
@ -86,10 +86,10 @@ Configuration variables:
- **name** (**Required**, string): The name for the binary sensor.
- **direction** (**Required**, string): The direction to measure. One of:
- **UP**
- **DOWN**
- **LEFT**
- **RIGHT**
- ``UP``
- ``DOWN``
- ``LEFT``
- ``RIGHT``
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.

2
components/sensor/ccs811.rst
View File

@ -54,7 +54,7 @@ Configuration variables:
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
- **version:** (*Optional*): This sensor reports the firmware ('application') version in text, with the internal hex representation of the version number behind it, so version 1.0.0 will be reported as '1.0.0 (0x1000)'.
- **version** (*Optional*): This sensor reports the firmware ('application') version in text, with the internal hex representation of the version number behind it, so version 1.0.0 will be reported as '1.0.0 (0x1000)'.
- **name** (**Required**, string): The name for the version sensor.

41
components/sensor/daly_bms.rst
View File

@ -1,5 +1,5 @@
Daly BMS
========
Daly BMS Sensor
===============
.. seo::
:description: Instructions for setting up a Daly Smart BMS
@ -23,10 +23,10 @@ The BMS communicates via :ref:`UART <uart>`.
tx_pin: GPIO1
rx_pin: GPIO3
baud_rate: 9600
daly_bms:
update_interval: 20s
sensor:
- platform: daly_bms
voltage:
@ -72,8 +72,8 @@ The BMS communicates via :ref:`UART <uart>`.
- platform: daly_bms
status:
name: "BMS Status"
binary_sensor:
- platform: daly_bms
charging_mos_enabled:
@ -84,12 +84,14 @@ The BMS communicates via :ref:`UART <uart>`.
Component/Hub
-------------
- **update_interval** (*Optional*, :ref:`config-time`): Delay between data requests.
Configuration variables:
************************
Sensor:
-------
- **update_interval** (*Optional*, :ref:`config-time`): Delay between data requests.
Sensor
------
A sensor platform to read BMS data
Configuration variables:
@ -184,15 +186,16 @@ Configuration variables:
- **name** (**Required**, string): The name for the second temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **cell_x_voltage** (*Optional*): The voltage of cell x.
- **cell_1_voltage** (*Optional*): The voltage of cell number 1. Cell number can be from 1 to 16.
- **name** (**Required**, string): The name for the cell voltage sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
Text Sensor:
------------
Text Sensor
-----------
Text sensor that indicates the status of BMS.
Configuration variables:
@ -204,8 +207,9 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Text Sensor <config-text_sensor>`.
Binary Sensor:
--------------
Binary Sensor
-------------
Binary sensor that indicates the status of MOS.
Configuration variables:
@ -223,8 +227,9 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
UART Connection:
----------------
UART Connection
---------------
Connect RX from BMS to TX in ESP board and TX from BMS to RX in ESP board
.. figure:: images/daly_bms_pinout.png

2
components/sensor/kalman_combinator.rst
View File

@ -45,7 +45,7 @@ Configuration variables:
source must have either **error** or **error_function** set. These work like
the **process_std_dev** parameter, with low values marking accurate data.
- **sensor** (**Required**, :ref:`config-id` of a :doc:`/components/sensor/index`): The
- **source** (**Required**, :ref:`config-id` of a :doc:`/components/sensor/index`): The
sensor that is used as sample source
- **error** (**Required**, float, :ref:`templatable <config-templatable>`): The standard deviation of the
sensor's measurements. If implemented as a template, the measurement is in

2
components/sensor/ltr390.rst
View File

@ -36,7 +36,7 @@ Configuration variables:
- **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. See table below for details. Default is ``"X3"``.
- **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. See table below for details. Default is ``18``.
- **window_correction_factor** (*Optional*, float): Window correction factor. Use larger values when using under tinted windows. Default is ``1.0``, must be ``>= 1.0``.
- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is `0x53`.
- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is ``0x53``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``. It is recommended that the update interval is at least 1 second since updates can take up to 800ms when using a high resolution value.

16
components/sensor/max9611.rst
View File

@ -8,10 +8,10 @@ MAX9611/9612 High Side Current+Voltage+Temperature Sensor
The ``MAX9611`` sensor platform allows you to use your MAX9611/MAX9612
(`datasheet <https://datasheets.maximintegrated.com/en/ds/MAX9611-MAX9612.pdf>`__)
High-side current, voltage and temperature sensors with ESPHome.
High-side current, voltage and temperature sensors with ESPHome.
This sensor supports up to +60V DC common mode voltage, has a 1.8V to 3.3V logic range,
a 12-Bit integrated ADC with :ref:`I²C <i2c>`, and is meant to act as a high-side current sense amplifier.
This sensor supports up to +60V DC common mode voltage, has a 1.8V to 3.3V logic range,
a 12-Bit integrated ADC with :ref:`I²C <i2c>`, and is meant to act as a high-side current sense amplifier.
The :ref:`I²C <i2c>` is
required to be set up in your configuration for this sensor to work.
@ -43,19 +43,19 @@ required to be set up in your configuration for this sensor to work.
Configuration variables:
------------------------
- **shunt_resistance** (*Required*): The value of the High Side Shunt Resistor.
- **shunt_resistance** (**Required**, ohms): The value of the High Side Shunt Resistor.
- **Voltage** (*Optional*): The information for the voltage sensor
- **voltage** (*Optional*): The information for the voltage sensor
- **name** (**Required**, string): The name for the voltage sensor.
- All other options from :ref:`Sensor <config-sensor>`.
- **Current** (*Optional*): The information for the current sensor, scaled by the gain factor and multiplied by voltage
- **current** (*Optional*): The information for the current sensor, scaled by the gain factor and multiplied by voltage
- **name** (**Required**, string): The name for the current sensor.
- All other options from :ref:`Sensor <config-sensor>`.
- **Power** (*Optional*): The information for the power sensor
- **power** (*Optional*): The information for the power sensor
- **name** (**Required**, string): The name for the power sensor.
- All other options from :ref:`Sensor <config-sensor>`.
@ -67,7 +67,7 @@ Configuration variables:
- **address** (*Optional*, int): Manually specify the I²C address of
the sensor. Defaults to ``0x70``.
the sensor. Defaults to ``0x70``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.

16
components/sensor/mlx90393.rst
View File

@ -40,12 +40,12 @@ Configuration variables:
- **name** (**Required**, string): The name for the x-axis sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- **resolution** (*Optional*, int): Set resolution. Defaults to ``19BIT``. Must be one of:
- ``16BIT``
- ``17BIT``
- ``18BIT``
- ``19BIT``
- All other options from :ref:`Sensor <config-sensor>`.
- **y_axis** (*Optional*): The information for the y-axis.
@ -53,12 +53,12 @@ Configuration variables:
- **name** (**Required**, string): The name for the y-axis sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- **resolution** (*Optional*, int): Set resolution. Defaults to ``19BIT``. Must be one of:
- ``16BIT``
- ``17BIT``
- ``18BIT``
- ``19BIT``
- All other options from :ref:`Sensor <config-sensor>`.
- **z_axis** (*Optional*): The information for the z-axis.
@ -66,19 +66,19 @@ Configuration variables:
- **name** (**Required**, string): The name for the z-axis sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- **resolution** (*Optional*, int): Set resolution. Defaults to ``16BIT``. Must be one of:
- ``16BIT``
- ``17BIT``
- ``18BIT``
- ``19BIT``
- All other options from :ref:`Sensor <config-sensor>`.
- **temperature** (*Optional*): Built-in 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.
- **oversampling** (*Optional*, int): On-chip oversampling for the temperature sensor. Defaults to `0`. Must be between `0` and `3`.
- **oversampling** (*Optional*, int): On-chip oversampling for the temperature sensor. Defaults to ``0``. Must be between ``0`` and ``3``.
- All other options from :ref:`Sensor <config-sensor>`.
- **drdy_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Data-ready pin. Often labelled ``INT``. Using this pin might lead to slightly quicker read times.

116
components/sensor/modbus_controller.rst
View File

@ -1,5 +1,5 @@
Modbus Sensor
=============
Modbus Controller Sensor
========================
.. seo::
:description: Instructions for setting up a modbus_controller device sensor.
@ -14,43 +14,59 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the sensor.
- **register_type** (**Required**): type of the modbus register.
- coil: coils are also called discrete output. Coils are 1-bit registers (on/off values) that are used to control discrete outputs. Read and Write access. Modbus function code 1 (Read Coil Status) will be used
- discrete_input: discrete input register (read only coil) are similar to coils but can only be read. Modbus function code 2 (Read Input Status) will be used.
- holding: Holding Registers - Holding registers are the most universal 16-bit register. Read and Write access. Modbus function code 3 (Read Holding Registers) will be used.
- read: Read Input Registers - registers are 16-bit registers used for input, and may only be read. Modbus function code 4 (Read Input Registers) will be used.
- **address**: (**Required**, int): start address of the first register in a range
- **value_type**: (**Required**): datatype of the mod_bus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first)
- U_WORD (unsigned 16 bit integer from 1 register = 16bit)
- S_WORD (signed 16 bit integer from 1 register = 16bit)
- U_DWORD (unsigned 32 bit integer from 2 registers = 32bit)
- S_DWORD (signed 32 bit integer from 2 registers = 32bit)
- U_DWORD_R (unsigned 32 bit integer from 2 registers low word first)
- S_DWORD_R (signed 32 bit integer from 2 registers low word first)
- U_QWORD (unsigned 64 bit integer from 4 registers = 64bit)
- S_QWORD (signed 64 bit integer from 4 registers = 64bit)
- U_QWORD_R (unsigned 64 bit integer from 4 registers low word first)
- S_QWORD_R (signed 64 bit integer from 4 registers low word first)
- FP32 (32 bit IEEE 754 floating point from 2 registers)
- FP32_R (32 bit IEEE 754 floating point - same as FP32 but low word first)s
- **bitmask**: (*Optional*) some values are packed in a response. The bitmask can be used to extract a value from the response. For example, if the high byte value register 0x9013 contains the minute value of the current time. To only exctract this value use bitmask: 0xFF00. The result will be automatically right shifted by the number of 0 before the first 1 in the bitmask. For 0xFF00 (0b1111111100000000) the result is shifted 8 posistions. More than one sensor can use the same address/offset if the bitmask is different.
- **skip_updates**: (*Optional*, int): By default all sensors of of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
- ``coil``: coils are also called discrete output. Coils are 1-bit registers (on/off values) that are used to control discrete outputs. Read and Write access. Modbus function code 1 (Read Coil Status) will be used
- ``discrete_input``: discrete input register (read only coil) are similar to coils but can only be read. Modbus function code 2 (Read Input Status) will be used.
- ``holding``: Holding Registers - Holding registers are the most universal 16-bit register. Read and Write access. Modbus function code 3 (Read Holding Registers) will be used.
- ``read``: Read Input Registers - registers are 16-bit registers used for input, and may only be read. Modbus function code 4 (Read Input Registers) will be used.
- **address** (**Required**, int): start address of the first register in a range
- **value_type** (**Required**): datatype of the mod_bus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first)
- ``U_WORD``: unsigned 16 bit integer from 1 register = 16bit
- ``S_WORD``: signed 16 bit integer from 1 register = 16bit
- ``U_DWORD``: unsigned 32 bit integer from 2 registers = 32bit
- ``S_DWORD``: signed 32 bit integer from 2 registers = 32bit
- ``U_DWORD_R``: unsigned 32 bit integer from 2 registers low word first
- ``S_DWORD_R``: signed 32 bit integer from 2 registers low word first
- ``U_QWORD``: unsigned 64 bit integer from 4 registers = 64bit
- ``S_QWORD``: signed 64 bit integer from 4 registers = 64bit
- ``U_QWORD_R``: unsigned 64 bit integer from 4 registers low word first
- ``S_QWORD_R``: signed 64 bit integer from 4 registers low word first
- ``FP32``: 32 bit IEEE 754 floating point from 2 registers
- ``FP32_R``: 32 bit IEEE 754 floating point - same as FP32 but low word first
- **bitmask** (*Optional*, int): some values are packed in a response. The bitmask can be used to extract a value from the response. For example, if the high byte value register 0x9013 contains the minute value of the current time. To only exctract this value use bitmask: 0xFF00. The result will be automatically right shifted by the number of 0 before the first 1 in the bitmask. For 0xFF00 (0b1111111100000000) the result is shifted 8 posistions. More than one sensor can use the same address/offset if the bitmask is different.
- **skip_updates** (*Optional*, int): By default all sensors of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
Note: The modbus_controller groups component by address ranges to reduce number of transactions. All compoents with the same address will be updated in one request. skip_updates applies for all components in the same range.
- **register_count**: (*Optional*): only required for uncommon response encodings or to :ref:`optimize modbus communications<modbus_register_count>`
- **register_count** (*Optional*): only required for uncommon response encodings or to :ref:`optimize modbus communications<modbus_register_count>`
The number of registers this data point spans. Overrides the defaults determined by ``value_type``.
If no value for ``register_count`` is provided, it is calculated based on the register type.
The default size for 1 register is 16 bits (1 Word). Some devices are not adhering to this convention and have registers larger than 16 bits. In this case ``register_count`` and ``response_size`` must be set. For example, if your modbus device uses 1 registers for a FP32 value instead the default of two set ``register_count: 1`` and ``response_size: 4``.
- **response_size**: (*Optional*): Size of the response for the register in bytes. Defaults to register_count*2.
- **force_new_range**: (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting ``force_new_range: true`` enforces the start of a new range at that address.
- **custom_data** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_data`` is used ``address`` and ``register_type`` can't be used.
- **response_size** (*Optional*, int): Size of the response for the register in bytes. Defaults to register_count*2.
- **force_new_range** (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting ``force_new_range: true`` enforces the start of a new range at that address.
- **custom_command** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_command`` is used ``address`` and ``register_type`` can't be used.
custom data must contain all required bytes including the modbus device address. The crc is automatically calculated and appended to the command.
See :ref:`modbus_custom_data` how to use ``custom_command``
See :ref:`modbus_custom_command` how to use ``custom_command``
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated every update interval to get the new value of the sensor.
- **offset**: (*Optional*, int): only required for uncommon response encodings
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
For coil or discrete input registers offset is the position of the coil/register because these registers encode 8 coils in one byte.
Parameters passed into the lambda
- **x** (float): The parsed float value of the modbus data
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
*note:* because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER>;`` the new value for the sensor.
- ``return NAN;`` if the state should be considered invalid to indicate an error (advanced).
- **offset** (*Optional*, int): only required for uncommon response encodings
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
For coil or discrete input registers offset is the position of the coil/register because these registers encode 8 coils in one byte.
- All other options from :ref:`Sensor <config-sensor>`.
@ -122,28 +138,14 @@ This example logs the value as parsed and the raw modbus bytes received for this
}
return x ;
.. _modbus_custom_command:
Parameters passed into the lambda
Using ``custom_command``
------------------------
- **x** (float): The parsed float value of the modbus data
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
note: because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER>;`` the new value for the sensor.
- ``return NAN;`` if the state should be considered invalid to indicate an error (advanced).
.. _modbus_custom_data:
Using custom_data
-----------------
``custom_data`` can be used to create an arbitrary modbus command. Combined with a lambda any response can be handled.
``custom_command`` can be used to create an arbitrary modbus command. Combined with a lambda any response can be handled.
This example re-implements the command to read the registers 0x156 (Total active energy) and 0x158 Total (reactive energy) from a SDM-120.
SDM-120 returns the values as floats using 32 bits in 2 registers.
SDM-120 returns the values as floats using 32 bits in 2 registers.
.. code-block:: yaml
@ -171,7 +173,7 @@ SDM-120 returns the values as floats using 32 bits in 2 registers.
# 0x4 : modbus function code
# 0x1 : high byte of modbus register address
# 0x56: low byte of modbus register address
# 0x00: high byte of total number of registers requested
# 0x00: high byte of total number of registers requested
# 0x02: low byte of total number of registers requested
custom_command: [ 0x2, 0x4, 0x1, 0x56,0x00, 0x02]
value_type: FP32
@ -205,10 +207,10 @@ SDM-120 returns the values as floats using 32 bits in 2 registers.
.. note:: **Optimize modbus communications**
``register_count`` can also be used to skip a register in consecutive range.
An example is a SDM meter:
``register_count`` can also be used to skip a register in consecutive range.
An example is a SDM meter:
.. code-block:: yaml
- platform: modbus_controller
@ -236,9 +238,9 @@ SDM-120 returns the values as floats using 32 bits in 2 registers.
value_type: FP32
accuracy_decimals: 1
Maybe you don’t care about the Voltage value for Phase 2 and Phase 3 (or you have a SDM-120).
Maybe you don’t care about the Voltage value for Phase 2 and Phase 3 (or you have a SDM-120).
Of course, you can delete the sensors your don’t care about. But then you have a gap in the addresses. The configuration above will generate one modbus command `read multiple registers from 0 to 6`. If you remove the registers at address 2 and 4 then 2 commands will be generated `read register 0` and `read register 6`.
To avoid the generation of multiple commands and reduce the amount of uart communication ``register_count`` can be used to fill the gaps
To avoid the generation of multiple commands and reduce the amount of uart communication ``register_count`` can be used to fill the gaps
.. code-block:: yaml
@ -256,7 +258,7 @@ SDM-120 returns the values as floats using 32 bits in 2 registers.
register_type: "read"
value_type: FP32
Because `register_count: 6` is used for the first register the command “read registers from 0 to 6” can still be used but the values in between are ignored.
Because `register_count: 6` is used for the first register the command “read registers from 0 to 6” can still be used but the values in between are ignored.
**Calculation:** FP32 is a 32 bit value and uses 2 registers. Therefore, to skip the 2 FP32 registers the size of these 2 registers must be added to the default size for the first register.
So we have 2 for address 0, 2 for address 2 and 2 for address 4 then ``register_count`` must be 6.

56
components/sensor/mopeka_ble.rst → components/sensor/mopeka_pro_check.rst
View File

@ -1,12 +1,12 @@
Mopeka Pro Check BLE Sensor
===============================
===========================
.. seo::
:description: Instructions for setting up Mopeka Pro Check bluetooth-based sensors in ESPHome.
:image: mopeka_pro_check.jpg
:keywords: Mopeka, Mopeka Pro Check, BLE, Bluetooth
The ``mopeka_pro_check`` sensor platform lets you track the output of Mopeka
The ``mopeka_pro_check`` sensor platform lets you track the output of Mopeka
Pro Check LP Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`.
This component will track the tank level, distance, temperature, and battery
percentage of a Mopeka Pro Check LP device every time the sensor sends
@ -27,33 +27,33 @@ out a BLE broadcast.
esp32_ble_tracker:
sensor:
# Example using 20lb vertical propane tank.
- platform: mopeka_pro_check
mac_address: D3:75:F2:DC:16:91
tank_type: 20LB_V
temperature:
name: "Propane test temp"
level:
name: "Propane test level"
distance:
name: "Propane test distance"
battery_level:
name: "Propane test battery level"
# Example using 20lb vertical propane tank.
- platform: mopeka_pro_check
mac_address: D3:75:F2:DC:16:91
tank_type: 20LB_V
temperature:
name: "Propane test temp"
level:
name: "Propane test level"
distance:
name: "Propane test distance"
battery_level:
name: "Propane test battery level"
# Custom example - user defined empty / full points
- platform: mopeka_pro_check
mac_address: D3:75:F2:DC:16:91
tank_type: CUSTOM
custom_distance_full: 40cm
custom_distance_empty: 10mm
temperature:
name: "Propane c test temp"
level:
name: "Propane c test level"
distance:
name: "Propane c test distance"
battery_level:
name: "Propane c test battery level"
# Custom example - user defined empty / full points
- platform: mopeka_pro_check
mac_address: D3:75:F2:DC:16:91
tank_type: CUSTOM
custom_distance_full: 40cm
custom_distance_empty: 10mm
temperature:
name: "Propane c test temp"
level:
name: "Propane c test level"
distance:
name: "Propane c test distance"
battery_level:
name: "Propane c test battery level"
Configuration variables:

4
components/sensor/radon_eye_ble.rst
View File

@ -37,8 +37,8 @@ take note of the device MAC address, and use it when configuring a sensor below.
Supported Devices
-----------------
Radon Eye RD200
***************
Radon Eye RD200 Sensor
**********************
Radon Eye RD200 tracks radon concentration over short periods (5 min interval) and longer periods
(24h or month).

10
components/sensor/rotary_encoder.rst
View File

@ -41,7 +41,7 @@ To modify additional parameters of pins like active state or pull-ups, you may a
.. code-block:: yaml
# Example of advanced pin configuration
pin_a:
pin_a:
number: D5
inverted: true
mode:
@ -62,9 +62,9 @@ Configuration variables:
- **resolution** (*Optional*, string): The resolution of the sensor, this controls how many
pulses are generated by one step:
- 1 (default)
- 2
- 4
- ``1`` - (Default)
- ``2``
- ``4``
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **min_value** (*Optional*, int): The minimum value this rotary encoder will go to, turning
@ -79,7 +79,7 @@ Configuration variables:
For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the
:doc:`esphome section </components/esphome>`.
- ``RESTORE_DEFAULT_ZERO`` (Default) - Attempt to restore state and default to zero (0) if not possible to restore.
- ``RESTORE_DEFAULT_ZERO`` - (Default) Attempt to restore state and default to zero (0) if not possible to restore.
- ``ALWAYS_ZERO`` - Always initialize the counter with value zero (0).
- **on_clockwise** (*Optional*, :ref:`Automation <automation>`): Actions to be performed when

8
components/sensor/tsl2591.rst
View File

@ -131,13 +131,13 @@ For the TSL2591 device:
- **update_interval** (*Optional*, :ref:`config-time`): The interval for checking the sensors.
Defaults to ``60s``.
- **power_save_mode** (*Optional*, boolean) Should the device be powered down between update intervals?
- **power_save_mode** (*Optional*, boolean): Should the device be powered down between update intervals?
Defaults to ``True``.
- **device_factor** (*Optional*, float) The default is ``53.0``.
- **device_factor** (*Optional*, float): The default is ``53.0``.
The device factor to be used as part of the lux equation for ``calculated_lux``.
- **glass_attenuation_factor** (*Optional*, float) The default is ``7.7``.
- **glass_attenuation_factor** (*Optional*, float): The default is ``7.7``.
The glass attenuation factor to be used as part of the lux equation for ``calculated_lux``.
- All other options for I²C devices described at :ref:`I²C Bus <i2c>`.

3
components/sensor/xiaomi_miscale.rst
View File

@ -47,7 +47,8 @@ Configuration variables:
- All other options from :ref:`Sensor <config-sensor>`.
- **clear_impedance** (*Optional*): Clear the impedance information if a weight reading without impedance is received. Defaults to ``false``. **Only available on MiScale2**
Useful in the example below if a person steps onto the scale without waiting for the complete measurement. Without setting the flag the impedance reading of the measurement before will be used for the currently measured person.
Useful in the example below if a person steps onto the scale without waiting for the complete measurement. Without setting the flag the impedance reading of the measurement before will be used for the currently measured person.
Configuration example with multiple users:
******************************************

18
components/sim800l.rst
View File

@ -75,7 +75,7 @@ Configuration variables:
- All other options from :ref:`Sensor <config-sensor>`.
Binary sensor
Binary Sensor
-------------
Configuration variables:
@ -127,6 +127,20 @@ Send a SMS message to a phone recipient using this action in automations.
message: !lambda |-
return id(reed_switch).state ? "Door is now OPEN" : "Hey door just CLOSED";
Configuration options:
- **recipient** (**Required**, string, :ref:`templatable <config-templatable>`): The message recipient.
number.
- **message** (**Required**, string, :ref:`templatable <config-templatable>`): The message content.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the SIM800L if you have multiple components.
.. note::
This action can also be written in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
id(sim800l1).send_sms("+15551234567", "The message content");
.. _sim800l-dial_action:
@ -144,7 +158,7 @@ Dial to a phone recipient using this action in automations.
Configuration options:
- **recipient** (***Required**, string, :ref:`templatable <config-templatable>`): The number to dial.
- **recipient** (**Required**, string, :ref:`templatable <config-templatable>`): The number to dial.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the SIM800L if you have multiple components.
.. note::

39
components/switch/modbus_controller.rst
View File

@ -1,5 +1,5 @@
Modbus Switch
=============
Modbus Controller Switch
========================
.. seo::
:description: Instructions for setting up a modbus_controller device sensor.
@ -14,35 +14,34 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the sensor.
- **register_type** (**Required**): type of the modbus register.
- **address**: (**Required**, int): start address of the first register in a range
- **offset**: (*Optional*, int): not required in most cases
- **address** (**Required**, int): start address of the first register in a range
- **offset** (*Optional*, int): not required in most cases
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
The value for offset depends on the register type. For holding input registers the offset is in bytes. For coil and discrete input resisters the LSB of the first data byte contains the coil addressed in the request. The other coils follow toward the high-order end of this byte and from low order to high order in subsequent bytes. For the registers offset is the position of the relevant bit.
To get the value of the coil register 2 can be retrived using address: 2 / offset: 0 or address: 0 / offset 2
- **bitmask** : some values are packed in a response. The bitmask is used to determined if the result is true or false
- **skip_updates**: (*Optional*, int): By default all sensors of of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
- **use_write_multiple**: (*Optional*, boolean): By default the modbus command ``Force Single Coil`` (function code 5) is used to send state changes to the device. If your device only supports ``Force Multiple Coils`` (function code 15) set this option to true.
- **custom_data** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_data`` is used ``address`` and ``register_type`` can't be used.
To get the value of the coil register 2 can be retrieved using address: 2 / offset: 0 or address: 0 / offset 2
- **bitmask** (*Optional*, int): Some values are packed in a response. The bitmask is used to determined if the result is true or false.
- **skip_updates** (*Optional*, int): By default all sensors of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
- **use_write_multiple** (*Optional*, boolean): By default the modbus command ``Force Single Coil`` (function code 5) is used to send state changes to the device. If your device only supports ``Force Multiple Coils`` (function code 15) set this option to true.
- **custom_command** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_command`` is used ``address`` and ``register_type`` can't be used.
custom data must contain all required bytes including the modbus device address. The crc is automatically calculated and appended to the command.
See :ref:`modbus_custom_data` how to use ``custom_command``
See :ref:`modbus_custom_command` how to use ``custom_command``
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated every update interval to read the status of the switch.
- **write_lambda** (*Optional*, :ref:`lambda <config-lambda>`): Lambda called before send.
Lambda is evaluated before the modbus write command is created.
**Parameters passed into write_lambda**
Parameters passed into the lambda
- **x** (float): The float value to be sent to the modbus device
- **x** (float): The float value to be sent to the modbus device
- **payload** (``std::vector<uint8_t>&payload``): empty vector for the payload. If payload is set in the lambda it is sent as a custom command and must include all required bytes for a modbus request
*note:* because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a Switch derived object): The sensor object itself.
- **payload** (`std::vector<uint8_t>&payload`): empty vector for the payload. If payload is set in the lambda it is sent as a custom command and must include all required bytes for a modbus request
note: because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a Switch derived object): The sensor object itself.
Possible return values for the lambda:
Possible return values for the lambda:
- ``return <true / false>;`` the new value for the sensor.
- ``return <anything>; and fill payload with data`` if the payload is added from the lambda then these bytes will be sent.
- ``return {};`` in the case the lambda handles the sending of the value itself.
- ``return <true / false>;`` the new value for the sensor.
- ``return <anything>; and fill payload with data`` if the payload is added from the lambda then these bytes will be sent.
- ``return {};`` in the case the lambda handles the sending of the value itself.
**Example**

64
components/text_sensor/modbus_controller.rst
View File

@ -1,5 +1,5 @@
Modbus Text Sensor
==================
Modbus Controller Text Sensor
=============================
.. seo::
:description: Instructions for setting up a modbus_controller modbus text sensor.
@ -13,43 +13,45 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the sensor.
- **register_type** (**Required**): type of the modbus register.
- coil: coils are also called discrete outout. Coils are 1-bit registers (on/off values) that are used to control discrete outputs. Read and Write access
- discrete_input: discrete input register (read only coil) are similar to coils but can only be read.
- holding: Holding Registers - Holding registers are the most universal 16-bit register. Read and Write access
- read: Read Input Registers - registers are 16-bit registers used for input, and may only be read
- **address**: (**Required**, int): start address of the first register in a range
- **skip_updates**: (*Optional*, int): By default all sensors of of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
- **register_count**: (*Optional*): The number of registers this data point spans. Default is 1
- **response_size**: (**Required**): Number of bytes of the response
- **raw_encode**: (*Optional*, enum) If the response is binary it can't be published directly. Since a text sensor only publishes strings the binary data can be encoded
- ``coil``: coils are also called discrete outout. Coils are 1-bit registers (on/off values) that are used to control discrete outputs. Read and Write access
- ``discrete_input``: discrete input register (read only coil) are similar to coils but can only be read.
- ``holding``: Holding Registers - Holding registers are the most universal 16-bit register. Read and Write access
- ``read``: Read Input Registers - registers are 16-bit registers used for input, and may only be read
- **address** (**Required**, int): start address of the first register in a range
- **skip_updates** (*Optional*, int): By default all sensors of a modbus_controller are updated together. For data points that don't change very frequently updates can be skipped. A value of 5 would only update this sensor range in every 5th update cycle
- **register_count** (*Optional*): The number of registers this data point spans. Default is 1
- **response_size** (**Required**): Number of bytes of the response
- **raw_encode** (*Optional*, enum): If the response is binary it can't be published directly. Since a text sensor only publishes strings the binary data can be encoded
- ``NONE``: Don't encode data.
- ``HEXBYTES``: 2 byte hex string. 0x2011 will be sent as "2011".
- ``COMMA``: Byte values as integers, delimited by a coma. 0x2011 will be sent as "32,17"
- **force_new_range**: (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting `foce_new_range: true` enforces the start of a new range at that address.
- **custom_data** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_data`` is used ``address`` and ``register_type`` can't be used.
custom data must contain all required bytes including the modbus device address. The crc is automatically calculated and appended to the command.
See :ref:`modbus_custom_data` how to use ``custom_command``
- **force_new_range** (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting ``force_new_range: true`` enforces the start of a new range at that address.
- **custom_command** (*Optional*, list of bytes): raw bytes for modbus command. This allows using non-standard commands. If ``custom_command`` is used ``address`` and ``register_type`` can't be used.
custom command must contain all required bytes including the modbus device address. The crc is automatically calculated and appended to the command.
See :ref:`modbus_custom_command` how to use ``custom_command``
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated every update interval to get the new value of the sensor. It is called after the encoding according to **raw_encode**.
- **offset**: (*Optional*, int): not required in most cases
Parameters passed into the lambda
- **x** (std:string): The parsed value of the modbus data according to **raw_encode**
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
*note:* because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <std::string>;`` the new value for the sensor.
- ``return {};`` uses the parsed value for the state (same as ``return x;``).
- **offset** (*Optional*, int): not required in most cases
offset from start address in bytes. If more than one register is read a modbus read registers command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type
- All options from :ref:`Text Sensor <config-text_sensor>`.
Parameters passed into the lambda
- **x** (std:string): The parsed value of the modbus data according to **raw_encode**
- **data** (std::vector<uint8_t): vector containing the complete raw modbus response bytes for this sensor
note: because the response contains data for all registers in the same range you have to use ``data[item->offset]`` to get the first response byte for your sensor.
- **item** (const pointer to a SensorItem derived object): The sensor object itself.
Possible return values for the lambda:
- ``return <std::string>;`` the new value for the sensor.
- ``return {};`` uses the parsed value for the state (same as ``return x;``).
**Example**

2
components/touchscreen/ektf2232.rst
View File

@ -24,7 +24,7 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen.
- **rts_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The reset pin of the controller.
- **interupt_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
- **interrupt_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
- All other options from :ref:`config-touchscreen`.

2
components/touchscreen/index.rst
View File

@ -59,7 +59,7 @@ buttons.
y_max: 100
page_id: home_page_id
Configuration Variables:
Configuration variables:
************************
- **name** (*Optional*, string): The name for the binary sensor.

2
components/touchscreen/lilygo_t5_47.rst
View File

@ -22,7 +22,7 @@ Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen.
- **interupt_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
- **interrupt_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
Must be ``GPIO13``.
- All other options from :ref:`config-touchscreen`.

6
components/tuya.rst
View File

@ -50,7 +50,7 @@ Configuration variables:
Automations:
- **on_datapoint_update**: (*Optional*): An automation to perform when a Tuya datapoint update is received. See :ref:`tuya-on_datapoint_update`.
- **on_datapoint_update** (*Optional*): An automation to perform when a Tuya datapoint update is received. See :ref:`tuya-on_datapoint_update`.
Tuya Automation
---------------
@ -107,8 +107,8 @@ The type of ``x`` variable is depending on ``datapoint_type`` configuration vari
Configuration variables:
- **sensor_datapoint** (*Required*, int): The datapoint id number of the sensor.
- **datapoint_type** (*Required*, string): The datapoint type one of *raw*, *string*, *bool*, *int*, *uint*, *enum*, *bitmask* or *any*.
- **sensor_datapoint** (**Required**, int): The datapoint id number of the sensor.
- **datapoint_type** (**Required**, string): The datapoint type one of *raw*, *string*, *bool*, *int*, *uint*, *enum*, *bitmask* or *any*.
- See :ref:`Automation <automation>`.

2
components/web_server.rst
View File

@ -57,7 +57,7 @@ Configuration variables:
- **include_internal** (*Optional*, boolean): Whether ``internal`` entities should be displayed on the
web interface. Defaults to ``false``.
- **ota** (*Optional*, boolean): Turn on or off the OTA feature inside webserver. Strongly not suggested without enabled authentication settings. Default: `true`
- **ota** (*Optional*, boolean): Turn on or off the OTA feature inside webserver. Strongly not suggested without enabled authentication settings. Defaults to ``true``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **version** (*Optional*, string): 1 or 2. Version 1 displays as a table. Version 2 uses web components and has more functionality. Default: `2`

1
conf.py
View File

@ -40,7 +40,6 @@ extensions = [
"github",
"seo",
"sitemap",
"schema_doc",
]
# Add any paths that contain templates here, relative to this directory.

2
guides/physical_device_connection.rst
View File

@ -231,7 +231,7 @@ require different parts and tools.
.. _jumper-wires:
* - :ref:`Jumper wires <jumper-wires>`
- Used to connect two things together electrically. The male end has metal
protuding and is plugged into the the female end of a wire or board.
protuding and is plugged into the female end of a wire or board.
They come in varying lengths too, but for our purposes, any length will
do.
- $3 to $8 for a pack

2
index.rst
View File

@ -588,7 +588,7 @@ Climate Components
Thermostat Controller, components/climate/thermostat, air-conditioner.svg
Custom Climate, components/climate/custom, language-cpp.svg
PID Controller, components/climate/pid, function.svg
IR Remote Climate, components/climate/ir_climate, air-conditioner-ir.svg
IR Remote Climate, components/climate/climate_ir, air-conditioner-ir.svg
Tuya Climate, components/climate/tuya, tuya.png
Midea, components/climate/midea, midea.svg
Anova Cooker, components/climate/anova, anova.png

13
markdown.py
View File

@ -172,6 +172,19 @@ class Translator(nodes.NodeVisitor):
def depart_block_quote(self, node):
pass
def visit_raw(self, node):
pass
def depart_raw(self, node):
pass
def visit_note(self, node):
self.write("\n > ")
pass
def depart_note(self, node):
pass
class MDWriter(writers.Writer):
"""GitHub-flavored markdown writer"""

1005
schema_doc.py
View File

File diff suppressed because it is too large Load Diff