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

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 <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!
 

components/api.rst

@@ -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
+When using the native API with Home Assistant, you can perform Home Assistant actions straight from ESPHome :ref:`Automations <automation>`.
-calls straight from ESPHome :ref:`Automations <automation>`.
 
 .. code-block:: yaml
 
     # In some trigger
     on_...:
       # Simple
-      - homeassistant.service:
+      - homeassistant.action:
-          service: notify.html5
+          action: notify.html5
           data:
             message: Button was pressed
       # With templates and variables
-      - homeassistant.service:
+      - homeassistant.action:
-          service: notify.html5
+          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/>`__
+- **action** (**Required**, string): The Home Assistant `Action <https://www.home-assistant.io/docs/scripts/service-calls/>`__
-  to call.
+  to perform.
-- **data** (*Optional*, mapping): Optional *static* data to pass along with the service call.
+- **data** (*Optional*, mapping): Optional *static* data to perform the action with.
-- **data_template** (*Optional*, mapping): Optional template data to pass along with the service call.
+- **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:
+      - homeassistant.action:
-          service: script.set_light_rgb
+          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.
+It is also possible to get data from Home Assistant to ESPHome with user-defined actions.
-When you declare services in your ESPHome YAML file, they will automatically show up in
+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:
+      actions:
-        - service: start_laundry
+        - 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:
+      actions:
-        - service: start_effect
+        - 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
+    # Example Home Assistant Action
-    service: esphome.livingroom_start_effect
+    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:

components/ble_client.rst

@@ -459,8 +459,8 @@ Secure connection with a dynamically generated passkey:
 .. code-block:: yaml
 
     api:
-      services:
+      actions:
-        - service: passkey_reply
+        - 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:

components/dfplayer.rst

@@ -345,19 +345,19 @@ Sample code
           logger.log: 'Playback finished event'
 
     api:
-      services:
+      actions:
-      - service: dfplayer_next
+      - 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
 

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:
+        actions:
-          - service: update_nextion
+          - 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:
+          actions:
-            - service: set_nextion_sensor
+            - 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

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.
+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 service ``esphome.test_node_enroll`` and in service data enter
+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:
+      actions:
-      - service: enroll
+      - 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:
 

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:
+      actions:
-        - service: send_rf_code
+        - 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

components/rtttl.rst

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

components/sensor/ld2410.rst

@@ -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:
+      actions:
-        - service: set_ld2410_bluetooth_password
+        - action: set_ld2410_bluetooth_password
           variables:
             password: string
           then:

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 <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:
+      actions:
-        - service: mhz19_calibrate_zero
+        - action: mhz19_calibrate_zero
           then:
             - mhz19.calibrate_zero: my_mhz19_id
 

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:
+      actions:
-        - service: set_pulse_total
+        - action: set_pulse_total
           variables:
             new_pulse_total: int
           then:

components/sensor/pulse_meter.rst

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

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:
+      actions:
-        - service: calibrate_co2_value
+        - 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:
+      actions:
-        - service: set_ambient_pressure
+        - action: set_ambient_pressure
           variables:
             pressure_mbar: int
           then:

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:
+      actions:
-        - service: send_sms
+        - 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"
 

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:
+      actions:
-        - service: set_multiplier
+        - 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
 

components/tm1651.rst

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

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

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:
+      actions:
-        - service: set_total
+        - 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

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 </components/api>`
-you can use the :apiclass:`api::CustomAPIDevice` class to declare services that can be executed from
+you can use the :apiclass:`api::CustomAPIDevice` class to declare actions that can be performed from
-Home Assistant, as well as starting services in Home Assistant.
+Home Assistant, as well as performing actions in Home Assistant.
 
 .. code-block:: cpp
 

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:
+      actions:
-        - service: start_laundry
+        - action: start_laundry
           then:
             - switch.turn_on: relay
             - delay: 3h

guides/index.rst

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