esphome-docs/components/sensor/atm90e32.rst

ATM90E32 Power Sensor
=====================

.. seo::
    :description: Instructions for setting up ATM90E32 energy metering sensors
    :image: atm90e32.jpg
    :keywords: ATM90E32, CircuitSetup, Split Single Phase Real Time Whole House Energy Meter, Expandable 6 Channel ESP32 Energy Meter Main Board

The ``atm90e32`` sensor platform allows you to use your ATM90E32 voltage/current and power sensors
(`datasheet <http://ww1.microchip.com/downloads/en/devicedoc/Atmel-46003-SE-M90E32AS-Datasheet.pdf>`__) with
ESPHome. This sensor is commonly found in CircuitSetup 2 and 6 channel energy meters and the `Gelidus Research <https://www.gelidus.ca/>`__ 2 channel power meter.

Communication with the device is done via an :ref:`SPI bus <spi>`, so you need to have an ``spi:`` entry in your configuration
with both ``mosi_pin`` and ``miso_pin`` set.

The ATM90E32 IC can measure up to three AC voltages although typically only one
voltage measurement would be used for the mains electricity phase of a
household. Three current measurements are read via CT clamps.

The `CircuitSetup Split Single Phase Energy Meter <https://circuitsetup.us/index.php/product/split-single-phase-real-time-whole-house-energy-meter-v1-2/>`__ can read 2 current channels and 1 (expandable to 2) voltage channel.

.. figure:: images/atm90e32-cs-2chan-full.jpg
    :align: center
    :width: 50.0%

    CircuitSetup Split Single Phase Real Time Whole House Energy Meter.

The `CircuitSetup 6-Channel Energy Monitor <https://circuitsetup.us/index.php/product/expandable-6-channel-esp32-energy-meter/>`__ can read 6 current channels and 2 voltage channels at a time, this board has two ATM90E32 ICs and requires two sensors to be configured in ESPHome.

.. figure:: images/atm90e32-cs-6chan-full.jpg
    :align: center
    :width: 50.0%

    CircuitSetup Expandable 6 Channel ESP32 Energy Meter Main Board.

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

- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin CS is connected to. For the 6 channel meter main board, this will always be 5 and 4. For the add-on boards a jumper can be selected for each CS pin, but default to 0 and 16.
- **line_frequency** (**Required**, string): The AC line frequency of the supply voltage. One of ``50Hz``, ``60Hz``.
- **phase_a** (*Optional*): The configuration options for the 1st phase.

  - **voltage** (*Optional*): Use the voltage value of this phase in V (RMS).
    All options from :ref:`Sensor <config-sensor>`.
  - **current** (*Optional*): Use the current value of this phase in amperes. All options from
    :ref:`Sensor <config-sensor>`.
  - **power** (*Optional*): Use the power value on this phase in watts. All options from
    :ref:`Sensor <config-sensor>`.
  - **reactive_power** (*Optional*): Use the reactive power value on this phase. All options from
    :ref:`Sensor <config-sensor>`.
  - **power_factor** (*Optional*): Use the power factor value on this phase. All options from
    :ref:`Sensor <config-sensor>`.
  - **phase_angle** (*Optional*): Use the phase angle value on this phase in degrees. All options from
    :ref:`Sensor <config-sensor>`.
  - **peak_current** (*Optional*): Use the peak current value on this phase in amperes. All options from
    :ref:`Sensor <config-sensor>`.
  - **harmonic_power** (*Optional*): Use the harmonic power value on this phase. All options from
    :ref:`Sensor <config-sensor>`.
  - **gain_voltage** (*Optional*, int): Voltage gain to scale the low voltage AC power pack to household mains feed.
    Defaults to ``7305``.
  - **gain_ct** (*Optional*, int): CT clamp calibration for this phase.
    Defaults to ``27961``.
  - **forward_active_energy** (*Optional*): Use the forward active energy value on this phase in watt-hours.
    All options from :ref:`Sensor <config-sensor>`.
  - **reverse_active_energy** (*Optional*): Use the reverse active energy value on this phase in watt-hours.
    All options from :ref:`Sensor <config-sensor>`.

