diff --git a/Doxygen b/Doxygen index eb7cda84ad..61b7ae467d 100644 --- a/Doxygen +++ b/Doxygen @@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 2024.12.2 +PROJECT_NUMBER = 2025.1.0-dev # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index 60539855ca..a844340deb 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2024.12.2 +ESPHOME_REF = dev PAGEFIND_VERSION=1.1.1 PAGEFIND=pagefind NET_PAGEFIND=../pagefindbin/pagefind diff --git a/_static/version b/_static/version index f36eb7f600..3eab46717b 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2024.12.2 \ No newline at end of file +2025.1.0-dev \ No newline at end of file diff --git a/components/climate/midea.rst b/components/climate/midea.rst index 08c1ffc47b..278c366f16 100644 --- a/components/climate/midea.rst +++ b/components/climate/midea.rst @@ -145,7 +145,7 @@ This action toggle the power state. Identical to pressing the power button on th ``midea_ac.follow_me`` Action ***************************** -This action transmit IR FollowMe command telling the air conditioner a more accurate +This action transmits an IR FollowMe command telling the air conditioner a more accurate room temperature value to be used instead of the internal indoor unit sensor. .. code-block:: yaml @@ -154,14 +154,22 @@ room temperature value to be used instead of the internal indoor unit sensor. then: - midea_ac.follow_me: temperature: !lambda "return x;" + use_fahrenheit: false beeper: false Configuration variables: -- **temperature** (**Required**, float, :ref:`templatable `): Set the - value of a internal temperature sensor. -- **beeper** (*Optional*, boolean, :ref:`templatable `): set beep on update. - Defaults to ``False`` +- **temperature** (**Required**, float, :ref:`templatable `): + Sets the value of an internal temperature sensor. The value will be **clamped** to the range: + + - `0 °C to 37 °C` when ``use_fahrenheit`` is ``false``. + - `32 °F to 99 °F` when ``use_fahrenheit`` is ``true``. + +- **use_fahrenheit** (*Optional*, boolean, :ref:`templatable `): + Specifies if the ``temperature`` value is in Fahrenheit. When set to ``true``, the temperature is parsed and sent in Fahrenheit. Defaults to ``false`` (Celsius). + +- **beeper** (*Optional*, boolean, :ref:`templatable `): + Sets beep on update. Defaults to ``false``. .. _midea_ac-display_toggle_action: diff --git a/components/display/qspi_dbi.rst b/components/display/qspi_dbi.rst index fbd54f7c87..e1030791a9 100644 --- a/components/display/qspi_dbi.rst +++ b/components/display/qspi_dbi.rst @@ -15,7 +15,8 @@ This driver has been tested with the following displays: - Lilygo T4-S3 - Lilygo T-Display S3 AMOLED - - JC4832W535 board using AXS15231 + - JC4832W535 board + - JC3636W518 board Usage ----- @@ -56,7 +57,13 @@ ESP-IDF. PSRAM is a requirement due to the size of the display buffer. A :ref:`q Configuration variables: ************************ -- **model** (**Required**): One of ``CUSTOM``, ``RM67162`` or ``RM690B0``. +- **model** (**Required**): One of + - ``CUSTOM`` + - ``RM67162`` + - ``RM690B0`` + - ``JC4832W535`` + - ``JC3636W518`` + - ``AXS15231`` - **init_sequence** (*Optional*, A list of byte arrays): Specifies the init sequence for the display. This is required when using the ``CUSTOM`` model - but may be empty. If specified for other models this data will be sent after the pre-configured sequence. - **cs_pin** (**Required**, :ref:`Pin Schema `): The chip select pin. - **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. @@ -77,13 +84,14 @@ Configuration variables: - **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``. - **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. This option cannot be used with ``rotation``. - - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes. + - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes. Not available for some chips - **mirror_x** (*Optional*, boolean): If true, mirror the x axis. - **mirror_y** (*Optional*, boolean): If true, mirror the y axis. -- **data_rate** (*Optional*): Set the data rate of the SPI interface to the display. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz`` (default), ``5MHz``, ``2MHz`` or ``1MHz``. +- **data_rate** (*Optional*, int): Set the data rate of the SPI interface to the display. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz`` (default), ``5MHz``, ``2MHz`` or ``1MHz``. - **spi_mode** (*Optional*): Set the mode for the SPI interface to the display. Default is ``MODE0``. -- **invert_colors** (*Optional*): With this boolean option you can invert the display colors. -- **draw_from_origin** (*Optional*): When set, all partial display updates will start at the origin (0,0). Defaults to false. +- **invert_colors** (*Optional*, boolean): With this boolean option you can invert the display colors. +- **draw_from_origin** (*Optional*, boolean): When set, all partial display updates will start at the origin (0,0). Defaults to false. +- **draw_rounding** (*Optional*, int): Caters for display chips that require partial drawing to be aligned to certain boundaries. Default is 2, must be a power of 2. - **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display. See :ref:`display-engine` for more information. @@ -202,17 +210,16 @@ This rotates the display into landscape mode using software rotation. display: - platform: qspi_dbi - model: axs15231 + model: JC4832W535 data_rate: 40MHz + rotation: 270 dimensions: height: 480 width: 320 cs_pin: number: 45 ignore_strapping_warning: true - auto_clear_enabled: false - update_interval: never - init_sequence: + show_test_card: true i2c: sda: 4 diff --git a/components/light/esp32_rmt_led_strip.rst b/components/light/esp32_rmt_led_strip.rst index fc27cc4863..e437991332 100644 --- a/components/light/esp32_rmt_led_strip.rst +++ b/components/light/esp32_rmt_led_strip.rst @@ -23,17 +23,9 @@ Configuration variables - **pin** (**Required**, :ref:`config-pin`): The pin for the data line of the light. - **num_leds** (**Required**, int): The number of LEDs in the strip. -- **rmt_channel** (**Required**, int): The RMT channel to use. If using multiple strips, you need to use different channels. +- **chipset** (**Required**, enum): The name of the chipset used; determines signal timing. Not required if + :ref:`specifying the timings manually`. - .. csv-table:: - :header: "ESP32 Variant", "Channels" - - "ESP32", "0, 1, 2, 3, 4, 5, 6, 7" - "ESP32-S2", "0, 1, 2, 3" - "ESP32-S3", "0, 1, 2, 3" - "ESP32-C3", "0, 1" - -- **chipset** (**Required**, enum): The chipset to apply known timings from. Not used if specifying the timings manually, see below. - ``WS2811`` - ``WS2812`` - ``SK6812`` @@ -41,6 +33,7 @@ Configuration variables - ``SM16703`` - **rgb_order** (**Required**, string): The RGB order of the strip. + - ``RGB`` - ``RBG`` - ``GRB`` @@ -50,13 +43,43 @@ Configuration variables - **is_rgbw** (*Optional*, boolean): Set to ``true`` if the strip is RGBW. Defaults to ``false``. - **is_wrgb** (*Optional*, boolean): Set to ``true`` if the strip is WRGB. Defaults to ``false``. -- **max_refresh_rate** (*Optional*, :ref:`config-time`): - A time interval used to limit the number of commands a light can handle per second. For example - 16ms will limit the light to a refresh rate of about 60Hz. Defaults to sending commands as quickly as - changes are made to the lights. +- **max_refresh_rate** (*Optional*, :ref:`config-time`): A time interval used to limit the number of commands a light + can handle per second. For example, ``16ms`` will limit the light to a refresh rate of about 60Hz. Defaults to + sending commands as quickly as changes are made to the lights. + +IDF configuration variables: +**************************** + +- **rmt_symbols** (*Optional*, int): The amount of RMT memory allocated to this component. Memory is shared by all + receivers and transmitters. On variants other than ``ESP32`` and ``ESP32-S2`` only half the symbol memory is + available to transmitters. Each symbol is 32 bits and contains two values. + + .. csv-table:: + :header: "ESP32 Variant", "Memory Size", "Block Size" + + "ESP32", "512 symbols", "64 symbols" + "ESP32-S2", "256 symbols", "64 symbols" + "ESP32-S3", "384 symbols", "48 symbols" + "ESP32-C3", "192 symbols", "48 symbols" + "ESP32-C6", "192 symbols", "48 symbols" + "ESP32-H2", "192 symbols", "48 symbols" + +Arduino configuration variables: +******************************** + +- **rmt_channel** (**Required**, int): The RMT channel to use. Each LED strip needs to use a unique channel. + + .. csv-table:: + :header: "ESP32 Variant", "Channels" + + "ESP32", "0, 1, 2, 3, 4, 5, 6, 7" + "ESP32-S2", "0, 1, 2, 3" + "ESP32-S3", "0, 1, 2, 3" + "ESP32-C3", "0, 1" - All other options from :ref:`Light `. +.. _esp32-rmt-led-strip-manual_timings: Manual Timings ************** diff --git a/components/opentherm.rst b/components/opentherm.rst index 4034fc353c..176bda1cbc 100644 --- a/components/opentherm.rst +++ b/components/opentherm.rst @@ -57,11 +57,32 @@ Configuration variables: - **sync_mode** (**Optional**, boolean, default **false**): Synchronous communication mode prevents other components from disabling interrupts while we are talking to the boiler. Enable if you experience a lot of random intermittent invalid response errors (very likely to happen while using Dallas temperature sensors). -- **opentherm_version** (**Optional**, float): OpenTherm version that is required for some boilers to work (message - id 124). You don't need to specify this if everything works. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Required if you have multiple busses. +Optional Boiler-specific Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Some boilers require certain OpenTherm messages to be sent by thermostat on initialization in order to work +correctly. You can use the following settings in hub configuration to make your particular boiler happy. + +- **controller_product_type** (**Optional**, byte [0-255], OpenTherm message id ``126`` high byte): Controller product + type +- **controller_product_version** (**Optional**, byte [0-255], OpenTherm message id ``126`` low byte): Controller product + version +- **opentherm_version_controller** (**Optional**, float, OpenTherm message id ``124``): Version of OpenTherm implemented + by controller +- **controller_configuration** (**Optional**, byte [0-255], OpenTherm message id ``2`` high byte): Controller + configuration +- **controller_id** (**Optional**, byte [0-255], OpenTherm message id ``2`` low byte): Controller ID code + +Automations +^^^^^^^^^^^ + +- **before_send** (**Optional**) An automation to perform on OpenTherm message before it is sent to the boiler. +- **before_process_response** (**Optional**) An automation to perform on boiler response before it is processed. + +See :ref:`on-the-fly-message-editing` for details. + Note about sync mode ******************** @@ -319,6 +340,42 @@ available: - ``otc_hc_ratio_ub``: OTC heat curve ratio upper bound - ``otc_hc_ratio_lb``: OTC heat curve ratio lower bound +.. _on-the-fly-message-editing: + +On-the-fly Message Editing +-------------------------- + +Some boilers use non-standard message ids and formats. For example, +`it's known `__ that Daikin D2C boiler uses message id +`162` instead of `56` to set target DHW temperature. In order to accomodate all sorts of non-standard behavior, I +introduced two automations that allow editing the low-level OpenTherm message: + +- **before_send**: fired just before the fully formed message is sent to the boiler. When you use a lambda, the message + is passed by reference as ``x``. +- **before_process_response**: fired when response message is received from the boiler and is about to be processed. + When you use a lambda, the message is passed by reference as ``x``. + +This allows to make arbitrary alterations to any message. Here is an example of overriding message id for DHW setpoint +for Daikin D2C boiler: + +.. code-block:: yaml + + opentherm: + # Usual hub config + before_send: + then: + - lambda: |- + if (x.id == 56) { // 56 is standard message id for DHW setpoint + x.id = 162; // message is passed by refence, so we can change anything, including message id + } + before_process_response: + then: + - lambda: |- + if (x.id == 162) { // We substitute the original id back, so that esphome is not confused. + x.id = 56; + } + +You can check the :apistruct:`OpenthermData ` for the list of all available fields. Examples -------- diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index d2374f7c0b..3a09d8e163 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -6,15 +6,16 @@ Remote Receiver :image: remote.svg :keywords: RF, infrared -The ``remote_receiver`` component lets you receive and decode any remote signal, these can -for example be infrared remotes or 433MHz signals. +The ``remote_receiver`` component lets you receive and decode various common remote control signals, such as infrared +or 433 MHz radio frequency (RF) signals. -The component is split up into two parts: the remote receiver hub which -handles setting the pin and some other settings, and individual -:ref:`remote receiver binary sensors ` -which will trigger when they hear their own configured signal. +The component is split into two parts: -**See** :ref:`remote-setting-up-infrared` **and** :ref:`remote-setting-up-rf` **for set up guides.** +- The remote receiver "hub", which defines the pin and a few additional settings, and... +- Individual :ref:`remote receiver binary sensors ` which will activate when their + respective signal is received. + +**See** :ref:`remote-setting-up-infrared` **and** :ref:`remote-setting-up-rf` **for details.** .. code-block:: yaml @@ -23,7 +24,7 @@ which will trigger when they hear their own configured signal. pin: GPIOXX dump: all -Multiple remote receivers can be configured as a list of dict definitions in remote_receiver. +Multiple remote receivers can be configured as a list of dict definitions within ``remote_receiver``. Configuration variables: ------------------------ @@ -32,7 +33,8 @@ Configuration variables: - **dump** (*Optional*, list): Decode and dump these remote codes in the logs (at log.level=DEBUG). Set to ``all`` to dump all available codecs: - - **abbwelcome**: Decode and dump ABB-Welcome codes. Messages are sent via copper wires. See :ref:`transmitter description ` for more details. + - **abbwelcome**: Decode and dump ABB-Welcome codes. Messages are sent via copper wires. See + :ref:`transmitter description ` for more details. - **aeha**: Decode and dump AEHA infrared codes. - **byronsx**: Decode and dump Byron SX doorbell RF codes. - **canalsat**: Decode and dump CanalSat infrared codes. @@ -63,17 +65,52 @@ Configuration variables: - **toshiba_ac**: Decode and dump Toshiba AC infrared codes. - **mirage**: Decode and dump Mirage infrared codes. -- **tolerance** (*Optional*, int, :ref:`config-time` or mapping): The percentage or time that the remote signal lengths can - deviate in the decoding process. Defaults to ``25%``. +- **tolerance** (*Optional*, int, :ref:`config-time` or mapping): The percentage or time that the remote signal lengths + can deviate in the decoding process. Defaults to ``25%``. - **type** (**Required**, enum): Set the type of the tolerance. Can be ``percentage`` or ``time``. - - **value** (**Required**, int or :ref:`config-time`): The percentage or time value. Allowed values are in range ``0`` to - ``100%`` or ``0`` to ``4294967295us``. + - **value** (**Required**, int or :ref:`config-time`): The percentage or time value. Allowed values are in range ``0`` + to ``100%`` or ``0`` to ``4294967295us``. - **buffer_size** (*Optional*, int): The size of the internal buffer for storing the remote codes. Defaults to ``10kB`` on the ESP32 and ``1kB`` on the ESP8266. -- **rmt_channel** (*Optional*, int): The RMT channel to use. Only on **esp32**. - The following ESP32 variants have these channels available: +- **filter** (*Optional*, :ref:`config-time`): Filter any pulses that are shorter than this. Useful for removing + glitches from noisy signals. Allowed values are in range ``0`` to ``4294967295us``. Defaults to ``50us``. +- **idle** (*Optional*, :ref:`config-time`): The amount of time that a signal should remain stable/unchanged for it to + be considered complete. Allowed values are in range ``0`` to ``4294967295us``. Defaults to ``10ms``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Useful when multiple + receivers are configured on a single device. + +ESP32 IDF configuration variables: +********************************** + +- **rmt_symbols** (*Optional*, int): If ``use_dma`` is enabled, ``rmt_symbols`` represents the size of the driver's + internal DMA buffer. If DMA is not enabled, ``rmt_symbols`` determines the amount of RMT memory allocated to this + component. Memory is shared by all receivers and transmitters. On variants other than ``ESP32`` and ``ESP32-S2``, + only half of the symbol memory is available to receivers. Each symbol is 32 bits and contains two values. + + .. csv-table:: + :header: "ESP32 Variant", "Memory Size", "Block Size" + + "ESP32", "512 symbols", "64 symbols" + "ESP32-S2", "256 symbols", "64 symbols" + "ESP32-S3", "384 symbols", "48 symbols" + "ESP32-C3", "192 symbols", "48 symbols" + "ESP32-C6", "192 symbols", "48 symbols" + "ESP32-H2", "192 symbols", "48 symbols" + +- **receive_symbols** (*Optional*, int): Maximum receive length in symbols. On some variants the maximum receive is + limited to ``rmt_symbols``. +- **filter_symbols** (*Optional*, int): Filter out any data received with a length in symbols less than + ``filter_symbols``. Useful for filtering out short bursts of noise. +- **clock_resolution** (*Optional*, int): The clock resolution used by the RMT peripheral in hz. Defaults to + ``1000000``. +- **use_dma** (*Optional*, boolean): Enable DMA on variants that support it. + +ESP32 Arduino configuration variables: +************************************** + +- **rmt_channel** (*Optional*, int): The RMT channel to use. The following ESP32 variants have these channels available: .. csv-table:: :header: "ESP32 Variant", "Channels" @@ -83,22 +120,16 @@ Configuration variables: "ESP32-S3", "4, 5, 6, 7" "ESP32-C3", "2, 3" -- **memory_blocks** (*Optional*, int): The number of RMT memory blocks used. Only used on ESP32 platform. The maximum +- **memory_blocks** (*Optional*, int): The number of RMT memory blocks used. The maximum number of blocks shared by all receivers and transmitters depends on the ESP32 variant. Defaults to ``3``. -- **filter** (*Optional*, :ref:`config-time`): Filter any pulses that are shorter than this. Useful for removing - glitches from noisy signals. Allowed values are in range ``0`` to ``4294967295us``. Defaults to ``50us``. -- **idle** (*Optional*, :ref:`config-time`): The amount of time that a signal should remain stable (i.e. not - change) for it to be considered complete. Allowed values are in range ``0`` to ``4294967295us``. Defaults to ``10ms``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this if you have - multiple remote receivers. - **clock_divider** (*Optional*, int): The clock divider used by the RMT peripheral. A clock divider of ``80`` leads to - a resolution of 1 µs per tick, ``160`` leads to 2 µs. Allowed values are in range ``1`` to ``255``. Only used on ESP32 - platform. Defaults to ``80``. + a resolution of 1 µs per tick, ``160`` leads to 2 µs. Allowed values are in range ``1`` to ``255``. Defaults to ``80`` .. note:: The dumped **raw** code is sequence of pulse widths (durations in microseconds), positive for on-pulses (mark) - and negative for off-pulses (space). Usually you can to copy this directly to the configuration or automation to be used later. + and negative for off-pulses (space). Usually you can to copy this directly to the configuration or automation + to be used later. Automations: @@ -218,8 +249,7 @@ Binary Sensor The ``remote_receiver`` binary sensor lets you track when a button on a remote control is pressed. -Each time the pre-defined signal is received, the binary sensor will briefly go ON and -then immediately OFF. +Each time the pre-defined signal is received, the binary sensor will briefly go ON and then immediately OFF. .. code-block:: yaml @@ -234,29 +264,32 @@ then immediately OFF. Configuration variables: ************************ -- **receiver_id** (*Optional*, :ref:`config-id`): The remote receiver to receive the - remote code with. Required if multiple receivers configured. +- **receiver_id** (*Optional*, :ref:`config-id`): The remote receiver to receive the remote code with. Required if + multiple receivers configured. - All other options from :ref:`Binary Sensor `. Remote code selection (exactly one of these has to be included): -- **abbwelcome**: Trigger on a decoded ABB-Welcome code with the given data, see the :ref:`transmitter description ` for more info. +- **abbwelcome**: Trigger on a decoded ABB-Welcome code with the given data, see the + :ref:`transmitter description ` for more info. - **source_address** (**Required**, int): The source address to trigger on. - **destination_address** (**Required**, int): The destination address to trigger on. - - **three_byte_address** (**Optional**, boolean): The length of the source and destination address. ``false`` means two bytes - and ``true`` means three bytes. Defaults to ``false``. + - **three_byte_address** (**Optional**, boolean): The length of the source and destination address. ``false`` means + two bytes and ``true`` means three bytes. Defaults to ``false``. - **retransmission** (**Optional**, boolean): ``true`` if the message was re-transmitted. Defaults to ``false``. - **message_type** (**Required**, int): The message type to trigger on. - - **message_id** (**Optional**, int): The random message ID to trigger on, see dumper output for more info. Defaults to any ID. - - **data** (**Optional**, 0-7 bytes list): The code to listen for. Usually you only need to copy this directly from the - dumper output. Defaults to ``[]`` + - **message_id** (**Optional**, int): The random message ID to trigger on, see dumper output for more info. Defaults + to any ID. + - **data** (**Optional**, 0-7 bytes list): The code to listen for. Usually you only need to copy this directly from + the dumper output. Defaults to ``[]`` - **aeha**: Trigger on a decoded AEHA remote code with the given data. - **address** (**Required**, int): The address to trigger on, see dumper output for more info. - - **data** (**Required**, 3-35 bytes list): The code to listen for, see :ref:`transmitter description ` - for more info. Usually you only need to copy this directly from the dumper output. + - **data** (**Required**, 3-35 bytes list): The code to listen for, see + :ref:`transmitter description ` for more info. Usually you only need to copy this + directly from the dumper output. - **byronsx**: Trigger on a decoded Byron SX Doorbell RF remote code with the given data. @@ -266,17 +299,20 @@ Remote code selection (exactly one of these has to be included): - **canalsat**: Trigger on a decoded CanalSat remote code with the given data. - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - - **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` + - **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. + Defaults to ``0``. - **command** (**Required**, int): The command to listen for. - **canalsatld**: Trigger on a decoded CanalSatLD remote code with the given data. - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - - **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` + - **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. + Defaults to ``0``. - **command** (**Required**, int): The command to listen for. -- **coolix**: Trigger on a decoded Coolix remote code with the given data. It is possible to directly specify a 24-bit code, - it will be checked for a match to at least one of the two received packets. The main configuration scheme is below. +- **coolix**: Trigger on a decoded Coolix remote code with the given data. It is possible to directly specify a 24-bit + code, it will be checked for a match to at least one of the two received packets. The main configuration scheme is + below. - **first** (**Required**, uint32_t): The first 24-bit Coolix code to trigger on, see dumper output for more info. - **second** (*Optional*, uint32_t): The second 24-bit Coolix code to trigger on, see dumper output for more info. @@ -312,8 +348,9 @@ Remote code selection (exactly one of these has to be included): - **haier**: Trigger on a Haier remote code with the given code. - - **code** (**Required**, 13-bytes list): The code to listen for, see :ref:`transmitter description ` - for more info. Usually you only need to copy this directly from the dumper output. + - **code** (**Required**, 13-bytes list): The code to listen for, see + :ref:`transmitter description ` for more info. Usually you only need to copy + this directly from the dumper output. - **lg**: Trigger on a decoded LG remote code with the given data. @@ -323,12 +360,14 @@ Remote code selection (exactly one of these has to be included): - **magiquest**: Trigger on a decoded MagiQuest wand remote code with the given wand ID. - **wand_id** (**Required**, int): The MagiQuest wand ID to trigger on, see dumper output for more info. - - **magnitude** (*Optional*, int): The magnitude of swishes and swirls of the wand. If omitted, will match on any activation of the wand. + - **magnitude** (*Optional*, int): The magnitude of swishes and swirls of the wand. If omitted, will match on any + activation of the wand. - **midea**: Trigger on a Midea remote code with the given code. - - **code** (**Required**, 5-bytes list): The code to listen for, see :ref:`transmitter description ` - for more info. Usually you only need to copy first 5 bytes directly from the dumper output. + - **code** (**Required**, 5-bytes list): The code to listen for, see + :ref:`transmitter description ` for more info. Usually you only need to copy + first 5 bytes directly from the dumper output. - **nec**: Trigger on a decoded NEC remote code with the given data. @@ -354,15 +393,17 @@ Remote code selection (exactly one of these has to be included): - **pronto**: Trigger on a Pronto remote code with the given code. - - **data** (**Required**, string): The code to listen for, see :ref:`transmitter description ` - for more info. Usually you only need to copy this directly from the dumper output. + - **data** (**Required**, string): The code to listen for, see + :ref:`transmitter description ` for more info. Usually you only need to copy this + directly from the dumper output. - **delta** (**Optional**, integer): This parameter allows you to manually specify the allowed difference between what Pronto code is specified, and what IR signal has been sent by the remote control. - **raw**: Trigger on a raw remote code with the given code. - - **code** (**Required**, list): The code to listen for, see :ref:`transmitter description ` - for more info. Usually you only need to copy this directly from the dumper output. + - **code** (**Required**, list): The code to listen for, see + :ref:`transmitter description ` for more info. Usually you only need to copy this + directly from the dumper output. - **rc5**: Trigger on a decoded RC5 remote code with the given data. @@ -378,21 +419,24 @@ Remote code selection (exactly one of these has to be included): - **code** (**Required**, string): The remote code to listen for, copy this from the dumper output. To ignore a bit in the received data, use ``x`` at that place in the **code**. - - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for + more info. - **rc_switch_type_a**: Trigger on a decoded RC Switch Type A remote code with the given data. - **group** (**Required**, string): The group, binary string. - **device** (**Required**, string): The device in the group, binary string. - **state** (**Required**, boolean): The on/off state to trigger on. - - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for + more info. - **rc_switch_type_b**: Trigger on a decoded RC Switch Type B remote code with the given data. - **address** (**Required**, int): The address, int from 1 to 4. - **channel** (**Required**, int): The channel, int from 1 to 4. - **state** (**Required**, boolean): The on/off state to trigger on. - - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for + more info. - **rc_switch_type_c**: Trigger on a decoded RC Switch Type C remote code with the given data. @@ -400,14 +444,16 @@ Remote code selection (exactly one of these has to be included): - **group** (**Required**, int): The group. Range is 1 to 4. - **device** (**Required**, int): The device. Range is 1 to 4. - **state** (**Required**, boolean): The on/off state to trigger on. - - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for + more info. - **rc_switch_type_d**: Trigger on a decoded RC Switch Type D remote code with the given data. - **group** (**Required**, int): The group. Range is 1 to 4. - **device** (**Required**, int): The device. Range is 1 to 3. - **state** (**Required**, boolean): The on/off state to trigger on. - - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for + more info. - **roomba**: Trigger on a decoded Roomba remote code with the given data. @@ -431,12 +477,14 @@ Remote code selection (exactly one of these has to be included): - **toshiba_ac**: Trigger on a decoded Toshiba AC remote code with the given data. - **rc_code_1** (**Required**, int): The remote control code to trigger on, see dumper output for more details. - - **rc_code_2** (*Optional*, int): The second part of the remote control code to trigger on, see dumper output for more details. + - **rc_code_2** (*Optional*, int): The second part of the remote control code to trigger on, see dumper output for + more details. - **mirage**: Trigger on a Mirage remote code with the given code. - - **code** (**Required**, 14-bytes list): The code to listen for, see :ref:`transmitter description ` - for more info. Usually you only need to copy this directly from the dumper output. + - **code** (**Required**, 14-bytes list): The code to listen for, see + :ref:`transmitter description ` for more info. Usually you only need to copy + this directly from the dumper output. .. note:: @@ -446,14 +494,15 @@ Remote code selection (exactly one of these has to be included): .. note:: - **NEC codes**: In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC standard. - 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. + **NEC codes**: In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with + the NEC standard. 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. .. note:: - To capture the codes more effectively with directly connected receiver like tsop38238 you can try to use ``INPUT_PULLUP``: + Some receivers, such as the TSOP38238, may require the use of a pull-up resistor. You can enable this as follows: .. code-block:: yaml diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index a2241277a9..83dd8e0188 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -6,19 +6,20 @@ Remote Transmitter :image: remote.svg :keywords: Infrared, IR, RF, Remote, TX, 433, Blaster -The ``remote_transmitter`` component lets you send digital packets to control -devices in your home. For example this includes infrared data or 433MHz RF signals. +The ``remote_transmitter`` component lets you send various common remote control signals, such as infrared +or 433 MHz radio frequency (RF) signals. -First, you need to setup a global hub that specifies which pin your remote -sender is connected to. Then you can use the available actions to send encoded -remote signals. +The component is split into two parts: -**See** :ref:`remote-setting-up-infrared` **and** :ref:`remote-setting-up-rf` **for set up guides.** +- The remote transmitter "hub", which defines the pin and a few additional settings, and... +- Individual :ref:`actions` to send encoded remote signals. + +**See** :ref:`remote-setting-up-infrared` **and** :ref:`remote-setting-up-rf` **for details.** .. note:: - This component is more accurate on the ESP32, since that chipset has a dedicated - peripheral for sending exact signal sequences. + This component performs best with an ESP32 or variant; they have a dedicated hardware peripheral which ensures + accurate signal timing. .. code-block:: yaml @@ -30,12 +31,39 @@ remote signals. Configuration variables: ------------------------ -- **pin** (**Required**, :ref:`config-pin`): The pin to transmit the remote signal on. -- **carrier_duty_percent** (*Optional*, int): How much of the time the remote is on. For example, infrared - protocols modulate the signal using a carrier signal. Set this to ``50%`` if you're working with IR LEDs and to - ``100%`` if working with other things like 433MHz transmitters. -- **rmt_channel** (*Optional*, int): The RMT channel to use. Only on **esp32**. - The following ESP32 variants have these channels available: +- **pin** (**Required**, :ref:`config-pin`): The pin to transmit the remote signal on. +- **carrier_duty_percent** (*Optional*, int): How much of the time the remote is on. For example, infrared protocols + modulate the signal using a carrier signal. Set this to ``50%`` if you're using IR LEDs and ``100%`` for RF + applications like 433 MHz transmitters. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Useful when multiple + transmitters are connected to a single device. + +ESP32 IDF configuration variables: +********************************** + +- **rmt_symbols** (*Optional*, int): If ``use_dma`` is enabled, ``rmt_symbols`` represents the size of the driver's + internal DMA buffer. If DMA is not enabled, ``rmt_symbols`` determines the amount of RMT memory allocated to this + component. Memory is shared by all receivers and transmitters. On variants other than ``ESP32`` and ``ESP32-S2``, + only half of the symbol memory is available to transmitters. Each symbol is 32 bits and contains two values. + + .. csv-table:: + :header: "ESP32 Variant", "Memory Size", "Block Size" + + "ESP32", "512 symbols", "64 symbols" + "ESP32-S2", "256 symbols", "64 symbols" + "ESP32-S3", "384 symbols", "48 symbols" + "ESP32-C3", "192 symbols", "48 symbols" + "ESP32-C6", "192 symbols", "48 symbols" + "ESP32-H2", "192 symbols", "48 symbols" + +- **clock_resolution** (*Optional*, int): The clock resolution used by the RMT peripheral in hz. Defaults to ``1000000``. +- **one_wire** (*Optional*, boolean): Allows the GPIO to be used as both a transmitter and receiver. +- **use_dma** (*Optional*, boolean): Enable DMA on variants that support it. + +ESP32 Arduino configuration variables: +************************************** + +- **rmt_channel** (*Optional*, int): The RMT channel to use. The following ESP32 variants have these channels available: .. csv-table:: :header: "ESP32 Variant", "Channels" @@ -45,8 +73,8 @@ Configuration variables: "ESP32-S3", "0, 1, 2, 3" "ESP32-C3", "0, 1" -- **id** (*Optional*, :ref:`config-id`): Manually specify - the ID used for code generation. Use this if you have multiple remote transmitters. +- **clock_divider** (*Optional*, int): The clock divider used by the RMT peripheral. A clock divider of ``80`` leads to + a resolution of 1 µs per tick, ``160`` leads to 2 µs. Allowed values are in range ``1`` to ``255``. Defaults to ``80``. Automations: ------------ @@ -73,9 +101,8 @@ Automations: Remote Transmitter Actions -------------------------- -Remote transmitters support a number of :ref:`actions ` that can be used -to send remote codes. All supported protocols are listed below. All actions additionally -have these configuration variables: +Remote transmitters support a number of :ref:`actions ` that can be used to send remote codes. All +supported protocols are listed below. All actions have these additional configuration variables: .. code-block::yaml @@ -88,17 +115,18 @@ have these configuration variables: Configuration variables: -- **repeat** (*Optional*): Optionally set the code to be repeated a number of times. - Defaults to sending the code only once. +- **repeat** (*Optional*): Defines the number of times the code is repeated when transmitted. By default, codes are + sent only once. - **times** (:ref:`templatable `, int): The number of times to repeat the code. - - **wait_time** (:ref:`templatable `, :ref:`config-time`): The time to wait between repeats (in µs as a result of a :ref:`lambda `). + - **wait_time** (:ref:`templatable `, :ref:`config-time`): The time to wait between repeats (in + µs as a result of a :ref:`lambda `). -- **transmitter_id** (*Optional*, :ref:`config-id`): The remote transmitter to send the - remote code with. Defaults to the first one defined in the configuration. +- **transmitter_id** (*Optional*, :ref:`config-id`): The remote transmitter to send the remote code with. Defaults to + the first one defined in the configuration. -If you're looking for the same functionality as is default in the ``rpi_rf`` integration in -Home Assistant, you'll want to set the **times** to 10 and the **wait_time** to 0s. +If you're looking for the same functionality as is default in the ``rpi_rf`` integration in Home Assistant, you'll want +to set the **times** to 10 and the **wait_time** to 0s. .. _remote_transmitter-transmit_abbwelcome: @@ -171,7 +199,8 @@ Configuration variables: with for infrared signals. Defaults to ``38000Hz``. - All other options from :ref:`remote_transmitter-transmit_action`. -AEHA refers to the Association for Electric Home Appliances in Japan, a format used by Panasonic and many other companies. +AEHA refers to the Association for Electric Home Appliances in Japan, a format used by Panasonic and many other +companies. .. _remote_transmitter-transmit_byronsx: @@ -214,7 +243,8 @@ This :ref:`action ` sends a CanalSat infrared remote code to a re Configuration variables: - **device** (**Required**, int): The device to send to, see dumper output for more details. -- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` +- **address** (*Optional*, int): The address (or sub-device) to send to, see dumper output for more details. + Defaults to ``0``. - **command** (**Required**, int): The command to send. - All other options from :ref:`remote_transmitter-transmit_action`. @@ -240,7 +270,8 @@ This :ref:`action ` sends a CanalSatLD infrared remote code to a Configuration variables: - **device** (**Required**, int): The device to send to, see dumper output for more details. -- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` +- **address** (*Optional*, int): The address (or sub-device) to send to, see dumper output for more details. + Defaults to ``0``. - **command** (**Required**, int): The command to send. - All other options from :ref:`remote_transmitter-transmit_action`. @@ -248,7 +279,7 @@ Configuration variables: ``remote_transmitter.transmit_coolix`` **Action** -This :ref:`action ` sends one or two (stricted or not) 24-bit Coolix infrared remote codes to a remote transmitter. +This :ref:`action ` sends one or two 24-bit Coolix infrared remote codes to a remote transmitter. .. code-block:: yaml @@ -259,8 +290,10 @@ This :ref:`action ` sends one or two (stricted or not) 24-bit Coo Configuration variables: -- **first** (**Required**, :ref:`templatable `, uint32_t): The first 24-bit Coolix code to send, see dumper output for more info. -- **second** (*Optional*, :ref:`templatable `, uint32_t): The second 24-bit Coolix code to send, see dumper output for more info. +- **first** (**Required**, :ref:`templatable `, uint32_t): The first 24-bit Coolix code to send; + see dumper output for more info. +- **second** (*Optional*, :ref:`templatable `, uint32_t): The second 24-bit Coolix code to send; + see dumper output for more info. - All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_dish: @@ -282,7 +315,8 @@ Configuration variables: - **command** (**Required**, int): The command to send, between 0 and 63 inclusive. - All other options from :ref:`remote_transmitter-transmit_action`. -You can find a list of commands in the `LIRC project `__. +You can find a list of commands in the +`LIRC project `__. .. _remote_transmitter-transmit_dooya: @@ -304,7 +338,8 @@ Configuration variables: - **id** (**Required**, int): The 24-bit ID to send. Each remote has a unique one. - **channel** (**Required**, int): The 8-bit channel to send, between 0 and 255 inclusive. - **button** (**Required**, int): The 4-bit button to send, between 0 and 15 inclusive. -- **check** (**Required**, int): The 4-bit check to send. Includes an indication that a button is being held down. See dumper output for more info. +- **check** (**Required**, int): The 4-bit check to send. Includes an indication that a button is being held down. + See dumper output for more info. - All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_drayton: @@ -375,7 +410,8 @@ Configuration variables: ``remote_transmitter.transmit_haier`` **Action** -This :ref:`action ` sends a 104-bit Haier code to a remote transmitter. 8-bits of checksum added automatically. +This :ref:`action ` sends a 104-bit Haier code to a remote transmitter. The 8-bit checksum is added +automatically. .. code-block:: yaml @@ -423,14 +459,16 @@ This :ref:`action ` sends a MagiQuest wand code to a remote trans Configuration variables: - **wand_id** (**Required**, int): The wand ID to send, as a hex integer. See the dumper output for your wand ID. -- **magnitude** (*Optional*, int): The magnitude of swishes and swirls of the want to transmit. See the dumper output for examples. If omitted, sends 0xFFFF (which the real wand never uses). +- **magnitude** (*Optional*, int): The magnitude of swishes and swirls the wand should transmit. See the dumper output + for examples. If omitted, sends 0xFFFF (which the real wand never uses). - All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_midea: ``remote_transmitter.transmit_midea`` **Action** -This :ref:`action ` sends a 40-bit Midea code to a remote transmitter. 8-bits of checksum added automatically. +This :ref:`action ` sends a 40-bit Midea code to a remote transmitter. 8-bits of checksum added +automatically. .. code-block:: yaml @@ -446,7 +484,8 @@ This :ref:`action ` sends a 40-bit Midea code to a remote transmi Configuration variables: -- **code** (**Required**, list, :ref:`templatable `): The 40-bit Midea code to send as a list of hex or integers. +- **code** (**Required**, list, :ref:`templatable `): The 40-bit Midea code to send as a list of + hex or integers. - All other options from :ref:`remote_transmitter-transmit_action`. ``remote_transmitter.transmit_nec`` **Action** @@ -455,11 +494,12 @@ This :ref:`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 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. - Additionally, ESPHome does not automatically generate parity bits or pad values to 2 bytes. - So, in order to send command 0x0, you need to use 0xFF00 (0x00 being the command and 0xFF being the logical inverse). + In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC + standard. 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. In additional, ESPHome + does not automatically generate parity bits or pad values to 2 bytes. For example, to send command ``0x0``, you + need to use ``0xFF00`` (``0x00`` being the command and ``0xFF`` being the logical inverse). .. code-block:: yaml @@ -473,7 +513,8 @@ Configuration variables: - **address** (**Required**, int): The 16-bit address to send, see dumper output for more details. - **command** (**Required**, int): The 16-bit NEC command to send. -- **command_repeats** (*Optional*, int): The number of times the command bytes are sent in one transmission. Defaults to `1`. +- **command_repeats** (*Optional*, int): The number of times the command bytes are sent in one transmission. + Defaults to `1`. - All other options from :ref:`remote_transmitter-transmit_action`. ``remote_transmitter.transmit_nexa`` **Action** @@ -493,7 +534,8 @@ This :ref:`action ` a Nexa RF remote code to a remote transmitter Configuration variables: - **device** (**Required**, int): The Nexa device code to send, see dumper output for more info. -- **state** (**Required**, int): The Nexa state code to send (0-OFF, 1-ON, 2-DIMMER LEVEL), see dumper output for more info. +- **state** (**Required**, int): The Nexa state code to send (0-OFF, 1-ON, 2-DIMMER LEVEL), see dumper output for more + info. - **group** (**Required**, int): The Nexa group code to send, see dumper output for more info. - **channel** (**Required**, int): The Nexa channel code to send, see dumper output for more info. - **level** (**Required**, int): The Nexa level code to send, see dumper output for more info. @@ -562,8 +604,8 @@ This :ref:`action ` sends a raw code to a remote transmitter spec Configuration variables: -- **data** (**Required**, string): The raw code to send specified as a string. - A lot of remote control Pronto codes can be found on http://remotecentral.com +- **data** (**Required**, string): The raw code to send specified as a string. Many remote control Pronto codes can be + found on http://remotecentral.com - All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_raw: @@ -772,10 +814,15 @@ This :ref:`action ` sends a Roomba infrared remote code to a remo Configuration variables: - **data** (**Required**, int): The Roomba code to send, see dumper output for more info. -- Note that ``repeat`` is still optional, however **Roomba vacuums require that a given code is received at least three times before they will act on it.** If your Roomba still does not respond to sent command increase this value. -- Note that ``wait_time`` is still optional; it will even work without this parameter, but Roomba Remote uses this 17 ms wait time between sent commands. - All other options from :ref:`remote_transmitter-transmit_action`. +**Important:** + +- While ``repeat`` is optional, **Roomba vacuums require that a given code is received at least three times before they + will respond to it.** If your Roomba does not respond to the command, increase this value. +- While ``wait_time`` is optional, the Roomba Remote uses a 17 ms wait time between commands. However, it appears to + work without this parameter. + .. _remote_transmitter-transmit_samsung: ``remote_transmitter.transmit_samsung`` **Action** @@ -866,7 +913,8 @@ Configuration variables: ``remote_transmitter.transmit_mirage`` **Action** -This :ref:`action ` sends a 112-bit Mirage code to a remote transmitter. 8-bits of checksum added automatically. +This :ref:`action ` sends a 112-bit Mirage code to a remote transmitter. 8-bits of checksum added +automatically. .. code-block:: yaml diff --git a/conf.py b/conf.py index 2866cdf2af..d7c0478777 100644 --- a/conf.py +++ b/conf.py @@ -71,9 +71,9 @@ # built documents. # # The short X.Y version. -version = "2024.12" +version = "2025.1" # The full version, including alpha/beta/rc tags. -release = "2024.12.2" +release = "2025.1.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/web-api/index.rst b/web-api/index.rst index ce651b9353..4ac1b63d65 100644 --- a/web-api/index.rst +++ b/web-api/index.rst @@ -75,6 +75,8 @@ to ``VERY_VERBOSE`` and check the ``object_id:`` in the logs. By creating a simple GET request for a URL of the form ``//`` you will get a JSON payload describing the current state of the component. This payload is equivalent to the ones sent by the event source API. +You can get verbose information about the component by adding the parameter ``detail=all`` +An example would be ``/select/my_select?detail=all`` To actually *control* the state of a component you need to send a POST request with a ``method`` like ``turn_on``. For example, to turn on a light, you would send a POST request to