mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-24 17:08:15 +01:00
Add ATM90E26 documentation (#3002)
This commit is contained in:
danieltwagner
GitHub
parent
2c3b017500
commit
87f7a1c82a
158
components/sensor/atm90e26.rst
Normal file
158
components/sensor/atm90e26.rst
Normal file
@ -0,0 +1,158 @@
|
||||
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: 18
|
||||
miso_pin: 19
|
||||
mosi_pin: 23
|
||||
|
||||
sensor:
|
||||
- platform: atm90e26
|
||||
cs_pin: 5
|
||||
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`
|
||||
BIN
images/atm90e26.jpg
Normal file
BIN
images/atm90e26.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
@ -249,6 +249,7 @@ Electricity
|
||||
.. imgtable::
|
||||
|
||||
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
|
||||
BL0939, components/sensor/bl0939, bl0939.png, Voltage & Current & Power & Energy
|
||||
BL0940, components/sensor/bl0940, bl0940.png, Voltage & Current & Power
|
||||
|
||||
Loading…
Reference in New Issue
Block a user