- **phase_b** (*Optional*): The configuration options for the 2nd phase. Same options as 1st phase.
- **phase_c** (*Optional*): The configuration options for the 3rd phase. Same options as 1st phase.
- **frequency** (*Optional*): Use the frequenycy value calculated by the meter. All options from
  :ref:`Sensor <config-sensor>`.
- **peak_current_signed** (*Optional*, boolean): Control the peak current output as signed or absolute. Defaults to ``false``.
- **chip_temperature** (*Optional*): Use the chip temperature value. All options from
  :ref:`Sensor <config-sensor>`.
- **gain_pga** (*Optional*, string): The gain for the CT clamp, ``2X`` for 100A, ``4X`` for 100A - 200A. One of ``1X``, ``2X``, ``4X``.
  Defaults to ``2X`` which is suitable for the popular SCT-013-000 clamp.
- **current_phases** (*Optional*): The number of phases the meter has, ``2`` or, ``3``
  The 6 Channel Expandable Energy Meter should be set to ``3``, and the Split Single Phase meter should be set to ``2``. Defaults to ``3``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component <spi>` if you want
  to use multiple SPI buses.

Calibration
-----------

This sensor needs calibration to show correct values. The default gain configuration is set to use the `SCT-013-000 <https://amzn.to/2E0KVvo>`__
current transformers, and the `Jameco Reliapro 9v AC transformer <https://amzn.to/2XcWJjI>`__.
A load which uses a known amount of current can be used to calibrate. For for a more accurate calibration use a
`Kill-A-Watt <https://amzn.to/2TXT7jx>`__ meter or similar, mains voltages can fluctuate depending on grid load.

Voltage
^^^^^^^

Use the expected mains voltage for your region 110V/230V or plug in the Kill-A-Watt and select voltage. See what
value the ATM90E32 sensor reports for voltage. To adjust the sensor use the calculation:

``New gain_voltage = (your voltage reading / ESPHome voltage reading) * existing gain_voltage value``

Update **gain_voltage** for all phases in your ESPHome yaml, recompile and upload. Repeat as necessary.

Here are common voltage calibrations for the **Split Single Energy Meter**:
   For meter <= v1.3:
      - 42080 - 9v AC Transformer - Jameco 112336
      - 32428 - 12v AC Transformer - Jameco 167151
   For meter > v1.4:
      - 37106 - 9v AC Transformer - Jameco 157041
      - 38302 - 9v AC Transformer - Jameco 112336
      - 29462 - 12v AC Transformer - Jameco 167151
   For Meters >= v1.4 rev.3
      - 3920 - 9v AC Transformer - Jameco 157041

Here are common voltage calibrations for the **Expandable 6 Channel Energy Meter**:
   For meter <= v1.2:
      - 42080 - 9v AC Transformer - Jameco 112336
      - 32428 - 12v AC Transformer - Jameco 167151
   For meter > v1.3:
      - 7305 - 9v AC Transformer - Jameco 157041

Current
^^^^^^^

Switch on the current load and see what value the ATM90E32 sensor reports for
current on the selected phase. Using the known or measured current adjust the
sensor using calculation:

``New gain_ct = (your current reading / ESPHome current reading) * existing gain_ct value``

Update **gain_ct** for the phase in your ESPHome yaml, recompile and upload. Repeat as necessary.

It is possible that the two identical CT current sensors will have different
**gain_ct** numbers due to variances in manufacturing, although it will be
small. The current calibration can be done once and used on all sensors or
repeated for each one.

Here are common current calibration values for the **Split Single Phase Energy Meter** when **gain_pga** is set to ``4X``:
   - 200A/100mA SCT-024: 12597

Here are common current calibration values for the **Split Single Phase Energy Meter** when **gain_pga** is set to ``2X``:
   - 20A/25mA SCT-006: 10170
   - 100A/50mA SCT-013-000: 25498
   - 120A/40mA SCT-016: 39473
   - Magnalab 100A: 46539

