mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-11-16 10:55:21 +01:00
88e315e0e4
* Many example yaml tidy-ups * Update components/sensor/hlw8012.rst --------- Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
163 lines
9.9 KiB
ReStructuredText
163 lines
9.9 KiB
ReStructuredText
ATM90E26 Power Sensor
|
|
=====================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up ATM90E26 energy metering sensors
|
|
:image: atm90e26.jpg
|
|
:keywords: ATM90E26, Single-Phase High-Performance Wide-SpanEnergy Metering IC, Single Phase Energy Meter
|
|
|
|
The ``atm90e26`` sensor platform allows you to use your ATM90E26 voltage/current and power sensors
|
|
(`datasheet <https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-46002-SE-M90E26-Datasheet.pdf>`__) with
|
|
ESPHome. This sensor is found in the `DitroniX GTEM ESP32 <https://ditronix.net/wiki/gtem-esp32-atm90e26-sdk-v1-specification/>`__ energy meter and other devices.
|
|
|
|
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 ATM90E26 IC measures a single phase's voltage (using a transformer) and current (using a shunt or CT clamp)
|
|
and additionally provides active, reactive, and apparent power, frequency, power factor and phase angle measurements.
|
|
|
|
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``.
|
|
- **meter_constant** (**Required**, float): The number of pulses per kWh. The ATM90E26 internally works based on pulses and
|
|
this value converts a pulse into Wh, which are emitted as ``forward_active_energy`` etc. Matching it against an existing
|
|
meter is useful in that it allows visual confirmation for some devices that blink an LED for each pulse. Common values are
|
|
1000 pulses/kWh, 1666.66 pulses/kWh, or 3200 pulses/kWh. See also **gain_metering** which determines after how much energy
|
|
a pulse is emitted.
|
|
- **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>`.
|
|
- **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>`.
|
|
- **frequency** (*Optional*): Use the frequency value calculated by the meter. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **pl_const** (*Optional*, int): A constant derived from the physical characteristics of your measurement setup. See the Calibration section.
|
|
Defaults to ``1429876``.
|
|
- **gain_metering** (*Optional*, int): This value determines how quickly internal energy registers accumulate and hence defines the value of a "pulse". Matching it against an existing meter is useful in that it allows visual confirmation for some devices that blink an LED for each pulse. See also the **meter_constant**.
|
|
Defaults to ``7481``.
|
|
- **gain_voltage** (*Optional*, int): Voltage gain to scale the low voltage AC power back to household mains feed.
|
|
Defaults to ``26400``.
|
|
- **gain_ct** (*Optional*, int): CT clamp calibration value.
|
|
Defaults to ``31251``.
|
|
- **gain_pga** (*Optional*, string): The gain for the CT clamp. Valid values are ``1X``, ``4X``, ``8X``, ``16X``, and ``24X``.
|
|
Defaults to ``1X``.
|
|
- **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. In order to calibrate your AC-AC transformer and CT clamp
|
|
it is easiest to start with the default values and then adjust them as necessary while measuring a known current.
|
|
For a more accurate calibration you can use a Kill-A-Watt or similar meter.
|
|
|
|
**Voltage** is adjusted linearly to bring the observed value in agreement with a reference measurement. If your
|
|
Kill-A-Watt shows 241 Volts and the ATM90E26 shows 234 Volts using the default `gain_voltage` of 26400, it would
|
|
need to be adjusted to `241 / 234 * 26400 = 27190`.
|
|
|
|
**Current** is best measured with an ideal load (e.g. a space heater). The process is the same as for voltage, but
|
|
you modify the `gain_ct` value instead. For a SCT-013-000 clamp a value of 28621 worked well for me but you should
|
|
calibrate your specific clamp. Note that the ATM90E26 can output a **maximum current of 65A**. If you expect to
|
|
measure higher current, simply "mis-calibrate" the CT clamp by a factor of e.g. 2 so that the ATM90E26 thinks it is
|
|
measuring a lower current (e.g. 10A when 20A are flowing) and multiply the sensor's output by 2.
|
|
|
|
**PL Constant** is computed using the physical characteristics of the device we use. We compute the constant
|
|
as `as 838860800 * gain_pga * <mV at 1A current> * <mV at ref voltage> / (<pulse constant> * <ref voltage>)`.
|
|
See Section 3.2.2 in the
|
|
`application note <https://ww1.microchip.com/downloads/en/Appnotes/Atmel-46102-SE-M90E26-ApplicationNote.pdf>`__
|
|
for additional details. Say we use a SCT-013-000 CT clamp, which has an output of 50mA for 100A input current. Our
|
|
burden has a value of 12 Ohm. We therefore expect to measure 6mV per amp of input current. Say our AC-AC
|
|
transformer outputs 19.3V at 230V and we use a 100:1 voltage divider in front of the ATM90E26. We would therefore
|
|
expect to measure 193 mV at a line voltage of 230V. The resulting PL Constant is, assuming a meter constant of
|
|
3200 pulses/kWh (see below): `838860800 * 1 * 6 * 193 / (3200 * 230) = 1319838`.
|
|
|
|
**Meter Calibration** is completed by matching the ATM90E26's CF1 (active energy) pulse to those of your electricity
|
|
meter by adjusting the `gain_metering` value until the pulses match. Next, set the `meter_constant`, which defines
|
|
how many pulses make up one kWh of energy. If you are matching an existing meter, typical values may be 3200 pulses/kWh,
|
|
1000 pulses/kWh, or for some rotating meters 1666.66 pulses per kWh. If you're not matching against a meter you may
|
|
want to calibrate this value to emit 1000 pulses per kWh, or whatever other value is useful for your project.
|
|
|
|
If your current clamp or voltage transformer aren't well matched to the specific A90E26-based device you're using
|
|
it **may be necessary to multiply values**, to stay within the value ranges specified in the
|
|
`datasheet <https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-46002-SE-M90E26-Datasheet.pdf>`__ and
|
|
`application note <https://ww1.microchip.com/downloads/en/Appnotes/Atmel-46102-SE-M90E26-ApplicationNote.pdf>`__.
|
|
This component will enforce the stated maxima. In the example below, the AC-AC transformer used read 230V line voltage
|
|
as 86.6V with default settings. This would imply a `gain_voltage` value of `230 / 86.6 * 26400 = 70115`.
|
|
However, the chip's application note says this value must be below 32768. If we divide the `gain_voltage` by 4, we
|
|
stay within the specified range, but must then multiply the voltage output as well as the power reading, which are
|
|
off by a factor of 4. This is due to the width of registers in the chip and **is not necessary if your components
|
|
can be calibrated within the specified range.**
|
|
|
|
Keeping the calibration values at the top of your yaml might make editing easier.
|
|
|
|
.. code-block:: yaml
|
|
|
|
substitutions:
|
|
plconst_cal: '1429876' # default: 1429876, compute as 838860800 * (gain_pga * <sampled voltage (mV) at 1Amp current> * <sampled voltage (mV) at reference voltage> / (<pulse constant (e.g. 3200 pulses/kWh)> * <reference voltage, e.g. 230V>))
|
|
current_cal: '32801' # default: 31251
|
|
voltage_cal: '17528' # default: 26400 - Application note says this should be < 32768, maybe for some internal computation?
|
|
metering_cal: '7481' # default: 7481 - Calibrate this to match your meter based on the CF1 (CFx) pulse.
|
|
|
|
spi:
|
|
clk_pin: GPIOXX
|
|
miso_pin: GPIOXX
|
|
mosi_pin: GPIOXX
|
|
|
|
sensor:
|
|
- platform: atm90e26
|
|
cs_pin: GPIOXX
|
|
voltage:
|
|
name: House Voltage
|
|
accuracy_decimals: 1
|
|
filters:
|
|
- multiply: 4
|
|
current:
|
|
name: House Amps
|
|
# The max value for current that the meter can output is 65.535. If you expect to measure current over 65A,
|
|
# divide the gain_ct by 2 (120A CT) or 4 (200A CT) and multiply the current and power values by 2 or 4 by uncommenting the filter below
|
|
# filters:
|
|
# - multiply: 2
|
|
power:
|
|
name: House Watts
|
|
accuracy_decimals: 1
|
|
filters:
|
|
- multiply: 4
|
|
reactive_power:
|
|
name: House Reactive Power
|
|
power_factor:
|
|
name: House Power Factor
|
|
accuracy_decimals: 2
|
|
forward_active_energy:
|
|
name: House Forward Active Energy
|
|
reverse_active_energy:
|
|
name: House Reverse Active Energy
|
|
frequency:
|
|
name: House Freq
|
|
line_frequency: 50Hz
|
|
pl_const: ${plconst_cal}
|
|
meter_constant: '3200.0' # My old rotating-disc meter has a meter constant of 1666.66
|
|
gain_metering: ${metering_cal}
|
|
gain_voltage: ${voltage_cal}
|
|
gain_ct: ${current_cal}
|
|
gain_pga: 1X
|
|
update_interval: '10s'
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`sensor-filters`
|
|
- :apiref:`atm90e26/atm90e26.h`
|
|
- :ghedit:`Edit`
|