diff --git a/Doxygen b/Doxygen index 69e1f3544..db752b75f 100644 --- a/Doxygen +++ b/Doxygen @@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 2023.10.4 +PROJECT_NUMBER = 2023.10.5 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index 1b3ee9f05..3a48e4894 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2023.10.4 +ESPHOME_REF = 2023.10.5 .PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify diff --git a/_static/version b/_static/version index bf2028ad5..cee421a96 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2023.10.4 \ No newline at end of file +2023.10.5 \ No newline at end of file diff --git a/changelog/2023.10.0.rst b/changelog/2023.10.0.rst index c5dc033a8..4505fb362 100644 --- a/changelog/2023.10.0.rst +++ b/changelog/2023.10.0.rst @@ -66,6 +66,14 @@ Release 2023.10.4 - October 30 - Fix bug when requesting italic gfonts :esphomepr:`5623` by :ghuser:`dewet22` - Handle enum type in tuya text_sensor :esphomepr:`5626` by :ghuser:`jesserockz` +Release 2023.10.5 - November 1 +------------------------------ + +- Add connection triggers to api :esphomepr:`5628` by :ghuser:`jesserockz` +- Add on_client_connected and disconnected to voice assistant :esphomepr:`5629` by :ghuser:`jesserockz` +- Ensure that all uses of strncpy in wifi component are safe. :esphomepr:`5636` by :ghuser:`kpfleming` +- Remove some explicit IPAddress casts :esphomepr:`5639` by :ghuser:`HeMan` + Breaking changes ---------------- diff --git a/components/api.rst b/components/api.rst index 7df6f8d6c..73d47db7a 100644 --- a/components/api.rst +++ b/components/api.rst @@ -66,13 +66,50 @@ Configuration variables: the ESP is connected to the network, when in fact it is not - only a full reboot fixes it. Can be disabled by setting this to ``0s``. Defaults to ``15min``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults to no password. - It is recommended to use the ``encryption`` -> ``key`` above instead of the the ``password``. +- **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults + to no password. It is recommended to use the ``encryption`` -> ``key`` above instead of the the ``password``. +- **on_client_connected** (*Optional*, :ref:`Action `): An automation to perform when a client + connects to the API. See :ref:`api-on_client_connected_trigger`. +- **on_client_disconnected** (*Optional*, :ref:`Action `): An automation to perform when a client + disconnects from the API. See :ref:`api-on_client_disconnected_trigger`. + +.. _api-actions: + +Actions +------- + +.. _api-homeassistant_event_action: + +``homeassistant.event`` Action +****************************** + +When using the native API with Home Assistant, you can create events in the Home Assistant event bus +straight from ESPHome :ref:`Automations `. + +.. code-block:: yaml + + # In some trigger + on_...: + # Simple + - homeassistant.event: + event: esphome.button_pressed + data: + message: Button was pressed + +Configuration variables: +```````````````````````` + +- **event** (**Required**, string): The event to create - must begin with ``esphome.`` +- **data** (*Optional*, mapping): Optional *static* data to pass along with the event. +- **data_template** (*Optional*, mapping): Optional template data to pass along with the event. + This is evaluated on the Home Assistant side with Home Assistant's templating engine. +- **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``. + Values are :ref:`lambdas ` and will be evaluated before sending the request. .. _api-homeassistant_service_action: ``homeassistant.service`` Action --------------------------------- +******************************** When using the native API with Home Assistant, you can create Home Assistant service calls straight from ESPHome :ref:`Automations `. @@ -97,7 +134,8 @@ calls straight from ESPHome :ref:`Automations `. my_variable: |- return id(my_sensor).state; -Configuration options: +Configuration variables: +```````````````````````` - **service** (**Required**, string): The Home Assistant `Service `__ to call. @@ -126,7 +164,7 @@ the parameters in plain format. - '{{ green }}' - '{{ blue }}' -Then in ESPHome +Then, in ESPHome: .. code-block:: yaml @@ -140,6 +178,86 @@ Then in ESPHome green: '199' blue: '71' +.. _api-homeassistant_tag_scanned_action: + +``homeassistant.tag_scanned`` Action +************************************ + +When using the native API with Home Assistant, you can push tag_scanned to Home Assistant +straight from ESPHome :ref:`Automations `. + +.. code-block:: yaml + + # In some trigger + on_...: + # Simple + - homeassistant.tag_scanned: some-tag + +Configuration variables: +```````````````````````` + +- **tag** (**Required**, :ref:`templatable `, string): The id of the scanned tag + +Triggers +-------- + +.. _api-on_client_connected_trigger: + +``on_client_connected`` Trigger +******************************* + +This trigger is activated each time a client connects to the API. Two variables of +type ``std::string`` are available for use by actions called from within this trigger: + +- ``client_address``: the IP address of the client that connected +- ``client_info``: the name of the client that connected + +.. code-block:: yaml + + api: + # ... + on_client_connected: + - logger.log: + format: "Client %s connected to API with IP %s" + args: ["client_info.c_str()", "client_address.c_str()"] + + +.. _api-on_client_disconnected_trigger: + +``on_client_disconnected`` Trigger +********************************** + +This trigger is activated each time the API disconnects from the API. Two variables of +type ``std::string`` are available for use by actions called from within this trigger: + +- ``client_address``: the IP address of the client that disconnected +- ``client_info``: the name of the client that disconnected + +.. code-block:: yaml + + api: + # ... + on_client_disconnected: + - logger.log: "API client disconnected!" + +.. _api-connected_condition: + +``api.connected`` Condition +--------------------------- + +This :ref:`Condition ` checks if at least one client is connected to the ESPHome +native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output +if logs are shown remotely. + +.. code-block:: yaml + + on_...: + if: + condition: + api.connected: + then: + - logger.log: API is connected! + .. _api-services: User-defined Services @@ -208,25 +326,6 @@ Each of these also exist in array form: - bool[]: An array of boolean values. C++ type: ``std::vector`` - ... - Same for other types. -.. _api-connected_condition: - -``api.connected`` Condition ---------------------------- - -This :ref:`Condition ` checks if at least one client is connected to the ESPHome -native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output -if logs are shown remotely. - -.. code-block:: yaml - - on_...: - if: - condition: - api.connected: - then: - - logger.log: API is connected! - - Advantages over MQTT -------------------- @@ -245,54 +344,6 @@ never be removed. Features of native API (vs. MQTT): - **Low Latency:** The native API is optimized for very low latency, usually this is only a couple of milliseconds and far less than can be noticed by the eye. - -.. _api-homeassistant_event_action: - -``homeassistant.event`` Action ------------------------------- - -When using the native API with Home Assistant, you can create events in the Home Assistant event bus -straight from ESPHome :ref:`Automations `. - -.. code-block:: yaml - - # In some trigger - on_...: - # Simple - - homeassistant.event: - event: esphome.button_pressed - data: - message: Button was pressed - -Configuration options: - -- **event** (**Required**, string): The event to create - must begin with ``esphome.`` -- **data** (*Optional*, mapping): Optional *static* data to pass along with the event. -- **data_template** (*Optional*, mapping): Optional template data to pass along with the event. - This is evaluated on the Home Assistant side with Home Assistant's templating engine. -- **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``. - Values are :ref:`lambdas ` and will be evaluated before sending the request. - - -.. _api-homeassistant_tag_scanned_action: - -``homeassistant.tag_scanned`` Action ------------------------------------- - -When using the native API with Home Assistant, you can push tag_scanned to Home Assistant -straight from ESPHome :ref:`Automations `. - -.. code-block:: yaml - - # In some trigger - on_...: - # Simple - - homeassistant.tag_scanned: some-tag - -Configuration options: - -- **tag** (**Required**, :ref:`templatable `, string): The id of the scanned tag - See Also -------- diff --git a/components/voice_assistant.rst b/components/voice_assistant.rst index 0a5fa2f54..c6cbd523a 100644 --- a/components/voice_assistant.rst +++ b/components/voice_assistant.rst @@ -58,6 +58,11 @@ Configuration: when the voice assistant has encountered an error. The error code and message are available to automations as the variables ``code`` and ``message``. +- **on_client_connected** (*Optional*, :ref:`Automation `): An automation to perform + when Home Assistant has connected and is waiting for Voice Assistant commands. +- **on_client_disconnected** (*Optional*, :ref:`Automation `): An automation to perform + when Home Assistant disconnects from the Voice Assistant. + - **noise_suppression_level** (*Optional*, integer): The noise suppression level to apply to the assist pipeline. Between 0 and 4 inclusive. Defaults to 0 (disabled). - **auto_gain** (*Optional*, dBFS): Auto gain level to apply to the assist pipeline. diff --git a/conf.py b/conf.py index 0950de8f5..c1563bcc4 100644 --- a/conf.py +++ b/conf.py @@ -69,7 +69,7 @@ author = "ESPHome" # The short X.Y version. version = "2023.10" # The full version, including alpha/beta/rc tags. -release = "2023.10.4" +release = "2023.10.5" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/automations.rst b/guides/automations.rst index 8e585928e..eb01fb168 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -323,7 +323,7 @@ if it fails to connect to the network without a reboot) All Triggers ------------ -- :ref:`api.services ` +- :ref:`api.services ` / :ref:`api.on_client_connected ` / :ref:`api.on_client_disconnected ` - :ref:`sensor.on_value ` / :ref:`sensor.on_raw_value ` / :ref:`sensor.on_value_range ` - :ref:`binary_sensor.on_press ` / :ref:`binary_sensor.on_release ` / :ref:`binary_sensor.on_state ` diff --git a/guides/supporters.rst b/guides/supporters.rst index 390f050fe..7d152b67f 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -601,6 +601,7 @@ Contributors - `jakehdk (@jakehdk) `__ - `Jake Shirley (@JakeShirley) `__ - `Jakob Reiter (@jakommo) `__ +- `jakub-medrzak (@jakub-medrzak) `__ - `James Braid (@jamesbraid) `__ - `James Duke (@jamesduke) `__ - `James Gao (@jamesgao) `__ @@ -1250,4 +1251,4 @@ Contributors - `Zsolt Zsiros (@ZsZs73) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated October 30, 2023.* +*This page was last updated November 1, 2023.*