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>
This commit is contained in:
Valentin Ochs
GitHub
parent
833d2d783a
commit
52e7be2e97
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
|
|
@ -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`
|
||||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
After Width: | Height: | Size: 1.9 KiB |
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue