From aa041a93fae0ceb925cd69474c2c563b8a070ae3 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Thu, 1 Aug 2024 22:38:39 +1200 Subject: [PATCH] [api] Update ``service`` -> ``action`` (#4104) --- changelog/v1.12.0.rst | 2 +- components/api.rst | 69 ++++++++++++++--------------- components/ble_client.rst | 6 +-- components/dfplayer.rst | 38 ++++++++-------- components/display/nextion.rst | 10 ++--- components/fingerprint_grow.rst | 14 +++--- components/rf_bridge.rst | 8 ++-- components/rtttl.rst | 4 +- components/sensor/ld2410.rst | 8 ++-- components/sensor/mhz19.rst | 6 +-- components/sensor/pulse_counter.rst | 6 +-- components/sensor/pulse_meter.rst | 4 +- components/sensor/scd4x.rst | 10 ++--- components/sim800l.rst | 16 +++---- components/sprinkler.rst | 16 +++---- components/tm1651.rst | 6 +-- cookbook/infostrip.rst | 6 +-- cookbook/power_meter.rst | 6 +-- custom/custom_component.rst | 4 +- guides/configuration-types.rst | 6 +-- guides/index.rst | 1 + 21 files changed, 123 insertions(+), 123 deletions(-) diff --git a/changelog/v1.12.0.rst b/changelog/v1.12.0.rst index 67a2059de..5ebdc124a 100644 --- a/changelog/v1.12.0.rst +++ b/changelog/v1.12.0.rst @@ -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 `, +``homeassistant.service`` call). With 1.12 you get :ref:`User-defined services `, 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! diff --git a/components/api.rst b/components/api.rst index 96d819ee6..398c46b14 100644 --- a/components/api.rst +++ b/components/api.rst @@ -60,7 +60,7 @@ Configuration variables: document.getElementById("api-key").value = bytesArrToBase64(array); -- **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 ` 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 `. @@ -127,31 +127,30 @@ Configuration variables: - **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``. Values are :ref:`lambdas ` 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 ` 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 `. +When using the native API with Home Assistant, you can perform Home Assistant actions straight from ESPHome :ref:`Automations `. .. 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 `. Configuration variables: ```````````````````````` -- **service** (**Required**, string): The Home Assistant `Service `__ - 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 `__ + 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 ` 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 ` 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 `. @@ -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: diff --git a/components/ble_client.rst b/components/ble_client.rst index 4198f3b54..06f08c193 100644 --- a/components/ble_client.rst +++ b/components/ble_client.rst @@ -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: diff --git a/components/dfplayer.rst b/components/dfplayer.rst index 672cc4615..512559c1e 100644 --- a/components/dfplayer.rst +++ b/components/dfplayer.rst @@ -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(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 diff --git a/components/display/nextion.rst b/components/display/nextion.rst index 09d8a85f9..d551f6c9f 100644 --- a/components/display/nextion.rst +++ b/components/display/nextion.rst @@ -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 diff --git a/components/fingerprint_grow.rst b/components/fingerprint_grow.rst index cdba66074..453a6dd51 100644 --- a/components/fingerprint_grow.rst +++ b/components/fingerprint_grow.rst @@ -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: diff --git a/components/rf_bridge.rst b/components/rf_bridge.rst index 0ab8e3b73..6aa4bc6e1 100644 --- a/components/rf_bridge.rst +++ b/components/rf_bridge.rst @@ -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 diff --git a/components/rtttl.rst b/components/rtttl.rst index b502a649e..dd0872e17 100644 --- a/components/rtttl.rst +++ b/components/rtttl.rst @@ -174,8 +174,8 @@ Sample code - logger.log: 'Song ended!' api: - services: - - service: play_rtttl + actions: + - action: play_rtttl variables: song_str: string then: diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index acc4b4823..1f897b69e 100644 --- a/components/sensor/ld2410.rst +++ b/components/sensor/ld2410.rst @@ -156,7 +156,7 @@ Configuration variables: - **detection_distance** (*Optional*, int): Distance in cm of target. All options from :ref:`Sensor `. - **gX** (*Optional*): Energies for the Xth gate (X => 0 to 8). - + - **move_energy** (*Optional*, int): When in :ref:`engineering mode`, the move energy of the gate, otherwise ``unknown``. Value between ``0`` and ``100`` inclusive. All options from :ref:`Sensor `. @@ -276,7 +276,7 @@ Configuration variables: Value between ``2`` and ``8`` inclusive. Defaults to ``8``. All options from :ref:`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: diff --git a/components/sensor/mhz19.rst b/components/sensor/mhz19.rst index 0d3c8f313..a62065672 100644 --- a/components/sensor/mhz19.rst +++ b/components/sensor/mhz19.rst @@ -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 ` to call it from Home Assistant +You can provide an :ref:`action ` 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 diff --git a/components/sensor/pulse_counter.rst b/components/sensor/pulse_counter.rst index 9486bd4de..8eecc593b 100644 --- a/components/sensor/pulse_counter.rst +++ b/components/sensor/pulse_counter.rst @@ -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: diff --git a/components/sensor/pulse_meter.rst b/components/sensor/pulse_meter.rst index 785f299c5..4c060a453 100644 --- a/components/sensor/pulse_meter.rst +++ b/components/sensor/pulse_meter.rst @@ -91,8 +91,8 @@ trying to match. .. code-block:: yaml api: - services: - - service: set_total + actions: + - action: set_total variables: new_total: int then: diff --git a/components/sensor/scd4x.rst b/components/sensor/scd4x.rst index f2d32ecaf..a43eab724 100644 --- a/components/sensor/scd4x.rst +++ b/components/sensor/scd4x.rst @@ -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: diff --git a/components/sim800l.rst b/components/sim800l.rst index 1f993dc37..273bea533 100644 --- a/components/sim800l.rst +++ b/components/sim800l.rst @@ -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" diff --git a/components/sprinkler.rst b/components/sprinkler.rst index 0221411f9..7e9d1706d 100644 --- a/components/sprinkler.rst +++ b/components/sprinkler.rst @@ -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 diff --git a/components/tm1651.rst b/components/tm1651.rst index 51dc85144..c439e348e 100644 --- a/components/tm1651.rst +++ b/components/tm1651.rst @@ -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: diff --git a/cookbook/infostrip.rst b/cookbook/infostrip.rst index e20060aa8..c0bf5e80c 100644 --- a/cookbook/infostrip.rst +++ b/cookbook/infostrip.rst @@ -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 diff --git a/cookbook/power_meter.rst b/cookbook/power_meter.rst index 0411666e2..9e9205d47 100644 --- a/cookbook/power_meter.rst +++ b/cookbook/power_meter.rst @@ -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 diff --git a/custom/custom_component.rst b/custom/custom_component.rst index 72e23baf9..a87dcb104 100644 --- a/custom/custom_component.rst +++ b/custom/custom_component.rst @@ -86,8 +86,8 @@ Native API Custom Component --------------------------- If you want to communicate directly with Home Assistant via the :doc:`native 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 diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst index c50fef15d..4b39a4b3e 100644 --- a/guides/configuration-types.rst +++ b/guides/configuration-types.rst @@ -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 diff --git a/guides/index.rst b/guides/index.rst index 1dd6ba9d7..e51c0fd51 100644 --- a/guides/index.rst +++ b/guides/index.rst @@ -3,5 +3,6 @@ Guides .. toctree:: :glob: + :maxdepth: 1 *