Here are common current calibrations for the **Expandable 6 Channel Energy Meter** when **gain_pga** is set to ``1X``:
   - 20A/25mA SCT-006: 11131
   - 30A/1V SCT-013-030: 8650
   - 50A/1V SCT-013-050: 15420
   - 80A/26.6mA SCT-010: 41996 (note this will saturate at 2^16/10^3 amps)
   - 100A/50ma SCT-013-000: 27961
   - 120A/40mA: SCT-016: 41880

Active Energy
^^^^^^^^^^^^^

The ATM90E32 chip has a high-precision built-in ability to count the amount of consumed energy on a per-phase basis.
For each phase both the Forward and Reverse active energy is counted in watt-hours.
Forward Active Energy is used to count consumed energy, whereas Reverse Active Energy is used to count exported energy
(e.g. with solar pv installations).
The counters are reset every time a given active energy value is read from the ATM90E32 chip.

Current implementation targets users who retrieve the energy values with a regular interval and store them in
a time-series-database, e.g. InfluxDB.

**Example:**

.. code-block:: yaml

    sensor:
    #IC1 Main
      - platform: atm90e32
        cs_pin: GPIOXX
        phase_a:
          forward_active_energy:
            name: ${disp_name} ct1 FAWattHours
            id: ct1FAWattHours
            state_topic: ${disp_name}/ct1/forward_active_energy
          reverse_active_energy:
            name: ${disp_name} ct1 RAWattHours
            id: ct1RAWattHours
            state_topic: ${disp_name}/ct1/reverse_active_energy

If the power, power_factor, reactive_power, forward_active_energy, or reverse_active_energy configuraion variables
are used, care must be taken to ensure that the line ATM90E32's voltage is from is the same phase as the current
transformer is installed on.  This is significant in split-phase or multi phase installations.  On a house with 240
split-phase wiring (very common in the US), one simple test is to reverse the orentation of the current transformer
on a line. If the power factor doesn't change sign, it is likely that the voltage fed to the ATM90E32 is from the other
phase.

The CircuitSetup Expandable 6 channel board can easilly handle this situation by cutting the jumpers JP12/13 to
allow a seperate VA2 to be input on the J3 pads. Make sure that current taps connected to CT 1-3 are on the phase
from which VA is fed (the barrel jack) and the taps connected to CT3-6 are on the phase from which VA2 is fed. See
the CicuitSetup repo for more details on this.

If a mulit board stack is being used, remember to cut JP12/13 on all boards and to feed VA2 to each board. VA is
fed to all boards through the stacking headers. Another detail is that each voltage transformer needs to have the
same polarity; getting this backwards will be just like having it on the wrong phase.

Note that the current measurement is the RMS value so is always positive. They only way to determine directon is to
look at the power factor. If there are only largly resistive loads and no power sources, (PF almost 1), it is simpler
to just create a template sensor that computes power from Irms*Vrms and ignore all these details. On the other
hand, one might be surprised how reactive some loads are and the CirciuitSetup designs are able to
handle these situations well.

Additional Examples
-------------------

.. code-block:: yaml

    # Example configuration entry for split single phase meter
    spi:
      clk_pin: GPIOXX
      miso_pin: GPIOXX
      mosi_pin: GPIOXX

    sensor:
      - platform: atm90e32
        cs_pin: GPIOXX
        phase_a:
          voltage:
            name: "EMON Line Voltage A"
          current:
            name: "EMON CT1 Current"
          power:
            name: "EMON Active Power CT1"
          reactive_power:
            name: "EMON Reactive Power CT1"
          power_factor:
            name: "EMON Power Factor CT1"
          gain_voltage: 3920
          gain_ct: 39473
        phase_c:
          current:
            name: "EMON CT2 Current"
          power:
            name: "EMON Active Power CT2"
          reactive_power:
            name: "EMON Reactive Power CT2"
          power_factor:
            name: "EMON Power Factor CT2"
          gain_voltage: 3920
          gain_ct: 39473
        frequency:
          name: "EMON Line Frequency"
        chip_temperature:
          name: "EMON Chip Temperature"
        line_frequency: 50Hz
        current_phases: 2
        gain_pga: 2X
        update_interval: 60s

