Add connection triggers to API doc (#3308)
This commit is contained in:
Keith Burzinski
Jesse Hills
parent
359f3595fa
commit
1927ee00e7
|
|
@ -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,75 @@ 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.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
api:
|
||||
# ...
|
||||
on_client_connected:
|
||||
- logger.log: "API client connected!"
|
||||
|
||||
.. _api-on_client_disconnected_trigger:
|
||||
|
||||
``on_client_disconnected`` Trigger
|
||||
**********************************
|
||||
|
||||
This trigger is activated each time the API disconnects from the API.
|
||||
|
||||
.. 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 +315,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 +333,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
|
||||
--------
|
||||
|
||||
|
|
|
|||
|
|
@ -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>`
|
||||
|
|
|
|||
Loading…
Reference in New Issue