Add connection triggers to API doc (#3308)

components/api.rst

@@ -66,13 +66,50 @@ Configuration variables:
   the ESP is connected to the network, when in fact it is not - only a full reboot fixes it.
   Can be disabled by setting this to ``0s``. Defaults to ``15min``.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-- **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults to no password.
+- **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults
-  It is recommended to use the ``encryption`` -> ``key`` above instead of the the ``password``.
+  to no password. It is recommended to use the ``encryption`` -> ``key`` above instead of the the ``password``.
+- **on_client_connected** (*Optional*, :ref:`Action <config-action>`): An automation to perform when a client
+  connects to the API. See :ref:`api-on_client_connected_trigger`.
+- **on_client_disconnected** (*Optional*, :ref:`Action <config-action>`): An automation to perform when a client
+  disconnects from the API. See :ref:`api-on_client_disconnected_trigger`.
+
+.. _api-actions:
+
+Actions
+-------
+
+.. _api-homeassistant_event_action:
+
+``homeassistant.event`` Action
+******************************
+
+When using the native API with Home Assistant, you can create events in the Home Assistant event bus
+straight from ESPHome :ref:`Automations <automation>`.
+
+.. code-block:: yaml
+
+    # In some trigger
+    on_...:
+      # Simple
+      - homeassistant.event:
+          event: esphome.button_pressed
+          data:
+            message: Button was pressed
+
+Configuration variables:
+````````````````````````
+
+- **event** (**Required**, string): The event to create - must begin with ``esphome.``
+- **data** (*Optional*, mapping): Optional *static* data to pass along with the event.
+- **data_template** (*Optional*, mapping): Optional template data to pass along with the event.
+  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.
 
 .. _api-homeassistant_service_action:
 
 ``homeassistant.service`` Action
---------------------------------
+********************************
 
 When using the native API with Home Assistant, you can create Home Assistant service
 calls straight from ESPHome :ref:`Automations <automation>`.
@@ -97,7 +134,8 @@ calls straight from ESPHome :ref:`Automations <automation>`.
             my_variable: |-
               return id(my_sensor).state;
 
-Configuration options:
+Configuration variables:
+````````````````````````
 
 - **service** (**Required**, string): The Home Assistant `Service <https://www.home-assistant.io/docs/scripts/service-calls/>`__
   to call.
@@ -126,7 +164,7 @@ the parameters in plain format.
             - '{{ green }}'
             - '{{ blue }}'
 
-Then in ESPHome
+Then, in ESPHome:
 
 .. code-block:: yaml
 
@@ -140,6 +178,75 @@ Then in ESPHome
             green: '199'
             blue: '71'
 
+.. _api-homeassistant_tag_scanned_action:
+
+``homeassistant.tag_scanned`` Action
+************************************
+
+When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
+straight from ESPHome :ref:`Automations <automation>`.
+
+.. code-block:: yaml
+
+    # In some trigger
+    on_...:
+      # Simple
+      - homeassistant.tag_scanned: some-tag
+
+Configuration variables:
+````````````````````````
+
+- **tag** (**Required**, :ref:`templatable <config-templatable>`, string): The id of the scanned tag
+
+Triggers
+--------
+
+.. _api-on_client_connected_trigger:
+
+``on_client_connected`` Trigger
+*******************************
+
+This trigger is activated each time a client connects to the API.
+
+.. code-block:: yaml
+
+    api:
+      # ...
+      on_client_connected:
+        - logger.log: "API client connected!"
+
+.. _api-on_client_disconnected_trigger:
+
+``on_client_disconnected`` Trigger
+**********************************
+
+This trigger is activated each time the API disconnects from the API.
+
+.. code-block:: yaml
+
+    api:
+      # ...
+      on_client_disconnected:
+        - logger.log: "API client disconnected!"
+
+.. _api-connected_condition:
+
+``api.connected`` Condition
+---------------------------
+
+This :ref:`Condition <config-condition>` checks if at least one client is connected to the ESPHome
+native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output
+if logs are shown remotely.
+
+.. code-block:: yaml
+
+    on_...:
+      if:
+        condition:
+          api.connected:
+        then:
+          - logger.log: API is connected!
+
 .. _api-services:
 
 User-defined Services
@@ -208,25 +315,6 @@ Each of these also exist in array form:
 - bool[]: An array of boolean values. C++ type: ``std::vector<bool>``
 - ... - Same for other types.
 
-.. _api-connected_condition:
-
-``api.connected`` Condition
----------------------------
-
-This :ref:`Condition <config-condition>` checks if at least one client is connected to the ESPHome
-native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output
-if logs are shown remotely.
-
-.. code-block:: yaml
-
-    on_...:
-      if:
-        condition:
-          api.connected:
-        then:
-          - logger.log: API is connected!
-
-
 Advantages over MQTT
 --------------------
 
@@ -245,54 +333,6 @@ never be removed. Features of native API (vs. MQTT):
 - **Low Latency:** The native API is optimized for very low latency, usually this is only
   a couple of milliseconds and far less than can be noticed by the eye.
 
-
-.. _api-homeassistant_event_action:
-
-``homeassistant.event`` Action
-------------------------------
-
-When using the native API with Home Assistant, you can create events in the Home Assistant event bus
-straight from ESPHome :ref:`Automations <automation>`.
-
-.. code-block:: yaml
-
-    # In some trigger
-    on_...:
-      # Simple
-      - homeassistant.event:
-          event: esphome.button_pressed
-          data:
-            message: Button was pressed
-
-Configuration options:
-
-- **event** (**Required**, string): The event to create - must begin with ``esphome.``
-- **data** (*Optional*, mapping): Optional *static* data to pass along with the event.
-- **data_template** (*Optional*, mapping): Optional template data to pass along with the event.
-  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.
-
-
-.. _api-homeassistant_tag_scanned_action:
-
-``homeassistant.tag_scanned`` Action
-------------------------------------
-
-When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
-straight from ESPHome :ref:`Automations <automation>`.
-
-.. code-block:: yaml
-
-    # In some trigger
-    on_...:
-      # Simple
-      - homeassistant.tag_scanned: some-tag
-
-Configuration options:
-
-- **tag** (**Required**, :ref:`templatable <config-templatable>`, string): The id of the scanned tag
-
 See Also
 --------
 

guides/automations.rst

@@ -323,7 +323,7 @@ if it fails to connect to the network without a reboot)
 All Triggers
 ------------
 
-- :ref:`api.services <api-services>`
+- :ref:`api.services <api-services>` / :ref:`api.on_client_connected <api-on_client_connected_trigger>` / :ref:`api.on_client_disconnected <api-on_client_disconnected_trigger>`
 - :ref:`sensor.on_value <sensor-on_value>` / :ref:`sensor.on_raw_value <sensor-on_raw_value>` / :ref:`sensor.on_value_range <sensor-on_value_range>`
 - :ref:`binary_sensor.on_press <binary_sensor-on_press>` / :ref:`binary_sensor.on_release <binary_sensor-on_release>` /
   :ref:`binary_sensor.on_state <binary_sensor-on_state>`