Documentation for sigma_delta_output component (#2500)

Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/output/sigma_delta.rst

@@ -0,0 +1,81 @@
+Sigma-Delta Output
+==================
+
+This integration uses `sigma-delta modulation <https://en.wikipedia.org/wiki/Delta-sigma_modulation>`__
+to output a floating-point value on a binary output. Unlike with :doc:`/components/output/slow_pwm`,
+it is possible to update the output value with each update cycle, not just at the end of a longer period.
+
+.. figure:: images/sigma-delta-example.png
+    :align: center
+    :width: 65.0%
+
+    Comparison between a *Slow PWM* with a period of 100s and a *sigma-delta output* with an update interval of 1s
+
+For example, if you choose to toggle the output at most once every 1 second and decide on a
+PWM period of 10 seconds, for reasonably frequent updates, with :doc:`/components/output/slow_pwm`
+there are only 10 possible levels, and for higher precision a longer update interval is needed,
+restricting the update rate. 
+
+A *sigma-delta* output is updated during each cycle, thus a higher precision can be achieved, without
+being constrained by a calculation timeframe (=period).
+
+So instead of having to define a ``period`` where the width of the pulse determines the output level, here you
+choose an ``update_interval`` which acts like a clock signal from where the pulse density determines the output level. 
+
+This component can be used as a drop-in replacement for :doc:`/components/output/slow_pwm` by changing the ``platform`` to
+``sigma_delta_output`` and changing ``period`` to ``update_interval`` (you usually want to set the *sigma-delta*'s
+``update_interval`` as a fraction of *Slow PWM*'s ``period`` for similar results)
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    output:
+      - platform: sigma_delta_output
+        update_interval: 10s
+        id: sd_heater_output
+
+        # Output to a pin
+        pin: 15
+
+        # Use the same output, but through automations
+        turn_on_action:
+          then:
+            - output.turn_on: heater_relay
+        turn_off_action:
+          then:
+            - output.turn_off: heater_relay
+    
+      - platform: gpio
+        pin: 15
+        id: heater_relay
+
+Configuration variables:
+
+- **update_interval** (**Required**, :ref:`Time <config-time>`): The cycle interval at which the output is recalculated.
+- **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 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.
+
+
+.. note::
+
+    If the output must not be active for more than some fixed time before it has
+    to be off for a while to e.g. cool down, :doc:`/components/output/slow_pwm`
+    should be used with a ``max_power`` setting to better control the duty
+    cycle.
+
+See Also
+--------
+
+- :doc:`/components/output/index`
+- `Sigma-Delta <https://en.wikipedia.org/wiki/Delta-sigma_modulation>`__
+- :doc:`/components/output/slow_pwm`
+- :apiref:`sigma_delta_output/sigma_delta_output.h`
+- :ghedit:`Edit`

components/output/slow_pwm.rst

@@ -67,12 +67,21 @@ Example:
           - output.turn_off: output1
 
 
+.. note::
+
+    If the duty cycle is not constrained to a maximum value, the
+    :doc:`/components/output/sigma_delta` component offers faster updates and
+    greater control over the switching frequency. This is better for loads that
+    need some time to fully change between on and off, like eletric thermal
+    actuator heads or fans.
+
 See Also
 --------
 
 - :doc:`/components/output/index`
 - :doc:`/components/output/esp8266_pwm`
 - :doc:`/components/output/ledc`
+- :doc:`/components/output/sigma_delta`
 - :doc:`/components/light/monochromatic`
 - :doc:`/components/fan/speed`
 - :doc:`/components/power_supply`

images/sigma-delta.svg

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   width="24"
+   height="24"
+   version="1.1"
+   id="svg4"
+   sodipodi:docname="sigma-delta.svg"
+   inkscape:version="1.2.1 (9c6d41e410, 2022-07-14)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs8" />
+  <sodipodi:namedview
+     id="namedview6"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     showgrid="false"
+     inkscape:zoom="56.791667"
+     inkscape:cx="11.920763"
+     inkscape:cy="12.026412"
+     inkscape:window-width="3836"
+     inkscape:window-height="2109"
+     inkscape:window-x="0"
+     inkscape:window-y="47"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg4" />
+  <g
+     id="g401"
+     transform="translate(-1.4174133)">
+    <path
+       d="m 3.1866865,6.2376005 h 9.3638995 v 3.6014996 h -0.7203 l -0.7203,-2.1608998 H 6.8314041 l 2.5858764,3.6951387 -2.9604324,4.22816 h 4.6531379 l 0.7203,-1.4406 h 0.7203 v 3.6015 H 3.1866865 L 7.220366,12 Z"
+       id="path2"
+       style="stroke-width:0.7203" />
+    <g
+       aria-label="Δ"
+       id="text946"
+       style="font-size:16.7517px;line-height:1.25;text-align:end;letter-spacing:0px;word-spacing:0px;text-anchor:end;stroke-width:1.57047">
+      <path
+         d="m 17.701614,6.2375126 h 1.77496 L 23.64814,16.60917 v 1.153316 H 13.464612 l 0.0082,-1.153316 z M 22.012232,16.486477 19.247547,9.435713 Q 19.002161,8.830427 18.789493,8.1760637 18.585004,7.5135209 18.568645,7.4153665 l -0.07362,0.2617453 q -0.253565,0.907929 -0.605286,1.7749603 l -2.772864,7.0344049 z"
+         id="path395" />
+    </g>
+  </g>
+</svg>

index.rst

@@ -447,6 +447,7 @@ Output Components
     BLE Binary Output, components/output/ble_client, bluetooth.svg
     Modbus Output, components/output/modbus_controller, modbus.png
     Custom Output, components/output/custom, language-cpp.svg
+    Sigma-Delta Output, components/output/sigma_delta, sigma-delta.svg
     Template Output, components/output/template, description.svg
     BP1658CJ, components/output/bp1658cj, bp1658cj.svg
     BP5758D, components/output/bp5758d, bp5758d.svg