esphome-docs/components/sensor/pulse_meter.rst
2021-12-02 17:10:24 +13:00

106 lines
3.2 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Pulse Meter Sensor
==================
.. seo::
:description: Instructions for setting up pulse meter sensors.
:image: pulse.svg
The pulse meter sensor allows you to count the number and frequency of pulses on any pin. It is intended to be a drop-in replacement
for :doc:`integration sensor </components/sensor/pulse_counter>`, but offering better resolution.
It measures the time between rising edges on a pin, for each pulse it outputs the frequency in pulses/min.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: pulse_meter
pin: 12
name: "Pulse Meter"
Configuration variables:
------------------------
- **pin** (**Required**, :ref:`config-pin`): The pin to count pulses on.
- **name** (**Required**, string): The name of the sensor.
- **internal_filter** (*Optional*, :ref:`config-time`): If a pulse shorter than this
time is detected, its discarded and no pulse is counted. Defaults to ``13us``. For S0 pulse meters that are used to meter power consumption 50-100 ms is a reasonable value.
- **timeout** (*Optional*, :ref:`config-time`): If we don't see a pulse for this length of time, we assume 0 pulses/sec. Defaults to ``5 min``.
- **total** (*Optional*, :ref:`config-id`): An additional sensor that outputs the total number of pulses counted.
- All other options from :ref:`Sensor <config-sensor>`.
Converting units
----------------
The sensor defaults to units of “pulses/min”. You can change this by using :ref:`sensor-filters`.
For example, if youre using the pulse meter with a photodiode to
count the light pulses on a power meter that outputs 1000 pulses per kWh,
you can use the following to output instantaneous usage in kW:
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: pulse_meter
pin: 12
unit_of_measurement: 'kW'
name: 'Electricity Usage'
filters:
- multiply: 0.06
Counting total pulses
---------------------
When the total sensor is configured, pulse_meter also reports the total
number of pulses measured. When used on a power meter, this can be used to
measure the total consumed energy in kWh.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: pulse_meter
pin: 12
unit_of_measurement: 'kW'
name: 'Electricity Usage'
internal_filter: 100ms
accuracy_decimals: 3
filters:
- multiply: 0.06
total:
name: "Electricity Total"
unit_of_measurement: "kWh"
accuracy_decimals: 3
filters:
- multiply: 0.001
(Re)Setting the total pulse count
---------------------------------
Using this action, you are able to reset/set the total pulse count. This can be useful
if you would like the ``total`` sensor to match what you see on your meter you are
trying to match.
.. code-block:: yaml
on_...:
then:
- pulse_meter.set_total_pulses:
id: pulse_meter_id
value: 12345
.. note::
This value is the raw count of pulses, and not the value you see after the filters
are applied.
See Also
--------
- :ref:`sensor-filters`
- :doc:`/components/sensor/pulse_counter`
- :apiref:`pulse_meter/pulse_meter_sensor.h`
- :ghedit:`Edit`