Break apart automations doc (#3957)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Jesse Hills <[email protected]>

Author: 3 people

Diff for: all_automations.json

@@ -0,0 +1,76 @@
+- **ags10:** ``new_i2c_address``, ``set_zero_point``
+- **alarm_control_panel:** ``arm_away``, ``arm_home``, ``arm_night``, ``chime``, ``disarm``, ``pending``, ``ready``, ``triggered``
+- **animation:** ``next_frame``, ``prev_frame``, ``set_frame``
+- **at581x:** ``reset``, ``settings``
+- **ble:** ``disable``, ``enable``
+- **ble_client:** ``ble_write``, ``connect``, ``disconnect``, ``numeric_comparison_reply``, ``passkey_reply``, ``remove_bond``
+- **bluetooth_password:** ``set``
+- **button:** ``press``
+- **canbus:** ``send``
+- **climate:** ``control``
+- **component:** ``resume``, ``suspend``, ``update``
+- **cover:** ``close``, ``control``, ``open``, ``stop``, ``toggle``
+- **cs5460a:** ``restart``
+- **deep_sleep:** ``allow``, ``enter``, ``prevent``
+- **dfplayer:** ``pause``, ``play``, ``play_folder``, ``play_mp3``, ``play_next``, ``play_previous``, ``random``, ``reset``, ``set_device``, ``set_eq``, ``set_volume``, ``sleep``, ``start``, ``stop``, ``volume_down``, ``volume_up``
+- **dfrobot_sen0395:** ``reset``, ``settings``
+- **display_menu:** ``down``, ``enter``, ``hide``, ``left``, ``right``, ``show``, ``show_main``, ``up``
+- **ds1307:** ``read_time``, ``write_time``
+- **esp32_ble_tracker:** ``start_scan``, ``stop_scan``
+- **event:** ``trigger``
+- **ezo_pmp:** ``arbitrary_command``, ``change_i2c_address``, ``clear_calibration``, ``clear_total_volume_dosed``, ``dose_continuously``, ``dose_volume``, ``dose_volume_over_time``, ``dose_with_constant_flow_rate``, ``find``, ``pause_dosing``, ``set_calibration_volume``, ``stop_dosing``
+- **fan:** ``cycle_speed``, ``toggle``, ``turn_off``, ``turn_on``
+- **fingerprint_grow:** ``aura_led_control``, ``cancel_enroll``, ``delete``, ``delete_all``, ``enroll``, ``led_control``
+- **globals:** ``set``
+- **grove_tb6612fng:** ``break``, ``change_address``, ``no_standby``, ``run``, ``standby``, ``stop``
+- **homeassistant:** ``event``, ``service``, ``tag_scanned``
+- **http_request:** ``get``, ``post``, ``send``
+- **htu21d:** ``set_heater``, ``set_heater_level``
+- **light:** ``addressable_set``, ``control``, ``dim_relative``, ``toggle``, ``turn_off``, ``turn_on``
+- **lightwaverf:** ``send_raw``
+- **lock:** ``lock``, ``open``, ``unlock``
+- **logger:** ``log``
+- **max6956:** ``set_brightness_global``, ``set_brightness_mode``
+- **media_player:** ``pause``, ``play``, ``play_media``, ``stop``, ``toggle``, ``volume_down``, ``volume_set``, ``volume_up``
+- **mhz19:** ``abc_disable``, ``abc_enable``, ``calibrate_zero``
+- **micro_wake_word:** ``start``, ``stop``
+- **microphone:** ``capture``, ``stop_capture``
+- **midea_ac:** ``beeper_off``, ``beeper_on``, ``display_toggle``, ``follow_me``, ``power_off``, ``power_on``, ``power_toggle``, ``swing_step``
+- **mqtt:** ``publish``, ``publish_json``
+- **number:** ``decrement``, ``increment``, ``operation``, ``set``, ``to_max``, ``to_min``
+- **output:** ``set_level``, ``turn_off``, ``turn_on``
+- **pcf85063:** ``read_time``, ``write_time``
+- **pcf8563:** ``read_time``, ``write_time``
+- **pmwcs3:** ``air_calibration``, ``new_i2c_address``, ``water_calibration``
+- **pulse_counter:** ``set_total_pulses``
+- **pulse_meter:** ``set_total_pulses``
+- **pzemac:** ``reset_energy``
+- **pzemdc:** ``reset_energy``
+- **remote_transmitter:** ``transmit_abbwelcome``, ``transmit_aeha``, ``transmit_byronsx``, ``transmit_canalsat``, ``transmit_canalsatld``, ``transmit_coolix``, ``transmit_dish``, ``transmit_dooya``, ``transmit_drayton``, ``transmit_haier``, ``transmit_jvc``, ``transmit_keeloq``, ``transmit_lg``, ``transmit_magiquest``, ``transmit_midea``, ``transmit_mirage``, ``transmit_nec``, ``transmit_nexa``, ``transmit_panasonic``, ``transmit_pioneer``, ``transmit_pronto``, ``transmit_raw``, ``transmit_rc5``, ``transmit_rc6``, ``transmit_rc_switch_raw``, ``transmit_rc_switch_type_a``, ``transmit_rc_switch_type_b``, ``transmit_rc_switch_type_c``, ``transmit_rc_switch_type_d``, ``transmit_roomba``, ``transmit_samsung``, ``transmit_samsung36``, ``transmit_sony``, ``transmit_toshiba_ac``
+- **rf_bridge:** ``beep``, ``learn``, ``send_advanced_code``, ``send_code``, ``send_raw``, ``start_advanced_sniffing``, ``start_bucket_sniffing``, ``stop_advanced_sniffing``
+- **rtttl:** ``play``, ``stop``
+- **scd30:** ``force_recalibration_with_reference``
+- **scd4x:** ``factory_reset``, ``perform_forced_calibration``
+- **script:** ``execute``, ``stop``, ``wait``
+- **select:** ``first``, ``last``, ``next``, ``operation``, ``previous``, ``set``, ``set_index``
+- **sen5x:** ``start_fan_autoclean``
+- **senseair:** ``abc_disable``, ``abc_enable``, ``abc_get_period``, ``background_calibration``, ``background_calibration_result``
+- **servo:** ``detach``, ``write``
+- **sim800l:** ``connect``, ``dial``, ``disconnect``, ``send_sms``, ``send_ussd``
+- **speaker:** ``play``, ``stop``
+- **sprinkler:** ``clear_queued_valves``, ``next_valve``, ``pause``, ``previous_valve``, ``queue_valve``, ``resume``, ``resume_or_start_full_cycle``, ``set_divider``, ``set_multiplier``, ``set_repeat``, ``set_valve_run_duration``, ``shutdown``, ``start_from_queue``, ``start_full_cycle``, ``start_single_valve``
+- **sps30:** ``start_fan_autoclean``
+- **stepper:** ``report_position``, ``set_acceleration``, ``set_deceleration``, ``set_speed``, ``set_target``
+- **switch:** ``toggle``, ``turn_off``, ``turn_on``
+- **tag:** ``emulation_off``, ``emulation_on``, ``polling_off``, ``polling_on``, ``set_clean_mode``, ``set_emulation_message``, ``set_format_mode``, ``set_read_mode``, ``set_write_message``, ``set_write_mode``
+- **text:** ``set``
+- **tm1651:** ``set_brightness``, ``set_level``, ``set_level_percent``, ``turn_off``, ``turn_on``
+- **uart:** ``write``
+- **ufire_ec:** ``calibrate_probe``, ``reset``
+- **ufire_ise:** ``calibrate_probe_high``, ``calibrate_probe_low``, ``reset``
+- **update:** ``perform``
+- **valve:** ``close``, ``control``, ``open``, ``stop``, ``toggle``
+- **voice_assistant:** ``start``, ``start_continuous``, ``stop``
+- **wifi:** ``disable``, ``enable``
+- **wireguard:** ``disable``, ``enable``
+

Diff for: automations/actions.rst

@@ -0,0 +1,31 @@
+- **alarm_control_panel:** ``is_armed``, ``ready``
+- **api:** ``connected``
+- **binary_sensor:** ``is_off``, ``is_on``
+- **ble:** ``enabled``
+- **dfplayer:** ``is_playing``
+- **display:** ``is_displaying_page``
+- **display_menu:** ``is_active``
+- **fan:** ``is_off``, ``is_on``
+- **light:** ``is_off``, ``is_on``
+- **lock:** ``is_locked``, ``is_unlocked``
+- **media_player:** ``is_idle``, ``is_playing``
+- **micro_wake_word:** ``is_running``
+- **microphone:** ``is_capturing``
+- **mqtt:** ``connected``
+- **number:** ``in_range``
+- **pn532:** ``is_writing``
+- **pn7150:** ``is_writing``
+- **pn7160:** ``is_writing``
+- **rtttl:** ``is_playing``
+- **script:** ``is_running``
+- **sensor:** ``in_range``
+- **speaker:** ``is_playing``
+- **sun:** ``is_above_horizon``, ``is_below_horizon``
+- **switch:** ``is_off``, ``is_on``
+- **text_sensor:** ``state``
+- **time:** ``has_time``
+- **update:** ``is_available``
+- **voice_assistant:** ``connected``, ``is_running``
+- **wifi:** ``connected``, ``enabled``
+- **wireguard:** ``enabled``, ``peer_online``
+

Diff for: automations/all_actions.rst

@@ -0,0 +1,32 @@
+.. _automation:
+
+Automation
+==========
+
+.. seo::
+    :description: Getting started guide for automations in ESPHome
+    :image: auto-fix.svg
+
+Automations are a very powerful aspect of ESPHome; they allow you to easily perform actions given some condition(s).
+
+When you want your ESPHome device to respond to its environment, you use an automation. Here are some examples:
+
+- Switch on a light when the cover is opened
+- Transmit an infrared (IR) code when I press this button
+- Turn on the heat when the temperature drops
+
+This page serves as an index which will walk to through the process of using ESPHome automations--actions, triggers,
+templates, and more--to customize your ESPHome device just how you like it.
+
+- :doc:`actions`
+- :doc:`templates`
+- :doc:`/components/globals`
+- :doc:`/components/script`
+- :doc:`/components/interval`
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+    :hidden:
+
+    *

Diff for: automations/all_conditions.rst

@@ -0,0 +1,117 @@
+.. _config-lambda:
+
+Templates
+=========
+
+.. seo::
+    :description: Guide for using templates in ESPHome
+    :image: auto-fix.svg
+
+*Templates* (also known as *lambdas*) allow you to do almost *anything* in ESPHome. For example, if you want to only
+perform a certain automation if a certain complex formula evaluates to true, you can do that with templates. Let's look
+at an example first:
+
+.. code-block:: yaml
+
+    binary_sensor:
+      - platform: gpio
+        name: "Cover End Stop"
+        id: top_end_stop
+    cover:
+      - platform: template
+        name: Living Room Cover
+        lambda: !lambda |-
+          if (id(top_end_stop).state) {
+            return COVER_OPEN;
+          } else {
+            return COVER_CLOSED;
+          }
+
+What's happening here? First, we define a binary sensor (notably with ``id: top_end_stop``) and then a
+:doc:`template cover </components/cover/template>`. (If you're new to Home Assistant, a 'cover' is something like a
+window blind, a roller shutter, or a garage door.) The *state* of the template cover is controlled by a template, or
+"lambda". In lambdas, you're just writing C++ code and therefore the name lambda is used instead of Home Assistant's
+"template" lingo to avoid confusion. Regardless, don't let lambdas scare you just because you saw "C++" -- writing
+lambdas is not that hard! Here's a bit of a primer:
+
+First, you might have already wondered what the ``lambda: !lambda |-`` part is supposed to mean. ``!lambda`` tells
+ESPHome that the following block is supposed to be interpreted as a lambda, or C++ code. Note that here, the
+``lambda:`` key would actually implicitly make the following block a lambda, so in this context, you could also have
+written ``lambda: |-``.
+
+Next, there's the weird ``|-`` character combination. This tells the YAML parser to treat the following **indented**
+block as plaintext. Without it, the YAML parser would attempt to read the following block as if it were made up of YAML
+keys like ``cover:`` for example. (You may also have seen variations of this like ``>-`` or just ``|`` or ``>``. There
+is a slight difference in how these different styles deal with whitespace, but for our purposes we can ignore that).
+
+With ``if (...) { ... } else { ... }`` we create a *condition*. What this effectively says that if the thing inside the
+first parentheses evaluates to ``true`` then execute the first block (in this case ``return COVER_OPEN;``, or else
+evaluate the second block. ``return ...;`` makes the code block give back a value to the template. In this case, we're
+either *returning* ``COVER_OPEN`` or ``COVER_CLOSED`` to indicate that the cover is closed or open.
+
+Finally, ``id(...)`` is a helper function that makes ESPHome fetch an object with the supplied ID (which you defined
+somewhere else, like ``top_end_stop``) and lets you call any of ESPHome's many APIs directly. For example, here we're
+retrieving the current state of the end stop using ``.state`` and using it to construct our cover state.
+
+.. note::
+
+    ESPHome does not check the validity of lambda expressions you enter and will blindly copy them into the generated
+    C++ code. If compilation fails or something else is not working as expected with lambdas, it's always best to look
+    at the generated C++ source file under ``<NODE_NAME>/src/main.cpp``.
+
+.. tip::
+
+    To store local variables inside lambdas that retain their value across executions, you can create ``static``
+    variables as shown in the example below. Here, the variable ``num_executions`` is incremented by one each time the
+    lambda is executed and the current value is logged.
+
+    .. code-block:: yaml
+
+        lambda: |-
+          static int num_executions = 0;
+          ESP_LOGD("main", "I am at execution number %d", num_executions);
+          num_executions += 1;
+
+.. _config-templatable:
+
+Templating Actions
+------------------
+
+ESPHome allows you to template most parameters for actions used in automations. For example, if you have a light and
+want to set it to a pre-defined color when a button is pressed, you can do this:
+
+.. code-block:: yaml
+
+    on_press:
+      then:
+        - light.turn_on:
+            id: some_light_id
+            transition_length: 0.5s
+            red: 0.8
+            green: 1.0
+            blue: !lambda |-
+              // The sensor outputs values from 0 to 100. The blue
+              // part of the light color will be determined by the sensor value.
+              return id(some_sensor).state / 100.0;
+
+When you see the label "templatable" in the documentation for a given action, it can be templated as in this example,
+using the lambda syntax as described/shown above.
+
+All Lambda Calls
+----------------
+
+- :ref:`Sensor <sensor-lambda_calls>`
+- :ref:`Binary Sensor <binary_sensor-lambda_calls>`
+- :ref:`Switch <switch-lambda_calls>`
+- :ref:`Display <display-engine>`
+- :ref:`Cover <cover-lambda_calls>`
+- :ref:`Text Sensor <text_sensor-lambda_calls>`
+- :ref:`Stepper <stepper-lambda_calls>`
+- :ref:`Number <number-lambda_calls>`
+
+See Also
+--------
+
+- :doc:`index`
+- :doc:`actions`
+- :ghedit:`Edit`

Diff for: automations/index.rst

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+
+if __name__ == "__main__":
+    file_name = "all_automations.json"
+    arg_choices = ["actions", "conditions", "pin_providers"]
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-t",
+        "--type",
+        choices=arg_choices,
+        help="Automation type to extract ('actions', 'conditions', 'pin_providers')",
+    )
+    args = parser.parse_args()
+
+    with open(file_name) as json_file:
+        raw_json = json.load(json_file)
+
+    if args.type not in arg_choices:
+        print("Unrecognized automation type")
+        exit()
+
+    automation_list = raw_json[args.type]
+
+    component_dict = {}
+
+    for item in automation_list:
+        parts = item.split(".")
+        if len(parts) == 2:
+            if parts[0] not in component_dict:
+                component_dict[parts[0]] = []
+            component_dict[parts[0]].append(parts[1])
+
+    out_str = ""
+
+    for comp, autos in component_dict.items():
+        out_str += f"- **{comp}:** "
+        for item in autos:
+            out_str += f"``{item}``, "
+        out_str = out_str[:-2] + "\n"
+
+    print(out_str)

Diff for: automations/templates.rst

@@ -27,6 +27,6 @@ Configuration variables:
 See Also
 --------
 
-- :doc:`/guides/automations`
+- :doc:`/automations/index`
 - :doc:`/components/button/index`
 - :ghedit:`Edit`

Diff for: build_automations_pages.py

@@ -26,6 +26,6 @@ Configuration variables:
 See Also
 --------
 
-- :doc:`/guides/automations`
+- :doc:`/automations/index`
 - :doc:`/components/event/index`
 - :ghedit:`Edit`