.. code-block:: yaml

    # Example CircuitSetup 6-channel entry
    spi:
      clk_pin: 18
      miso_pin: 19
      mosi_pin: 23
    sensor:
      - platform: atm90e32
        cs_pin: 5
        phase_a:
          voltage:
            name: "EMON Line Voltage A"
          current:
            name: "EMON CT1 Current"
          power:
            name: "EMON Active Power CT1"
          gain_voltage: 7305
          gain_ct: 12577
        phase_b:
          current:
            name: "EMON CT2 Current"
          power:
            name: "EMON Active Power CT2"
          gain_voltage: 7305
          gain_ct: 12577
        phase_c:
          current:
            name: "EMON CT3 Current"
          power:
            name: "EMON Active Power CT3"
          gain_voltage: 7305
          gain_ct: 12577
        frequency:
          name: "EMON Line Frequency"
        line_frequency: 50Hz
        current_phases: 3
        gain_pga: 1X
        update_interval: 60s
      - platform: atm90e32
        cs_pin: 4
        phase_a:
          current:
            name: "EMON CT4 Current"
          power:
            name: "EMON Active Power CT4"
          gain_voltage: 7305
          gain_ct: 12577
        phase_b:
          current:
            name: "EMON CT5 Current"
          power:
            name: "EMON Active Power CT5"
          gain_voltage: 7305
          gain_ct: 12577
        phase_c:
          current:
            name: "EMON CT6 Current"
          power:
            name: "EMON Active Power CT6"
          gain_voltage: 7305
          gain_ct: 12577
        line_frequency: 50Hz
        current_phases: 3
        gain_pga: 1X
        update_interval: 60s


.. code-block:: yaml

    # Example CircuitSetup 6-channel without jumpers jp9-jp11 joined or < meter v1.4
    # power is calculated in a template

    substitutions:
      disp_name: 6C
      update_time: 10s
      current_cal: '27961'

    spi:
      clk_pin: 18
      miso_pin: 19
      mosi_pin: 23
    sensor:
      - platform: atm90e32
        cs_pin: 5
        phase_a:
          voltage:
            name: ${disp_name} Volts A
            id: ic1Volts
            accuracy_decimals: 1
          current:
            name: ${disp_name} CT1 Amps
            id: ct1Amps
          gain_voltage: 7305
          gain_ct: ${current_cal}
        phase_b:
          current:
            name: ${disp_name} CT2 Amps
            id: ct2Amps
          gain_ct: ${current_cal}
        phase_c:
          current:
            name: ${disp_name} CT3 Amps
            id: ct3Amps
          gain_ct: ${current_cal}
        frequency:
          name: ${disp_name} Freq A
        line_frequency: 60Hz
        current_phases: 3
        gain_pga: 1X
        update_interval: ${update_time}
      - platform: atm90e32
        cs_pin: 4
        phase_a:
          voltage:
            name: ${disp_name} Volts B
            id: ic2Volts
            accuracy_decimals: 1
          current:
            name: ${disp_name} CT4 Amps
            id: ct4Amps
          gain_voltage: 7305
          gain_ct: ${current_cal}
        phase_b:
          current:
            name: ${disp_name} CT5 Amps
            id: ct5Amps
          gain_ct: ${current_cal}
        phase_c:
          current:
            name: ${disp_name} CT6 Amps
            id: ct6Amps
          gain_ct: ${current_cal}
        frequency:
          name: ${disp_name} Freq B
        line_frequency: 60Hz
        current_phases: 3
        gain_pga: 1X
        update_interval: ${update_time}

    #Watts per channel
      - platform: template
        name: ${disp_name} CT1 Watts
        id: ct1Watts
        lambda: return id(ct1Amps).state * id(ic1Volts).state;
        accuracy_decimals: 0
        unit_of_measurement: W
        icon: "mdi:flash-circle"
        update_interval: ${update_time}
      - platform: template
        name: ${disp_name} CT2 Watts
        id: ct2Watts
        lambda: return id(ct2Amps).state * id(ic1Volts).state;
        accuracy_decimals: 0
        unit_of_measurement: W
        icon: "mdi:flash-circle"
        update_interval: ${update_time}
      - platform: template
        name: ${disp_name} CT3 Watts
        id: ct3Watts
        lambda: return id(ct3Amps).state * id(ic1Volts).state;
        accuracy_decimals: 0
        unit_of_measurement: W
        icon: "mdi:flash-circle"
        update_interval: ${update_time}
      - platform: template
        name: ${disp_name} CT4 Watts
        id: ct4Watts
        lambda: return id(ct4Amps).state * id(ic2Volts).state;
        accuracy_decimals: 0
        unit_of_measurement: W
        icon: "mdi:flash-circle"
        update_interval: ${update_time}
      - platform: template
        name: ${disp_name} CT5 Watts
        id: ct5Watts
        lambda: return id(ct5Amps).state * id(ic2Volts).state;
        accuracy_decimals: 0
        unit_of_measurement: W
        icon: "mdi:flash-circle"
        update_interval: ${update_time}
      - platform: template
        name: ${disp_name} CT6 Watts
        id: ct6Watts
        lambda: return id(ct6Amps).state * id(ic2Volts).state;
        accuracy_decimals: 0
        unit_of_measurement: W
        icon: "mdi:flash-circle"
        update_interval: ${update_time}
    #Total Amps
      - platform: template
        name: ${disp_name} Total Amps
        id: totalAmps
        lambda: return id(ct1Amps).state + id(ct2Amps).state + id(ct3Amps).state + id(ct4Amps).state + id(ct5Amps).state + id(ct6Amps).state ;
        accuracy_decimals: 2
        unit_of_measurement: A
        icon: "mdi:flash"
        update_interval: ${update_time}
    #Total Watts
      - platform: template
        name: ${disp_name} Total Watts
        id: totalWatts
        lambda: return id(totalAmps).state * id(ic1Volts).state;
        accuracy_decimals: 1
        unit_of_measurement: W
        icon: "mdi:flash-circle"
        update_interval: ${update_time}
    #kWh
      - platform: total_daily_energy
        name: ${disp_name} Total kWh
        power_id: totalWatts
        filters:
          - multiply: 0.001
        unit_of_measurement: kWh

