commit
79b90216d4
2
Doxygen
2
Doxygen
|
@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
|
||||||
# could be handy for archiving the generated documentation or if some version
|
# could be handy for archiving the generated documentation or if some version
|
||||||
# control system is used.
|
# 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
|
# 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
|
# for a project that appears at the top of each page and should give viewer a
|
||||||
|
|
2
Makefile
2
Makefile
|
@ -1,5 +1,5 @@
|
||||||
ESPHOME_PATH = ../esphome
|
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
|
.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
|
||||||
|
|
||||||
|
|
|
@ -1 +1 @@
|
||||||
2023.10.4
|
2023.10.5
|
|
@ -66,6 +66,14 @@ Release 2023.10.4 - October 30
|
||||||
- Fix bug when requesting italic gfonts :esphomepr:`5623` by :ghuser:`dewet22`
|
- Fix bug when requesting italic gfonts :esphomepr:`5623` by :ghuser:`dewet22`
|
||||||
- Handle enum type in tuya text_sensor :esphomepr:`5626` by :ghuser:`jesserockz`
|
- 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
|
Breaking changes
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
|
|
|
@ -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.
|
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``.
|
Can be disabled by setting this to ``0s``. Defaults to ``15min``.
|
||||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
- **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.
|
- **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults
|
||||||
It is recommended to use the ``encryption`` -> ``key`` above instead of the the ``password``.
|
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:
|
.. _api-homeassistant_service_action:
|
||||||
|
|
||||||
``homeassistant.service`` Action
|
``homeassistant.service`` Action
|
||||||
--------------------------------
|
********************************
|
||||||
|
|
||||||
When using the native API with Home Assistant, you can create Home Assistant service
|
When using the native API with Home Assistant, you can create Home Assistant service
|
||||||
calls straight from ESPHome :ref:`Automations <automation>`.
|
calls straight from ESPHome :ref:`Automations <automation>`.
|
||||||
|
@ -97,7 +134,8 @@ calls straight from ESPHome :ref:`Automations <automation>`.
|
||||||
my_variable: |-
|
my_variable: |-
|
||||||
return id(my_sensor).state;
|
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/>`__
|
- **service** (**Required**, string): The Home Assistant `Service <https://www.home-assistant.io/docs/scripts/service-calls/>`__
|
||||||
to call.
|
to call.
|
||||||
|
@ -126,7 +164,7 @@ the parameters in plain format.
|
||||||
- '{{ green }}'
|
- '{{ green }}'
|
||||||
- '{{ blue }}'
|
- '{{ blue }}'
|
||||||
|
|
||||||
Then in ESPHome
|
Then, in ESPHome:
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
@ -140,6 +178,86 @@ Then in ESPHome
|
||||||
green: '199'
|
green: '199'
|
||||||
blue: '71'
|
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:
|
.. _api-services:
|
||||||
|
|
||||||
User-defined 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>``
|
- bool[]: An array of boolean values. C++ type: ``std::vector<bool>``
|
||||||
- ... - Same for other types.
|
- ... - 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
|
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
|
- **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.
|
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
|
See Also
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|
|
@ -58,6 +58,11 @@ Configuration:
|
||||||
when the voice assistant has encountered an error. The error code and message are available to
|
when the voice assistant has encountered an error. The error code and message are available to
|
||||||
automations as the variables ``code`` and ``message``.
|
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.
|
- **noise_suppression_level** (*Optional*, integer): The noise suppression level to apply to the assist pipeline.
|
||||||
Between 0 and 4 inclusive. Defaults to 0 (disabled).
|
Between 0 and 4 inclusive. Defaults to 0 (disabled).
|
||||||
- **auto_gain** (*Optional*, dBFS): Auto gain level to apply to the assist pipeline.
|
- **auto_gain** (*Optional*, dBFS): Auto gain level to apply to the assist pipeline.
|
||||||
|
|
2
conf.py
2
conf.py
|
@ -69,7 +69,7 @@ author = "ESPHome"
|
||||||
# The short X.Y version.
|
# The short X.Y version.
|
||||||
version = "2023.10"
|
version = "2023.10"
|
||||||
# The full version, including alpha/beta/rc tags.
|
# 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
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
# for a list of supported languages.
|
# for a list of supported languages.
|
||||||
|
|
|
@ -323,7 +323,7 @@ if it fails to connect to the network without a reboot)
|
||||||
All Triggers
|
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:`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_press <binary_sensor-on_press>` / :ref:`binary_sensor.on_release <binary_sensor-on_release>` /
|
||||||
:ref:`binary_sensor.on_state <binary_sensor-on_state>`
|
:ref:`binary_sensor.on_state <binary_sensor-on_state>`
|
||||||
|
|
|
@ -601,6 +601,7 @@ Contributors
|
||||||
- `jakehdk (@jakehdk) <https://github.com/jakehdk>`__
|
- `jakehdk (@jakehdk) <https://github.com/jakehdk>`__
|
||||||
- `Jake Shirley (@JakeShirley) <https://github.com/JakeShirley>`__
|
- `Jake Shirley (@JakeShirley) <https://github.com/JakeShirley>`__
|
||||||
- `Jakob Reiter (@jakommo) <https://github.com/jakommo>`__
|
- `Jakob Reiter (@jakommo) <https://github.com/jakommo>`__
|
||||||
|
- `jakub-medrzak (@jakub-medrzak) <https://github.com/jakub-medrzak>`__
|
||||||
- `James Braid (@jamesbraid) <https://github.com/jamesbraid>`__
|
- `James Braid (@jamesbraid) <https://github.com/jamesbraid>`__
|
||||||
- `James Duke (@jamesduke) <https://github.com/jamesduke>`__
|
- `James Duke (@jamesduke) <https://github.com/jamesduke>`__
|
||||||
- `James Gao (@jamesgao) <https://github.com/jamesgao>`__
|
- `James Gao (@jamesgao) <https://github.com/jamesgao>`__
|
||||||
|
@ -1250,4 +1251,4 @@ Contributors
|
||||||
- `Zsolt Zsiros (@ZsZs73) <https://github.com/ZsZs73>`__
|
- `Zsolt Zsiros (@ZsZs73) <https://github.com/ZsZs73>`__
|
||||||
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
|
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
|
||||||
|
|
||||||
*This page was last updated October 30, 2023.*
|
*This page was last updated November 1, 2023.*
|
||||||
|
|
Loading…
Reference in New Issue