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 `__) 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 ` 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 `. See note below about throttling. - **voltage** (*Optional*): The sensor subcomponent that will report RMS voltage values in Volts. All options from :ref:`Sensor `. See note below about throttling. - **power** (*Optional*): The sensor subcomponent that will report the power readings in Watts. All options from :ref:`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 ` 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`