INA2XX current/power monitor

Device driver for Texas Instruments INA219/INA2XX Bi-Directional CURRENT/POWER MONITOR with Two-Wire Interface. More...

Detailed Description

Device driver for Texas Instruments INA219/INA2XX Bi-Directional CURRENT/POWER MONITOR with Two-Wire Interface.

Supported Hardware

This driver currently supports the INA219 and the INA2XX - and possibly other devices of the INA2xx family. The popular INA219 breakout boards are supported out of the box.

Choosing the Right Shunt Resistor

The shunt resistor should generate a voltage drop of at least 40 mV and of at most 320 mV at maximum current (add some safety margin to the maximum current). E.g. when the expected maximum current is 500 mA and we add a safety margin of 33 mA, a 75 mΩ shunt resistor would cause a drop of 40 mV at about 533 mA, and a 600 mΩ shunt resistor would cause a drop of 320 mV. So every shunt resistor between 75 mΩ and 600 mΩ would result in a decent resolution, but shunt resistors that almost max out one of the selectable shunt voltage ranges (40 mV, 80 mV, 160 mV and 320 mV) would be ideal. Often the voltage drop should be as low as possible, therefore the lowest reasonable shunt resistor has to be chosen in that case.

The popular INA219 breakout boards have a shunt resistor of 100 mΩ, which allows to measure a current of up to 400 mA at PGA = /1, and of up two 3.2 A at PGA = /8.

Files

file  ina2xx_defines.h
 Various definitions for Texas Instruments INA219/INA220 Bi-Directional CURRENT/POWER MONITOR with Two-Wire Interface.
 
file  ina2xx_params.h
 Default configuration for INA2xx power/current monitors.
 
file  ina2xx.h
 Device driver interface for Texas Instruments INA219/INA2XX Bi-Directional CURRENT/POWER MONITOR with Two-Wire Interface.
 

Data Structures

struct  ina2xx_params_t
 Configuration parameters of the INA2xx driver. More...
 
struct  ina2xx_t
 Device descriptor for INA2XX sensors. More...
 

Typedefs

typedef enum ina2xx_mode ina2xx_mode_t
 INA2XX possible mode settings.
 
typedef enum ina2xx_sadc ina2xx_sadc_t
 Shunt ADC settings. More...
 
typedef enum ina2xx_badc ina2xx_badc_t
 Bus ADC settings. More...
 
typedef enum ina2xx_pga ina2xx_pga_t
 Shunt voltage measurement range (PGA settings)
 
typedef enum ina2xx_brng ina2xx_brng_t
 Bus voltage measurement range.
 
typedef enum ina2xx_i_range ina2xx_i_range_t
 Current measurement range. More...
 

Enumerations

enum  ina2xx_mode {
  INA2XX_MODE_POWERDOWN = 0x0000, INA2XX_MODE_TRIGGER_SHUNT_ONLY = 0x0001, INA2XX_MODE_TRIGGER_BUS_ONLY = 0x0002, INA2XX_MODE_TRIGGER_SHUNT_BUS = 0x0003,
  INA2XX_MODE_ADC_DISABLE = 0x0004, INA2XX_MODE_CONTINUOUS_SHUNT_ONLY = 0x0005, INA2XX_MODE_CONTINUOUS_BUS_ONLY = 0x0006, INA2XX_MODE_CONTINUOUS_SHUNT_BUS = 0x0007
}
 INA2XX possible mode settings. More...
 
enum  ina2xx_sadc {
  INA2XX_SADC_9BIT = 0x0000, INA2XX_SADC_10BIT = 0x0008, INA2XX_SADC_11BIT = 0x0010, INA2XX_SADC_12BIT = 0x0018,
  INA2XX_SADC_AVG_1_SAMPLE = 0x0040, INA2XX_SADC_AVG_2_SAMPLES = 0x0048, INA2XX_SADC_AVG_4_SAMPLES = 0x0050, INA2XX_SADC_AVG_8_SAMPLES = 0x0058,
  INA2XX_SADC_AVG_16_SAMPLES = 0x0060, INA2XX_SADC_AVG_32_SAMPLES = 0x0068, INA2XX_SADC_AVG_64_SAMPLES = 0x0070, INA2XX_SADC_AVG_128_SAMPLES = 0x0078
}
 Shunt ADC settings. More...
 
enum  ina2xx_badc {
  INA2XX_BADC_9BIT = 0x0000, INA2XX_BADC_10BIT = 0x0080, INA2XX_BADC_11BIT = 0x0100, INA2XX_BADC_12BIT = 0x0180,
  INA2XX_BADC_AVG_1_SAMPLE = 0x0400, INA2XX_BADC_AVG_2_SAMPLES = 0x0480, INA2XX_BADC_AVG_4_SAMPLES = 0x0500, INA2XX_BADC_AVG_8_SAMPLES = 0x0580,
  INA2XX_BADC_AVG_16_SAMPLES = 0x0600, INA2XX_BADC_AVG_32_SAMPLES = 0x0680, INA2XX_BADC_AVG_64_SAMPLES = 0x0700, INA2XX_BADC_AVG_128_SAMPLES = 0x0780
}
 Bus ADC settings. More...
 
