[esp32_improv] Doc updates for esphome/esphome#7461 (#4256)

components/esp32_improv.rst

@@ -37,8 +37,120 @@ Configuration variables:
   to be re-authorized. Defaults to ``1min``.
 - **status_indicator** (*Optional*, :ref:`config-id`): An :doc:`output <output/index>` to display feedback to the user.
 - **identify_duration** (*Optional*, :ref:`config-time`): The amount of time to identify for. Defaults to ``10s``.
-- **wifi_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before starting the improv service after Wi-Fi
-  is no longer connected. Defaults to ``1min``.
+- **wifi_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before starting the Improv service
+  after Wi-Fi is no longer connected. Defaults to ``1min``.
+- **on_start** (*Optional*, :ref:`Automation<automation>`): An action to be performed when Improv is waiting for
+  authorization and/or upon authorization. See :ref:`improv-on_start`.
+- **on_provisioned** (*Optional*, :ref:`Automation<automation>`): An action to be performed when provisioning has
+  completed. See :ref:`improv-on_provisioned`.
+- **on_provisioning** (*Optional*, :ref:`Automation<automation>`): An action to be performed when the device begins the
+  provisioning process. See :ref:`improv-on_provisioning`.
+- **on_stop** (*Optional*, :ref:`Automation<automation>`): An action to be performed when Improv has stopped.
+  See :ref:`improv-on_stop`.
+- **on_state** (*Optional*, :ref:`Automation<automation>`): An action to be performed when an Improv state change
+  happens. See :ref:`improv-on_state`.
+
+.. _improv-automations:
+
+Improv Automations
+------------------
+
+The ESP32 Improv component provides various :ref:`automations <automation>` that can be used to provide feedback during
+the Improv provisioning process.
+
+.. _improv-on_start:
+
+``on_start``
+************
+
+This automation will be triggered when the device is waiting for authorization (usually by pressing a button on the
+device, if configured -- see ``authorizer`` above) and/or upon authorization.
+
+.. code-block:: yaml
+
+    esp32_improv:
+      on_start:
+        then:
+          - logger.log: "Improv awaiting authorization/authorized"
+
+.. _improv-on_provisioned:
+
+``on_provisioned``
+******************
+
+This automation will be triggered when provisioning has completed.
+
+.. code-block:: yaml
+
+    esp32_improv:
+      on_provisioned:
+        then:
+          - logger.log: "Improv provisioned"
+
+.. _improv-on_provisioning:
+
+``on_provisioning``
+*******************
+
+This automation will be triggered when provisioning begins.
+
+.. code-block:: yaml
+
+    esp32_improv:
+      on_provisioning:
+        then:
+          - logger.log: "Improv provisioning"
+
+.. _improv-on_stop:
+
+``on_stop``
+***********
+
+This automation will be triggered when Improv has stopped.
+
+.. code-block:: yaml
+
+    esp32_improv:
+      on_stop:
+        then:
+          - logger.log: "Improv stopped"
+
+.. _improv-on_state:
+
+``on_state``
+************
+
+This automation will be triggered on every state change.
+
+Two variables are available for use in :ref:`lambdas<config-lambda>` within this automation. They are:
+
+- ``state``, an ``enum`` named ``improv::State``, having one of the following values:
+
+  -  ``improv::STATE_STOPPED``
+  -  ``improv::STATE_AWAITING_AUTHORIZATION``
+  -  ``improv::STATE_AUTHORIZED``
+  -  ``improv::STATE_PROVISIONING``
+  -  ``improv::STATE_PROVISIONED``
+
+- ``error``, an ``enum`` named ``improv::Error``, having one of the following values:
+
+  -  ``improv::ERROR_NONE``
+  -  ``improv::ERROR_INVALID_RPC``
+  -  ``improv::ERROR_UNKNOWN_RPC``
+  -  ``improv::ERROR_UNABLE_TO_CONNECT``
+  -  ``improv::ERROR_NOT_AUTHORIZED``
+  -  ``improv::ERROR_UNKNOWN``
+
+.. code-block:: yaml
+
+    esp32_improv:
+      on_state:
+        then:
+          - if:
+              condition:
+                lambda: return state == improv::STATE_AUTHORIZED;
+              then:
+                - logger.log: "Improv state is STATE_AUTHORIZED"
 
 Status Indicator
 ----------------