diff --git a/changelog/2024.7.0.rst b/changelog/2024.7.0.rst index 8b3edca170..f8ff569734 100644 --- a/changelog/2024.7.0.rst +++ b/changelog/2024.7.0.rst @@ -22,6 +22,29 @@ Breaking Changes - [modbus_text_sensor] new default ANSI encoding type :esphomepr:`6975` by :ghuser:`dudanov` (breaking-change) - [micro_wake_word] Version 2 :esphomepr:`7032` by :ghuser:`kahrendt` (breaking-change) +Beta Changes +^^^^^^^^^^^^ + +- helpers.cpp: Fix GLIBCXX_RELEASE check < 8 :esphomepr:`7062` by :ghuser:`ferbar` +- Fix pmsa003i cold boot marked as failed on ESP32 et al :esphomepr:`7064` by :ghuser:`z3liff` +- [http_request] Fix follow_redirects on arduino :esphomepr:`7054` by :ghuser:`guillempages` +- [ethernet] Fix compile warning for IPv6 :esphomepr:`7048` by :ghuser:`HeMan` +- Update webserver local assets to 20240704-081526 :esphomepr:`7041` by :ghuser:`esphomebot` +- Add braces to if statement to avoid compiler warning. :esphomepr:`7036` by :ghuser:`colmbuckley` +- [mitsubishi] Fix current temperature :esphomepr:`6909` by :ghuser:`ttaborda` +- [climate] fix dump output of unsupported features :esphomepr:`7005` by :ghuser:`dudanov` +- [climate-traits] improved performance :esphomepr:`7006` by :ghuser:`dudanov` +- Add default icon to restart button :esphomepr:`7076` by :ghuser:`leejoow` +- Add support for the Gree YAC1FB9 in climate_ir :esphomepr:`7056` by :ghuser:`topeju` +- add ESP32-C6 support to esp32_can :esphomepr:`7063` by :ghuser:`Adminius` +- Fix voice assistant crash when no speaker configured :esphomepr:`7075` by :ghuser:`kevdliu` +- Bump HeatpumpIR, add protocols, remove IRremoteESP8266 :esphomepr:`6996` by :ghuser:`nagyrobi` +- LTR390 separate ALS and UV gain and resolution :esphomepr:`7026` by :ghuser:`latonita` +- [improv_serial] Fix linker error created in #6998 :esphomepr:`7082` by :ghuser:`kbx81` +- [i2s_audio] Allow config for primary/secondary i2s mode :esphomepr:`7092` by :ghuser:`jesserockz` +- [micro_wake_word] Allow simpler model config :esphomepr:`7094` by :ghuser:`jesserockz` +- [ota] Print Arduino update errors :esphomepr:`7096` by :ghuser:`jesserockz` + All changes ^^^^^^^^^^^ @@ -86,6 +109,25 @@ All changes - [micro_wake_word] Version 2 :esphomepr:`7032` by :ghuser:`kahrendt` (breaking-change) - UART component support added for host platform :esphomepr:`6912` by :ghuser:`paveldn` - Configure ap ip for RP2040 :esphomepr:`7065` by :ghuser:`HeMan` +- helpers.cpp: Fix GLIBCXX_RELEASE check < 8 :esphomepr:`7062` by :ghuser:`ferbar` +- Fix pmsa003i cold boot marked as failed on ESP32 et al :esphomepr:`7064` by :ghuser:`z3liff` +- [http_request] Fix follow_redirects on arduino :esphomepr:`7054` by :ghuser:`guillempages` +- [ethernet] Fix compile warning for IPv6 :esphomepr:`7048` by :ghuser:`HeMan` +- Update webserver local assets to 20240704-081526 :esphomepr:`7041` by :ghuser:`esphomebot` +- Add braces to if statement to avoid compiler warning. :esphomepr:`7036` by :ghuser:`colmbuckley` +- [mitsubishi] Fix current temperature :esphomepr:`6909` by :ghuser:`ttaborda` +- [climate] fix dump output of unsupported features :esphomepr:`7005` by :ghuser:`dudanov` +- [climate-traits] improved performance :esphomepr:`7006` by :ghuser:`dudanov` +- Add default icon to restart button :esphomepr:`7076` by :ghuser:`leejoow` +- Add support for the Gree YAC1FB9 in climate_ir :esphomepr:`7056` by :ghuser:`topeju` +- add ESP32-C6 support to esp32_can :esphomepr:`7063` by :ghuser:`Adminius` +- Fix voice assistant crash when no speaker configured :esphomepr:`7075` by :ghuser:`kevdliu` +- Bump HeatpumpIR, add protocols, remove IRremoteESP8266 :esphomepr:`6996` by :ghuser:`nagyrobi` +- LTR390 separate ALS and UV gain and resolution :esphomepr:`7026` by :ghuser:`latonita` +- [improv_serial] Fix linker error created in #6998 :esphomepr:`7082` by :ghuser:`kbx81` +- [i2s_audio] Allow config for primary/secondary i2s mode :esphomepr:`7092` by :ghuser:`jesserockz` +- [micro_wake_word] Allow simpler model config :esphomepr:`7094` by :ghuser:`jesserockz` +- [ota] Print Arduino update errors :esphomepr:`7096` by :ghuser:`jesserockz` Past Changelogs --------------- diff --git a/components/binary_sensor/ble_presence.rst b/components/binary_sensor/ble_presence.rst index b9fdd1f007..412049a504 100644 --- a/components/binary_sensor/ble_presence.rst +++ b/components/binary_sensor/ble_presence.rst @@ -10,7 +10,7 @@ The ``ble_presence`` binary sensor platform lets you track the presence of a Blu .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -27,7 +27,7 @@ The ``ble_presence`` binary sensor platform lets you track the presence of a Blu binary_sensor: # Presence based on MAC address - platform: ble_presence - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "ESP32 BLE Tracker Google Home Mini" min_rssi: -80dB # Presence based on Identity Resolving Key (IRK) @@ -96,7 +96,7 @@ the logs to see discovered Bluetooth Low Energy devices. Using the configuration above, first you should see a ``Starting scan...`` debug message at boot-up. Then, when a BLE device is discovered, you should see messages like -``Found device AC:37:43:77:5F:4C`` together with some information about their +``Found device XX:XX:XX:XX:XX:XX`` together with some information about their address type and advertised name. If you don't see these messages, your device is unfortunately currently not supported. diff --git a/components/ble_client.rst b/components/ble_client.rst index 98697f8407..4198f3b549 100644 --- a/components/ble_client.rst +++ b/components/ble_client.rst @@ -12,7 +12,7 @@ connections to them for use by other components. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -36,7 +36,7 @@ to discover available client devices. esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black auto_connect: true @@ -73,7 +73,7 @@ This automation is triggered when the client connects to the BLE device. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_connect: then: @@ -90,7 +90,7 @@ This automation is triggered when the client disconnects from a BLE device. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_disconnect: then: @@ -108,7 +108,7 @@ This automation is triggered when the BLE device requests a passkey for authenti .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_passkey_request: then: @@ -126,7 +126,7 @@ This automation is triggered when a passkey is received from the BLE device. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_passkey_notification: then: @@ -144,7 +144,7 @@ This automation is triggered when a numeric comparison is requested by the BLE d .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_numeric_comparison_request: then: @@ -174,10 +174,10 @@ on, hence the stop and start of the scan during connect. ble_client: - id: ble_clock - mac_address: 17:75:BC:F2:94:4D + mac_address: XX:XX:XX:XX:XX:XX auto_connect: false - id: other_device - mac_address: 0D:33:12:66:00:D4 + mac_address: XX:XX:XX:XX:XX:XX interval: - interval: 60min @@ -222,7 +222,7 @@ Example usage: .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: my_ble_client switch: @@ -308,7 +308,7 @@ Example usage: .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: my_ble_client on_connect: then: @@ -391,9 +391,9 @@ display them in the log: .. code-block:: text - [18:24:56][D][ble_client:043]: Found device at MAC address [FC:58:FA:B1:F8:93] - [18:24:56][I][ble_client:072]: Attempting BLE connection to fc:58:fa:b1:f8:93 - [18:24:56][I][ble_client:097]: [fc:58:fa:b1:f8:93] ESP_GATTC_OPEN_EVT + [18:24:56][D][ble_client:043]: Found device at MAC address [XX:XX:XX:XX:XX:XX] + [18:24:56][I][ble_client:072]: Attempting BLE connection to XX:XX:XX:XX:XX:XX + [18:24:56][I][ble_client:097]: [XX:XX:XX:XX:XX:XX] ESP_GATTC_OPEN_EVT [18:24:57][I][ble_client:143]: Service UUID: 0x1800 [18:24:57][I][ble_client:144]: start_handle: 0x1 end_handle: 0x5 [18:24:57][I][ble_client:305]: characteristic 0x2A00, handle 0x3, properties 0x2 @@ -445,7 +445,7 @@ Secure connection with a fixed passkey: esp32_ble_tracker: ble_client: - - mac_address: A4:C1:38:B1:CD:7F + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display on_passkey_request: then: @@ -483,7 +483,7 @@ Secure connection with a dynamically generated passkey: esp32_ble_tracker: ble_client: - - mac_address: AA:BB:CC:DD:EE:FF + - mac_address: XX:XX:XX:XX:XX:XX id: my_ble_client on_passkey_request: then: diff --git a/components/button/wake_on_lan.rst b/components/button/wake_on_lan.rst index 3d702036ac..10b510201c 100644 --- a/components/button/wake_on_lan.rst +++ b/components/button/wake_on_lan.rst @@ -14,7 +14,7 @@ by specifying its MAC address. button: - platform: wake_on_lan name: "Start the Server" - target_mac_address: E9:48:B8:CA:58:A1 + target_mac_address: XX:XX:XX:XX:XX:XX Configuration variables: ------------------------ diff --git a/components/canbus.rst b/components/canbus.rst deleted file mode 100644 index 8c562f6263..0000000000 --- a/components/canbus.rst +++ /dev/null @@ -1,498 +0,0 @@ -.. _canbus: - -CAN bus -======= - -.. seo:: - :description: Instructions for setting up an CAN bus in ESPHome - :image: canbus.svg - :keywords: CAN - -Controller Area Network (CAN bus) is a serial bus protocol to connect individual systems and sensors -as an alternative to conventional multi-wire looms. -It allows automotive components to communicate on a single or dual-wire networked data bus up to 1Mbps. -CAN is an International Standardization Organization (ISO) defined serial communications bus originally -developed for the automotive industry to replace the complex wiring harness with a two-wire bus. The -specification calls for high immunity to electrical interference and the ability to self-diagnose and repair -data errors. These features have led to CAN’s popularity in a variety of industries including building -automation, medical, and manufacturing. - -The current ESPHome implementation supports single frame data transfer. In this way you may send and -receive data frames up to 8 bytes. -With this you can transmit the press of a button or the feedback from a sensor on the bus. -All other devices on the bus will be able to get this data to switch on/off a light or display the -transmitted data. - -The CAN bus itself has only two wires named Can High and Can Low or CanH and CanL. For the ESPHome -CAN bus to work you need to select the device that has the physical CAN bus implemented. -You can configure multiple buses. - -Any can bus node can transmit data at any time, and any node can send any ``can_id`` value and any -node can receive any can_id too. Is up to you how to organize the can_id values. You can setup a can -bus network where each node has a can id which will use to broadcast data about itself, if a node -should, e.g. turn on a light, it can listen for can messages with the can id assigned to it. -So you can have several nodes being able to control a light in e.g. node 20. - -Base CAN Bus Configuration --------------------------- - -Each canbus platform extends this configuration schema. - -.. code-block:: yaml - - # Example configuration entry - canbus: - - platform: ... - can_id: 4 - on_frame: - - can_id: 500 - use_extended_id: false - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("can id 500", "%s", &b[0] ); - -.. _config-canbus: - -Configuration variables: -************************ - -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **can_id** (**Required**, int): default *can id* used for transmitting frames. -- **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``. - - - ``1KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``5KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``10KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``12K5BPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``16KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``20KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``25KBPS`` - - ``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`` - - See :ref:`this table ` for a list of supported bit rates by the internal CAN (TWAI) controllers of different ESP32 variants. - - -Automations: ------------- - -- **on_frame** (*Optional*, :ref:`Automation `): An automation to perform when a - CAN frame is received. See :ref:`canbus-on-frame`. - -.. _canbus-on-frame: - -``on_frame`` Trigger -******************** - -This automation will be triggered when a CAN frame is received. The variables ``x`` (of type -``std::vector``) containing the frame data, ``can_id`` (of type ``uint32_t``) containing the actual -received CAN id and ``remote_transmission_request`` (of type ``bool``) containing the corresponding field -from the CAN frame are passed to the automation for use in lambdas. - -.. note:: - - Messages this node sends to the same ID will not show up as received messages. - -.. code-block:: yaml - - canbus: - - platform: ... - on_frame: - - can_id: 43 # the received can_id - then: - - if: - condition: - lambda: 'return (x.size() > 0) ? x[0] == 0x11 : false;' - then: - light.toggle: light1 - - can_id: 0b00000000000000000000001000000 - can_id_mask: 0b11111000000000011111111000000 - use_extended_id: true - remote_transmission_request: false - then: - - lambda: |- - auto pdo_id = can_id >> 14; - switch (pdo_id) - { - case 117: - ESP_LOGD("canbus", "exhaust_fan_duty"); - break; - case 118: - ESP_LOGD("canbus", "supply_fan_duty"); - break; - case 119: - ESP_LOGD("canbus", "supply_fan_flow"); - break; - // to be continued... - } - - -Configuration variables: -************************ - -- **can_id** (**Required**, int): The received CAN id to trigger this automation on. -- **can_id_mask** (*Optional*, int): The bit mask to apply to the received CAN id before trying to match it - with *can_id*, defaults to ``0x1fffffff`` (all bits of received CAN id are compared with *can_id*). -- **use_extended_id** (*Optional*, boolean): Identifies the type of *can_id* to match on, defaults to *false*. -- **remote_transmission_request** (*Optional*, boolean): Whether to run for CAN frames with the "remote - transmission request" bit set or not set, defaults to not checking, i.e. to run for both cases. - -``canbus.send`` Action -********************** - -The can bus can transmit frames by means of the ``canbus.send`` action. -There are several forms to use it: - -.. code-block:: yaml - - on_...: - - canbus.send: - data: [ 0x10, 0x20, 0x30 ] - canbus_id: my_mcp2515 # optional if you only have 1 canbus device - can_id: 23 # override the can_id configured in the can bus - - on_...: - - canbus.send: [ 0x11, 0x22, 0x33 ] - - - canbus.send: 'hello' - - # Templated, return type is std::vector - - canbus.send: !lambda return {0x00, 0x20, 0x42}; - -Configuration variables: - -- **data** (**Required**, binary data, :ref:`templatable `): Data to transmit, up to 8 bytes or - characters are supported by can bus per frame. -- **canbus_id** (*Optional*): Optionally set the can bus id to use for transmitting - the frame. Not needed if you are using only 1 can bus. -- **can_id** (*Optional*, int): Allows to override the can id configured in - the can bus device. -- **use_extended_id** (*Optional*, boolean): default *false* identifies the type of *can_id*: - *false*: Standard 11 Bit IDs, *true*: Extended 29Bit ID -- **remote_transmission_request** (*Optional*, boolean): Set to send CAN bus frame to request data from another node - (defaults to *false*). If a certain data length code needs to be sent, provide as many (dummy) bytes in *data*. - -ESP32 CAN Component -------------------- - -The ESP32 has an integrated CAN controller and therefore doesn't need an external controller necessarily. -You only need to specify the RX and TX pins. Any GPIO will work. - -.. code-block:: yaml - - # Example configuration entry - canbus: - - platform: esp32_can - tx_pin: GPIOXX - rx_pin: GPIOXX - can_id: 4 - bit_rate: 50kbps - on_frame: - ... - - -.. _esp32-can-bit-rate: - -The table lists the specific bit rates supported by the component for ESP32 variants: - =================== ======= ========== ========== ========== ========== ========== - bit_rate ESP32 ESP32-S2 ESP32-S3 ESP32-C3 ESP32-C6 ESP32-H2 - =================== ======= ========== ========== ========== ========== ========== - 1KBPS x x x x x - 5KBPS x x x x x - 10KBPS x x x x x - 12K5BPS x x x x x - 16KBPS x x x x x - 20KBPS x x x x x - 25KBPS x x x x x x - 31K25BPS - 33KBPS - 40KBPS - 50KBPS x x x x x x - 80KBPS - 83K38BPS - 95KBPS - 100KBPS x x x x x x - 125KBPS (Default) x x x x x x - 250KBPS x x x x x x - 500KBPS x x x x x x - 800KBPS x x x x x x - 1000KBPS x x x x x x - =================== ======= ========== ========== ========== ========== ========== - - -Wiring options -************** - -5V CAN transceivers are cheap and generate compliant levels. If you power your -board with 5V this is the preferred option. R501 is important to reduce the 5V -logic level down to 3.3V, to avoid damaging the ESP32. You can alternatively -use a voltage divider here instead. - -.. figure:: images/canbus_esp32_5v.png - :align: center - :target: ../_images/canbus_esp32_5v.png - -If you prefer to only have a 3.3V power supply, special 3.3V CAN transceivers are available. - -.. figure:: images/canbus_esp32_3v3.png - :align: center - :target: ../_images/canbus_esp32_3v3.png - - -Configuration variables: -************************ - -- **rx_pin** (**Required**, :ref:`Pin `): Receive pin. -- **tx_pin** (**Required**, :ref:`Pin `): Transmit pin. -- All other options from :ref:`Canbus `. - -MCP2515 Component ------------------ - -The MCP2515 is a spi device and therefore you must first add the configuration for the spi bus to your file. -You need to have an :ref:`SPI bus ` in your configuration with both the **mosi_pin** and **miso_pin** set. - -For wiring up the MSP2515 please refer to the section below. - -.. code-block:: yaml - - # Example configuration entry - canbus: - - platform: mcp2515 - cs_pin: GPIOXX - can_id: 4 - bit_rate: 50kbps - on_frame: - - can_id: 500 - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("canid 500", "%s", &b[0] ); - - light.turn_off: light_1 - - can_id: 501 - then: - - light.turn_on: - id: light_1 - brightness: !lambda "return (x.size() > 0) ? (float) x[0]/255 : 0;" - -Configuration variables: -************************ - -- **cs_pin** (**Required**, :ref:`Pin Schema `): Is used to tell the receiving SPI device - when it should listen for data on the SPI bus. Each device has an individual ``CS`` line. - Sometimes also called ``SS``. -- **clock** (*Optional*): One of ``8MHZ``, ``12MHz``, ``16MHZ`` or ``20MHZ``. Clock crystal used on the MCP2515 device. - 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 - -- All other options from :ref:`Canbus `. - -Note that not all combinations of clock and bitrate are supported. An unsupported -combination will not be flagged at compile time, check the runtime log for a message like -``Invalid frequency/bitrate combination`` if you suspect this is an issue. - -Wiring options -************** - -Easiest approach is to just use fully assembled boards and just add one resistor in the MISO line. -This runs MOSI, SCK and CS out of specification which is nearly never a problem. - -.. figure:: images/canbus_mcp2515_resistor.png - :align: center - :target: ../_images/canbus_mcp2515_resistor.png - -A more advanced option is to fully convert the 5V and 3.3V logic levels with a level shifter. - -.. figure:: images/canbus_mcp2515_txs0108e.png - :align: center - :target: ../_images/canbus_mcp2515_txs0108e.png - -Extended ID ------------ -Standard IDs and Extended IDs can coexist on the same segment. - -.. note:: - - It is important to know that for example Standard 0x123 and Extended 0x123 are different addresses. - This example shows how the different ID types are used in the configuration for transmission and receiving. - For the IDs decimal or hexadecimal notation is possible: - 0x000 - 0x7ff / 0-2047 for Standard IDs only. - 0x00000000 - 0x1fffffff / 0-536870911 for Extended IDs. - -.. code-block:: yaml - - # Transmission of extended and standard ID 0x100 every second - time: - - platform: sntp - on_time: - - seconds: /1 - then: - - canbus.send: - # Extended ID explicit - use_extended_id: true - can_id: 0x100 - data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] - - canbus.send: - # Standard ID by default - can_id: 0x100 - data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] - - canbus: - - platform: mcp2515 - id: my_mcp2515 - spi_id: McpSpi - cs_pin: GPIOXX - can_id: 0x1fff - use_extended_id: true - bit_rate: 125kbps - on_frame: - - can_id: 0x123 - use_extended_id: true - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("can extended id 0x123", "%s", &b[0] ); - - can_id: 0x123 - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("can standard id 0x123", "%s", &b[0] ); - -Binary Sensor Example ---------------------- -Example for the following application: -Button is connected on a can node which sends an A message on ID 0x100 with payload 0x01 for contact closed and 0x00 for contact open. - -.. code-block:: yaml - - spi: - id: McpSpi - clk_pin: GPIOXX - mosi_pin: GPIOXX - miso_pin: GPIOXX - - binary_sensor: - - platform: template - name: "CAN Bus Button" - id: "can_bus_button" - - canbus: - - platform: mcp2515 - id: my_mcp2515 - spi_id: McpSpi - cs_pin: GPIOXX - can_id: 4 - bit_rate: 125kbps - on_frame: - - can_id: ${0x100} - then: - - lambda: |- - if(x.size() > 0) { - switch(x[0]) { - case 0x0: id(can_bus_button).publish_state(false); break; // button release - case 0x1: id(can_bus_button).publish_state(true); break; // button down - } - } - -Cover Example -------------- -Example for following application: -Buttons are connected on the CAN-Node and also the motor is connected via CAN. - -.. epigraph:: - - | **Button 1:** ID 0x50B - 1 byte payload - | (0: Button release, 1: Button down, 2: long down, 3: long release, 4 double click) - | **Button 2:** ID 0x50C - 1 byte payload - | (0: Button release, 1: Button down, 2: long down, 3: long release, 4 double click) - | **Motor:** ID 0x51A - 1 byte payload - | (0: off, 1: open, 2: close) - -.. code-block:: yaml - - spi: - id: McpSpi - clk_pin: GPIOXX - mosi_pin: GPIOXX - miso_pin: GPIOXX - - canbus: - - platform: mcp2515 - id: my_mcp2515 - spi_id: McpSpi - cs_pin: GPIOXX - can_id: 4 - bit_rate: 125kbps - on_frame: - - can_id: 0x50c - then: - - lambda: |- - if(x.size() > 0) { - auto call = id(TestCover).make_call(); - switch(x[0]) { - case 0x2: call.set_command_open(); call.perform(); break; // long pressed - case 0x1: // button down - case 0x3: call.set_command_stop(); call.perform(); break; // long released - case 0x4: call.set_position(1.0); call.perform(); break; // double click - } - } - - can_id: 0x50b - then: - - lambda: |- - if(x.size() > 0) { - auto call = id(TestCover).make_call(); - switch(x[0]) { - case 0x2: call.set_command_close(); call.perform(); break; // long pressed - case 0x1: // button down - case 0x3: call.set_command_stop(); call.perform(); break; // long released - case 0x4: call.set_position(0.0); call.perform(); break; // double click - } - } - - cover: - - platform: time_based - name: "MyCanbusTestCover" - id: TestCover - device_class: shutter - has_built_in_endstop: true - open_action: - - canbus.send: - data: [ 0x01 ] - canbus_id: my_mcp2515 - can_id: 0x51A - open_duration: 2min - close_action: - - canbus.send: - data: [ 0x02 ] - canbus_id: my_mcp2515 - can_id: 0x51A - close_duration: 2min - stop_action: - - canbus.send: - data: [ 0x00 ] - canbus_id: my_mcp2515 - can_id: 0x51A - -See Also --------- - -- :apiref:`spi/spi.h` -- :ghedit:`Edit` diff --git a/components/canbus/esp32_can.rst b/components/canbus/esp32_can.rst new file mode 100644 index 0000000000..bc973f08e2 --- /dev/null +++ b/components/canbus/esp32_can.rst @@ -0,0 +1,83 @@ +ESP32 CAN +========= + +.. seo:: + :description: Instructions for setting up the ESP32 CAN bus platform in ESPHome + :image: canbus.svg + :keywords: CAN, ESP32 + +The ESP32 has an integrated CAN controller and therefore doesn't necessarily need an external controller. +You only need to specify the RX and TX pins. Any GPIO will work. + +.. code-block:: yaml + + # Example configuration entry + canbus: + - platform: esp32_can + tx_pin: GPIOXX + rx_pin: GPIOXX + can_id: 4 + bit_rate: 50kbps + on_frame: + ... + +Configuration variables: +------------------------ + +- **rx_pin** (**Required**, :ref:`Pin `): Receive pin. +- **tx_pin** (**Required**, :ref:`Pin `): Transmit pin. +- All other options from :ref:`Canbus `. + +.. _esp32-can-bit-rate: + +The following table lists the bit rates supported by the component for ESP32 variants: + +=================== ======= ========== ========== ========== ========== ========== +bit_rate ESP32 ESP32-S2 ESP32-S3 ESP32-C3 ESP32-C6 ESP32-H2 +=================== ======= ========== ========== ========== ========== ========== +1KBPS x x x x x +5KBPS x x x x x +10KBPS x x x x x +12K5BPS x x x x x +16KBPS x x x x x +20KBPS x x x x x +25KBPS x x x x x x +31K25BPS +33KBPS +40KBPS +50KBPS x x x x x x +80KBPS +83K38BPS +95KBPS +100KBPS x x x x x x +125KBPS (Default) x x x x x x +250KBPS x x x x x x +500KBPS x x x x x x +800KBPS x x x x x x +1000KBPS x x x x x x +=================== ======= ========== ========== ========== ========== ========== + +Wiring options +-------------- + +5V CAN transceivers are cheap and generate compliant levels. If you power your +board with 5V this is the preferred option. R501 is important to reduce the 5V +logic level down to 3.3V, to avoid damaging the ESP32. You can alternatively +use a voltage divider here instead. + +.. figure:: images/canbus_esp32_5v.png + :align: center + :target: ../_images/canbus_esp32_5v.png + +If you prefer to only have a 3.3V power supply, special 3.3V CAN transceivers are available. + +.. figure:: images/canbus_esp32_3v3.png + :align: center + :target: ../_images/canbus_esp32_3v3.png + +See Also +-------- + +- :doc:`index` +- :apiref:`canbus/canbus.h` +- :ghedit:`Edit` diff --git a/components/images/canbus_esp32_3v3.png b/components/canbus/images/canbus_esp32_3v3.png similarity index 100% rename from components/images/canbus_esp32_3v3.png rename to components/canbus/images/canbus_esp32_3v3.png diff --git a/components/images/canbus_esp32_5v.png b/components/canbus/images/canbus_esp32_5v.png similarity index 100% rename from components/images/canbus_esp32_5v.png rename to components/canbus/images/canbus_esp32_5v.png diff --git a/components/images/canbus_mcp2515_resistor.png b/components/canbus/images/canbus_mcp2515_resistor.png similarity index 100% rename from components/images/canbus_mcp2515_resistor.png rename to components/canbus/images/canbus_mcp2515_resistor.png diff --git a/components/images/canbus_mcp2515_txs0108e.png b/components/canbus/images/canbus_mcp2515_txs0108e.png similarity index 100% rename from components/images/canbus_mcp2515_txs0108e.png rename to components/canbus/images/canbus_mcp2515_txs0108e.png diff --git a/components/canbus/index.rst b/components/canbus/index.rst new file mode 100644 index 0000000000..a16a727085 --- /dev/null +++ b/components/canbus/index.rst @@ -0,0 +1,369 @@ +CAN Bus +======= + +.. seo:: + :description: Instructions for setting up an CAN bus in ESPHome + :image: canbus.svg + :keywords: CAN + +The Controller Area Network (CAN) bus is a serial bus protocol to connect individual systems and sensors +as an alternative to conventional multi-wire looms. It allows automotive components to communicate on a +single or dual-wire data bus at speeds up to 1Mbps. + +CAN is an International Standardization Organization (ISO) defined serial communications bus originally +developed for the automotive industry to replace the complex wiring harness with a two-wire bus. The +specification calls for high immunity to electrical interference and the ability to self-diagnose and repair +data errors. These features have led to CAN’s popularity in a variety of industries including building +automation, medical, and manufacturing. + +The current ESPHome implementation supports single frame data transfer. In this way you may send and +receive data frames up to 8 bytes. +With this you can transmit the press of a button or the feedback from a sensor on the bus. +All other devices on the bus will be able to get this data to switch on/off a light or display the +transmitted data. + +The CAN bus itself has only two wires named Can High and Can Low or CanH and CanL. For the ESPHome +CAN bus to work, you need to select the device that has the physical CAN bus implemented. +You can configure multiple buses. + +Any CAN bus node can transmit data at any time; any node can both send and/or receive any ``can_id`` value. +You must determine how to organize the ``can_id`` values; for example, you can set up a CAN bus network where +each node has a ``can_id`` it will use to broadcast data about itself. If a given node should (for example) turn +on a light, it can listen to the CAN bus for messages containing its specific ``can_id`` and react accodingly. +With this architecture, you can have multiple nodes able to control a light connected to a single, specific node. + +Base CAN Bus Configuration +-------------------------- + +Each ``canbus`` platform extends the following configuration schema: + +.. code-block:: yaml + + # Example configuration entry + canbus: + - platform: ... + can_id: 4 + on_frame: + - can_id: 500 + use_extended_id: false + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("can id 500", "%s", &b[0] ); + +.. _config-canbus: + +**Configuration variables:** + +- **platform** (**Required**, :ref:`platform`): One of the supported CAN bus :ref:`platforms-canbus`. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **can_id** (**Required**, int): default *CAN ID* used for transmitting frames. +- **use_extended_id** (*Optional*, boolean): Identifies the type of ``can_id``: + + - ``false``: Standard 11-bit IDs *(default)* + - ``true``: Extended 29-bit IDs + +- **bit_rate** (*Optional*, enum): One of the supported bit rates. See :ref:`this table ` for a + list of supported bit rates by the internal CAN (TWAI) controllers of different ESP32 variants. Defaults to ``125KBPS``. + + - ``1KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``5KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``10KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``12K5BPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``16KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``20KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``25KBPS`` + - ``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`` + +- **on_frame** (*Optional*, :ref:`Automation `): An automation to perform when a + CAN frame is received. See :ref:`canbus-on-frame`. + +.. _platforms-canbus: + +Platforms +--------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +Automations +----------- + +.. _canbus-on-frame: + +``on_frame`` Trigger +******************** + +This automation will be triggered when a CAN frame is received. The variables ``x`` (of type +``std::vector``) containing the frame data, ``can_id`` (of type ``uint32_t``) containing the actual +received CAN ID and ``remote_transmission_request`` (of type ``bool``) containing the corresponding field +from the CAN frame are passed to the automation for use in lambdas. + +.. note:: + + Messages this node sends to the same ID will not show up as received messages. + +.. code-block:: yaml + + canbus: + - platform: ... + on_frame: + - can_id: 43 # the received can_id + then: + - if: + condition: + lambda: 'return (x.size() > 0) ? x[0] == 0x11 : false;' + then: + light.toggle: light1 + - can_id: 0b00000000000000000000001000000 + can_id_mask: 0b11111000000000011111111000000 + use_extended_id: true + remote_transmission_request: false + then: + - lambda: |- + auto pdo_id = can_id >> 14; + switch (pdo_id) + { + case 117: + ESP_LOGD("canbus", "exhaust_fan_duty"); + break; + case 118: + ESP_LOGD("canbus", "supply_fan_duty"); + break; + case 119: + ESP_LOGD("canbus", "supply_fan_flow"); + break; + // to be continued... + } + + +**Configuration variables:** + +- **can_id** (**Required**, int): The CAN ID which, when received, will trigger this automation. +- **can_id_mask** (*Optional*, int): The bit mask to apply to the received CAN ID before trying to match it + with *can_id*. Defaults to ``0x1fffffff`` (all bits of received CAN ID are compared with *can_id*). +- **use_extended_id** (*Optional*, boolean): Identifies the type of ``can_id`` to match on. Defaults to ``false``. +- **remote_transmission_request** (*Optional*, boolean): Whether to run for CAN frames with the "remote + transmission request" bit set or not set. Defaults to not checking (the automation will run for both cases). + +``canbus.send`` Action +********************** + +The CAN bus can transmit frames by means of the ``canbus.send`` action. There are several ways to use it: + +.. code-block:: yaml + + on_...: + - canbus.send: + data: [ 0x10, 0x20, 0x30 ] + canbus_id: my_mcp2515 # optional if you only have 1 canbus device + can_id: 23 # override the can_id configured in the can bus + + on_...: + - canbus.send: [ 0x11, 0x22, 0x33 ] + + - canbus.send: 'hello' + + # Templated; return type must be std::vector + - canbus.send: !lambda return {0x00, 0x20, 0x42}; + +**Configuration variables:** + +- **data** (**Required**, binary data, :ref:`templatable `): Data to transmit, up to eight + bytes/characters are supported by CAN bus per frame. +- **canbus_id** (*Optional*): Sets the CAN bus ID to use for transmitting the frame. Required if you are have multiple + CAN bus platforms defined in your configuration. +- **can_id** (*Optional*, int): Allows overriding the ``can_id`` configured for the CAN bus device. +- **use_extended_id** (*Optional*, boolean): Identifies the type of ``can_id``: + + - ``false``: Standard 11-bit IDs *(default)* + - ``true``: Extended 29-bit IDs + +- **remote_transmission_request** (*Optional*, boolean): Set to send CAN bus frame to request data from another node. + If a certain data length code needs to be sent, include the necessary (dummy) bytes in ``data``. Defaults to ``false``. + +Extended ID +----------- + +Standard IDs and Extended IDs can coexist on the same segment. + +.. note:: + + It is important to know that "standard" and "extended" addresses denote different addresses. For example, + Standard ``0x123`` and Extended ``0x123`` are, in fact, different addresses. + +Decimal or hexadecimal notation may be used for IDs: + +- Standard IDs use ``0x000`` to ``0x7ff`` (hexadecimal) or ``0`` to ``2047`` (decimal) +- Extended IDs use ``0x00000000`` to ``0x1fffffff`` (hexadecimal) or ``0`` to ``536870911`` (decimal) + +This example illustrates how different ID types may be used in your configuration for both transmitting and receiving. + +.. code-block:: yaml + + # Transmission of extended and standard ID 0x100 every second + time: + - platform: sntp + on_time: + - seconds: /1 + then: + - canbus.send: + # Extended ID explicit + use_extended_id: true + can_id: 0x100 + data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] + - canbus.send: + # Standard ID by default + can_id: 0x100 + data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] + + canbus: + - platform: ... + can_id: 0x1fff + use_extended_id: true + bit_rate: 125kbps + on_frame: + - can_id: 0x123 + use_extended_id: true + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("CAN extended ID 0x123", "%s", &b[0]); + - can_id: 0x123 + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("CAN standard ID 0x123", "%s", &b[0]); + +Binary Sensor Example +--------------------- + +Given that we have a button connected to a remote CAN node which will send a message to ID ``0x100`` with the payload +``0x1`` for contact closed and ``0x0`` for contact open, this example will look for this message and update the state +of its ``binary_sensor`` accordingly. + +.. code-block:: yaml + + binary_sensor: + - platform: template + name: CAN Bus Button + id: can_bus_button + + canbus: + - platform: ... + can_id: 4 + bit_rate: 125kbps + on_frame: + - can_id: ${0x100} + then: + - lambda: |- + if(x.size() > 0) { + switch(x[0]) { + case 0x0: // button release + id(can_bus_button).publish_state(false); + break; + case 0x1: // button press + id(can_bus_button).publish_state(true); + break; + } + } + +Cover Example +------------- + +In this example, three nodes are connected to the CAN bus: + +- Node 1 sends a one-byte payload to ID ``0x50B`` +- Node 2 sends a one-byte payload to ID ``0x50C`` + + These nodes send the following one-byte payload which is based on the state of a button connected to each of them: + + - 0: Button release + - 1: Button press + - 2: Long press + - 3: Long release + - 4: Double-click + +- Node 3 controls a motor connected to it. It expects a message to ID ``0x51A`` where the one-byte payload is: + + - 0: Off + - 1: Open + - 2: Close + +.. code-block:: yaml + + canbus: + - platform: ... + id: my_canbus + can_id: 4 + bit_rate: 125kbps + on_frame: + - can_id: 0x50c + then: + - lambda: |- + if(x.size() > 0) { + auto call = id(TestCover).make_call(); + switch(x[0]) { + case 0x2: call.set_command_open(); call.perform(); break; // long press + case 0x1: // button press + case 0x3: call.set_command_stop(); call.perform(); break; // long release + case 0x4: call.set_position(1.0); call.perform(); break; // double-click + } + } + - can_id: 0x50b + then: + - lambda: |- + if(x.size() > 0) { + auto call = id(TestCover).make_call(); + switch(x[0]) { + case 0x2: call.set_command_close(); call.perform(); break; // long press + case 0x1: // button press + case 0x3: call.set_command_stop(); call.perform(); break; // long release + case 0x4: call.set_position(0.0); call.perform(); break; // double-click + } + } + + cover: + - platform: time_based + name: Canbus Test Cover + id: TestCover + device_class: shutter + has_built_in_endstop: true + open_action: + - canbus.send: + data: [ 0x01 ] + canbus_id: my_canbus + can_id: 0x51A + open_duration: 2min + close_action: + - canbus.send: + data: [ 0x02 ] + canbus_id: my_canbus + can_id: 0x51A + close_duration: 2min + stop_action: + - canbus.send: + data: [ 0x00 ] + canbus_id: my_canbus + can_id: 0x51A + +See Also +-------- + +- :apiref:`canbus/canbus.h` +- :ghedit:`Edit` diff --git a/components/canbus/mcp2515.rst b/components/canbus/mcp2515.rst new file mode 100644 index 0000000000..eab97d2ebe --- /dev/null +++ b/components/canbus/mcp2515.rst @@ -0,0 +1,79 @@ +MCP2515 +======= + +.. seo:: + :description: Instructions for setting up the MCP2515 CAN bus platform in ESPHome + :image: canbus.svg + :keywords: CAN, MCP2515 + +The MCP2515 communicates with ESPHome via the :ref:`SPI bus `; to use it, you must have at least one +:ref:`SPI bus ` with both the ``mosi_pin`` and ``miso_pin`` defined in your ESPHome configuration. + +The :ref:`mcp2515-wiring` section below illustrates how to wire up your MCP2515. + +.. code-block:: yaml + + # Example configuration entry + canbus: + - platform: mcp2515 + cs_pin: GPIOXX + can_id: 4 + bit_rate: 50kbps + on_frame: + - can_id: 500 + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("canid 500", "%s", &b[0] ); + - light.turn_off: light_1 + - can_id: 501 + then: + - light.turn_on: + id: light_1 + brightness: !lambda "return (x.size() > 0) ? (float) x[0]/255 : 0;" + +Configuration variables: +------------------------ + +- **cs_pin** (**Required**, :ref:`Pin Schema `): Is used to signal to a SPI device when it should + listen for data on the SPI bus. Each SPI device has its own ``CS`` line. Sometimes also called ``SS``. +- **clock** (*Optional*, frequency): The frequency of the clock crystal used on the MCP2515 device. One of ``8MHZ``, + ``12MHz``, ``16MHZ`` or ``20MHZ``. Defaults to ``8MHZ``. +- **mode** (*Optional*, enum): Operating mode. One of: + + - ``NORMAL``: Normal operation. *(default)* + - ``LOOPBACK``: Loopback mode is useful for testing your connections to/from the device. + - ``LISTENONLY``: Receive data only. + +- All other options from :ref:`Canbus `. + +.. note:: + + Not all combinations of clock and bitrate are supported. An unsupported combination will not be flagged at + compile time. Check your ESPHome device's logs for a message like ``Invalid frequency/bitrate combination`` + if you suspect this is an issue. + +.. _mcp2515-wiring: + +Wiring options +-------------- + +The easiest approach is to use fully assembled boards and just add one resistor on the MISO line. This runs MOSI, SCK +and CS out of specification which is rarely a problem. + +.. figure:: images/canbus_mcp2515_resistor.png + :align: center + :target: ../_images/canbus_mcp2515_resistor.png + +A more complex option is to properly convert the 3.3V and 5V logic levels with a level shifter. + +.. figure:: images/canbus_mcp2515_txs0108e.png + :align: center + :target: ../_images/canbus_mcp2515_txs0108e.png + +See Also +-------- + +- :doc:`index` +- :apiref:`canbus/canbus.h` +- :ghedit:`Edit` diff --git a/components/climate/anova.rst b/components/climate/anova.rst index 0cfa3eac71..fe0e4d4654 100644 --- a/components/climate/anova.rst +++ b/components/climate/anova.rst @@ -36,7 +36,7 @@ need to do conversion again within the frontend if you use Fahrenheit. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:aa:bb:cc + - mac_address: XX:XX:XX:XX:XX:XX id: my_anova climate: diff --git a/components/climate/bedjet.rst b/components/climate/bedjet.rst index e9cf9d5347..d20c370e62 100644 --- a/components/climate/bedjet.rst +++ b/components/climate/bedjet.rst @@ -31,7 +31,7 @@ and delegates status updates to individual platform components. esp32_ble_tracker: ble_client: - - mac_address: C4:4F:33:00:00:01 + - mac_address: XX:XX:XX:XX:XX:XX id: bedjet_ble_id1 bedjet: diff --git a/components/climate/climate_ir.rst b/components/climate/climate_ir.rst index 7013e66929..8cf167f221 100644 --- a/components/climate/climate_ir.rst +++ b/components/climate/climate_ir.rst @@ -10,17 +10,15 @@ control signal, just as the unit's handheld remote controller would. .. figure:: images/climate-ui.png :align: center - :width: 60.0% + :width: 40.0% There is a growing list of compatible units. If your unit is not listed below you should submit a feature request (see FAQ). +---------------------------------------+---------------------+----------------------+ -| Name | Platform name | Supports receiver | +| Supported units | Platform name | Supports receiver | | | | | +=======================================+=====================+======================+ -| :ref:`Arduino-HeatpumpIR` | ``heatpumpir`` | | -+---------------------------------------+---------------------+----------------------+ | Ballu | ``ballu`` | yes | +---------------------------------------+---------------------+----------------------+ | Coolix | ``coolix`` | yes | @@ -39,7 +37,7 @@ submit a feature request (see FAQ). +---------------------------------------+---------------------+----------------------+ | :ref:`GREE` | ``gree`` | | +---------------------------------------+---------------------+----------------------+ -| Hitachi | ``hitachi_ac344`` | yes | +| Hitachi | ``hitachi_ac344``, | yes | | | ``hitachi_ac424`` | | +---------------------------------------+---------------------+----------------------+ | :ref:`LG` | ``climate_ir_lg`` | yes | @@ -62,11 +60,15 @@ submit a feature request (see FAQ). +---------------------------------------+---------------------+----------------------+ | :ref:`ZH/LT-01` | ``zhlt01`` | yes | +---------------------------------------+---------------------+----------------------+ +| :ref:`Arduino-HeatpumpIR` | ``heatpumpir`` | | +| library | | | ++---------------------------------------+---------------------+----------------------+ This component requires that you have configured a :doc:`/components/remote_transmitter`. Due to the unidirectional nature of IR remote controllers, this component cannot determine the actual state of the device and will assume the state of the device is the latest state requested. +The assumed state can be restored at boot. However, when receiver is supported, you can optionally add a :doc:`/components/remote_receiver` component so the climate state will be tracked when it is operated with the original remote @@ -80,7 +82,7 @@ controller unit. carrier_duty_percent: 50% climate: - - platform: coolix # adjust to match your AC unit! + - platform: REPLACEME name: "Living Room AC" Configuration Variables: @@ -95,98 +97,16 @@ Configuration Variables: receiver. see: :ref:`ir-receiver_id`. - All other options from :ref:`Climate `. -Advanced Options ----------------- +**Advanced Options** - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **transmitter_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the remote transmitter. -.. _heatpumpir: - -Arduino-HeatpumpIR ------------------- - -The ``heatpumpir`` platform supports dozens of manufacturers and hundreds of AC units by utilising the `Arduino-HeatpumpIR library `__. - -This platform should only be used if your AC unit is not supported by any of the other (native) platforms. No support can be provided for Arduino-HeatpumpIR, because it is a third party library. - -This platform utilises the library's generic one-size-fits-all API, which might not line up perfectly with all of the supported AC units. For example, some AC units have more fan speed options than what the generic API supports. - -Additional configuration must be specified for this platform: - -- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: - ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``carrier_qlima_1``, ``carrier_qlima_1``, ``daikin``, ``daikin_arc417``, - ``daikin_arc480``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeyaa``, ``greeyac``, ``greeyan``, ``greeyap``, - ``greeyt``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, - ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, - ``mitsubishi_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``nibe``, ``panasonic_ckp``, ``panasonic_dke``, - ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_aqv12msan``, - ``samsung_fjm``, ``sharp``, ``toshiba``, ``toshiba_daiseikai``, ``zhjg01``, ``zhlt01``. - - -- **horizontal_default** (**Required**, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Options are: ``left``, ``mleft``, ``middle``, ``mright``, ``right``, ``auto``. -- **vertical_default** (**Required**, string): What to default to when the AC unit's vertical direction is *not* set to swing. Options are: ``down``, ``mdown``, ``middle``, ``mup``, ``up``, ``auto``. -- **max_temperature** (**Required**, float): The maximum temperature that the AC unit supports being set to. -- **min_temperature** (**Required**, float): The minimum temperature that the AC unit supports being set to. -- **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient temperature. - -.. note:: - - - The ``greeyac`` protocol supports a feature Gree calls "I-Feel". The handheld remote control - has a built-in temperature sensor and it will periodically transmit the temperature from this sensor to the - AC unit. If a ``sensor`` is provided in the configuration with this model, the sensor's temperature will be - transmitted to the ``greeyac`` device in the same manner as the original remote controller. How often the - temperature is transmitted is determined by the ``update_interval`` assigned to the ``sensor``. Note that - ``update_interval`` must be less than 10 minutes or the ``greeyac`` device will revert to using its own - internal temperature sensor; a value of 2 minutes seems to work well. See :doc:`/components/sensor/index` - for more information. - - - The ``zhlt01`` protocol supports multiple AC brands: Eurom, Chigo, Tristar, Tecnomaster, Elgin, Geant, Tekno, Topair, Proma, Sumikura, JBS, Turbo Air, Nakatomy, Celestial Air, Ager, Blueway, Airlux, etc. - -.. _ir-receiver_id: - -Using a Receiver ----------------- - -.. note:: - - This is only supported with select climate devices, see "Supports receiver" in the table at the top of the page. - -Optionally, some platforms can listen to data the climate device sends over infrared to update their state ( -for example what mode the device is in). By setting up a :doc:`remote_receiver ` -and passing its ID to the climate platform you can enable this mode. - -When using a receiver it is recommended to put the IR receiver as close as possible to the equipment's -IR receiver. - -.. code-block:: yaml - - # Example configuration entry - remote_receiver: - id: rcvr - pin: - number: GPIOXX - inverted: true - mode: - input: true - pullup: true - # high 55% tolerance is recommended for some remote control units - tolerance: 55% - - climate: - - platform: coolix - name: "Living Room AC" - receiver_id: rcvr +**Specific configuration variables:** .. _climate_ir_lg: -``climate_ir_lg`` Climate -------------------------- - -Additional configuration is available for this platform - - -Configuration variables: +``climate_ir_lg`` **Climate**: - **header_high** (*Optional*, :ref:`config-time`): time for the high part of the header for the LG protocol. Defaults to ``8000us`` - **header_low** (*Optional*, :ref:`config-time`): time for the low part of the header for the LG protocol. Defaults to ``4000us`` @@ -204,31 +124,12 @@ Configuration variables: header_high: 3265us # AC Units from LG in Brazil, for example use these timings header_low: 9856us -.. _daikin_arc: - -``daikin_arc`` Climate -------------------------- - -The Daikin ARC remotes are used by the japanese model of Daikin. - -.. code-block:: yaml - - # Example configuration entry - climate: - - platform: daikin_arc - name: "AC" - sensor: room_temperature - .. _daikin_brc: -``daikin_brc`` Climate -------------------------- +``daikin_brc`` **Climate**: The Daikin BRC remotes are used by the ceiling cassette model of Daikin heatpumps. - -Configuration variables: - - **use_fahrenheit** (*Optional*, boolean): U.S. models of the Daikin BRC remote send the temperature in Fahrenheit, if your remote shows Fahrenheit and can not be changed to Celsius then set this to true. Defaults to ``false``. .. code-block:: yaml @@ -240,29 +141,44 @@ Configuration variables: sensor: room_temperature use_fahrenheit: true - .. _delonghi_ir: -``delonghi`` Climate -------------------------- +``delonghi`` **Climate**: -Currently supports the protocol used by some Delonghi portable units +The ``delonghi`` climate currently supports the protocol used by some Delonghi portable units, known working with Delonghi PAC WE 120HP. -Known working with: +.. _daikin_arc: -- Delonghi PAC WE 120HP +``daikin_arc`` **Climate**: -.. _midea_ir: +The Daikin ARC remotes (``daikin_arc`` climate, ``daikin_arc417``, ``daikin_arc480`` protocols of :ref:`Arduino-HeatpumpIR`) are used by the japanese model of Daikin. -``midea_ir`` Climate -------------------------- +.. _gree_ir: -These air conditioners support two protocols: Midea and Coolix. Therefore, when using an IR receiver, it considers both protocols and publishes the received states. +``gree`` **Climate**: -Additional configuration is available for this platform +- **model** (*Required*, string): GREE has a few different protocols depending on model. One of these will work for you. + - ``generic`` + - ``yan`` + - ``yaa`` + - ``yac`` + - ``yac1fb9`` + +.. code-block:: yaml + + # Example configuration entry + climate: + - platform: gree + name: "AC" + sensor: room_temperature + model: yan + +.. _midea_ir: -Configuration variables: +``midea_ir`` **Climate**: + +These air conditioners support two protocols: Midea and Coolix. Therefore, when using an IR receiver, it considers both protocols and publishes the received states. - **use_fahrenheit** (*Optional*, boolean): Allows you to transfer the temperature to the air conditioner in degrees Fahrenheit. The air conditioner display also shows the temperature in Fahrenheit. Defaults to ``false``. @@ -282,17 +198,12 @@ Configuration variables: .. _mitsubishi: -``mitsubishi`` Climate ------------------------- - -Additonal configurations available for this platform. - -Configuration variables: +``mitsubishi`` **Climate**: - **set_fan_mode** (*Optional*, string): Select the fan modes desired or that are supported on your remote. Defaults to ``3levels`` - - Options are: ``3levels`` , ``4levels``, ``quiet_4levels``. - + - Options are: ``3levels`` , ``4levels``, ``quiet_4levels``. + - ``3levels``; Low [fan speed 1], Medium [2], High [3] - ``4levels``; Low [1], Middle [2], Medium [3], High [4] - ``quiet_4levels``; Low [1], Middle [2], Medium [3], High [4], Quiet [5] @@ -300,10 +211,10 @@ Configuration variables: - **supports_dry** (*Optional*, boolean): Enables setting dry mode for this unit. Defaults to ``false``. - **supports_fan_only** (*Optional*, boolean): Enables setting fan only mode for this unit. Confirm that mode is supported on your remote. Defaults to ``false``. -- **horizontal_default** (*Optional*, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Defaults to ``middle``. +- **horizontal_default** (*Optional*, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Defaults to ``middle``. - Options are: ``left``, ``middle-left``, ``middle``, ``middle-right``, ``right``, ``auto`` -- **vertical_default** (*Optional*, string): What to default to when the AC unit's vertical direction is *not* set to swing. Defaults to ``middle``. +- **vertical_default** (*Optional*, string): What to default to when the AC unit's vertical direction is *not* set to swing. Defaults to ``middle``. - Options are: ``down``, ``middle-down``, ``middle``, ``middle-up``, ``up``, ``auto`` @@ -325,13 +236,7 @@ Configuration variables: .. _toshiba: -``toshiba`` Climate -------------------- - -Additional configuration is available for this model. - - -Configuration variables: +``toshiba`` **Climate**: - **model** (*Optional*, string): There are two valid models @@ -357,32 +262,18 @@ Configuration variables: - This climate IR component is also known to work with Midea model MAP14HS1TBL and may work with other similar models, as well. (Midea acquired Toshiba's product line and re-branded it.) - .. _whirlpool: +``whirlpool`` **Climate**: -``whirlpool`` Climate ---------------------- - -Additional configuration is available for this model. - - -Configuration variables: - -- **model** (*Optional*, string): There are two valid models +- **model** (*Optional*, string): There are two valid models to choose from: - ``DG11J1-3A``: Temperature range is from 18 to 32 (default) - ``DG11J1-91``: Temperature range is from 16 to 30 .. _whynter: -``whynter`` Climate -------------------------- - -Additional configuration is available for this platform - - -Configuration variables: +``whynter`` **Climate**: - **use_fahrenheit** (*Optional*, boolean): Allows you to transfer the temperature to the air conditioner in degrees Fahrenheit. The air conditioner display also shows the temperature in Fahrenheit. Defaults to ``false``. @@ -396,64 +287,84 @@ Configuration variables: use_fahrenheit: true supports_heat: true +.. _zhlt01: -.. _gree_ir: - +``zhlt01`` **Climate**: -``gree`` Climate ---------------------- +The ``zhlt01`` climate and protocol, based on the ZH/LT-01 remote controller, is used with many locally branded airconditioners, like: Eurom, Chigo, Tristar, Tecnomaster, Elgin, Geant, Tekno, Topair, Proma, Sumikura, JBS, Turbo Air, Nakatomy, Celestial Air, Ager, Blueway, Airlux, etc. -Additional configuration is available for this model. +.. _ir-receiver_id: +Using a Receiver +---------------- -Configuration variables: +.. note:: -- **model** (*Required*, string): GREE has a few different protocols depending on model. One of these will work for you. + This is only supported with select climate devices, see "Supports receiver" in the table at the top of the page. - - ``generic`` - - ``yan`` - - ``yaa`` - - ``yac`` - - ``yac1fb9`` +Optionally, some platforms can listen to data the climate device sends over infrared to update their state ( +for example what mode the device is in). By setting up a :doc:`remote_receiver ` +and passing its ID to the climate platform you can enable this mode. +When using a receiver it is recommended to put the IR receiver as close as possible to the equipment's +IR receiver. .. code-block:: yaml # Example configuration entry + remote_receiver: + id: rcvr + pin: + number: GPIOXX + inverted: true + mode: + input: true + pullup: true + # high 55% tolerance is recommended for some remote control units + tolerance: 55% + climate: - - platform: gree - name: "AC" - sensor: room_temperature - model: yan + - platform: REPLACEME + name: "Living Room AC" + receiver_id: rcvr -.. _zhlt01: +.. _heatpumpir: + +Arduino-HeatpumpIR +------------------ + +The ``heatpumpir`` platform supports dozens of manufacturers and hundreds of AC units by utilising the `Arduino-HeatpumpIR library `__. + +This platform compiles only under ``arduino`` framework or LibreTiny, and should only be used if your AC unit is not supported by any of the other (native) platforms from above. No support can be provided for Arduino-HeatpumpIR, because it is a third party library. + +This platform utilises the library's generic one-size-fits-all API, which might not line up perfectly with all of the supported AC units. For example, some AC units have more fan speed options than what the generic API supports. +Additional configuration must be specified for this platform: -``zhlt01`` Climate ---------------------- - -ZH/LT-01 is a remote control that is used with many locally branded split airconditioners. -Supported brands include: - -- Eurom -- Chigo -- Tristar -- Tecnomaster -- Elgin -- Geant -- Tekno -- Topair -- Proma -- Sumikura -- JBS -- Turbo Air -- Nakatomy -- Celestial Air -- Ager -- Blueway -- Airlux - -No additional configuration is required for this model. +- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: + ``airway``, ``aux``, ``ballu``, ``bgh_aud``, ``carrier_mca``, ``carrier_nqv``, ``carrier_qlima_1``, ``carrier_qlima_1``, ``daikin``, + ``daikin_arc417``, ``daikin_arc480``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeyaa``, ``greeyac``, ``greeyan``, + ``greeyap``, ``greeyt``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, + ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_kj``, + ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``nibe``, ``panasonic_altdke``, ``panasonic_ckp``, ``panasonic_dke``, + ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``r51m``, ``samsung_aqv``, ``samsung_aqv12msan``, ``samsung_fjm``, ``sharp``, + ``toshiba``, ``toshiba_daiseikai``, ``vaillantvai8``, ``zhjg01``, ``zhlt01`` +- **horizontal_default** (**Required**, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Options are: ``left``, ``mleft``, ``middle``, ``mright``, ``right``, ``auto`` +- **vertical_default** (**Required**, string): What to default to when the AC unit's vertical direction is *not* set to swing. Options are: ``down``, ``mdown``, ``middle``, ``mup``, ``up``, ``auto`` +- **max_temperature** (**Required**, float): The maximum temperature that the AC unit supports being set to. +- **min_temperature** (**Required**, float): The minimum temperature that the AC unit supports being set to. +- **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient temperature. + +.. note:: + + The ``greeyac`` protocol in ``heatpumpir`` supports a feature Gree calls "I-Feel". The handheld remote control + has a built-in temperature sensor and it will periodically transmit the temperature from this sensor to the + AC unit. If a ``sensor`` is provided in the configuration with this model, the sensor's temperature will be + transmitted to the ``greeyac`` device in the same manner as the original remote controller. How often the + temperature is transmitted is determined by the ``update_interval`` assigned to the ``sensor``. Note that + ``update_interval`` must be less than 10 minutes or the ``greeyac`` device will revert to using its own + internal temperature sensor; a value of 2 minutes seems to work well. See :doc:`/components/sensor/index` + for more information. See Also -------- @@ -463,14 +374,15 @@ See Also - :doc:`/components/remote_transmitter` - :doc:`/components/sensor/index` - :apiref:`ballu.h `, -- :apiref:`coolix.h `, + :apiref:`climate_ir_lg.h ` + :apiref:`coolix.h `, :apiref:`daikin.h ` :apiref:`fujitsu_general.h `, + :apiref:`gree.h `, :apiref:`hitachi_ac344.h `, :apiref:`midea_ir.h `, :apiref:`mitsubishi.h `, :apiref:`tcl112.h `, :apiref:`yashima.h ` :apiref:`whirlpool.h ` - :apiref:`climate_ir_lg.h ` - :ghedit:`Edit` diff --git a/components/cover/am43.rst b/components/cover/am43.rst index c1f05f5056..227b1afd18 100644 --- a/components/cover/am43.rst +++ b/components/cover/am43.rst @@ -27,7 +27,7 @@ and state of the motor. esp32_ble_tracker: ble_client: - - mac_address: AA:BB:CC:DD:EE:FF + - mac_address: XX:XX:XX:XX:XX:XX id: am43_kitchen cover: diff --git a/components/cover/time_based.rst b/components/cover/time_based.rst index d879948227..d5888b9233 100644 --- a/components/cover/time_based.rst +++ b/components/cover/time_based.rst @@ -7,7 +7,8 @@ Time Based Cover The ``time_based`` cover platform allows you to create covers with position control that do not have any position feedback. The state of the cover is thus always an assumed one, the current -position is approximated with the time the cover has been moving in a direction. +position is approximated with the time the cover has been moving in a direction. The state +of the cover can be restored at node reboot. .. figure:: images/more-info-ui.png :align: center @@ -71,12 +72,6 @@ Configuration variables: The stop button on the UI is always enabled even when the cover is stopped and each press on the button will cause the ``stop_action`` to be performed. -.. note:: - - The state of the cover can be restored from flash after a node reboot, with - ``esp8266_restore_from_flash: true`` option set. - See :doc:`esp8266_restore_from_flash ` for details. - Handle stop_action: ------------------------ For some cover controllers, separate switches for UP and DOWN action are used while a stop is issued when sending a counter command. diff --git a/components/display/pvvx_mithermometer.rst b/components/display/pvvx_mithermometer.rst index 799b25333c..05cc787231 100644 --- a/components/display/pvvx_mithermometer.rst +++ b/components/display/pvvx_mithermometer.rst @@ -29,7 +29,7 @@ The firmware configuration can be changed via browser using `TelinkMiFlasher.htm esp32_ble_tracker: ble_client: - - mac_address: "A4:C1:38:B1:CD:7F" + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display display: @@ -139,12 +139,12 @@ The following example display the sensor states of a MiFlora sensor on a pvvx di esp32_ble_tracker: ble_client: - - mac_address: "A4:C1:38:B1:CD:7F" + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: @@ -154,7 +154,7 @@ The following example display the sensor states of a MiFlora sensor on a pvvx di battery_voltage: name: "PVVX Battery-Voltage" - platform: xiaomi_hhccjcy01 - mac_address: '94:2B:FF:5C:91:61' + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi HHCCJCY01 Temperature" id: miflora_temperature @@ -199,12 +199,12 @@ The following example will synchronized the time of the pvvx device once a day. esp32_ble_tracker: ble_client: - - mac_address: "A4:C1:38:B1:CD:7F" + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: diff --git a/components/display/sdl.rst b/components/display/sdl.rst index c075dfc773..3e30ad60c8 100644 --- a/components/display/sdl.rst +++ b/components/display/sdl.rst @@ -17,14 +17,13 @@ than compiling for and flashing a microcontroller target system. .. code-block:: yaml # Example configuration entry + esphome: + name: sdl + host: - mac_address: "62:23:45:AF:B3:DD" display: - platform: sdl - id: sdl_display - update_interval: 1s - auto_clear_enabled: false show_test_card: true dimensions: width: 450 @@ -95,13 +94,7 @@ Linux instructions above. See https://learn.microsoft.com/en-us/windows/wsl/inst Build and run ------------- -The ``esphome`` command will not automatically run the build file on the ``host`` platform. Instead use ``esphome compile yourfile.yaml`` -then locate the executable file called ``program`` within the ``.esphome`` build tree: - -.. code-block:: sh - - `find .esphome -name program` - +The ``esphome run yourfile.yaml`` command will compile and automatically run the build file on the ``host`` platform. See Also -------- diff --git a/components/esp32_ble_tracker.rst b/components/esp32_ble_tracker.rst index 818f8d513c..1474e429a0 100644 --- a/components/esp32_ble_tracker.rst +++ b/components/esp32_ble_tracker.rst @@ -14,7 +14,7 @@ the MAC address of a device and track it using ESPHome. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -26,15 +26,15 @@ the MAC address of a device and track it using ESPHome. binary_sensor: - platform: ble_presence - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "ESP32 BLE Presence Google Home Mini" sensor: - platform: ble_rssi - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "BLE Google Home Mini RSSI value" - platform: xiaomi_hhccjcy01 - mac_address: 94:2B:FF:5C:91:61 + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi MiFlora Temperature" moisture: @@ -46,7 +46,7 @@ the MAC address of a device and track it using ESPHome. battery_level: name: "Xiaomi MiFlora Battery Level" - platform: xiaomi_lywsdcgq - mac_address: 7A:80:8E:19:36:BA + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi MiJia Temperature" humidity: @@ -116,9 +116,9 @@ This automation will be triggered when a Bluetooth advertising is received. A va esp32_ble_tracker: on_ble_advertise: - - mac_address: - - 11:11:11:11:11:11 - - 22:22:22:22:22:22 + - mac_address: + - XX:XX:XX:XX:XX:XX + - XX:XX:XX:XX:XX:XX then: - lambda: |- ESP_LOGD("ble_adv", "New BLE device"); @@ -159,7 +159,7 @@ variable ``x`` of type ``std::vector`` is passed to the automation for esp32_ble_tracker: on_ble_manufacturer_data_advertise: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX manufacturer_id: 0590 then: - lambda: |- @@ -190,7 +190,7 @@ variable ``x`` of type ``std::vector`` is passed to the automation for esp32_ble_tracker: on_ble_service_data_advertise: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX service_uuid: 181A then: - lambda: 'id(ble_sensor).publish_state(x[0]);' diff --git a/components/globals.rst b/components/globals.rst index c1f34bf1a6..6097d95fe7 100644 --- a/components/globals.rst +++ b/components/globals.rst @@ -40,7 +40,6 @@ Configuration variables: ``int`` (for integers), ``float`` (for decimal numbers), ``int[50]`` for an array of 50 integers, etc. - **restore_value** (*Optional*, boolean): Whether to try to restore the state on boot up. Be careful: on the ESP8266, you only have a total of 96 bytes available for this! Defaults to ``no``. - This will use storage in "RTC memory", so it won't survive a power-cycle unless you use the ``esp8266_restore_from_flash`` option to save to flash. See :doc:`esp8266_restore_from_flash ` for details. - **max_restore_data_length** (*Optional*, integer): Only applies to variables of type ``std::string``. ESPHome will allocate enough space for this many characters, plus single character of overhead. Strings longer than this will not be saved. The max value of this variable is 254 characters, and the default is 63 characters. - **initial_value** (*Optional*, string): The value with which to initialize this variable if the state @@ -68,6 +67,14 @@ Configuration variables: - **value** (**Required**, :ref:`templatable `): The value to set the global variable to. +.. note:: + + This action can also be written in lambdas: + + .. code-block:: cpp + + id(my_global_var) = 10; + See Also -------- diff --git a/components/host.rst b/components/host.rst index 38897cd87f..1013bdd30a 100644 --- a/components/host.rst +++ b/components/host.rst @@ -23,17 +23,23 @@ configure wifi - network will automatically be available using the host computer # Example configuration entry host: - mac_address: "98:35:69:ab:f6:79" + mac_address: "06:35:69:ab:f6:79" Configuration variables: ------------------------ - **mac_address** (**Optional**, MAC address): A dummy MAC address to use when communicating with HA. +Build and run +------------- + +The ``esphome run yourfile.yaml`` command will compile and automatically run the build file on the ``host`` platform. + See Also -------- +- :ref:`SDL display ` - :doc:`esphome` - :doc:`/components/time/host` - :ghedit:`Edit` diff --git a/components/http_request.rst b/components/http_request.rst index c483275dea..545d203387 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -88,8 +88,8 @@ This :ref:`action ` sends a GET request. - logger.log: format: 'Response status: %d, Duration: %u ms' args: - - status_code - - duration_ms + - response->status_code + - response->duration_ms # Short form - http_request.get: https://esphome.io @@ -159,7 +159,7 @@ This :ref:`action ` sends a request. This automation will be triggered when the HTTP request is complete. The following variables are available for use in :ref:`lambdas `: -- ``response`` as a ``HttpContainer`` object which contains ``content_length``, ``status_code`` and ``duration_ms``. +- ``response`` as a pointer to ``HttpContainer`` object which contains ``content_length``, ``status_code`` and ``duration_ms``. - ``body`` as ``std::string`` which contains the response body when ``capture_response`` (see :ref:`http_request-get_action`) is set to ``true``. @@ -174,8 +174,8 @@ The following variables are available for use in :ref:`lambdas `: - logger.log: format: "Response status: %d, Duration: %u ms" args: - - response.status_code - - response.duration_ms + - response->status_code + - response->duration_ms .. _http_request-examples: diff --git a/components/index.rst b/components/index.rst index 5ccbbb4b1a..f937b80a23 100644 --- a/components/index.rst +++ b/components/index.rst @@ -6,6 +6,7 @@ Components :glob: binary_sensor/index + canbus/index climate/index cover/index fan/index diff --git a/components/light/index.rst b/components/light/index.rst index 5ccae3afb5..60125554ec 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -43,8 +43,6 @@ Configuration variables: - **flash_transition_length** (*Optional*, :ref:`config-time`): The transition length to use when flash is called. Defaults to ``0s``. - **restore_mode** (*Optional*): Control how the light attempts to restore state on bootup. - For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the - :doc:`esphome section `. - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore. - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst index 7e84843f9b..dc44ccbe1b 100644 --- a/components/microphone/i2s_audio.rst +++ b/components/microphone/i2s_audio.rst @@ -46,6 +46,7 @@ Configuration variables: will be scaled down to 16bit before being forwarded. One of ``16bit`` or ``32bit``. Defaults to ``16bit``. - **use_apll** (*Optional*, boolean): I2S using APLL as main I2S clock, enable it to get accurate clock. Defaults to ``false``. +- **i2s_mode** (*Optional*, enum): The I²S mode to use. One of ``primary`` or ``secondary``. Defaults to ``primary``. - **i2s_audio_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`I²S Audio ` you wish to use for this microphone. - All other options from :ref:`Microphone ` diff --git a/components/output/ble_client.rst b/components/output/ble_client.rst index 3aed40ed78..53c1f4452c 100644 --- a/components/output/ble_client.rst +++ b/components/output/ble_client.rst @@ -12,7 +12,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -22,7 +22,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black output: @@ -39,7 +39,7 @@ Configuration variables: - **service_uuid** (**Required**, UUID): UUID of the service on the device. - **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to write to. - **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. -- **require_response** (*Optional*, boolean): Control whether to require a remote response from the device when writing. +- **require_response** (*Optional*, boolean): Control whether to require a remote response from the device when writing. Whether or not this is required will vary by device. Defaults to ``false`` - All other options from :ref:`Output `. diff --git a/components/sensor/airthings_ble.rst b/components/sensor/airthings_ble.rst index e6fad15e7d..697dd7bad6 100644 --- a/components/sensor/airthings_ble.rst +++ b/components/sensor/airthings_ble.rst @@ -29,7 +29,7 @@ The device will then listen for nearby devices, and display a message like this .. code-block:: text [D][airthings_ble:019]: - Found AirThings device Serial: 123456789 (MAC: 01:02:03:04:05:06) + Found AirThings device Serial: 123456789 (MAC: XX:XX:XX:XX:XX:XX) 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. @@ -75,7 +75,7 @@ Configuration example: name: "WavePlus Battery Voltage" ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: airthings01 esp32_ble_tracker: @@ -110,7 +110,7 @@ Configuration example: name: "WaveMini Battery Voltage" ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: airthingsmini esp32_ble_tracker: diff --git a/components/sensor/am43.rst b/components/sensor/am43.rst index 108c75f5e2..79637cda15 100644 --- a/components/sensor/am43.rst +++ b/components/sensor/am43.rst @@ -25,7 +25,7 @@ to the device over the ESP32's BLE peripheral. esp32_ble_tracker: ble_client: - - mac: AA:BB:CC:DD:EE:FF + - mac: XX:XX:XX:XX:XX:XX id: am43_device sensor: diff --git a/components/sensor/b_parasite.rst b/components/sensor/b_parasite.rst index ce738a98a4..42089f036a 100644 --- a/components/sensor/b_parasite.rst +++ b/components/sensor/b_parasite.rst @@ -24,7 +24,7 @@ The ``b_parasite`` sensor platform tracks b-parasite's Bluetooth Low Energy (BLE sensor: - platform: b_parasite - mac_address: F0:CA:F0:CA:01:01 + mac_address: XX:XX:XX:XX:XX:XX humidity: name: 'b-parasite Air Humidity' temperature: diff --git a/components/sensor/ble_client.rst b/components/sensor/ble_client.rst index 469c810992..963cfefd35 100644 --- a/components/sensor/ble_client.rst +++ b/components/sensor/ble_client.rst @@ -13,7 +13,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -23,7 +23,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black sensor: diff --git a/components/sensor/ble_rssi.rst b/components/sensor/ble_rssi.rst index d169f49f5c..4590f368ce 100644 --- a/components/sensor/ble_rssi.rst +++ b/components/sensor/ble_rssi.rst @@ -13,7 +13,7 @@ instructions for setting up this platform. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -26,7 +26,7 @@ instructions for setting up this platform. sensor: # RSSI based on MAC address - platform: ble_rssi - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "BLE Google Home Mini RSSI value" # RSSI based on Identity Resolving Key (IRK) - platform: ble_rssi diff --git a/components/sensor/inkbird_ibsth1_mini.rst b/components/sensor/inkbird_ibsth1_mini.rst index 530fc4e5a3..ac82f8eff7 100644 --- a/components/sensor/inkbird_ibsth1_mini.rst +++ b/components/sensor/inkbird_ibsth1_mini.rst @@ -38,7 +38,7 @@ many IBS-TH1/TH2 devices at once as you want. sensor: - platform: inkbird_ibsth1_mini - mac_address: 38:81:D7:0A:9C:11 + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Inkbird IBS-TH1 Temperature" external_temperature: @@ -88,21 +88,21 @@ like so: esp32_ble_tracker: -After uploading the ESP32 will immediately try to scan for BLE devices such as the Inkbird IBS-TH1/TH2. +After uploading the ESP32 will immediately try to scan for BLE devices such as the Inkbird IBS-TH1/TH2. When it detects these sensors, it will automatically parse the BLE message print a message like this one: .. code:: - [13:36:43][D][esp32_ble_tracker:544]: Found device 38:81:D7:0A:9C:11 RSSI=-53 + [13:36:43][D][esp32_ble_tracker:544]: Found device XX:XX:XX:XX:XX:XX RSSI=-53 [13:36:43][D][esp32_ble_tracker:565]: Address Type: PUBLIC [13:36:43][D][esp32_ble_tracker:567]: Name: 'sps' Note that it can sometimes take some time for the first BLE broadcast to be received. Please note that address type -should say 'PUBLIC' and the device name should be 'sps', this is how you find the Inkbird IBS-TH1/TH2 among all the +should say 'PUBLIC' and the device name should be 'sps', this is how you find the Inkbird IBS-TH1/TH2 among all the other devices. -Then just copy the address (``38:81:D7:0A:9C:11``) into a new ``sensor.inkbird_ibsth1_mini`` platform +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.inkbird_ibsth1_mini`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/ltr390.rst b/components/sensor/ltr390.rst index 4b6933d75e..d80ed21177 100644 --- a/components/sensor/ltr390.rst +++ b/components/sensor/ltr390.rst @@ -44,6 +44,28 @@ Configuration variables: - **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. +Granular control over gain and resolution +......................................... +By default, the ``gain`` and ``resolution`` parameters set same values for both ALS and UV measurements. In real life scenarios there might be significant +differences in the light intensity and UV index, so it is recommended to use different gain and resolution values for ALS and for UV sensor to avoid saturation. +See the example below, where the gain and resolution are set to different values for ALS and UV sensors.: + +.. code-block:: yaml + + sensor: + - platform: ltr390 + uv: + name: "UV Sensor Counts" + ambient_light: + name: "Light Sensor Counts" + gain: + ambient_light: X9 + uv: X3 + resolution: + ambient_light: 18 + uv: 13 + + Lux and UVI Formulas -------------------- diff --git a/components/sensor/mopeka_pro_check.rst b/components/sensor/mopeka_pro_check.rst index ec003a832a..6647cb0c2c 100644 --- a/components/sensor/mopeka_pro_check.rst +++ b/components/sensor/mopeka_pro_check.rst @@ -9,7 +9,7 @@ Mopeka Pro Check BLE Sensor The ``mopeka_pro_check`` sensor platform lets you track the output of Mopeka Pro Check LP, Mopeka Pro Plus, Mopeka Pro Universal or Lippert Propane Tank Sensors, 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 +will track the tank level, distance, temperature, and battery percentage of a device every time the sensor sends out a BLE broadcast. .. warning:: @@ -21,7 +21,7 @@ device every time the sensor sends out a BLE broadcast. + Lippert Propane Tank Sensor, part number 2021130655 Sensors are calibrated for propane only. - + See :doc:`/components/sensor/mopeka_std_check` for original Mopeka Check sensors support. .. figure:: images/mopeka_pro_check.jpg @@ -32,7 +32,7 @@ device every time the sensor sends out a BLE broadcast. .. figure:: images/mopeka_pro_check_lippert.jpg :align: center - Lippert™ Propane Tank Sensor + Lippert™ Propane Tank Sensor The original Mopeka Check sensors are not supported. @@ -46,7 +46,7 @@ Mopeka Pro Check LP over BLE: sensor: # Example using 20lb vertical propane tank. - platform: mopeka_pro_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: 20LB_V temperature: name: "Propane test temp" @@ -59,7 +59,7 @@ Mopeka Pro Check LP over BLE: # Custom example - user defined empty / full points - platform: mopeka_pro_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: CUSTOM custom_distance_full: 40cm custom_distance_empty: 10mm @@ -137,9 +137,9 @@ For all sensors found the ``mopeka_ble`` component will print a message like thi .. code:: - [20:43:26][I][mopeka_ble:074]: MOPEKA PRO (NRF52) SENSOR FOUND: D3:75:F2:DC:16:91 + [20:43:26][I][mopeka_ble:074]: MOPEKA PRO (NRF52) SENSOR FOUND: XX:XX:XX:XX:XX:XX -Then just copy the address (``D3:75:F2:DC:16:91``) into a new +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.mopeka_pro_check`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/mopeka_std_check.rst b/components/sensor/mopeka_std_check.rst index e9f7f6f6de..84c6c594e4 100644 --- a/components/sensor/mopeka_std_check.rst +++ b/components/sensor/mopeka_std_check.rst @@ -7,9 +7,9 @@ Mopeka Standard Check BLE Sensor :keywords: Mopeka, Mopeka Standard Check, Mopeka Std Check, BLE, Bluetooth The ``mopeka_std_check`` sensor platform lets you track the output of Mopeka -Standard 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 Standard Check LP BLE +Standard 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 Standard Check LP BLE device every time the sensor sends out a BLE broadcast. .. warning:: @@ -29,7 +29,7 @@ device every time the sensor sends out a BLE broadcast. sensor: # Example using 11kg 100% propane tank. - platform: mopeka_std_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: Europe_11kg temperature: name: "Propane test temp" @@ -42,7 +42,7 @@ device every time the sensor sends out a BLE broadcast. # Custom example - user defined empty / full points and 80% butane and 20% propane. - platform: mopeka_std_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: CUSTOM custom_distance_full: 40cm custom_distance_empty: 32mm @@ -125,15 +125,15 @@ and the ``mopeka_ble`` component like so: mopeka_ble: -After uploading, the ESP32 will immediately try to scan for BLE devices. For Mopeka Standard devices you must press and hold the green sync button for it to be identified. +After uploading, the ESP32 will immediately try to scan for BLE devices. For Mopeka Standard devices you must press and hold the green sync button for it to be identified. Or alternativly set the configuration flag ``show_sensors_without_sync: true`` to see all devices. For all sensors found the ``mopeka_ble`` component will print a message like this one: .. code:: - [20:43:26][I][mopeka_ble:056]: MOPEKA STD (CC2540) SENSOR FOUND: D3:75:F2:DC:16:91 + [20:43:26][I][mopeka_ble:056]: MOPEKA STD (CC2540) SENSOR FOUND: XX:XX:XX:XX:XX:XX -Then just copy the address (``D3:75:F2:DC:16:91``) into a new +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.mopeka_std_check`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/radon_eye_ble.rst b/components/sensor/radon_eye_ble.rst index cbf7356661..eea0374b84 100644 --- a/components/sensor/radon_eye_ble.rst +++ b/components/sensor/radon_eye_ble.rst @@ -29,7 +29,7 @@ The device will then listen for nearby devices, and display a message like this .. code-block:: text [D][radon_eye_ble:017]: - Found Radon Eye RD200 device Name: FR:R20:SN1234 (MAC: 01:02:03:04:05:06) + Found Radon Eye RD200 device Name: FR:R20:SN1234 (MAC: XX:XX:XX:XX:XX:XX) Once the device is found, remove the ``radon_eye_ble`` device tracker from your configuration and take note of the device MAC address, and use it when configuring a sensor below. @@ -61,7 +61,7 @@ Configuration example: esp32_ble_tracker: ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: radon_eye_ble_id sensor: @@ -80,7 +80,7 @@ Here is an example to use pCi/L (to match the value on the device display): esp32_ble_tracker: ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: radon_eye_ble_id sensor: @@ -99,4 +99,3 @@ Here is an example to use pCi/L (to match the value on the device display): accuracy_decimals: 2 filters: - lambda: return x / 37; - diff --git a/components/sensor/rotary_encoder.rst b/components/sensor/rotary_encoder.rst index 476b4319c6..c5c9aa5e04 100644 --- a/components/sensor/rotary_encoder.rst +++ b/components/sensor/rotary_encoder.rst @@ -76,8 +76,6 @@ Configuration variables: "unknown" value at first. If you set this option to true, the value is published once after boot and when it changes. Defaults to ``false``. - **restore_mode** (*Optional*): Control how the Rotary Encoder attempts to restore state on bootup. - For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the - :doc:`esphome section `. - ``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). diff --git a/components/sensor/ruuvitag.rst b/components/sensor/ruuvitag.rst index b38f807408..b69d7a3dd4 100644 --- a/components/sensor/ruuvitag.rst +++ b/components/sensor/ruuvitag.rst @@ -30,7 +30,7 @@ movement count and measurement sequence number are also tracked. sensor: - platform: ruuvitag - mac_address: FF:56:D3:2F:7D:E8 + mac_address: XX:XX:XX:XX:XX:XX humidity: name: "RuuviTag Humidity" temperature: @@ -167,11 +167,11 @@ print a message like this one: .. code:: - Got ruuvi RuuviTag (FF:56:D3:2F:7D:E8): Humidity: 67.5%, Temperature: 22.97°C, + Got ruuvi RuuviTag (XX:XX:XX:XX:XX:XX): Humidity: 67.5%, Temperature: 22.97°C, Pressure: 977.09hPa, Acceleration X: 0.005G, Acceleration Y: 0.017G, Acceleration Z: 1.066G, Battery Voltage: 3.223V -Then just copy the address (``FF:56:D3:2F:7D:E8``) into a new +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.ruuvitag`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/xiaomi_ble.rst b/components/sensor/xiaomi_ble.rst index cee4a1a6af..cf88a30bf3 100644 --- a/components/sensor/xiaomi_ble.rst +++ b/components/sensor/xiaomi_ble.rst @@ -32,7 +32,7 @@ Configuration example: sensor: - platform: xiaomi_hhccjcy01 - mac_address: '94:2B:FF:5C:91:61' + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi HHCCJCY01 Temperature" moisture: @@ -64,7 +64,7 @@ Configuration example: sensor: - platform: xiaomi_gcls002 - mac_address: "94:2B:FF:5C:91:61" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "GCLS02 Temperature" moisture: @@ -89,7 +89,7 @@ Configuration example: sensor: - platform: xiaomi_hhccpot002 - mac_address: "94:2B:FF:5C:91:61" + mac_address: XX:XX:XX:XX:XX:XX moisture: name: "HHCCPOT002 Moisture" conductivity: @@ -110,7 +110,7 @@ Configuration example: sensor: - platform: xiaomi_lywsdcgq - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "LYWSDCGQ Temperature" humidity: @@ -135,7 +135,7 @@ Configuration example: sensor: - platform: xiaomi_lywsd02 - mac_address: "3F:5B:7D:82:58:4E" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "LYWSD02 Temperature" humidity: @@ -160,7 +160,7 @@ Configuration example: sensor: - platform: xiaomi_cgg1 - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "CGG1 Temperature" humidity: @@ -168,7 +168,7 @@ Configuration example: battery_level: name: "CGG1 Battery Level" - platform: xiaomi_cgg1 - mac_address: "7A:80:8E:28:39:CD" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "00112233445566778899aabbccddeeff" temperature: name: "CGG1 (New) Temperature" @@ -200,7 +200,7 @@ Configuration example for Xiaomi stock firmware or ATC MiThermometer firmware se sensor: - platform: xiaomi_lywsd03mmc - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "eef418daf699a0c188f3bfd17e4565d9" temperature: name: "LYWSD03MMC Temperature" @@ -215,7 +215,7 @@ Configuration example for PVVX MiThermometer firmware set to "Custom" advertisem sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: @@ -233,7 +233,7 @@ Configuration example for ATC MiThermometer firmware set to "Custom" advertiseme sensor: - platform: atc_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "ATC Temperature" humidity: @@ -263,7 +263,7 @@ Configuration example: sensor: - platform: xiaomi_mhoc303 - mac_address: "E7:50:59:32:A0:1C" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "MHO-C303 Climate Temperature" humidity: @@ -296,7 +296,7 @@ Configuration example for Xiaomi stock firmware: sensor: - platform: xiaomi_mhoc401 - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "eef418daf699a0c188f3bfd17e4565d9" temperature: name: "MHOC401 Temperature" @@ -311,7 +311,7 @@ Configuration example for PVVX MiThermometer firmware set to "Custom" advertisem sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: @@ -337,7 +337,7 @@ Configuration example: sensor: - platform: xiaomi_cgd1 - mac_address: "A4:C1:38:8C:34:B7" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "fe39106baeedb7c801e3d63c4396f97e" temperature: name: "CGD1 Temperature" @@ -362,7 +362,7 @@ Configuration example: sensor: - platform: xiaomi_cgdk2 - mac_address: "58:2D:34:11:34:B7" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "fe39106baeedb7c801e3d63c4396f97e" temperature: name: "CGDK2 Temperature" @@ -386,7 +386,7 @@ Configuration example: sensor: - platform: xiaomi_jqjcy01ym - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "JQJCY01YM Temperature" humidity: @@ -413,7 +413,7 @@ Configuration example: binary_sensor: - platform: xiaomi_wx08zm - mac_address: "74:a3:4a:b5:07:34" + mac_address: XX:XX:XX:XX:XX:XX tablet: name: "WX08ZM Mosquito Tablet" battery_level: @@ -437,7 +437,7 @@ Configuration example: binary_sensor: - platform: xiaomi_mue4094rt name: "MUE4094RT Night Light" - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX timeout: "5s" MJYD02YL-A @@ -458,7 +458,7 @@ Configuration example: binary_sensor: - platform: xiaomi_mjyd02yla name: "MJYD02YL-A Night Light" - mac_address: "50:EC:50:CD:32:02" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "48403ebe2d385db8d0c187f81e62cb64" idle_time: name: "MJYD02YL-A Idle Time" @@ -485,7 +485,7 @@ Configuration example: binary_sensor: - platform: xiaomi_cgpr1 name: "CGPR1 Motion detector" - mac_address: 58:2D:34:60:32:A2 + mac_address: XX:XX:XX:XX:XX:XX bindkey: "ff1ae526b23b4aebeadcaaad86f59055" idle_time: name: "CGPR1 Idle Time" @@ -510,7 +510,7 @@ Configuration example: xiaomi_rtcgq02lm: - id: motion_one - mac_address: 01:23:45:67:89:AB + mac_address: XX:XX:XX:XX:XX:XX bindkey: fe39106baeedb7c801e3d63c4396f97e binary_sensor: @@ -567,11 +567,11 @@ After uploading, the ESP32 will immediately try to scan for BLE devices. When it .. code:: - Found device A4:C1:38:4E:16:78 RSSI=-78 + Found device XX:XX:XX:XX:XX:XX RSSI=-78 Address Type: PUBLIC Name: 'LYWSD03MMC' -It can sometimes take some time for the first BLE broadcast to be received. Once the device has been found, copy the address ``A4:C1:38:4E:16:78`` into a new platform entry like shown in the example configurations. +It can sometimes take some time for the first BLE broadcast to be received. Once the device has been found, copy the address ``XX:XX:XX:XX:XX:XX`` into a new platform entry like shown in the example configurations. .. _obtaining_the_bindkey: @@ -621,7 +621,7 @@ Another option is to use a SSL packet sniffer. It can be setup on either an Andr packet: POST /app/device/bltbind - "data" = "{"did":"blt.3.129q4nasgeg00","token":"20c665a7ff82a5bfb5eefc36","props":[{"type":"prop","key":"bind_key","value":"cfc7cc892f4e32f7a733086cf3443cb0"}, {"type":"prop","key":"smac","value":"A4:C1:38:8C:34:B7"}]}" + "data" = "{"did":"blt.3.129q4nasgeg00","token":"20c665a7ff82a5bfb5eefc36","props":[{"type":"prop","key":"bind_key","value":"cfc7cc892f4e32f7a733086cf3443cb0"}, {"type":"prop","key":"smac","value":XX:XX:XX:XX:XX:XX}]}" The ``bind_key`` is the 32 digits "value" item in the above output which needs to be inserted into the config file. diff --git a/components/sensor/xiaomi_hhccjcy10.rst b/components/sensor/xiaomi_hhccjcy10.rst index d70aad5e8f..54328bc17f 100644 --- a/components/sensor/xiaomi_hhccjcy10.rst +++ b/components/sensor/xiaomi_hhccjcy10.rst @@ -16,7 +16,7 @@ MiFlora, tuya (pink) version, measures temperature, moisture, ambient light and sensor: - platform: xiaomi_hhccjcy10 - mac_address: '94:2B:FF:5C:91:61' + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi HHCCJCY10 Temperature" moisture: diff --git a/components/sensor/xiaomi_miscale.rst b/components/sensor/xiaomi_miscale.rst index c054788d98..61dbba5aba 100644 --- a/components/sensor/xiaomi_miscale.rst +++ b/components/sensor/xiaomi_miscale.rst @@ -26,7 +26,7 @@ Miscale (left) measures weight only. Miscale2 (right) measures weight and impeda sensor: - platform: xiaomi_miscale - mac_address: '5C:CA:D3:70:D4:A2' + mac_address: XX:XX:XX:XX:XX:XX weight: name: "Xiaomi Mi Scale Weight" impedance: @@ -59,7 +59,7 @@ You have to replace the numbers in the lambdas to determine your weight which is sensor: - platform: xiaomi_miscale - mac_address: '5C:CA:D3:70:D4:A2' + mac_address: XX:XX:XX:XX:XX:XX weight: name: "Xiaomi Mi Scale Weight" id: weight_miscale diff --git a/components/switch/ble_client.rst b/components/switch/ble_client.rst index 96b3599b9c..13ab0cabf2 100644 --- a/components/switch/ble_client.rst +++ b/components/switch/ble_client.rst @@ -13,7 +13,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -23,7 +23,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black switch: diff --git a/components/text_sensor/ble_client.rst b/components/text_sensor/ble_client.rst index f3ba0cd37e..1ea20be7cd 100644 --- a/components/text_sensor/ble_client.rst +++ b/components/text_sensor/ble_client.rst @@ -16,7 +16,7 @@ For more information on BLE services and characteristics, see esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black text_sensor: diff --git a/components/text_sensor/ble_scanner.rst b/components/text_sensor/ble_scanner.rst index 6b4c0873e4..c577d4d08e 100644 --- a/components/text_sensor/ble_scanner.rst +++ b/components/text_sensor/ble_scanner.rst @@ -19,7 +19,7 @@ the data in JSON format. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -39,7 +39,7 @@ Example json log: { "timestamp":1578254525, - "address":"D7:E7:E7:66:DD:33", + "address": "XX:XX:XX:XX:XX:XX", "rssi":"-80", "name":"MI Band 2" } diff --git a/guides/supporters.rst b/guides/supporters.rst index b12964913d..9512a2d9c7 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -47,6 +47,7 @@ Contributors - `Attila Darazs (@adarazs) `__ - `ADeadPixel (@ADeadPixel) `__ - `adezerega (@adezerega) `__ +- `Eugen (@Adminius) `__ - `Andrea Donno (@adonno) `__ - `Adrian Cuzman (@adriancuzman) `__ - `Adrian Fretwell (@AdrianFretwell) `__ @@ -940,6 +941,7 @@ Contributors - `Kenny Stier (@KennyStier) `__ - `Robert Kiss (@kepten) `__ - `kernelpanic85 (@kernelpanic85) `__ +- `kevdliu (@kevdliu) `__ - `Kevin O'Rourke (@kevinior) `__ - `Kevin Reilly (@kevireilly) `__ - `kevlar10 (@kevlar10) `__ @@ -1313,6 +1315,7 @@ Contributors - `Chris Nussbaum (@nuttytree) `__ - `Michał Sochoń (@nvtkaszpir) `__ - `Nathaniel Wesley Filardo (@nwf) `__ +- `Olivier ARCHER (@oarcher) `__ - `obrain17 (@obrain17) `__ - `Ockert Marais (@OckertM) `__ - `Dave Walker (@oddsockmachine) `__ @@ -1759,12 +1762,14 @@ Contributors - `Tom Price (@tomtom5152) `__ - `Anthony Bourguignon (@Toniob) `__ - `tony (@tony-fav) `__ +- `Tomi Junnila (@topeju) `__ - `David Kiliani (@torfbolt) `__ - `Aleksandra M (@tort32) `__ - `Torwag (@torwag) `__ - `Teemu Simola (@tpssim) `__ - `tracestep (@tracestep) `__ - `Trent Houliston (@TrentHouliston) `__ +- `Trevor Schirmer (@TrevorSchirmer) `__ - `Felix Eckhofer (@tribut) `__ - `Trick van Staveren (@trickv) `__ - `TripitakaBC (@TripitakaBC) `__ @@ -1778,6 +1783,7 @@ Contributors - `Trevor North (@trvrnrth) `__ - `Trygve Laugstøl (@trygvis) `__ - `Gediminas Šaltenis (@trylika) `__ +- `ttaborda (@ttaborda) `__ - `Tuan (@tuanpmt) `__ - `tubalainen (@tubalainen) `__ - `tube0013 (@tube0013) `__ @@ -1881,6 +1887,7 @@ Contributors - `Jevgeni Kiski (@yozik04) `__ - `YuanL.Lee (@yuanl) `__ - `Yuval Aboulafia (@yuvalabou) `__ +- `Z3LIFF (@z3liff) `__ - `ZabojnikM (@ZabojnikM) `__ - `Björn Stenberg (@zagor) `__ - `zaluthar (@zaluthar) `__ @@ -1903,4 +1910,4 @@ Contributors - `Christian Zufferey (@zuzu59) `__ - `Zynth-dev (@Zynth-dev) `__ -*This page was last updated July 11, 2024.* +*This page was last updated July 17, 2024.* diff --git a/images/mcp2515.svg b/images/mcp2515.svg new file mode 100644 index 0000000000..a656b7ef19 --- /dev/null +++ b/images/mcp2515.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 88edddeffd..970ace46e9 100644 --- a/index.rst +++ b/index.rst @@ -243,7 +243,7 @@ Hardware Peripheral Interfaces/Busses .. imgtable:: - CAN Bus, components/canbus, canbus.svg + CAN Bus, components/canbus/index, canbus.svg I²C Bus, components/i2c, i2c.svg I²S Audio, components/i2s_audio, i2s_audio.svg SPI Bus, components/spi, spi.svg @@ -268,6 +268,15 @@ I/O Expanders/Multiplexers WeiKai SPI/I²C UART/IO Expander, components/weikai, wk2168.jpg XL9535, components/xl9535, xl9535.svg +CAN Bus +------- + +.. imgtable:: + + CAN Bus, components/canbus/index, canbus.svg + ESP32 CAN, components/canbus/esp32_can, esp32.svg + MCP2515, components/canbus/mcp2515, mcp2515.svg + Sensor Components -----------------