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.

typedef enum ina2xx_badc	ina2xx_badc_t
	Bus ADC settings.

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.

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.

int	ina2xx_read_shunt (const ina2xx_t dev, int16_t voltage)
	Read shunt voltage in E-05 V.

int	ina2xx_read_bus (const ina2xx_t dev, uint16_t voltage)
	Read bus voltage in mV.

int	ina2xx_read_current (const ina2xx_t dev, int32_t current)
	Read shunt current in E-05 A.

int	ina2xx_read_power (const ina2xx_t dev, uint32_t power)
	Read power consumption in E-04 W.

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

typedef enum ina2xx_i_range 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

enum 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

enum 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

enum 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

enum 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

enum 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]	dev	device descriptor of sensor to initialize
[in]	params	Configuration parameters to use

Returns: 0 on success, <0 on error.

Return values

0	Success
-ENODEV	Device seems not to be an INA2XX device
-EINVAL	`dev` or `params` is NULL
-ERANGE	`params` contained invalid setting: Increase current range
<0	Failure, 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]	dev	device descriptor of sensor
[out]	voltage	The measured bus voltage in mV

Returns: <0 on error, >= 0 on success

Return values

0	Success, no new power value available
1	Success, new value for ina2xx_read_power ready
-EDOM	Overflow during power/current calculations.
<0	Error 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]	dev	device descriptor of sensor
[out]	current	measured 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]	dev	device descriptor of sensor
[out]	power	measured 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]	dev	device descriptor of sensor
[out]	voltage	measured voltage across shunt resistor in E-05 V

Returns: 0 on success; <0 on error

Detailed Description

Supported Hardware

Choosing the Right Shunt Resistor

Files

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

◆ ina2xx_badc_t

◆ ina2xx_i_range_t

◆ ina2xx_sadc_t

Enumeration Type Documentation

◆ ina2xx_badc

◆ ina2xx_brng

◆ ina2xx_i_range

◆ ina2xx_mode

◆ ina2xx_pga

◆ ina2xx_sadc

Function Documentation

◆ ina2xx_init()

◆ ina2xx_read_bus()

◆ ina2xx_read_current()

◆ ina2xx_read_power()

◆ ina2xx_read_shunt()