Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-11-12 10:24:00 +01:00
Code Issues Projects Releases Wiki Activity

[api] Update `service -> action` (#4104)

Browse Source
This commit is contained in:
Jesse Hills 2024-08-01 22:38:39 +12:00 committed by GitHub
parent a8be32d761
commit aa041a93fa
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
21 changed files with 123 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
changelog/v1.12.0.rst
View File

@ -23,7 +23,7 @@ It's release day! 🎉 Today I'm happy to release ESPHome 1.12.0. What's new? A
stuff got added! Let me walk you through it:
Before 1.12, it was only possible to transfer data from ESPHome to Home Assistant (with the
``homeassistant.service`` call). With 1.12 you get :ref:`User-defined services <api-services>`,
``homeassistant.service`` call). With 1.12 you get :ref:`User-defined services <api-device-actions>`,
just define a service in your ESPHome file and call it like any other service from HA. All the
rest (like variables, data validation, etc) are handled automatically!

69
components/api.rst
View File

@ -60,7 +60,7 @@ Configuration variables:
document.getElementById("api-key").value = bytesArrToBase64(array);
</script>
- **services** (*Optional*, list): A list of user-defined services. See :ref:`api-services`.
- **actions** (*Optional*, list): A list of user-defined actions. See :ref:`api-device-actions`.
- **reboot_timeout** (*Optional*, :ref:`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.
@ -79,7 +79,7 @@ Actions
-------
Before using any of the actions below, you'll need to tell Home Assistant to allow your device to
make service calls.
perform actions.
Open the ESPHome integration page on your Home Assistant instance:
@ -91,7 +91,7 @@ Then:
#. Find your device in the device list
#. Click the "configure" button next to it
#. Check the "Allow the device to make Home Assistant service calls" box
#. Check the "Allow the device to perform Home Assistant actions" box
#. Then click "submit".
.. _api-homeassistant_event_action:
@ -102,7 +102,7 @@ Then:
.. note::
Be sure to :ref:`follow the instructions above <api-actions>` to tell Home Assistant to allow
your device to make service calls.
your device to perform actions.
When using the native API with Home Assistant, you can create events in the Home Assistant event bus
straight from ESPHome :ref:`Automations <automation>`.
@ -127,31 +127,30 @@ Configuration variables:
- **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_action-action:
``homeassistant.service`` Action
``homeassistant.action`` Action
********************************
.. note::
Be sure to :ref:`follow the instructions above <api-actions>` to tell Home Assistant to allow
your device to make service calls.
your device to perform actions.
When using the native API with Home Assistant, you can create Home Assistant service
calls straight from ESPHome :ref:`Automations <automation>`.
When using the native API with Home Assistant, you can perform Home Assistant actions straight from ESPHome :ref:`Automations <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.service:
service: notify.html5
- homeassistant.action:
action: notify.html5
data:
message: Button was pressed
# With templates and variables
- homeassistant.service:
service: notify.html5
- homeassistant.action:
action: notify.html5
data:
title: New Humidity
data_template:
@ -163,10 +162,10 @@ calls straight from ESPHome :ref:`Automations <automation>`.
Configuration variables:
````````````````````````
- **service** (**Required**, string): The Home Assistant `Service <https://www.home-assistant.io/docs/scripts/service-calls/>`__
to call.
- **data** (*Optional*, mapping): Optional *static* data to pass along with the service call.
- **data_template** (*Optional*, mapping): Optional template data to pass along with the service call.
- **action** (**Required**, string): The Home Assistant `Action <https://www.home-assistant.io/docs/scripts/service-calls/>`__
to perform.
- **data** (*Optional*, mapping): Optional *static* data to perform the action with.
- **data_template** (*Optional*, mapping): Optional template data to perform the action with.
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.
@ -182,7 +181,7 @@ the parameters in plain format.
set_light_rgb:
alias: 'ESPHome RGB light set'
sequence:
- service: light.turn_on
- action: light.turn_on
data_template:
entity_id: '{{ light_name }}'
rgb_color:
@ -196,8 +195,8 @@ Then, in ESPHome:
# In some trigger
on_...:
- homeassistant.service:
service: script.set_light_rgb
- homeassistant.action:
action: script.set_light_rgb
data:
light_name: 'my_light'
red: '255'
@ -212,7 +211,7 @@ Then, in ESPHome:
.. note::
Be sure to :ref:`follow the instructions above <api-actions>` to tell Home Assistant to allow
your device to make service calls.
your device to make action calls.
When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
straight from ESPHome :ref:`Automations <automation>`.
@ -289,27 +288,27 @@ if logs are shown remotely.
then:
- logger.log: API is connected!
.. _api-services:
.. _api-device-actions:
User-defined Services
---------------------
User-defined Actions
--------------------
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
It is also possible to get data from Home Assistant to ESPHome with user-defined actions.
When you declare actions 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
actions:
- action: 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
For example with the configuration seen above, after uploading you will see an action
called ``esphome.livingroom_start_laundry`` (livingroom is the node name) which you can
then call.
@ -319,8 +318,8 @@ Additionally, you can also transmit data from Home Assistant to ESPHome with thi
# Example configuration entry
api:
services:
- service: start_effect
actions:
- action: start_effect
variables:
my_brightness: int
my_effect: string
@ -331,18 +330,18 @@ Additionally, you can also transmit data from Home Assistant to ESPHome with thi
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:
For example the action seen above would be executed with something like this:
.. code-block:: yaml
# Example Home Assistant Service Call
service: esphome.livingroom_start_effect
# Example Home Assistant Action
action: 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
triggered by the user-defined action 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:

6
components/ble_client.rst
View File

@ -459,8 +459,8 @@ Secure connection with a dynamically generated passkey:
.. code-block:: yaml
api:
services:
- service: passkey_reply
actions:
- action: passkey_reply
variables:
passkey: int
then:
@ -468,7 +468,7 @@ Secure connection with a dynamically generated passkey:
- ble_client.passkey_reply:
id: my_ble_client
passkey: !lambda return passkey;
- service: numeric_comparison_reply
- action: numeric_comparison_reply
variables:
accept: bool
then:

38
components/dfplayer.rst
View File

@ -345,19 +345,19 @@ Sample code
logger.log: 'Playback finished event'
api:
services:
- service: dfplayer_next
actions:
- action: dfplayer_next
then:
- dfplayer.play_next:
- service: dfplayer_previous
- action: dfplayer_previous
then:
- dfplayer.play_previous:
- service: dfplayer_play
- action: dfplayer_play
variables:
file: int
then:
- dfplayer.play: !lambda 'return file;'
- service: dfplayer_play_loop
- action: dfplayer_play_loop
variables:
file: int
loop_: bool
@ -365,7 +365,7 @@ Sample code
- dfplayer.play:
file: !lambda 'return file;'
loop: !lambda 'return loop_;'
- service: dfplayer_play_folder
- action: dfplayer_play_folder
variables:
folder: int
file: int
@ -374,7 +374,7 @@ Sample code
folder: !lambda 'return folder;'
file: !lambda 'return file;'
- service: dfplayer_play_loop_folder
- action: dfplayer_play_loop_folder
variables:
folder: int
then:
@ -382,54 +382,54 @@ Sample code
folder: !lambda 'return folder;'
loop: true
- service: dfplayer_set_device_tf
- action: dfplayer_set_device_tf
then:
- dfplayer.set_device: TF_CARD
- service: dfplayer_set_device_usb
- action: dfplayer_set_device_usb
then:
- dfplayer.set_device: USB
- service: dfplayer_set_volume
- action: dfplayer_set_volume
variables:
volume: int
then:
- dfplayer.set_volume: !lambda 'return volume;'
- service: dfplayer_set_eq
- action: dfplayer_set_eq
variables:
preset: int
then:
- dfplayer.set_eq: !lambda 'return static_cast<dfplayer::EqPreset>(preset);'
- service: dfplayer_sleep
- action: dfplayer_sleep
then:
- dfplayer.sleep
- service: dfplayer_reset
- action: dfplayer_reset
then:
- dfplayer.reset
- service: dfplayer_start
- action: dfplayer_start
then:
- dfplayer.start
- service: dfplayer_pause
- action: dfplayer_pause
then:
- dfplayer.pause
- service: dfplayer_stop
- action: dfplayer_stop
then:
- dfplayer.stop
- service: dfplayer_random
- action: dfplayer_random
then:
- dfplayer.random
- service: dfplayer_volume_up
- action: dfplayer_volume_up
then:
- dfplayer.volume_up
- service: dfplayer_volume_down
- action: dfplayer_volume_down
then:
- dfplayer.volume_down

10
components/display/nextion.rst
View File

@ -115,8 +115,8 @@ The developer tools in Home Assistant can be used to trigger the update. The bel
.. code-block:: yaml
api:
services:
- service: update_nextion
actions:
- action: update_nextion
then:
- lambda: 'id(nextion1)->upload_tft();'
@ -151,8 +151,8 @@ The developer tools in Home Assistant can be used to trigger the update. The bel
# Enable Home Assistant API
api:
services:
- service: set_nextion_sensor
actions:
- action: set_nextion_sensor
variables:
nextion_type: int
name: string
@ -160,7 +160,7 @@ The developer tools in Home Assistant can be used to trigger the update. The bel
then:
- lambda: |-
id(nextion1).set_nextion_sensor_state(nextion_type,name,state);
- service: set_nextion_text
- action: set_nextion_text
variables:
name: string
state: string

14
components/fingerprint_grow.rst
View File

@ -475,8 +475,8 @@ All actions
Test setup
----------
With the following code you can quickly setup a node and use Home Assistant's service in the developer tools.
E.g. for calling ``fingerprint_grow.enroll`` select the service ``esphome.test_node_enroll`` and in service data enter
With the following code you can quickly setup a node and use Home Assistant's action in the developer tools.
E.g. for calling ``fingerprint_grow.enroll`` select the action ``esphome.test_node_enroll`` and in action data enter
.. code-block:: json
@ -527,8 +527,8 @@ Sample code
finger_id: !lambda 'return finger_id;'
api:
services:
- service: enroll
actions:
- action: enroll
variables:
finger_id: int
num_scans: int
@ -536,16 +536,16 @@ Sample code
- fingerprint_grow.enroll:
finger_id: !lambda 'return finger_id;'
num_scans: !lambda 'return num_scans;'
- service: cancel_enroll
- action: cancel_enroll
then:
- fingerprint_grow.cancel_enroll:
- service: delete
- action: delete
variables:
finger_id: int
then:
- fingerprint_grow.delete:
finger_id: !lambda 'return finger_id;'
- service: delete_all
- action: delete_all
then:
- fingerprint_grow.delete_all:

8
components/rf_bridge.rst
View File

@ -345,8 +345,8 @@ Home Assistant as events and will also setup a service so you can send codes wit
.. code-block:: yaml
api:
services:
- service: send_rf_code
actions:
- action: send_rf_code
variables:
sync: int
low: int
@ -358,7 +358,7 @@ Home Assistant as events and will also setup a service so you can send codes wit
low: !lambda 'return low;'
high: !lambda 'return high;'
code: !lambda 'return code;'
- service: learn
- action: learn
then:
- rf_bridge.learn
@ -391,7 +391,7 @@ To trigger the automation from Home Assistant you can invoke the service with th
automation:
# ...
action:
- service: esphome.rf_bridge_send_rf_code
- action: esphome.rf_bridge_send_rf_code
data:
sync: 0x700
low: 0x800

4
components/rtttl.rst
View File

@ -174,8 +174,8 @@ Sample code
- logger.log: 'Song ended!'
api:
services:
- service: play_rtttl
actions:
- action: play_rtttl
variables:
song_str: string
then:

8
components/sensor/ld2410.rst
View File

@ -156,7 +156,7 @@ Configuration variables:
- **detection_distance** (*Optional*, int): Distance in cm of target.
All options from :ref:`Sensor <config-sensor>`.
- **gX** (*Optional*): Energies for the Xth gate (X => 0 to 8).
- **move_energy** (*Optional*, int): When in :ref:`engineering mode<ld2410-engineering-mode>`, the move energy of the gate, otherwise ``unknown``.
Value between ``0`` and ``100`` inclusive.
All options from :ref:`Sensor <config-sensor>`.
@ -276,7 +276,7 @@ Configuration variables:
Value between ``2`` and ``8`` inclusive. Defaults to ``8``.
All options from :ref:`Number <config-number>`.
- **gX** (*Optional*): Thresholds for the Xth gate (X => 0 to 8).
- **move_threshold** (**Required**, int): Threshold for the gate for motion detection.
Above this level for the considered gate (distance), movement detection will be triggered.
Value between ``0`` and ``100`` inclusive. See default values below.
@ -435,8 +435,8 @@ To change the password from HA you can use the following example config:
id: my_ld2410
api:
services:
- service: set_ld2410_bluetooth_password
actions:
- action: set_ld2410_bluetooth_password
variables:
password: string
then:

6
components/sensor/mhz19.rst
View File

@ -82,13 +82,13 @@ for over 20 minutes and you execute this function.
then:
- mhz19.calibrate_zero: my_mhz19_id
You can provide :ref:`service <api-services>` to call it from Home Assistant
You can provide an :ref:`action <api-device-actions>` to perform from Home Assistant
.. code-block:: yaml
api:
services:
- service: mhz19_calibrate_zero
actions:
- action: mhz19_calibrate_zero
then:
- mhz19.calibrate_zero: my_mhz19_id

6
components/sensor/pulse_counter.rst
View File

@ -111,10 +111,10 @@ trying to match.
.. code-block:: yaml
# Set pulse counter total from home assistant using this service call:
# Set pulse counter total from home assistant using this action:
api:
services:
- service: set_pulse_total
actions:
- action: set_pulse_total
variables:
new_pulse_total: int
then:

4
components/sensor/pulse_meter.rst
View File

@ -91,8 +91,8 @@ trying to match.
.. code-block:: yaml
api:
services:
- service: set_total
actions:
- action: set_total
variables:
new_total: int
then:

10
components/sensor/scd4x.rst
View File

@ -105,13 +105,13 @@ As of April 2022 the average fresh air Co² concentration is 419 ppm.
value: 419 # outside average April 2022
id: my_scd41
value can also be a template, for example to define a Home Assistant calibration service:
value can also be a template, for example to define a Home Assistant calibration action:
.. code-block:: yaml
api:
services:
- service: calibrate_co2_value
actions:
- action: calibrate_co2_value
variables:
co2_ppm: int
then:
@ -166,8 +166,8 @@ This example creates a service `set_ambient_pressure` that can be called from Ho
.. code-block:: yaml
api:
services:
- service: set_ambient_pressure
actions:
- action: set_ambient_pressure
variables:
pressure_mbar: int
then:

16
components/sim800l.rst
View File

@ -249,8 +249,8 @@ on Home Assistant and will also setup a service so you can send messages and dia
.. code-block:: yaml
api:
services:
- service: send_sms
actions:
- action: send_sms
variables:
recipient: string
message: string
@ -258,19 +258,19 @@ on Home Assistant and will also setup a service so you can send messages and dia
- sim800l.send_sms:
recipient: !lambda 'return recipient;'
message: !lambda 'return message;'
- service: dial
- action: dial
variables:
recipient: string
then:
- sim800l.dial:
recipient: !lambda 'return recipient;'
- service: connect
- action: connect
then:
- sim800l.connect
- service: disconnect
- action: disconnect
then:
- sim800l.disconnect
- service: send_ussd
- action: send_ussd
variables:
ussdCode: string
then:
@ -324,11 +324,11 @@ To trigger the automation from Home Assistant you can invoke the service with th
automation:
# ...
action:
- service: esphome.livingroom_send_sms
- action: esphome.livingroom_send_sms
data:
recipient: "+15551234567"
message: "Hello World!"
- service: esphome.livingroom_dial
- action: esphome.livingroom_dial
data:
recipient: "+15551234567"

16
components/sprinkler.rst
View File

@ -1087,38 +1087,38 @@ memory use.
Expose Sprinkler Controller Actions via user-API
************************************************
This configuration snippet illustrates how user-defined ESPHome API services may be used to expose
This configuration snippet illustrates how user-defined ESPHome API actions may be used to expose
various sprinkler controller actions to the front end. This could be useful to change settings
and/or trigger sprinkler controller actions using automations.
.. code-block:: yaml
api:
services:
- service: set_multiplier
actions:
- action: set_multiplier
variables:
multiplier: float
then:
- sprinkler.set_multiplier:
id: lawn_sprinkler_ctrlr
multiplier: !lambda 'return multiplier;'
- service: start_full_cycle
- action: start_full_cycle
then:
- sprinkler.start_full_cycle: lawn_sprinkler_ctrlr
- service: start_single_valve
- action: start_single_valve
variables:
valve: int
then:
- sprinkler.start_single_valve:
id: lawn_sprinkler_ctrlr
valve_number: !lambda 'return valve;'
- service: next_valve
- action: next_valve
then:
- sprinkler.next_valve: lawn_sprinkler_ctrlr
- service: previous_valve
- action: previous_valve
then:
- sprinkler.previous_valve: lawn_sprinkler_ctrlr
- service: shutdown
- action: shutdown
then:
- sprinkler.shutdown: lawn_sprinkler_ctrlr

6
components/tm1651.rst
View File

@ -133,14 +133,14 @@ You also can control this component with lambda expressions
.. code-block:: yaml
api:
services:
- service: battery_level
actions:
- action: battery_level
variables:
level: int
then:
- lambda: |-
id(tm1651_battery).set_level(level);
- service: battery_brightness
- action: battery_brightness
variables:
brightness: int
then:

6
cookbook/infostrip.rst
View File

@ -111,7 +111,7 @@ The automation to show the CO2 warning light (e.g. red if CO2 > 1000 ppm) is don
above: 1000
condition: []
action:
- service: light.turn_on
- action: light.turn_on
data:
color_name: red
entity_id: light.pl2
@ -125,7 +125,7 @@ The automation to show the CO2 warning light (e.g. red if CO2 > 1000 ppm) is don
below: 800
condition: []
action:
- service: light.turn_off
- action: light.turn_off
entity_id: light.pl2
mode: single
- alias: "State Light Mapping"
@ -134,7 +134,7 @@ The automation to show the CO2 warning light (e.g. red if CO2 > 1000 ppm) is don
# You can also match on interval. This will match every 5 minutes
minutes: "/5"
action:
- service: light.turn_on
- action: light.turn_on
data_template:
entity_id: light.pl1
brightness_pct: 30

6
cookbook/power_meter.rst
View File

@ -108,8 +108,8 @@ Using this action, you are able to reset/set the total pulse count. This can be
.. code-block:: yaml
api:
services:
- service: set_total
actions:
- action: set_total
variables:
new_total: int
then:
@ -137,7 +137,7 @@ Additionally you can also calculate the total daily energy generated, for which
filters:
# Multiplication factor from W to kW is 0.001
- multiply: 0.001
time:
- platform: homeassistant
id: homeassistant_time

4
custom/custom_component.rst
View File

@ -86,8 +86,8 @@ Native API Custom Component
---------------------------
If you want to communicate directly with Home Assistant via the :doc:`native API </components/api>`
you can use the :apiclass:`api::CustomAPIDevice` class to declare services that can be executed from
Home Assistant, as well as starting services in Home Assistant.
you can use the :apiclass:`api::CustomAPIDevice` class to declare actions that can be performed from
Home Assistant, as well as performing actions in Home Assistant.
.. code-block:: cpp

6
guides/configuration-types.rst
View File

@ -358,7 +358,7 @@ Consider the following example where the author put common pieces of configurati
I²C into base files and extends it with some device specific configurations in the main config.
Note how the piece of configuration describing ``api`` component in ``device_base.yaml`` gets
merged with the services definitions from main config file.
merged with the actions definitions from main config file.
.. code-block:: yaml
@ -372,8 +372,8 @@ merged with the services definitions from main config file.
device_base: !include common/device_base.yaml
api:
services:
- service: start_laundry
actions:
- action: start_laundry
then:
- switch.turn_on: relay
- delay: 3h

1
guides/index.rst
View File

@ -3,5 +3,6 @@ Guides
.. toctree::
:glob:
:maxdepth: 1
*