mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-11-18 11:15:36 +01:00
88e315e0e4
* Many example yaml tidy-ups * Update components/sensor/hlw8012.rst --------- Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
312 lines
12 KiB
ReStructuredText
312 lines
12 KiB
ReStructuredText
ADE7880 Power Sensor
|
|
====================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up ADE7880 energy metering sensors
|
|
:keywords: ADE7880, Shelly 3EM
|
|
|
|
The ``ade7880`` sensor platform allows you to use ADE7880
|
|
voltage/current/power sensors (`datasheet`_) with ESPHome. This sensor
|
|
chip is commonly found in Shelly 3EM and 3EM Pro devices.
|
|
|
|
Communication with the chip is over an :ref:`I2C bus <i2c>`, so
|
|
you need to have an ``i2c:`` entry in your configuration with both
|
|
``sda`` and ``scl`` set. It is also recommended to set the I2C
|
|
``frequency`` to ``200kHz`` or higher, if the board containing the
|
|
chip can support it (this speed has been verified to work in the
|
|
Shelly 3EM). While this is not necessary, if a significant number of
|
|
the ``ade7880`` individual sensors (e.g. more than six) are enabled,
|
|
the time consumed by the I2C transactions can be substantial and
|
|
result in warning messages in the ESPHome logs.
|
|
|
|
The ADE7880 chip can measure up to three power phases, along with a
|
|
neutral. Current can be measured on all four inputs, while voltage and
|
|
power can be measured on the power phases. Current is measured using
|
|
CT clamps.
|
|
|
|
While the chip is designed for 3-phase AC power, the phase inputs are
|
|
independent of each other, so the chip can be used with single-phase
|
|
and two-phase AC power circuits as well (or a mixture of them).
|
|
|
|
Instantaneous vs. Accumulated Sensors
|
|
-------------------------------------
|
|
|
|
The digital signal processor (DSP) in the ADE7880 executes its
|
|
computations 8,000 times per second. As a result, each sensor listed
|
|
below as 'instantaneous' reports the computed value from the most
|
|
recent DSP cycle; it does not report an average over the time period
|
|
since the last update.
|
|
|
|
Each sensor listed as 'accumulated' below reports the sum of all
|
|
computed values since the last update.
|
|
|
|
The update interval defaults to 60 seconds, but can be lowered if you
|
|
wish to have more frequent readings; this will increase the load (and
|
|
database growth) of the connected Home Assistant correspondingly.
|
|
|
|
Configuration Variables
|
|
-----------------------
|
|
|
|
- **irq1_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`):
|
|
The GPIO pin that the ADE7880's IRQ1 output is connected to. The
|
|
``ade7880`` component uses this input to determine when the ADE7880
|
|
chip has completed its power-up and reset cycles.
|
|
|
|
- **irq0_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`):
|
|
The GPIO pin that the ADE7880's IRQ0 output is connected to, if
|
|
any. The ``ade7880`` component does not use this input, but if the
|
|
IRQ0 output is connected to a GPIO and that GPIO is *not* configured
|
|
as an ``input``, the chip will produce excessive heat and its
|
|
lifetime could be shortened. The simplest way to ensure that the
|
|
GPIO pin is properly connected is to supply it here, but if you wish
|
|
to configure it elsewhere in your configuration that is a reasonable
|
|
alternative.
|
|
|
|
- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`):
|
|
The GPIO pin that the ADE7880's RESET input is connected to, if
|
|
any. If this pin is configured, the ``ade7880`` component will use
|
|
it to initiate a 'hardware reset' of the chip when needed; if this
|
|
pin is not configured, the component will attempt to initiate a
|
|
'software reset' of the chip when needed, but this could fail if the
|
|
chip is not responding properly to the I2C bus.
|
|
|
|
- **frequency** (*Optional*, string): The AC line frequency of the
|
|
supply voltage. The supported range is ``45Hz`` to
|
|
``65Hz``. Defaults to ``50Hz``.
|
|
|
|
- **phase_a** (*Optional*): The configuration variables for the 'A'
|
|
phase inputs of the chip. Refer to the configuration examples below
|
|
for the `simple` and `detailed` sensor configuration options.
|
|
|
|
- **name** (*Optional*, string): The name of the phase, which will
|
|
be used a prefix in the names of all of the phase's sensors.
|
|
|
|
- **voltage** (instantaneous) (*Optional*): Report the RMS voltage
|
|
value of this phase in volts (V). In detailed configuration mode,
|
|
all options from :ref:`Sensor <config-sensor>` are supported.
|
|
|
|
- **current** (instantaneous) (*Optional*): Report the RMS current
|
|
value of this phase in amperes (A). In detailed configuration
|
|
mode, all options from :ref:`Sensor <config-sensor>` are
|
|
supported.
|
|
|
|
- **active_power** (instantaneous) (*Optional*): Report the active
|
|
(consumed) power value of this phase in watts (W). In detailed
|
|
configuration mode, all options from :ref:`Sensor <config-sensor>`
|
|
are supported.
|
|
|
|
- **apparent_power** (instantaneous) (*Optional*): Report the
|
|
apparent (voltage multiplied by current) power value of this phase
|
|
in volt-amperes (VA). In detailed configuration mode, all options
|
|
from :ref:`Sensor <config-sensor>` are supported.
|
|
|
|
- **power_factor** (instantaneous) (*Optional*): Report the power
|
|
factor value of this phase as a percentage (%). In detailed
|
|
configuration mode, all options from :ref:`Sensor <config-sensor>`
|
|
are supported.
|
|
|
|
- **forward_active_energy** (accumulated) (*Optional*): Report the
|
|
forward active energy value of this phase in watt-hours (Wh). In
|
|
detailed configuration mode, all options from :ref:`Sensor
|
|
<config-sensor>` are supported.
|
|
|
|
- **reverse_active_energy** (accumulated) (*Optional*): Report the
|
|
reverse active energy value of this phase in
|
|
volt-ampere-reactive-hours (VARh). In detailed configuration mode,
|
|
all options from :ref:`Sensor <config-sensor>` are supported.
|
|
|
|
- **calibration** (**Required**): The calibration values necessary
|
|
for this phase's sensors to report correct values.
|
|
|
|
- **current_gain** (**Required**, integer): The value for the
|
|
``AIGAIN`` calibration register.
|
|
|
|
- **voltage_gain** (**Required**, integer): The value for the
|
|
``AVGAIN`` calibration register.
|
|
|
|
- **power_gain** (**Required**, integer): The value for the
|
|
``APGAIN`` calibration register.
|
|
|
|
- **phase_angle** (**Required**, integer): The value for the
|
|
``APHCAL`` calibration register.
|
|
|
|
- **phase_b** (*Optional*): The configuration variables for the 'B'
|
|
phase inputs of the chip. Identical to ``phase_a``.
|
|
|
|
- **phase_c** (*Optional*): The configuration variables for the 'C'
|
|
phase inputs of the chip. Identical to ``phase_a``.
|
|
|
|
- **neutral** (*Optional*): The configuration variables for the
|
|
'neutral' phase of the chip.
|
|
|
|
- **name** (*Optional*, string): The name of the phase, which will
|
|
be used a prefix in the names of all of the phase's sensors.
|
|
|
|
- **current** (instantaneous) (**Required**): Report the RMS current
|
|
value of the neutral in amperes (A). In detailed configuration
|
|
mode, all options from :ref:`Sensor <config-sensor>` are
|
|
supported.
|
|
|
|
- **calibration** (**Required**): The calibration values necessary
|
|
for this phase's sensors to report correct values.
|
|
|
|
- **current_gain** (**Required**, integer): The value for the
|
|
``NIGAIN`` calibration register.
|
|
|
|
- **update_interval** (*Optional*, :ref:`config-time`): The interval
|
|
to report the sensor values. Defaults to ``60s``.
|
|
|
|
- **i2c_id** (*Optional*, :ref:`config-id`): Specify the ID of the
|
|
:ref:`I2C Component <i2c>` if your configuration includes multiple
|
|
I2C buses.
|
|
|
|
Calibration
|
|
-----------
|
|
|
|
These sensors needs calibration to report correct values. For the
|
|
Shelly 3EM and 3EM Pro devices, the calibration is performed during
|
|
manufacturing, and the calibration data is included in the firmware
|
|
stored in the device. See the `Shelly 3EM`_ section of the ESPHome
|
|
Devices site for details on how to obtain the calibration data for a
|
|
3EM device.
|
|
|
|
Configuration Examples
|
|
----------------------
|
|
|
|
There are two sensor configuration modes supported: *simple* and
|
|
*detailed*. The mode can be chosen for each sensor indepedently from
|
|
all other sensors.
|
|
|
|
The *simple* mode is useful when you have no need to provide IDs for
|
|
sensors, or to override any of the default sensor settings (unit of
|
|
measurement, device class, state class, decimal accuracy). The value
|
|
provided for each sensor variable will be the sensor's name
|
|
(optionally prefixed with the phase name, if it has been
|
|
configured).
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example simple sensor configuration mode
|
|
sensor:
|
|
- platform: ade7880
|
|
irq0_pin:
|
|
number: GPIOXX
|
|
irq1_pin:
|
|
number: GPIOXX
|
|
phase_a:
|
|
name: Room Heater
|
|
voltage: Voltage
|
|
current: Current
|
|
active_power: Active Power
|
|
power_factor: Power Factor
|
|
forward_active_energy: Forward Active Energy
|
|
reverse_active_energy: Reverse Active Energy
|
|
calibration:
|
|
current_gain: 3116628
|
|
voltage_gain: -757178
|
|
power_gain: -1344457
|
|
phase_angle: 188
|
|
|
|
Because the phase name 'Room Heater' was configured, the resulting
|
|
names for the various sensors will be 'Room Heater Voltage', 'Room
|
|
Heater Current', etc.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example detailed sensor configuration mode
|
|
sensor:
|
|
- platform: ade7880
|
|
irq0_pin:
|
|
number: GPIOXX
|
|
irq1_pin:
|
|
number: GPIOXX
|
|
phase_a:
|
|
voltage: Voltage
|
|
current:
|
|
name: Current
|
|
accuracy_decimals: 0
|
|
active_power: Active Power
|
|
power_factor:
|
|
id: ade_power_factor
|
|
name: Power Factor
|
|
forward_active_energy: Forward Active Energy
|
|
reverse_active_energy: Reverse Active Energy
|
|
calibration:
|
|
current_gain: 3116628
|
|
voltage_gain: -757178
|
|
power_gain: -1344457
|
|
phase_angle: 188
|
|
|
|
In this example, the ``accuracy_decimals`` variable for the
|
|
``current`` sensor has been specified (overriding the default), and an
|
|
``ID`` has been specified for the ``power_factor`` sensor. The
|
|
remaining sensors for the 'A' phase are configured using 'simple'
|
|
configuration mode.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example full platform configuration
|
|
sensor:
|
|
- platform: ade7880
|
|
irq0_pin:
|
|
number: GPIOXX
|
|
irq1_pin:
|
|
number: GPIOXX
|
|
reset_pin:
|
|
number: GPIOXX
|
|
frequency: 60Hz
|
|
phase_a:
|
|
name: Phase A
|
|
voltage: Voltage
|
|
current: Current
|
|
active_power: Active Power
|
|
power_factor: Power Factor
|
|
forward_active_energy: Forward Active Energy
|
|
reverse_active_energy: Reverse Active Energy
|
|
calibration:
|
|
current_gain: 3116628
|
|
voltage_gain: -757178
|
|
power_gain: -1344457
|
|
phase_angle: 188
|
|
phase_b:
|
|
name: Phase B
|
|
voltage: Voltage
|
|
current: Current
|
|
active_power:: Active Power
|
|
power_factor: Power Factor
|
|
forward_active_energy: Forward Active Energy
|
|
reverse_active_energy: Reverse Active Energy
|
|
calibration:
|
|
current_gain: 3133655
|
|
voltage_gain: -755235
|
|
power_gain: -1345638
|
|
phase_angle: 188
|
|
phase_c:
|
|
name: Phase C
|
|
voltage: Voltage
|
|
current: Current
|
|
active_power: Active Power
|
|
power_factor: Power Factor
|
|
forward_active_energy: Forward Active Energy
|
|
reverse_active_energy: Reverse Active Energy
|
|
calibration:
|
|
current_gain: 3111158
|
|
voltage_gain: -743813
|
|
power_gain: -1351437
|
|
phase_angle: 180
|
|
neutral:
|
|
name: Test 3 Unused
|
|
current: Current
|
|
calibration:
|
|
current_gain: 3011156
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`sensor-filters`
|
|
- :apiref:`ade7880/ade7880.h`
|
|
- :ghedit:`Edit`
|
|
|
|
.. _datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ADE7880.pdf
|
|
.. _`Shelly 3EM`: https://devices.esphome.io/devices/Shelly-3EM
|