Harmonic Power
--------------

Harmonic power in AC systems refers to deviations from the ideal sinusoidal waveform, caused by multiples of the
fundamental frequency. It results from non-linear loads and can lead to issues like voltage distortion, equipment
overheating, and misoperation of protective devices. The ATM90E32 can output advanced harmonic power measurements
providing important analysis data for monitoring power anomalies on the bus.

**Harmonic Power Example:**

.. code-block:: yaml

    sensor:
      - platform: atm90e32
        phase_a:
          harmonic_power:
            name: ${disp_name} CT1 Harmonic Power

Phase Angle
-----------

Phase angle in AC systems represents the angular displacement of a sinusoidal waveform from a reference point.
It's a measure of timing difference between voltage and current. Phase angle is crucial for power factor assessment
and efficient power transfer. This advanced measurement function is available with an ATM90E32.

**Phase Angle Example:**

.. code-block:: yaml

    sensor:
      - platform: atm90e32
        phase_a:
          phase_angle:
            name: ${disp_name} L1 Phase Angle

Peak Current
------------

Peak current in AC systems refers to the maximum value of the alternating current waveform. It signifies the highest
magnitude reached during each cycle of the sinusoidal waveform. Peak current is relevant for sizing components and
assessing the capacity of electrical equipment in the system. This advanced measurement is avaiable from the ATM90E32.
Peak current can be displayed in signed or unsigned format using a bolean parameter which spans all phases.
The default is false which is unsigned.

**Peak Current Example:**

.. code-block:: yaml

    sensor:
      - platform: atm90e32
        phase_a:
          peak_current:
            name: ${disp_name} CT1 Peak Current
      peak_current_signed: True

See Also
--------

- :ref:`sensor-filters`
- :apiref:`atm90e32/atm90e32.h`
- :ghedit:`Edit`