enum  ina2xx_pga { INA2XX_SHUNT_RANGE_40MV = 0x0000, INA2XX_SHUNT_RANGE_80MV = 0x0800, INA2XX_SHUNT_RANGE_160MV = 0x1000, INA2XX_SHUNT_RANGE_320MV = 0x1800 }
 Shunt voltage measurement range (PGA settings) More...
 
enum  ina2xx_brng { INA2XX_BUS_RANGE_16V = 0x0000, INA2XX_BUS_RANGE_32V = 0x2000 }
 Bus voltage measurement range. More...
 
enum  ina2xx_i_range {
  INA2XX_CURRENT_RANGE_327_MA, INA2XX_CURRENT_RANGE_655_MA, INA2XX_CURRENT_RANGE_1310_MA, INA2XX_CURRENT_RANGE_2621_MA,
  INA2XX_CURRENT_RANGE_5242_MA, INA2XX_CURRENT_RANGE_10485_MA
}
 Current measurement range. More...
 

Functions

int ina2xx_init (ina2xx_t *dev, const ina2xx_params_t *params)
 Initialize a current sensor. More...
 
int ina2xx_read_shunt (const ina2xx_t *dev, int16_t *voltage)
 Read shunt voltage in E-05 V. More...
 
int ina2xx_read_bus (const ina2xx_t *dev, uint16_t *voltage)
 Read bus voltage in mV. More...
 
int ina2xx_read_current (const ina2xx_t *dev, int32_t *current)
 Read shunt current in E-05 A. More...
 
int ina2xx_read_power (const ina2xx_t *dev, uint32_t *power)
 Read power consumption in E-04 W. More...
 

Typedef Documentation

◆ ina2xx_badc_t

typedef enum ina2xx_badc ina2xx_badc_t

Bus ADC settings.

See also
Table 4 in INA2XX data sheet

◆ ina2xx_i_range_t

Current measurement range.

Warning
Choosing a low range and a small shunt resistor can cause ina2xx_init to fail. But for high resolution measurements of low currents a "big" shunt resistor (e.g. 100 mΩ) should be chosen anyway.

Choosing the lowest sufficient range for your use case will result in the optimal resolution

◆ ina2xx_sadc_t

typedef enum ina2xx_sadc ina2xx_sadc_t

Shunt ADC settings.

See also
Table 4 in INA2XX data sheet

Enumeration Type Documentation

◆ ina2xx_badc

Bus ADC settings.

See also
Table 4 in INA2XX data sheet
Enumerator
INA2XX_BADC_9BIT 

9 bit resolution, 84 us conversion time

INA2XX_BADC_10BIT 

10 bit resolution, 148 us conversion time

INA2XX_BADC_11BIT 

11 bit resolution, 276 us conversion time

INA2XX_BADC_12BIT 

12 bit resolution, 532 us conversion time, default

INA2XX_BADC_AVG_1_SAMPLE 

12 bit resolution, 532 us conversion time, same as INA2XX_BADC_12BIT

INA2XX_BADC_AVG_2_SAMPLES 

2 sample average, 1.06 ms conversion time

INA2XX_BADC_AVG_4_SAMPLES 

4 sample average, 2.13 ms conversion time

INA2XX_BADC_AVG_8_SAMPLES 

8 sample average, 4.26 ms conversion time

INA2XX_BADC_AVG_16_SAMPLES 

16 sample average, 8.51 ms conversion time

INA2XX_BADC_AVG_32_SAMPLES 

32 sample average, 17.02 ms conversion time

INA2XX_BADC_AVG_64_SAMPLES 

64 sample average, 34.05 ms conversion time

INA2XX_BADC_AVG_128_SAMPLES 

128 sample average, 68.10 ms conversion time

Definition at line 109 of file ina2xx.h.

◆ ina2xx_brng

Bus voltage measurement range.

Enumerator
INA2XX_BUS_RANGE_16V 

16 V bus voltage full scale range

INA2XX_BUS_RANGE_32V 

32 V bus voltage full scale range, default.

Definition at line 149 of file ina2xx.h.

◆ ina2xx_i_range

Current measurement range.

Warning
Choosing a low range and a small shunt resistor can cause ina2xx_init to fail. But for high resolution measurements of low currents a "big" shunt resistor (e.g. 100 mΩ) should be chosen anyway.

Choosing the lowest sufficient range for your use case will result in the optimal resolution

Enumerator
INA2XX_CURRENT_RANGE_327_MA 

±327.68 mA, 0.01mA resolution.

INA2XX_CURRENT_RANGE_655_MA 

±655.36 mA, 0.02mA resolution.

INA2XX_CURRENT_RANGE_1310_MA 

±1310.72 mA, 0.04mA resolution.

INA2XX_CURRENT_RANGE_2621_MA 

±2621.44 mA, 0.08mA resolution.

INA2XX_CURRENT_RANGE_5242_MA 

