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

Merge pull request #3317 from esphome/bump-2023.10.5 

2023.10.5
This commit is contained in:
Jesse Hills 2023-11-01 14:07:59 +13:00 committed by GitHub
parent 359f3595fa 28f1fed3dc
commit 79b90216d4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 143 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doxygen
View File

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

2
Makefile
View File

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

2
_static/version
View File

@ -1 +1 @@
2023.10.4
2023.10.5

8
changelog/2023.10.0.rst
View File

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

195
components/api.rst
View File

@ -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 <config-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 <config-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 <automation>`.
.. 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 <config-lambda>` 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 <automation>`.
@ -97,7 +134,8 @@ calls straight from ESPHome :ref:`Automations <automation>`.
my_variable: |-
return id(my_sensor).state;
Configuration options:
Configuration variables:
````````````````````````
- **service** (**Required**, string): The Home Assistant `Service <https://www.home-assistant.io/docs/scripts/service-calls/>`__
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 <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.tag_scanned: some-tag
Configuration variables:
````````````````````````
- **tag** (**Required**, :ref:`templatable <config-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 <config-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<bool>``
- ... - Same for other types.
.. _api-connected_condition:
``api.connected`` Condition
---------------------------
This :ref:`Condition <config-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 <automation>`.
.. 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 <config-lambda>` 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 <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.tag_scanned: some-tag
Configuration options:
- **tag** (**Required**, :ref:`templatable <config-templatable>`, string): The id of the scanned tag
See Also
--------

5
components/voice_assistant.rst
View File

@ -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 <automation>`): An automation to perform
when Home Assistant has connected and is waiting for Voice Assistant commands.
- **on_client_disconnected** (*Optional*, :ref:`Automation <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.

2
conf.py
View File

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

2
guides/automations.rst
View File

@ -323,7 +323,7 @@ if it fails to connect to the network without a reboot)
All Triggers
------------
- :ref:`api.services <api-services>`
- :ref:`api.services <api-services>` / :ref:`api.on_client_connected <api-on_client_connected_trigger>` / :ref:`api.on_client_disconnected <api-on_client_disconnected_trigger>`
- :ref:`sensor.on_value <sensor-on_value>` / :ref:`sensor.on_raw_value <sensor-on_raw_value>` / :ref:`sensor.on_value_range <sensor-on_value_range>`
- :ref:`binary_sensor.on_press <binary_sensor-on_press>` / :ref:`binary_sensor.on_release <binary_sensor-on_release>` /
:ref:`binary_sensor.on_state <binary_sensor-on_state>`

3
guides/supporters.rst
View File

@ -601,6 +601,7 @@ Contributors
- `jakehdk (@jakehdk) <https://github.com/jakehdk>`__
- `Jake Shirley (@JakeShirley) <https://github.com/JakeShirley>`__
- `Jakob Reiter (@jakommo) <https://github.com/jakommo>`__
- `jakub-medrzak (@jakub-medrzak) <https://github.com/jakub-medrzak>`__
- `James Braid (@jamesbraid) <https://github.com/jamesbraid>`__
- `James Duke (@jamesduke) <https://github.com/jamesduke>`__
- `James Gao (@jamesgao) <https://github.com/jamesgao>`__
@ -1250,4 +1251,4 @@ Contributors
- `Zsolt Zsiros (@ZsZs73) <https://github.com/ZsZs73>`__
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
*This page was last updated October 30, 2023.*
*This page was last updated November 1, 2023.*