diff --git a/components/output/images/sigma-delta-example.png b/components/output/images/sigma-delta-example.png new file mode 100644 index 000000000..c4cebdc28 Binary files /dev/null and b/components/output/images/sigma-delta-example.png differ diff --git a/components/output/sigma_delta.rst b/components/output/sigma_delta.rst new file mode 100644 index 000000000..f8938c314 --- /dev/null +++ b/components/output/sigma_delta.rst @@ -0,0 +1,81 @@ +Sigma-Delta Output +================== + +This integration uses `sigma-delta 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 `): The cycle interval at which the output is recalculated. +- **pin** (*Optional*, :ref:`Pin Schema `): The pin to pulse. +- **state_change_action** (*Optional*, :ref:`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 `): 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 `): 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 `. + +.. 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 `__ +- :doc:`/components/output/slow_pwm` +- :apiref:`sigma_delta_output/sigma_delta_output.h` +- :ghedit:`Edit` diff --git a/components/output/slow_pwm.rst b/components/output/slow_pwm.rst index 6f3ec6f83..9c129f4d9 100644 --- a/components/output/slow_pwm.rst +++ b/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` diff --git a/images/sigma-delta.svg b/images/sigma-delta.svg new file mode 100644 index 000000000..56a417c2f --- /dev/null +++ b/images/sigma-delta.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + diff --git a/index.rst b/index.rst index a12ee82e0..a8a2ecf8d 100644 --- a/index.rst +++ b/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