±5242.88 mA, 0.16mA resolution.

INA2XX_CURRENT_RANGE_10485_MA 

±10485.76 mA, 0.32mA resolution.

Definition at line 164 of file ina2xx.h.

◆ ina2xx_mode

INA2XX possible mode settings.

Enumerator
INA2XX_MODE_POWERDOWN 

Power down.

INA2XX_MODE_TRIGGER_SHUNT_ONLY 

Shunt Voltage, Triggered.

INA2XX_MODE_TRIGGER_BUS_ONLY 

Bus Voltage, Triggered.

INA2XX_MODE_TRIGGER_SHUNT_BUS 

Shunt and Bus, Triggered.

INA2XX_MODE_ADC_DISABLE 

ADC Off (disabled)

INA2XX_MODE_CONTINUOUS_SHUNT_ONLY 

Shunt Voltage, Continuous.

INA2XX_MODE_CONTINUOUS_BUS_ONLY 

Bus Voltage, Continuous.

INA2XX_MODE_CONTINUOUS_SHUNT_BUS 

Shunt and Bus, Continuous, default.

Definition at line 61 of file ina2xx.h.

◆ ina2xx_pga

enum ina2xx_pga

Shunt voltage measurement range (PGA settings)

Enumerator
INA2XX_SHUNT_RANGE_40MV 

+/- 40 mV range

INA2XX_SHUNT_RANGE_80MV 

+/- 80 mV range

INA2XX_SHUNT_RANGE_160MV 

+/- 160 mV range

INA2XX_SHUNT_RANGE_320MV 

+/- 320 mV range, default

Definition at line 139 of file ina2xx.h.

◆ ina2xx_sadc

Shunt ADC settings.

See also
Table 4 in INA2XX data sheet
Enumerator
INA2XX_SADC_9BIT 

9 bit resolution, 84 us conversion time

INA2XX_SADC_10BIT 

10 bit resolution, 148 us conversion time

INA2XX_SADC_11BIT 

11 bit resolution, 276 us conversion time

INA2XX_SADC_12BIT 

12 bit resolution, 532 us conversion time, default

INA2XX_SADC_AVG_1_SAMPLE 

12 bit resolution, 532 us conversion time, same as INA2XX_SADC_12BIT

INA2XX_SADC_AVG_2_SAMPLES 

2 sample average, 1.06 ms conversion time

INA2XX_SADC_AVG_4_SAMPLES 

4 sample average, 2.13 ms conversion time

INA2XX_SADC_AVG_8_SAMPLES 

8 sample average, 4.26 ms conversion time

INA2XX_SADC_AVG_16_SAMPLES 

16 sample average, 8.51 ms conversion time

INA2XX_SADC_AVG_32_SAMPLES 

32 sample average, 17.02 ms conversion time

INA2XX_SADC_AVG_64_SAMPLES 

64 sample average, 34.05 ms conversion time

INA2XX_SADC_AVG_128_SAMPLES 

128 sample average, 68.10 ms conversion time

Definition at line 77 of file ina2xx.h.

Function Documentation

◆ ina2xx_init()

int ina2xx_init ( ina2xx_t dev,
const ina2xx_params_t params 
)

Initialize a current sensor.

Parameters
[out]devdevice descriptor of sensor to initialize
[in]paramsConfiguration parameters to use
Returns
0 on success, <0 on error.
Return values
0Success
-ENODEVDevice seems not to be an INA2XX device
-EINVALdev or params is NULL
-ERANGEparams contained invalid setting: Increase current range
<0Failure, error of i2c_read_regs or i2c_write_regs passed through

◆ ina2xx_read_bus()

int ina2xx_read_bus ( const ina2xx_t dev,
uint16_t *  voltage 
)

Read bus voltage in mV.

Parameters
[in]devdevice descriptor of sensor
[out]voltageThe measured bus voltage in mV
Returns
<0 on error, >= 0 on success
Return values
0Success, no new power value available
1Success, new value for ina2xx_read_power ready
-EDOMOverflow during power/current calculations.
<0Error code of i2c_read_regs passed through

◆ ina2xx_read_current()

int ina2xx_read_current ( const ina2xx_t dev,
int32_t *  current 
)

Read shunt current in E-05 A.

Parameters
[in]devdevice descriptor of sensor
[out]currentmeasured current through shunt resistor in E-05 A
Returns
0 on success
<0 on error

◆ ina2xx_read_power()

int ina2xx_read_power ( const ina2xx_t dev,
uint32_t *  power 
)

Read power consumption in E-04 W.

Parameters
[in]devdevice descriptor of sensor
[out]powermeasured power consumption in E-04 W
Returns
0 on success
<0 on error

◆ ina2xx_read_shunt()

int ina2xx_read_shunt ( const ina2xx_t dev,
int16_t *  voltage 
)

Read shunt voltage in E-05 V.

Parameters
[in]devdevice descriptor of sensor
[out]voltagemeasured voltage across shunt resistor in E-05 V
Returns
0 on success
<0 on error