150 lines
8.3 KiB
ReStructuredText
150 lines
8.3 KiB
ReStructuredText
CS5460A Power Sensor
|
|
====================
|
|
|
|
.. seo::
|
|
:description: CS5460A component configuration
|
|
:image: cs5460a.png
|
|
:keywords: cs5460a
|
|
|
|
The ``cs5460a`` sensor platform allows you to use a CS5460A AC voltage, current and power meter
|
|
chip (`datasheet <https://statics.cirrus.com/pubs/proDatasheet/CS5460A_F5.pdf>`__) with ESPHome.
|
|
The chip is usually sold on a breakout board with a 4.096 MHz crystal. However it requires a few
|
|
extra components, specifically a current sensing circuit and a voltage sensing circuit.
|
|
|
|
.. figure:: ../../images/cs5460a.png
|
|
:align: center
|
|
:width: 30.0%
|
|
|
|
CS5460A Single-Phase Power/Energy IC module
|
|
|
|
.. warning::
|
|
|
|
Do not work near live mains connections and only modify existing electrical installations if
|
|
you're qualified.
|
|
|
|
Configuration:
|
|
--------------
|
|
|
|
Your device communicates with the CS5460A over SPI so you need to have an :ref:`SPI bus <spi>` in
|
|
your configuration with the pin numbers set for the ``MOSI``, ``MISO`` and ``CLK`` lines. These
|
|
connect to the ``SDI``, ``SDO`` and ``SCLK`` pins on the CS5460A respectively. The ``CS``
|
|
(chip-select) pin of the CS5460A can be driven by any GPIO you have available or wired to ground
|
|
if the CS5460A is the only device connected to your device's SPI bus. The RESET pin can also be
|
|
driven by a GPIO or wired to VCC.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
sensor:
|
|
- platform: cs5460a
|
|
current:
|
|
name: "Kitchen current (RMS)"
|
|
filters:
|
|
delta: 0.1
|
|
power:
|
|
name: "Kitchen power"
|
|
filters:
|
|
delta: 5
|
|
voltage:
|
|
name: "Mains voltage (RMS)"
|
|
filters:
|
|
delta: 5
|
|
samples: 1600
|
|
current_gain: 0.01
|
|
voltage_gain: 0.000573
|
|
pulse_energy: 1 Wh
|
|
cs_pin: GPIOXX
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **current** (*Optional*): The sensor subcomponent that will report RMS current values in Amperes.
|
|
All options from :ref:`Sensor <config-sensor>`. See note below about throttling.
|
|
- **voltage** (*Optional*): The sensor subcomponent that will report RMS voltage values in Volts.
|
|
All options from :ref:`Sensor <config-sensor>`. See note below about throttling.
|
|
- **power** (*Optional*): The sensor subcomponent that will report the power readings in Watts.
|
|
All options from :ref:`Sensor <config-sensor>`. See note below about throttling.
|
|
- **samples** (*Optional*): The number of samples that go into each reading -- determines that
|
|
update interval of the sensors and the accuracy of the readings. This is the number N from the
|
|
CS5460A datasheet, defined as the number of *conversion cycles* within a *computation cycle*. The
|
|
component reports data at the end of each *computation cycle*. With the standard 4.096MHz clock
|
|
rate, each *conversion* takes 0.25ms so setting this to 2000 means 0.5s update interval, 40000
|
|
means 10s update interval and so on, similarly for other clock-rates. It is recommended that
|
|
the interval be an integer number of the mains AC cycles, so for the 50 Hz AC frequency countries
|
|
the interval should be a multiple of 20ms, for the 60 Hz countries a multiple of 16.66 ms.
|
|
Defaults to ``4000`` (1 second at 4.096MHz). Admits values from 1 to 16777215.
|
|
- **pga_gain** (*Optional*): If set to ``10X`` (default), the differential voltage at the current
|
|
inputs must be between -250mV and +250mV. If set to ``50X`` it must be within -100mV to +100mV.
|
|
- **current_gain** (*Optional*): Set this to the ratio of the differential voltage at the current
|
|
inputs (in Volts) vs. the actual line current to be calculated (in Amperes). When using a shunt
|
|
resistor as the current sensing element, this is going to simply equal the resistance since
|
|
the differential voltage is the line current multiplied by the resistance. When using a current
|
|
transformer, the value is going to be the burden resistor's value divided by the number of turns
|
|
of the transformer winding. For a 2000 turn current transformer clamp and a 2 Ohm burden
|
|
resistor this works out to 0.001 (the default if **current_gain** is not specified).
|
|
- **voltage_gain** (*Optional*): Set this to the ratio of the voltage at the voltage input pins
|
|
of CS5460A to the line voltage. When using a simple voltage divider, this is the divider's ratio.
|
|
When using a voltage transformer this is the secondary turns to primary turns ratio. When using a
|
|
current transformer (such as the ZMPT101B) this is equals
|
|
``(secondary turns * burden resistor value) / (primary turns * limiting resistor value)``, and
|
|
similarly for combinations of transfomers and voltage dividers. Defaults to ``0.001``. Must be
|
|
a positive number.
|
|
- **phase_offset** (*Optional*): This can be used to account for a phase offset between the voltage
|
|
sensing circuit and the current sensing circuit to improve power measurement accuracy. Admits
|
|
integer values between -64 to 63, which should be offset by 0.5 and multiplied by about 8.2
|
|
CS5460A clock intervals to get the resulting time offset. With the typical 4.096 MHz clocking
|
|
this scales to a range of -128 μs to 128 μs, or -2.3º to 2.3º phase offset at 50Hz and a -2.8º to
|
|
2.8º phase offset at 60Hz. Defaults to ``0`` (i.e. time offset of 4.1 MCLK cycles). An easy way
|
|
to find the correct value is to plug in a resisitve load such as an incandescent light-bulb and
|
|
find the ``phase_offset`` value that results in the highest power reported by the sensor.
|
|
- **pulse_energy** (*Optional*): Sets the energy (in Watt-hours) per individual pulse on the
|
|
CS5460A's EOUT pin that can be used to driver external counters / meters or a LED. The allowed
|
|
range depends on the gain parameters, defaults to ``10 Wh``.
|
|
- **current_hpf** (*Optional*): Enables and disables the High-pass Filter on the current processing
|
|
path in the CS5460A. Defaults to ``true`` (enabled).
|
|
- **voltage_hpf** (*Optional*): Enables and disables the High-pass Filter on the voltage processing
|
|
path in the CS5460A. Defaults to ``true`` (enabled).
|
|
|
|
.. note:: Negative values
|
|
|
|
Since the current and voltage values reported are the RMS values, they're absolute numbers
|
|
and are always positive. However the power measurement is signed depending on the direction
|
|
in which energy is being transmitted through the shunt resistor or the current transformer.
|
|
In other words if the sensor is installed between two circuits (e.g. the power grid and a
|
|
household) the sign informs which side is producing and which side is consuming energy in
|
|
the last *computation cycle*. If the power values are inverted compared to what you expect
|
|
to see, set a negative ``current_gain`` value.
|
|
|
|
.. note:: Throttling sensors
|
|
|
|
If ``samples`` is set to a low value, e.g. in the range of a few seconds per sample or
|
|
shorter, consider :ref:`filtering <sensor-filters>` the measurements if you have a Home
|
|
Assistant instance to avoid filling the logs with too much data. The ``throttle`` and
|
|
``sliding_window_moving_average`` filters are some options. Additionally the ``delta``
|
|
filter is almost always a good idea for all numeric sensors regardless of Home Assistant.
|
|
|
|
.. _cs5460a-restart_action:
|
|
|
|
``cs5460a.restart`` Action
|
|
---------------------------------
|
|
|
|
This action can be used in automations to interrupt the current *computation cycle* and start a
|
|
new one. This is useful if you're measuring multiple current/power values using a single
|
|
CS5460A chip and a signal multiplexer. As an example you can measure the power usage on up to
|
|
wall sockets in a house by using one voltage transformer and 16 current transformers, each on
|
|
the cable leading to the corresponding wall socket. One side of all the current transformers
|
|
connects directly to your CS5460A current input terminal (plus any filtering and protection
|
|
circuitry as recommended in the datasheet), while the other side each connects to one channel
|
|
of a CD74HC4067 analog multiplexer. The multiplexer's single signal pin then connects to the
|
|
CS5460A's second current input terminal. Every time the CS5460A sensor publishes a new power
|
|
value, an automation can switch the multiplexer to the next channel but it needs to interrupt
|
|
the *computation cycle* automatically started when the previous one ended, and start a new
|
|
cycle that uses current samples only from the new CD74HC4067 multiplexer channel.
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`sensor-filters`
|
|
- :apiref:`cs5460a/cs5460a.h`
|
|
- :ghedit:`Edit`
|