Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added pulse width accumulate #4622

Open
wants to merge 7 commits into
base: current
Choose a base branch
from
Open

added pulse width accumulate #4622

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
931bf87
added pulse width accumulate
patrick-kiwi Jan 30, 2025
575c5a0
smaller pic
patrick-kiwi Jan 30, 2025
a8faba2
changed text to reflect impoved accuracy from modified source code
patrick-kiwi Jan 31, 2025
2923c75
added experimental detail
patrick-kiwi Feb 3, 2025
ad723bc
improvements
patrick-kiwi Feb 3, 2025
0cc107c
implement suggested changes
patrick-kiwi Feb 3, 2025
ece4fb5
minor fix
patrick-kiwi Feb 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions components/sensor/pulse_width_accumulate.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
Pulse Width Sensor
==================

.. seo::
:description: Instructions for setting up pulse width accumulation sensors
in ESPHome to measure total on-time of GPIO inputs for MOSFETs and TRIACs


The ``pulse_width_accumulate`` sensor allows you to sum the total on-time of
a GPIO input. For example, this can be used to externally measure the on-time
of a rapidly switched MOSFET or TRIAC. The sensor zeros itself every polling
interval. Units of measurement are on-time seconds per update interval.
An optional frequency sensor is also provided.

.. Note::

Threshold stability values were experimentally determined for an ESP32 DevKit-v4:
- Minimum pulse width: ≥ 25 µs
- Minimum pulse width delay: ≥ 75 µs
- Maximum implied frequency: ~10 kHz
- Maximum polling window: 71.58 minutes (see text below)

.. code-block:: yaml

# Example configuration entry
sensor:
- platform: pulse_width_accumulate
pin: GPIO32
name: Cumulative on-time sensor
frequency:
name: Average frequency sensor


.. note::

Important implementation details:

Check failure on line 36 in components/sensor/pulse_width_accumulate.rst

View workflow job for this annotation

GitHub Actions / build 

Directive 'note' must be indented with 4 spaces, not 2. See components/sensor/pulse_width_accumulate.rst:36

1. The polling function resets the microsecond counter to prevent overflow at 71.58 minutes
2. Sensor accuracy is a function of the input signal frequency:
- Test Condition #1 (25 µs pulses, 75 µs delay, 1 sec polling, 27380 samples):
* Frequency. Expected 10 kHz. Observed mean 9980.5 Hz. Standard deviation=5.5 Hz
* On-time. Expected based on time stamps 6846.75 s. Observed 6844.33 s
- Test Condition #2 (300 µs pulses, 300 µs delay, 1 min polling, 289 samples):
* Frequency, expected 1666.67 Hz, Observed mean 1666.57 Hz, standard deviation=0.08 Hz
* On-time. Expected based on time stamps 8640 s. Observed 8639.98 s

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix note directive indentation.

The note directive must be indented with 4 spaces, not 2, to comply with RST formatting requirements.

-.. note::
-
-  Important implementation details:
-
-  1. The polling function resets the microsecond counter to prevent overflow at 71.58 minutes
-  2. Sensor accuracy is a function of the input signal frequency: 
-    - Test Condition #1 (25 µs pulses, 75 µs delay, 1 sec polling, 27380 samples):
-      * Frequency. Expected 10 kHz. Observed mean 9980.5 Hz. Standard deviation=5.5 Hz
-      * On-time. Expected based on time stamps 6846.75 s. Observed 6844.33 s
-    - Test Condition #2 (300 µs pulses, 300 µs delay, 1 min polling, 289 samples):
-      * Frequency, expected 1666.67 Hz, Observed mean 1666.57 Hz, standard deviation=0.08 Hz
-      * On-time. Expected based on time stamps 8640 s. Observed 8639.98 s  
+.. note::
+
+    Important implementation details:
+
+    1. The polling function resets the microsecond counter to prevent overflow at 71.58 minutes
+    2. Sensor accuracy is a function of the input signal frequency: 
+        - Test Condition #1 (25 µs pulses, 75 µs delay, 1 sec polling, 27380 samples):
+            * Frequency. Expected 10 kHz. Observed mean 9980.5 Hz. Standard deviation=5.5 Hz
+            * On-time. Expected based on time stamps 6846.75 s. Observed 6844.33 s
+        - Test Condition #2 (300 µs pulses, 300 µs delay, 1 min polling, 289 samples):
+            * Frequency, expected 1666.67 Hz, Observed mean 1666.57 Hz, standard deviation=0.08 Hz
+            * On-time. Expected based on time stamps 8640 s. Observed 8639.98 s
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
.. note::
Important implementation details:
1. The polling function resets the microsecond counter to prevent overflow at 71.58 minutes
2. Sensor accuracy is a function of the input signal frequency:
- Test Condition #1 (25 µs pulses, 75 µs delay, 1 sec polling, 27380 samples):
* Frequency. Expected 10 kHz. Observed mean 9980.5 Hz. Standard deviation=5.5 Hz
* On-time. Expected based on time stamps 6846.75 s. Observed 6844.33 s
- Test Condition #2 (300 µs pulses, 300 µs delay, 1 min polling, 289 samples):
* Frequency, expected 1666.67 Hz, Observed mean 1666.57 Hz, standard deviation=0.08 Hz
* On-time. Expected based on time stamps 8640 s. Observed 8639.98 s
.. note::
Important implementation details:
1. The polling function resets the microsecond counter to prevent overflow at 71.58 minutes
2. Sensor accuracy is a function of the input signal frequency:
- Test Condition #1 (25 µs pulses, 75 µs delay, 1 sec polling, 27380 samples):
* Frequency. Expected 10 kHz. Observed mean 9980.5 Hz. Standard deviation=5.5 Hz
* On-time. Expected based on time stamps 6846.75 s. Observed 6844.33 s
- Test Condition #2 (300 µs pulses, 300 µs delay, 1 min polling, 289 samples):
* Frequency, expected 1666.67 Hz, Observed mean 1666.57 Hz, standard deviation=0.08 Hz
* On-time. Expected based on time stamps 8640 s. Observed 8639.98 s
🧰 Tools
🪛 GitHub Check: build

[failure] 36-36:
Directive 'note' must be indented with 4 spaces, not 2. See components/sensor/pulse_width_accumulate.rst:36

🪛 GitHub Actions: Lint

[error] 36-36: Directive 'note' must be indented with 4 spaces, not 2


Configuration variables:
------------------------

- **pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin to observe for the
pulse width.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor.
Defaults to ``60s``.

- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.

See Also
--------

- :ref:`sensor-filters`
- :apiref:`pulse_width_accumulate/pulse_width_accumulate.h`
- :apiref:`pulse_width/pulse_width.h`
- :apiref:`pulse_meter/pulse_meter_sensor.h`
- :ghedit:`Edit`

Loading