From 070c9c228c32218de95bf220c6e1a6cd9223fbfc Mon Sep 17 00:00:00 2001
From: Martin <25747549+martgras@users.noreply.github.com>
Date: Sun, 9 Jan 2022 20:00:05 +0100
Subject: [PATCH] Document slow_pwm triggers (#1730)

Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>
---
 components/output/slow_pwm.rst | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/components/output/slow_pwm.rst b/components/output/slow_pwm.rst
index 7222d763d..c23d5b7d4 100644
--- a/components/output/slow_pwm.rst
+++ b/components/output/slow_pwm.rst
@@ -30,12 +30,41 @@ heating element through a relay where a fast PWM update cycle would not be appro
 Configuration variables:
 ------------------------
 
-- **pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin to pulse.
 - **id** (**Required**, :ref:`config-id`): The id to use for this output component.
 - **period** (**Required**, :ref:`config-time`): The duration of each cycle. (i.e. a 10s
   period at 50% duty would result in the pin being turned on for 5s, then off for 5s)
+- **pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin to pulse.
+- **state_change_action**  (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is switched. If a lambda is used the boolean ``state`` parameter holds the new status.
+- **turn_on_action**  (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is turned on. Can be used to control for example a switch or output component.
+- **turn_off_action** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the load is turned off. ``turn_on_action`` and ``turn_off_action`` must be configured together.
+
 - All other options from :ref:`Output <config-output>`.
 
+
+.. note::
+
+    - If ``pin`` is defined the GPIO pin state is writen before any action is executed.
+    - ``state_change_action`` and ``turn_on_action``/``turn_off_action`` can be used togther. ``state_change_action`` is called before ``turn_on_action``/``turn_off_action``. It's recommended to use either ``state_change_action`` or ``turn_on_action``/``turn_off_action`` to change the state of an output. Using both automations together is only recommended for monitoring.
+
+
+Example:
+--------
+
+.. code-block:: yaml
+
+
+    output:
+      - platform: slow_pwm
+        id: my_slow_pwm
+        period: 15s
+        turn_on_action:
+          - lambda: |-
+              auto *out1 = id(output1);
+              out1->turn_on();
+        turn_off_action:
+          - output.turn_off: output1
+
+
 See Also
 --------