mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-11-05 09:20:08 +01:00
134 lines
5.3 KiB
ReStructuredText
134 lines
5.3 KiB
ReStructuredText
HLW8012 Power Sensor
|
|
====================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up HLW8012 power sensors for the Sonoff Pow R1
|
|
:image: hlw8012.svg
|
|
:keywords: HLW8012, CSE7759, BL0937, Sonoff Pow R1
|
|
|
|
The ``hlw8012`` sensor platform allows you to use your HLW8012 voltage/current and power sensors
|
|
(`datasheet <https://github.com/xoseperez/hlw8012/blob/master/docs/HLW8012.pdf>`__) sensors with
|
|
ESPHome. This sensor is commonly found in Sonoff POWs. CSE7759 and BL0937 are similar to HLW8012
|
|
and work with this integration. Beware that CSE7759B is different and should be used
|
|
with the :doc:`CSE7766 <cse7766>` integration.
|
|
|
|
.. note::
|
|
|
|
SAFETY HAZARD: Some devices such as Sonoff POWs/Shelly/etc, have the digital GND connected directly to mains voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent any use of the dangerous digital pins.
|
|
|
|
This sensor has two data outputs which both encode values using the frequency of a modulated signal: CF and CF1.
|
|
CF's frequency is proportional to the (active) power measured and CF1 is proportional to the current/voltage. Using
|
|
the SEL pin, one can choose between which mode to use.
|
|
|
|
ESPHome will continuously cycle the state of the SEL pin to measure current *and* voltage, though both cannot
|
|
be measured at the same exact points in time.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
sensor:
|
|
- platform: hlw8012
|
|
sel_pin: 5
|
|
cf_pin: 14
|
|
cf1_pin: 13
|
|
current:
|
|
name: "HLW8012 Current"
|
|
voltage:
|
|
name: "HLW8012 Voltage"
|
|
power:
|
|
name: "HLW8012 Power"
|
|
energy:
|
|
name: "HLW8012 Energy"
|
|
update_interval: 60s
|
|
|
|
.. note::
|
|
|
|
The configuration above should work for Sonoff POWs (R1).
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **sel_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin SEL is connected to.
|
|
- **cf_pin** (**Required**, :ref:`config-pin`): The pin CF is connected to.
|
|
- **cf1_pin** (**Required**, :ref:`config-pin`): The pin CF1 is connected to.
|
|
- **current** (*Optional*): Use the current value of the sensor in amperes. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **power** (*Optional*): Use the (active) power value of the sensor in watts. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **voltage** (*Optional*): Use the voltage value of the sensor in V (RMS).
|
|
All options from :ref:`Sensor <config-sensor>`.
|
|
- **energy** (*Optional*): Use the total energy value of the sensor in Wh.
|
|
All options from :ref:`Sensor <config-sensor>`.
|
|
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
|
|
|
|
Advanced Options:
|
|
|
|
- **current_resistor** (*Optional*, float): The value of the shunt resistor for current measurement.
|
|
Defaults to the Sonoff POW's value ``0.001 ohm``.
|
|
- **voltage_divider** (*Optional*, float): The value of the voltage divider on the board as ``(R_upstream + R_downstream) / R_downstream``.
|
|
Defaults to the Sonoff POW's value ``2351``.
|
|
- **model** (*Optional*, string): The sensor model on the board, to set internal constant factors to convert pulses to measurements.
|
|
Possible values are ``HLW8012``, ``CSE7759``, ``BL0937``. Defaults to ``HLW8012``.
|
|
CSE7759 uses same constants and it also works with default. Must be set for BL0937 to be able to calibrate all three measurements at the same time.
|
|
- **change_mode_every** (*Optional*, int): After how many updates to cycle between the current/voltage measurement mode.
|
|
Note that the first value after switching is discarded because it is often inaccurate. Defaults to ``8``.
|
|
- **initial_mode** (*Optional*, string): The initial measurement mode. Defaults to ``VOLTAGE``.
|
|
Possible initial measurement modes are ``VOLTAGE`` or ``CURRENT``.
|
|
|
|
Permanent SEL Pin
|
|
-----------------
|
|
|
|
Some devices have the SEL pin permanently pulled high or low. If this is the case, you can configure
|
|
the initial measurement mode to match whichever mode the device uses, and disable mode switching.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry for device with fixed measurement mode
|
|
sensor:
|
|
- platform: hlw8012
|
|
sel_pin: 5
|
|
cf_pin: 14
|
|
cf1_pin: 13
|
|
current:
|
|
name: "HLW8012 Current"
|
|
voltage:
|
|
name: "HLW8012 Voltage"
|
|
power:
|
|
name: "HLW8012 Power"
|
|
update_interval: 60s
|
|
initial_mode: CURRENT
|
|
change_mode_every: 4294967295
|
|
|
|
SEL Pin Inversion
|
|
-----------------
|
|
|
|
If using model ``BL0937`` the function of the SEL pin is inverted compared to default. When SEL=0 current is measured,
|
|
when SEL=1 voltage is measured. To accommodate this change use the following configuration:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry for device BL0937 using inverted SEL pin functionality
|
|
sensor:
|
|
- platform: hlw8012
|
|
model: BL0937
|
|
sel_pin:
|
|
number: 12
|
|
inverted: true
|
|
cf_pin: 4
|
|
cf1_pin: 5
|
|
current:
|
|
name: "BL0937 Current"
|
|
voltage:
|
|
name: "BL0937 Voltage"
|
|
power:
|
|
name: "BL0937 Power"
|
|
update_interval: 60s
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`sensor-filters`
|
|
- :apiref:`hlw8012/hlw8012.h`
|
|
- `HLW8012 Library <https://github.com/xoseperez/hlw8012>`__ by `Xose Pérez <https://github.com/xoseperez>`__
|
|
- :ghedit:`Edit`
|