New component: ADE7880 voltage/current/power/energy sensor (#3123)

components/sensor/ade7880.rst

@@ -0,0 +1,311 @@
+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: GPIO13
+        irq1_pin:
+          number: GPIO5
+        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: GPIO13
+        irq1_pin:
+          number: GPIO5
+        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: GPIO13
+        irq1_pin:
+          number: GPIO5
+        reset_pin:
+          number: GPIO16
+        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

images/ade7880.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 132 25" id="svg5" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"><defs id="defs9"/><path d="M5 0H127a5 5 0 015 5v15a5 5 0 01-5 5H5a5 5 0 01-5-5V5a5 5 0 015-5z" style="fill:#000" id="path2"/><g aria-label="ade7880" id="component-text" style="font-weight:900;font-size:25px;font-family:Montserrat;letter-spacing:1.1px;fill:#fffffc"><path d="m14.525 21v-2.425l-.4-.65v-4.6q0-1-.625-1.525-.6-.525-1.975-.525-.925.0-1.875.3Q8.7 11.85 8.025 12.35l-1.8-3.725q1.2-.75 2.875-1.15t3.275-.4q3.525.0 5.45 1.575 1.95 1.575 1.95 5V21zm-3.875.25q-1.675.0-2.8-.575Q6.725 20.1 6.15 19.15 5.575 18.175 5.575 17q0-1.325.675-2.25t2.05-1.4q1.4-.475 3.525-.475h2.85V15.6h-1.95q-.9.0-1.325.3-.4.275-.4.85.0.475.35.8.375.3 1 .3.575.0 1.05-.3.5-.325.725-1l.725 1.675q-.325 1.525-1.375 2.275t-2.825.75z" id="path11"/><path d="m29.575005 21.25q-1.775.0-3.3-.85-1.5-.875-2.4-2.45-.9-1.6-.9-3.8t.9-3.775q.9-1.6 2.4-2.45 1.525-.85 3.3-.85 1.8.0 2.95.775 1.15.75 1.7 2.325.55 1.55.55 3.975.0 2.45-.525 4.025-.5 1.575-1.65 2.325-1.125.75-3.025.75zm1.35-4.4q.625.0 1.125-.3t.8-.9q.3-.625.3-1.5.0-.9-.3-1.475-.3-.6-.8-.9t-1.125-.3-1.125.3-.8.9q-.3.575-.3 1.475.0.875.3 1.5.3.6.8.9t1.125.3zm2.4 4.15v-1.85l-.025-5-.25-5v-6.7h5.65V21z" id="path13"/><path d="m49.850003 21.25q-2.5.0-4.375-.925-1.85-.925-2.875-2.525-1.025-1.625-1.025-3.65.0-2.075 1-3.675 1.025-1.6 2.775-2.5 1.775-.9 3.975-.9 2.025.0 3.725.8 1.725.8 2.75 2.375 1.05 1.575 1.05 3.9.0.3-.025.675-.025.35-.05.65h-10.525V12.75h7.525l-2.125.725q0-.8-.3-1.35-.275-.575-.775-.875-.5-.325-1.2-.325t-1.225.325q-.5.3-.775.875-.275.55-.275 1.35v.85q0 .875.35 1.5t1 .95q.65.3 1.575.3.95.0 1.55-.25.625-.25 1.3-.75l2.95 2.975q-1 1.075-2.475 1.65-1.45.55-3.5.55z" id="path15"/><path d="m61.07501 21 6.6-15.4 1.575 2.475h-8.3l2.3-2.675v5.225h-4.875V3.5h14.975V7.125L67.52501 21z" id="path17"/><path d="m83.175035 21.4q-2.325.0-4.1-.675-1.75-.7-2.75-1.95-1-1.275-1-2.975.0-1.7 1.025-2.9 1.025-1.2 2.8-1.825 1.775-.625 4.025-.625t4.025.625 2.8 1.825q1.025 1.2 1.025 2.9t-1 2.975q-1 1.25-2.775 1.95-1.75.675-4.075.675zm0-3.975q.85.0 1.375-.475.55-.5.55-1.35t-.55-1.325q-.525-.5-1.375-.5t-1.4.5q-.525.475-.525 1.325t.525 1.35q.55.475 1.4.475zm0-4.125q-2.05.0-3.7-.575-1.625-.6-2.575-1.7-.95-1.125-.95-2.7.0-1.6.925-2.75.925-1.175 2.55-1.825 1.625-.65 3.75-.65t3.75.65q1.625.65 2.55 1.825.925 1.15.925 2.75.0 1.575-.95 2.7-.95 1.1-2.575 1.7-1.625.575-3.7.575zm0-3.225q.6.0 1-.4t.4-1.1q0-.725-.4-1.1-.4-.4-1-.4t-1 .4q-.4.375-.4 1.1.0.7.4 1.1t1 .4z" id="path19"/><path d="m101.22502 21.4q-2.324997.0-4.099997-.675-1.75-.7-2.75-1.95-1-1.275-1-2.975.0-1.7 1.025-2.9 1.025-1.2 2.8-1.825 1.775-.625 4.024997-.625 2.25.0 4.025.625t2.8 1.825q1.025 1.2 1.025 2.9t-1 2.975q-1 1.25-2.775 1.95-1.75.675-4.075.675zm0-3.975q.85.0 1.375-.475.55-.5.55-1.35t-.55-1.325q-.525-.5-1.375-.5t-1.399997.5q-.525.475-.525 1.325t.525 1.35q.549997.475 1.399997.475zm0-4.125q-2.049997.0-3.699997-.575-1.625-.6-2.575-1.7-.95-1.125-.95-2.7.0-1.6.925-2.75.925-1.175 2.55-1.825 1.625-.65 3.749997-.65 2.125.0 3.75.65 1.625.65 2.55 1.825.925 1.15.925 2.75.0 1.575-.95 2.7-.95 1.1-2.575 1.7-1.625.575-3.7.575zm0-3.225q.6.0 1-.4t.4-1.1q0-.725-.4-1.1-.4-.4-1-.4t-1 .4q-.399997.375-.399997 1.1.0.7.399997 1.1.4.4 1 .4z" id="path21"/><path d="m119.45001 21.4q-2.325.0-4.125-1.075-1.775-1.075-2.8-3.125-1-2.05-1-4.95.0-2.9 1-4.95 1.025-2.05 2.8-3.125 1.8-1.075 4.125-1.075t4.1 1.075q1.8 1.075 2.8 3.125 1.025 2.05 1.025 4.95t-1.025 4.95q-1 2.05-2.8 3.125-1.775 1.075-4.1 1.075zm0-4.725q.575.0 1.025-.4.45-.4.7-1.375.275-.975.275-2.65.0-1.7-.275-2.65-.25-.975-.7-1.375t-1.025-.4-1.025.4-.725 1.375q-.25.95-.25 2.65.0 1.675.25 2.65.275.975.725 1.375.45.4 1.025.4z" id="path23"/></g></svg>

index.rst

@@ -262,6 +262,7 @@ Electricity
 ***********
 .. imgtable::
 
+    ADE7880, components/sensor/ade7880, ade7880.svg, Voltage & Current & Power
     ADE7953, components/sensor/ade7953, ade7953.svg, Power
     ATM90E26, components/sensor/atm90e26, atm90e26.jpg, Voltage & Current & Power
     ATM90E32, components/sensor/atm90e32, atm90e32.jpg, Voltage & Current & Power