diff --git a/components/sensor/images/ina228-full.jpg b/components/sensor/images/ina228-full.jpg new file mode 100644 index 000000000..45070b846 Binary files /dev/null and b/components/sensor/images/ina228-full.jpg differ diff --git a/components/sensor/ina2xx.rst b/components/sensor/ina2xx.rst new file mode 100644 index 000000000..f74f7b91f --- /dev/null +++ b/components/sensor/ina2xx.rst @@ -0,0 +1,199 @@ +INA2xx family of digital power monitors +======================================= + +.. seo:: + :description: Instructions for setting up INA228, INA229, INA237, INA238, INA239 DC current, power, and charge sensors + :image: ina228.jpg + :keywords: ina228 ina229 ina237 ina238 ina239 + +.. figure:: images/ina228-full.jpg + :align: center + :width: 50.0% + + INA228 Module with integrated shunt from Adafruit + +Supported devices +----------------- +The ``ina2xx`` sensor platform allows you to use family of Texas Instruments current and power +sensors with ESPHome. Appropriate interface (:ref:`I²C Bus ` or :ref:`SPI Bus `) is +requred to be set up in your configuration for this sensor to work. + + + +========================================================== ========== ========================================================== + Product Protocol Description +========================================================== ========== ========================================================== + `INA228 `__ I²C 85-V, 20-Bit, Ultra-Precise Power/Energy/Charge Monitor + `INA229 `__ SPI 85-V, 20-Bit, Ultra-Precise Power/Energy/Charge Monitor + `INA238 `__ I²C 85-V, 16-Bit, High-Precision Power Monitor + `INA239 `__ SPI 85-V, 16-Bit, High-Precision Power Monitor + `INA237 `__ I²C 85-V, 16-Bit, Precision Power Monitor +========================================================== ========== ========================================================== + +All devices can measure a selectable full-scale differential input of ±163.84 mV +or ±40.96 mV across the shunt with common-mode voltage support from –0.3 V to +85 V. + +INA228 and INA229 are the most comprehensive devices of the family with extra features: 20-bit ADC resolution, +energy and charge accumulation, and capability to utilize the temperature measurement to compensate +for shunt resistor temperature variance. + +Over I²C +-------- +Use ``ina2xx_i2c`` component to connect INA228, INA237, or INA238 device over :ref:`I²C ` bus. + +.. code-block:: yaml + + # Example configuration entry for I²C + i2c: + sda: D1 + scl: D2 + + sensor: + - platform: ina2xx_i2c + id: my_charge_sensor + model: INA228 + address: 0x40 + shunt_resistance: 0.010 ohm + max_current: 10 A + adc_range: 0 + update_interval: 60s + current: "INA228 Current" + bus_voltage: "INA228 Bus Voltage" + charge: "INA228 Charge" + + +Configuration variables: +************************ + +- **model** (**Required**, string): The model of the INA2xx sensor. Options are ``INA228``, ``INA237``, ``INA238``. +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x40``. +- **shunt_resistance** (**Required**, float): The value of the shunt resistor used for current calculation. No default value. +- **max_current** (**Required**, float): The maximum current you are expecting. Component will use it to + calibrate the sensor. No default value. +- **adc_range** (*Optional*, ``0`` or ``1``): Selects the range for differential input across shunt + resistor. ``0`` for ±163.84 mV, ``1`` for ±40.96 mV range. Defaults to ``0``. +- **adc_time** (*Optional*, :ref:`config-time`): The time in microseconds to perform a single ADC conversion. + Defaults to ``4120 us``. Valid values are ``50 us``, ``84 us``, ``150 us``, ``280 us``, ``540 us``, + ``1052 us``, ``2074 us``, ``4120 us``. + + Instead of one time for all ADC measurements, separate configuration of conversion times for shunt voltage, + bus voltage, and temperature measurements possible. Options are the same as for ``adc_time``. + + - **bus_voltage** (*Optional*, :ref:`config-time`): Conversion time for bus voltage measurement. + - **shunt_voltage** (*Optional*, :ref:`config-time`): Conversion time for shunt voltage measurement. + - **temperature** (*Optional*, :ref:`config-time`): Conversion time for temperature measurement. + +- **adc_averaging** (*Optional*, integer): Selects ADC sample averaging count. Defaults to ``128``. + Valid values are ``1``, ``4``, ``16``, ``64``, ``128``, ``256``, ``512``, ``1024``. +- **temperature_coefficient** (*Optional*, integer from ``0`` to ``16383``): Temperature coefficient (ppm/°C) of the + shunt for temperature compensation correction. Only applicable to INA228 and INA229 devices. Zero value means + no compensation is done. Defaults to ``0``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. +- All other options for I²C device as descibed in respective documentation. + + +Over SPI +-------- + +Use ``ina2xx_spi`` component to connect INA229 or INA239 device over :ref:`SPI ` bus. + + +.. code-block:: yaml + + # Example configuration entry for SPI + spi: + clk_pin: D0 + mosi_pin: D1 + miso_pin: D2 + + sensor: + - platform: ina2xx_spi + cs_pin: D3 + model: INA239 + shunt_resistance: 0.001130 ohm + max_current: 40 A + adc_range: 0 + temperature_coefficient: 50 + current: "INA239 Current" + power: "INA239 Power" + + +Configuration variables: +************************ + +- **model** (**Required**, string): The model of the INA2xx sensor. Options are ``INA229``, ``INA239``. +- **cs_pin** (**Required**, :ref:`Pin Schema `): The Chip Select (CS) pin. +- **shunt_resistance** (**Required**, float): The value of the shunt resistor used for current calculation. No default value. +- **max_current** (**Required**, float): The maximum current you are expecting. Component will use it to + calibrate the sensor. No default value. +- **adc_range** (*Optional*, ``0`` or ``1``): Selects the range for differential input across shunt + resistor. ``0`` for ±163.84 mV, ``1`` for ±40.96 mV range. Defaults to ``0``. +- **adc_time** (*Optional*, :ref:`config-time`): The time in microseconds to perform a single ADC conversion. + Defaults to ``4120 us``. Valid values are ``50 us``, ``84 us``, ``150 us``, ``280 us``, ``540 us``, + ``1052 us``, ``2074 us``, ``4120 us``. + + Instead of one time for all ADC measurements, separate configuration of conversion times for shunt voltage, + bus voltage, and temperature measurements possible. Options are the same as for ``adc_time``. + + - **bus_voltage** (*Optional*, :ref:`config-time`): Conversion time for bus voltage measurement. + - **shunt_voltage** (*Optional*, :ref:`config-time`): Conversion time for shunt voltage measurement. + - **temperature** (*Optional*, :ref:`config-time`): Conversion time for temperature measurement. + +- **adc_averaging** (*Optional*, integer): Selects ADC sample averaging count. Defaults to ``128``. + Valid values are ``1``, ``4``, ``16``, ``64``, ``128``, ``256``, ``512``, ``1024``. +- **temperature_coefficient** (*Optional*, integer from ``0`` to ``16383``): Temperature coefficient (ppm/°C) of the + shunt for temperature compensation correction. Only applicable to INA228 and INA229 devices. Zero value means + no compensation is done. Defaults to ``0``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. +- All other options for SPI device as descibed in respective documentation. + + +Sensors +------- +The component offers nine sensors. You can configure all or any subset of the sensors. Each configured sensor +is reported separately on each update_interval. The ``name`` option is required for each sensor configured. +All other options from :ref:`Sensor `. Shorthand notation can be used for the sensors like this: +``current: "Current"``. + +- **current** (*Optional*): Calculated current output, A +- **power** (*Optional*): Calculated power output, always positive, W +- **shunt_voltage** (*Optional*): Differential voltage measured across the shunt, mV +- **bus_voltage** (*Optional*): Bus voltage output, V +- **temperature** (*Optional*): Internal die temperature measurement, °C +- **energy** (*Optional*): Calculated energy output, Wh (*INA228/229 only*) +- **energy_joules** (*Optional*): Calculated energy output, Joules (*INA228/229 only*) +- **charge** (*Optional*): Calculated charge output, Ah (*INA228/229 only*) +- **charge_coulombs** (*Optional*): Calculated charge output, Coulombs (*INA228/229 only*) + +Lambda calls +------------ + +The component exposes one function to reset INA228/INA229 energy and charge accumulators. + +- ``reset_energy_counters()`` + + .. code-block:: cpp + + // Within lambda, reset counters. + id(my_charge_sensor).reset_energy_counters(); + +To simplify the use of this function, you can use the following example to add a button to reset the counters. + + .. code-block:: yaml + + button: + - platform: template + name: "Reset counters" + on_press: + - lambda: "id(my_change_sensor).reset_energy_counters();" + + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`ina219` +- :doc:`ina226` +- :doc:`ina3221` +- :apiref:`ina2xx_base/ina2xx_base.h` +- :ghedit:`Edit` diff --git a/images/ina228.jpg b/images/ina228.jpg new file mode 100644 index 000000000..a0c24657b Binary files /dev/null and b/images/ina228.jpg differ diff --git a/images/ina2xx.jpg b/images/ina2xx.jpg new file mode 100644 index 000000000..8528b1d9e Binary files /dev/null and b/images/ina2xx.jpg differ diff --git a/index.rst b/index.rst index 3f6bdf1b8..2088abb8c 100644 --- a/index.rst +++ b/index.rst @@ -354,6 +354,11 @@ Electricity HLW8012, components/sensor/hlw8012, hlw8012.svg, Voltage & Current & Power INA219, components/sensor/ina219, ina219.jpg, DC Current INA226, components/sensor/ina226, ina226.jpg, DC Current & Power + INA228, components/sensor/ina2xx, ina228.jpg, DC Voltage & Current & Power & Charge + INA229, components/sensor/ina2xx, ina2xx.jpg, DC Voltage & Current & Power & Charge + INA237, components/sensor/ina2xx, ina2xx.jpg, DC Voltage & Current & Power + INA238, components/sensor/ina2xx, ina2xx.jpg, DC Voltage & Current & Power + INA239, components/sensor/ina2xx, ina2xx.jpg, DC Voltage & Current & Power INA260, components/sensor/ina260, ina260.jpg, DC Current & Power INA3221, components/sensor/ina3221, ina3221.jpg, 3-Ch DC current Kamstrup KMP, components/sensor/kamstrup_kmp, kamstrup_kmp.jpg, District Heating Meter