This commit is contained in:
Otto Winter 2019-03-13 18:57:39 +01:00
commit 666a1d51a5
No known key found for this signature in database
GPG Key ID: DB66C0BE6013F97E
2 changed files with 69 additions and 3 deletions

View File

@ -30,6 +30,7 @@ Configuration variables:
- **port** (*Optional*, integer): The port to run the API Server on. Defaults to ``6053``.
- **password** (*Optional*, string): The password to protect the API Server with. Defaults to no password.
- **services** (*Optional*, list): A list of user-defined services. See :ref:`api-services`.
- **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
client connects to the API. This is needed because sometimes the low level ESP functions report that
the ESP is connected to the network, when in fact it is not - only a full reboot fixes it.
@ -156,6 +157,71 @@ Configuration options:
- **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-services:
User-defined Services
---------------------
It is also possible to get data from Home Assistant to ESPHome with user-defined services.
When you declare services in your ESPHome YAML file, they will automatically show up in
Home Assistant and you can call them directly.
.. code-block:: yaml
# Example configuration entry
api:
services:
- service: start_laundry
then:
- switch.turn_on: relay
- delay: 3h
- switch.turn_off: relay
For example with the configuration seen above, after uploading you will see a service
called ``esphome.livingroom_start_laundry`` (livingroom is the node name) which you can
then call.
Additionally, you can also transmit data from Home Assistant to ESPHome with this method:
.. code-block:: yaml
# Example configuration entry
api:
services:
- service: start_effect
variables:
my_brightness: int
my_effect: string
then:
- light.turn_on:
id: my_light
brightness: !lambda 'return my_brightness;'
my_effect: !lambda 'return my_effect;'
Using the ``variables`` key you can tell ESPHome which variables to expect from Home Assistant.
For example the service seen above would be executed with something like this:
.. code-block:: yaml
# Example Home Assistant Service Call
service: esphome.livingroom_start_effect
data_template:
my_brightness: "{{ states.brightness.state }}"
my_effect: "Rainbow"
Then each variable you define in the ``variables`` section is accessible in the automation
triggered by the user-defined service through the name you gave it in the variables section
(note: this is a local variable, so do not wrap it in ``id(...)`` to access it).
There are currently 4 types of variables:
- bool: A boolean (ON/OFF). C++ type: ``bool``
- int: An integer. C++ type: ``int``/``int32_t``
- float: A floating point number. C++ type: ``float``
- string: A string. C++ type: ``std::string``
Advantages over MQTT
--------------------
@ -174,7 +240,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.
See Also
--------

View File

@ -311,15 +311,16 @@ in the :doc:`wifi component </components/wifi>` and :doc:`mqtt component </compo
All Triggers
------------
- :ref:`mqtt.on_message <mqtt-on_message>` / :ref:`mqtt.on_json_message <mqtt-on_json_message>`
- :ref:`api.services <api-services>`
- :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>`
- :ref:`binary_sensor.on_click <binary_sensor-on_click>` / :ref:`binary_sensor.on_double_click <binary_sensor-on_double_click>` /
:ref:`binary_sensor.on_multi_click <binary_sensor-on_multi_click>`
- :ref:`esphome.on_boot <esphome-on_boot>` / :ref:`esphome.on_shutdown <esphome-on_shutdown>` / :ref:`esphome.on_loop <esphome-on_loop>`
- :ref:`pn532.on_tag <pn532-on_tag>`
- :ref:`time.on_time <time-on_time>`
- :ref:`mqtt.on_message <mqtt-on_message>` / :ref:`mqtt.on_json_message <mqtt-on_json_message>`
- :ref:`pn532.on_tag <pn532-on_tag>`
- :ref:`interval.interval <interval>`
- :ref:`switch.on_turn_on / switch.on_turn_off <switch-on_turn_on_off_trigger>`