Documentation for WireGuard actions and conditions (#3342)

components/wireguard.rst

@@ -225,6 +225,22 @@ This binary sensor tracks the connection status (*online*/*offline*) of the remo
 All options from :ref:`Binary Sensor <config-binary_sensor>` can be added to the
 above configuration.
 
+Enabled Binary Sensor
+^^^^^^^^^^^^^^^^^^^^^
+
+This binary sensor tracks if |wireguard| is *enabled* or not.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    binary_sensor:
+      - platform: wireguard
+        enabled:
+          name: 'WireGuard Enabled'
+
+All options from :ref:`Binary Sensor <config-binary_sensor>` can be added to the
+above configuration.
+
 Latest Handshake Sensor
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -257,6 +273,85 @@ This sensor exposes to the frontend the configured :ref:`address <wireguard-addr
 All options from :ref:`Text Sensor <config-text_sensor>` can be added to the
 above configuration.
 
+.. _wireguard-actions:
+
+Actions
+-------
+
+The following actions are available.
+
+``wireguard.disable``
+^^^^^^^^^^^^^^^^^^^^^
+
+This action drops down the active VPN link (if any) and disables the component.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - wireguard.disable:
+
+The lambda equivalent is ``id(wireguard_id).disable()``.
+
+.. note::
+
+    To disable |wireguard| since device boot you can execute this action
+    in the :ref:`esphome-on_boot` step.
+
+``wireguard.enable``
+^^^^^^^^^^^^^^^^^^^^
+
+This action enables the component and starts the connection to the remote peer.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - wireguard.enable:
+
+The lambda equivalent is ``id(wireguard_id).enable()``.
+
+.. _wireguard-conditions:
+
+Conditions
+----------
+
+The following conditions are available.
+
+``wireguard.enabled``
+^^^^^^^^^^^^^^^^^^^^^
+
+This condition checks if |wireguard| is currently enabled or not.
+
+.. code-block:: yaml
+
+    on_...:
+      - if:
+          condition: wireguard.enabled
+          then:
+            - ...
+          else:
+            - ...
+
+The lambda equivalent is ``id(wireguard_id).is_enabled()``.
+
+``wireguard.peer_online``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This condition checks if the remote peer is *online*.
+
+.. code-block:: yaml
+
+    on_...:
+      - if:
+          condition: wireguard.peer_online
+          then:
+            - ...
+          else:
+            - ...
+
+The lambda equivalent is ``id(wireguard_id).is_peer_up()``.
+
 .. _wireguard-installation:
 
 Remote peer setup
@@ -305,6 +400,7 @@ See Also
 
 - :doc:`time/index`
 - :doc:`time/sntp`
+- :ref:`automation`
 - |wireguard|_ official website
 - `Home Assistant Community Add-on: WireGuard
   <https://community.home-assistant.io/t/home-assistant-community-add-on-wireguard/134662>`__

guides/automations.rst

@@ -410,6 +410,7 @@ All Actions
 - :ref:`media_player.play <media_player-play>` / :ref:`media_player.pause <media_player-pause>` / :ref:`media_player.stop <media_player-stop>` / :ref:`media_player.toggle <media_player-toggle>`
   / :ref:`media_player.volume_up <media_player-volume_up>` / :ref:`media_player.volume_down <media_player-volume_down>` / :ref:`media_player.volume_set <media_player-volume_set>`
 - :ref:`ble_client.ble_write <ble_client-ble_write_action>`
+- :ref:`wireguard.disable <wireguard-actions>` / :ref:`wireguard.enable <wireguard-actions>`
 
 .. _config-condition:
 
@@ -432,6 +433,7 @@ All Conditions
 - :ref:`display.is_displaying_page <display-is_displaying_page-condition>`
 - :ref:`number.in_range <number-in_range_condition>`
 - :ref:`fan.is_on <fan-is_on_condition>` / :ref:`fan.is_off <fan-is_off_condition>`
+- :ref:`wireguard.enabled <wireguard-conditions>` / :ref:`wireguard.peer_online <wireguard-conditions>`
 
 All Lambda Calls
 ----------------