mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-11-08 09:52:07 +01:00
88e315e0e4
* Many example yaml tidy-ups * Update components/sensor/hlw8012.rst --------- Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
289 lines
11 KiB
ReStructuredText
289 lines
11 KiB
ReStructuredText
ADE7953 Power Sensor
|
|
====================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up ADE7953 power sensors
|
|
:image: ade7953.svg
|
|
|
|
.. note::
|
|
|
|
This page is incomplete and could use some work. If you want to contribute, please read the
|
|
:doc:`contributing guide </guides/contributing>`. This page is missing:
|
|
|
|
- A complete configuration example for the Shelly 2.5
|
|
- An image for the front page
|
|
|
|
The ``ade7953`` sensor platform allows you to use ADE7953 single phase energy metering ICs
|
|
(`datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/ADE7953.pdf>`__)
|
|
with ESPHome. These are commonly found in **Shelly** devices.
|
|
|
|
This sensor can measure voltage and has two channels for reading current and active power (A & B).
|
|
|
|
.. note::
|
|
|
|
SAFETY HAZARD: Some devices such as Sonoff POWs/Shelly/etc, have the digital GND connected directly to mains voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent any use of the dangerous digital pins.
|
|
|
|
The :ref:`I²C Bus <i2c>`
|
|
or :ref:`SPI Bus <spi>`
|
|
is required to be set up in your configuration for this sensor to work.
|
|
|
|
Over I²C
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry for i2c
|
|
sensor:
|
|
- platform: ade7953_i2c
|
|
irq_pin: GPIOXX
|
|
voltage:
|
|
name: ADE7953 Voltage
|
|
frequency:
|
|
name: ADE7953 Frequency
|
|
current_a:
|
|
name: ADE7953 Current A
|
|
current_b:
|
|
name: ADE7953 Current B
|
|
power_factor_a:
|
|
name: "ADE7953 Power Factor A"
|
|
power_factor_b:
|
|
name: "ADE7953 Power Factor B"
|
|
apparent_power_a:
|
|
name: "ADE7953 Apparent Power A"
|
|
apparent_power_b:
|
|
name: "ADE7953 Apparent Power B"
|
|
active_power_a:
|
|
name: ADE7953 Active Power A
|
|
active_power_b:
|
|
name: ADE7953 Active Power B
|
|
reactive_power_a:
|
|
name: "ADE7953 Reactive Power A"
|
|
reactive_power_b:
|
|
name: "ADE7953 Reactive Power B"
|
|
|
|
Configuration variables:
|
|
************************
|
|
|
|
- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x38``.
|
|
- **irq_pin** (*Optional*, :ref:`config-pin`): The pin connected to the ADE7935 IRQ line (if connected)
|
|
- **voltage** (*Optional*): Use the voltage value of the sensor in volts. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **frequency** (*Optional*): Use the frequency value of the sensor in hertzs. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **current_a** (*Optional*): Use the current value of the A channel in amperes. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **current_b** (*Optional*): Use the current value of the B channel in amperes. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **power_factor_a** (*Optional*): Use the power factor of the A channel in percentage. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **power_factor_b** (*Optional*): Use the power factor of the B channel in percentage. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **aparent_power_a** (*Optional*): Use the apparent power value of the A channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **aparent_power_b** (*Optional*): Use the apparent power value of the B channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **active_power_a** (*Optional*): Use the power value of the A channel in watts. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **active_power_b** (*Optional*): Use the power value of the B channel in watts. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **reactive_power_a** (*Optional*): Use the rective power value of the A channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **reactive_power_b** (*Optional*): Use the rective power value of the B channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **voltage_pga_gain** (*Optional*, mapping): Set the input PGA voltage amplification. Defaults to ``1x``. Possible values are:
|
|
|
|
- ``1x``
|
|
- ``2x``
|
|
- ``4x``
|
|
- ``8x``
|
|
- ``16x``
|
|
- ``22x``
|
|
|
|
- **current_pga_gain_a** (*Optional*, mapping): Set the input PGA current amplification of the A channel. Defaults to ``1x``. Possible values are:
|
|
|
|
- ``1x``
|
|
- ``2x``
|
|
- ``4x``
|
|
- ``8x``
|
|
- ``16x``
|
|
- ``22x``
|
|
|
|
- **current_pga_gain_b** (*Optional*, mapping): Set input PGA current amplification of the B channel. Defaults to ``1x``. Possible values are:
|
|
|
|
- ``1x``
|
|
- ``2x``
|
|
- ``4x``
|
|
- ``8x``
|
|
- ``16x``
|
|
|
|
- **voltage_gain** (*Optional*, int): Set the voltage amplification. Defaults to ``0x400000``.
|
|
- **current_gain_a** (*Optional*, int): Set the current amplification of the A channel. Defaults to ``0x400000``.
|
|
- **current_gain_b** (*Optional*, int): Set the current amplification of the B channel. Defaults to ``0x400000``.
|
|
- **active_power_gain_a** (*Optional*, int): Set the active power amplification of the A channel. Defaults to ``0x400000``.
|
|
- **active_power_gain_b** (*Optional*, int): Set the active power amplification of the B channel. Defaults to ``0x400000``.
|
|
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
|
|
- **use_accumulated_energy_registers** (*Optional*, boolean): Use ADE7935 accumulated energy registers instead of instant power registers. These registers store the accumulated energy since the last read and should provide better accuracy for power calculation. Defaults to ``false``.
|
|
|
|
Over SPI
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry for SPI
|
|
sensor:
|
|
- platform: ade7953_spi
|
|
cs_pin: GPIOXX
|
|
irq_pin: GPIOXX
|
|
voltage:
|
|
name: "Voltage"
|
|
frequency:
|
|
name: ADE7953 Frequency
|
|
current_a:
|
|
name: "Current A"
|
|
current_b:
|
|
name: "Current B"
|
|
power_factor_a:
|
|
name: "Power Factor A"
|
|
power_factor_b:
|
|
name: "ADE7953 Power Factor B"
|
|
apparent_power_a:
|
|
name: "Apparent Power A"
|
|
apparent_power_b:
|
|
name: "Apparent Power B"
|
|
active_power_a:
|
|
name: "Power A"
|
|
active_power_b:
|
|
name: "Power B"
|
|
reactive_power_a:
|
|
name: "Reactive Power A"
|
|
reactive_power_b:
|
|
name: "Reactive Power B"
|
|
|
|
Configuration variables:
|
|
************************
|
|
|
|
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The chip select pin.
|
|
- **irq_pin** (*Optional*, :ref:`config-pin`): The pin connected to the ADE7935 IRQ line (if connected)
|
|
- **voltage** (*Optional*): Use the voltage value of the sensor in volts. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **frequency** (*Optional*): Use the frequency value of the sensor in hertzs. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **current_a** (*Optional*): Use the current value of the A channel in amperes. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **current_b** (*Optional*): Use the current value of the B channel in amperes. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **power_factor_a** (*Optional*): Use the power factor of the A channel in percentage. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **power_factor_b** (*Optional*): Use the power factor of the B channel in percentage. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **aparent_power_a** (*Optional*): Use the apparent power value of the A channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **aparent_power_b** (*Optional*): Use the apparent power value of the B channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **active_power_a** (*Optional*): Use the power value of the A channel in watts. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **active_power_b** (*Optional*): Use the power value of the B channel in watts. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **reactive_power_a** (*Optional*): Use the rective power value of the A channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **reactive_power_b** (*Optional*): Use the rective power value of the B channel in volt ampers. All options from
|
|
:ref:`Sensor <config-sensor>`.
|
|
- **voltage_pga_gain** (*Optional*, mapping): Set the input PGA voltage amplification. Defaults to ``1x``. Possible values are:
|
|
|
|
- ``1x``
|
|
- ``2x``
|
|
- ``4x``
|
|
- ``8x``
|
|
- ``16x``
|
|
- ``22x``
|
|
|
|
- **current_pga_gain_a** (*Optional*, mapping): Set the input PGA current amplification of the A channel. Defaults to ``1x``. Possible values are:
|
|
|
|
- ``1x``
|
|
- ``2x``
|
|
- ``4x``
|
|
- ``8x``
|
|
- ``16x``
|
|
- ``22x``
|
|
|
|
- **current_pga_gain_b** (*Optional*, mapping): Set input PGA current amplification of the B channel. Defaults to ``1x``. Possible values are:
|
|
|
|
- ``1x``
|
|
- ``2x``
|
|
- ``4x``
|
|
- ``8x``
|
|
- ``16x``
|
|
|
|
- **voltage_gain** (*Optional*, int): Set the voltage amplification. Defaults to ``0x400000``.
|
|
- **current_gain_a** (*Optional*, int): Set the current amplification of the A channel. Defaults to ``0x400000``.
|
|
- **current_gain_b** (*Optional*, int): Set the current amplification of the B channel. Defaults to ``0x400000``.
|
|
- **active_power_gain_a** (*Optional*, int): Set the active power amplification of the A channel. Defaults to ``0x400000``.
|
|
- **active_power_gain_b** (*Optional*, int): Set the active power amplification of the B channel. Defaults to ``0x400000``.
|
|
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
|
|
- **use_accumulated_energy_registers** (*Optional*, boolean): Use ADE7935 accumulated energy registers instead of instant power registers. These registers store the accumulated energy since the last read and should provide better accuracy for power calculation. Defaults to ``false``.
|
|
|
|
Use with Shelly 2.5
|
|
-------------------
|
|
|
|
The Shelly 2.5 device contains this sensor for power monitoring. An example config for the Shelly 2.5
|
|
is given below.
|
|
|
|
There are three oddities with the Shelly 2.5:
|
|
|
|
- First, the A and B channels are mixed up - the chip's A channel is label B on the outside and
|
|
vice versa. Probably to make the PCB easier to manufacture.
|
|
- Secondly, due to the first point the active_power values are inverted. This is fixed by
|
|
using a multiply filter as seen in the config below.
|
|
- Lastly, the ADE7953 IRQ line is connected to the GPIO16. The irq_pin MUST be set to GPIO16 to prevent device overheat (>70ºC idling).
|
|
|
|
Additionally, the device has an ::doc:`NTC temperature sensor <ntc>`.
|
|
|
|
.. code-block:: yaml
|
|
|
|
i2c:
|
|
sda: GPIO12
|
|
scl: GPIO14
|
|
|
|
sensor:
|
|
- platform: ade7953_i2c
|
|
irq_pin: GPIO16
|
|
voltage:
|
|
name: Shelly Voltage
|
|
current_a:
|
|
name: Shelly Current B
|
|
current_b:
|
|
name: Shelly Current A
|
|
active_power_a:
|
|
name: Shelly Active Power B
|
|
filters:
|
|
- multiply: -1
|
|
active_power_b:
|
|
name: Shelly Active Power A
|
|
filters:
|
|
- multiply: -1
|
|
update_interval: 60s
|
|
|
|
# NTC Temperature
|
|
- platform: ntc
|
|
sensor: temp_resistance_reading
|
|
name: "Shelly Temperature"
|
|
calibration:
|
|
b_constant: 3350
|
|
reference_resistance: 10kOhm
|
|
reference_temperature: 298.15K
|
|
- platform: resistance
|
|
id: temp_resistance_reading
|
|
sensor: temp_analog_reading
|
|
configuration: DOWNSTREAM
|
|
resistor: 32kOhm
|
|
- platform: adc
|
|
id: temp_analog_reading
|
|
pin: A0
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`sensor-filters`
|
|
- :apiref:`ade7953/ade7953.h`
|
|
- :ghedit:`Edit`
|