The INA228. More...

#include "ina228.h"
#include <string.h>

Macros
#define	CODE20_MAX 524287
	Ends of a 20-bit two's complement register.
#define	CODE20_MIN (-524288)
#define	FS_NARROW_NV 40960000u
	Full-scale shunt voltages as max mA × µΩ, which is nV (Table 8-1).
#define	FS_WIDE_NV 163840000u

Functions
uint16_t	ina228_adc_config (uint8_t mode, uint8_t vbusct, uint8_t vshct, uint8_t vtct, uint8_t avg)
	ADC_CONFIG from its fields; each is masked to its width.
static uint32_t	ina228_ct_us (uint8_t code)
	Conversion time of a VBUSCT, VSHCT or VTCT code, µs (Table 7-6).
uint32_t	ina228_averages (uint8_t code)
	Samples averaged for an AVG code (Table 7-6).
uint32_t	ina228_cycle_us (uint16_t adc_config)
	Time from one result to the next for an ADC_CONFIG, µs: the enabled inputs' conversion times, one after another, times the averages (§7.3.4).
bool	ina228_identity_ok (uint16_t maker, uint16_t device)
	Whether MANUFACTURER_ID and DEVICE_ID name an INA228.
ina228_setup_err_t	ina228_calibrate (uint32_t shunt_uohm, uint32_t max_ma, ina228_cal_t *out)
	SHUNT_CAL and ADCRANGE for a shunt and a maximum current. `out` is filled only on INA228_SETUP_OK.
static uint64_t	r_k (const ina228_cal_t *cal)
	R × 4 at ADCRANGE 1: the denominator every quantity scaled by CURRENT_LSB = SHUNT_CAL / (13107.2 × R[µΩ] × (4 at ADCRANGE 1)) shares.
int32_t	ina228_code20 (uint32_t raw24)
	The 20-bit value in bits 23-4 of a 24-bit register (VSHUNT, VBUS, CURRENT), as raw: -2^19 to 2^19 - 1.
static sense_clip_t	clip20 (int32_t code)
	Classify a 20-bit code: at either end of its range it is a clip.
sense_value_t	ina228_current_ua (const ina228_cal_t *cal, int32_t code)
	CURRENT in µA; a code at either end is a clip.
sense_value_t	ina228_vshunt_nv (const ina228_cal_t *cal, int32_t code)
	VSHUNT in nV: 312.5 nV a step at ADCRANGE 0, 78.125 nV at 1 (Table 7-9); a code at either end is a clip.
int32_t	ina228_vbus_uv (int32_t code)
	VBUS in µV, 195.3125µV a step (Table 7-10).
int32_t	ina228_dietemp_mdegc (uint16_t raw)
	DIETEMP in m°C, 7.8125m°C a step (Table 7-11).
uint64_t	ina228_power_uw (const ina228_cal_t *cal, uint32_t raw24)
	POWER (24 bit, unsigned) in µW: 3.2 × CURRENT_LSB a step (Eq.
uint64_t	ina228_energy_mj (const ina228_cal_t *cal, uint64_t raw40)
	ENERGY (40 bit, unsigned) in mJ: 16 × 3.2 × CURRENT_LSB a step (Eq.
int64_t	ina228_charge_uc (const ina228_cal_t *cal, uint64_t raw40)
	CHARGE (40 bit, two's complement) in µC: CURRENT_LSB a step (Eq.
ina228_setup_err_t	ina228_init (ina228_t d, sense_bus_t bus, uint8_t addr, uint32_t shunt_uohm, uint32_t max_ma, uint16_t adc_config)
	A part at `addr` with a shunt, a maximum current and an ADC_CONFIG (INA228_ADC_BENCH for this bench).
static bool	read16 (ina228_t d, uint8_t reg, uint16_t v)
	Read a 16-bit register.
static bool	write16 (ina228_t *d, uint8_t reg, uint16_t v)
	Write a 16-bit register.
static sense_state_t	probe (ina228_t *d)
	Probe the part: identity, then the set-up written and read back.
bool	ina228_step (ina228_t *d, uint32_t now_ms)
	Every tick: probes the part when it is due – at the first call, and SENSE_RETRY_MS after it was found absent, wrong, refused or offline.
sense_state_t	ina228_state (const ina228_t *d)
	The part's state as of the last probe.
static sense_err_t	read24 (ina228_t d, uint8_t reg, uint32_t raw)
	Read a 24-bit register value, 3 bytes.
static sense_err_t	read40 (ina228_t d, uint8_t reg, uint64_t raw)
	Read a 40-bit register value, 5 bytes.
static sense_err_t	read_reg16 (ina228_t d, uint8_t reg, uint16_t raw)
	Read a 16-bit register value, 2 bytes.
sense_err_t	ina228_read_current (ina228_t d, sense_value_t ua)
	Readings.
sense_err_t	ina228_read_vshunt (ina228_t d, sense_value_t nv)
	Read the shunt voltage.
sense_err_t	ina228_read_vbus (ina228_t d, int32_t uv)
	Read the bus voltage.
sense_err_t	ina228_read_power (ina228_t d, uint64_t uw)
	Read the power.
sense_err_t	ina228_read_dietemp (ina228_t d, int32_t mdegc)
	Read the die temperature.
sense_err_t	ina228_read_diag (ina228_t d, uint16_t diag)
	DIAG_ALRT as read; the read clears the latched flags (Table 7-16).
sense_err_t	ina228_read_energy (ina228_t d, uint64_t mj)
	Read the energy.
sense_err_t	ina228_read_charge (ina228_t d, int64_t uc)
	Read the charge.
sense_err_t	ina228_clear_totals (ina228_t *d)
	ENERGY and CHARGE to 0: CONFIG with RSTACC, then without.
sense_err_t	ina228_verify (ina228_t d, bool lost)
	ADC_CONFIG read back against the value written.

Detailed Description

The INA228.

See ina228.h; tables and equations are TI SLYS021A's.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ FS_NARROW_NV

#define FS_NARROW_NV 40960000u

Full-scale shunt voltages as max mA × µΩ, which is nV (Table 8-1).

±40.96mV, ADCRANGE 1

◆ FS_WIDE_NV

#define FS_WIDE_NV 163840000u

±163.84mV, ADCRANGE 0

Function Documentation

◆ clip20()

sense_clip_t clip20 ( int32_t code )

static

Classify a 20-bit code: at either end of its range it is a clip.

Parameters

code	The 20-bit code, -524288 to 524287.

Returns: SENSE_CLIP_HIGH at 524287 or above, SENSE_CLIP_LOW at -524288 or below, else SENSE_CLIP_NONE.

◆ ina228_adc_config()

uint16_t ina228_adc_config	(	uint8_t	mode,
		uint8_t	vbusct,
		uint8_t	vshct,
		uint8_t	vtct,
		uint8_t	avg )

ADC_CONFIG from its fields; each is masked to its width.

Parameters

mode	Operating mode.
vbusct	Bus voltage conversion time code.
vshct	Shunt voltage conversion time code.
vtct	Temperature conversion time code.
avg	Averaging code.

Returns: The ADC_CONFIG register value.

◆ ina228_averages()

uint32_t ina228_averages ( uint8_t code )

Samples averaged for an AVG code (Table 7-6).

Parameters

code	The AVG code.

Returns: The number of samples averaged.

◆ ina228_calibrate()

ina228_setup_err_t ina228_calibrate	(	uint32_t	shunt_uohm,
		uint32_t	max_ma,
		ina228_cal_t *	out )

SHUNT_CAL and ADCRANGE for a shunt and a maximum current. out is filled only on INA228_SETUP_OK.

Parameters

shunt_uohm	Shunt resistance, in µΩ.
max_ma	Maximum current, in mA.
out	Receives the calibration.

Returns: INA228_SETUP_OK, or the reason the set-up was refused.

◆ ina228_charge_uc()

int64_t ina228_charge_uc	(	const ina228_cal_t *	cal,
		uint64_t	raw40 )

CHARGE (40 bit, two's complement) in µC: CURRENT_LSB a step (Eq.

7).

Parameters

cal	The calibration.
raw40	The 40-bit CHARGE register value.

Returns: The charge in µC.

◆ ina228_clear_totals()

sense_err_t ina228_clear_totals ( ina228_t * d )

ENERGY and CHARGE to 0: CONFIG with RSTACC, then without.

A failure of the second write leaves RSTACC set; the call is to be repeated.

Parameters

d	The driver.

Returns: SENSE_OK, or the bus error.

◆ ina228_code20()

int32_t ina228_code20 ( uint32_t raw24 )

The 20-bit value in bits 23-4 of a 24-bit register (VSHUNT, VBUS, CURRENT), as raw: -2^19 to 2^19 - 1.

Parameters

raw24 The 24-bit register value.

Returns: The signed 20-bit code.

◆ ina228_ct_us()

uint32_t ina228_ct_us ( uint8_t code )

static

Conversion time of a VBUSCT, VSHCT or VTCT code, µs (Table 7-6).

Parameters

code	The conversion time code.

Returns: The typical conversion time, in µs.

◆ ina228_current_ua()

sense_value_t ina228_current_ua	(	const ina228_cal_t *	cal,
		int32_t	code )

CURRENT in µA; a code at either end is a clip.

Parameters

cal	The calibration.
code	The CURRENT code.

Returns: The current in µA.

◆ ina228_cycle_us()

uint32_t ina228_cycle_us ( uint16_t adc_config )

Time from one result to the next for an ADC_CONFIG, µs: the enabled inputs' conversion times, one after another, times the averages (§7.3.4).

0 for a mode that does not convert continuously.

Parameters

adc_config The ADC_CONFIG register value.

Returns: The cycle time, in µs.

◆ ina228_dietemp_mdegc()

int32_t ina228_dietemp_mdegc ( uint16_t raw )

DIETEMP in m°C, 7.8125m°C a step (Table 7-11).

Parameters

raw	The DIETEMP register value.

Returns: The die temperature in m°C.

◆ ina228_energy_mj()

uint64_t ina228_energy_mj	(	const ina228_cal_t *	cal,
		uint64_t	raw40 )

ENERGY (40 bit, unsigned) in mJ: 16 × 3.2 × CURRENT_LSB a step (Eq.

6).

Parameters

cal	The calibration.
raw40	The 40-bit ENERGY register value.

Returns: The energy in mJ.

◆ ina228_identity_ok()

bool ina228_identity_ok	(	uint16_t	maker,
		uint16_t	device )

Whether MANUFACTURER_ID and DEVICE_ID name an INA228.

Parameters

maker	The MANUFACTURER_ID register value.
device	The DEVICE_ID register value.

Returns: true when the IDs name an INA228.

◆ ina228_init()

ina228_setup_err_t ina228_init	(	ina228_t *	d,
		sense_bus_t *	bus,
		uint8_t	addr,
		uint32_t	shunt_uohm,
		uint32_t	max_ma,
		uint16_t	adc_config )

A part at addr with a shunt, a maximum current and an ADC_CONFIG (INA228_ADC_BENCH for this bench).

On anything but INA228_SETUP_OK the part is left SENSE_PART_UNSET and nothing is ever sent to it.

Parameters

d	The driver to set up.
bus	The sensor bus the part sits on.
addr	I2C address of the part.
shunt_uohm	Shunt resistance, in µΩ.
max_ma	Maximum current, in mA.
adc_config	The ADC_CONFIG register value.

Returns: INA228_SETUP_OK, or the reason the set-up was refused.

◆ ina228_power_uw()

uint64_t ina228_power_uw	(	const ina228_cal_t *	cal,
		uint32_t	raw24 )

POWER (24 bit, unsigned) in µW: 3.2 × CURRENT_LSB a step (Eq.

5).

Parameters

cal	The calibration.
raw24	The 24-bit POWER register value.

Returns: The power in µW.

◆ ina228_read_charge()

sense_err_t ina228_read_charge	(	ina228_t *	d,
		int64_t *	uc )

Read the charge.

Parameters

d	The driver.
uc	Receives the charge, in µC.

Returns: SENSE_OK, or the bus error.

◆ ina228_read_current()

sense_err_t ina228_read_current	(	ina228_t *	d,
		sense_value_t *	ua )

Readings.

Each is one transaction; on anything but SENSE_OK the output is left as it was.

Parameters

d	The driver.
ua	Receives the current, in µA.

Returns: SENSE_OK, or the bus error.

◆ ina228_read_diag()

sense_err_t ina228_read_diag	(	ina228_t *	d,
		uint16_t *	diag )

DIAG_ALRT as read; the read clears the latched flags (Table 7-16).

Parameters

d	The driver.
diag	Receives the DIAG_ALRT value.

Returns: SENSE_OK, or the bus error.

◆ ina228_read_dietemp()

sense_err_t ina228_read_dietemp	(	ina228_t *	d,
		int32_t *	mdegc )

Read the die temperature.

Parameters

d	The driver.
mdegc	Receives the die temperature, in m°C.

Returns: SENSE_OK, or the bus error.

◆ ina228_read_energy()

sense_err_t ina228_read_energy	(	ina228_t *	d,
		uint64_t *	mj )

Read the energy.

Parameters

d	The driver.
mj	Receives the energy, in mJ.

Returns: SENSE_OK, or the bus error.

◆ ina228_read_power()

sense_err_t ina228_read_power	(	ina228_t *	d,
		uint64_t *	uw )

Read the power.

Parameters

d	The driver.
uw	Receives the power, in µW.

Returns: SENSE_OK, or the bus error.

◆ ina228_read_vbus()

sense_err_t ina228_read_vbus	(	ina228_t *	d,
		int32_t *	uv )

Read the bus voltage.

Parameters

d	The driver.
uv	Receives the bus voltage, in µV.

Returns: SENSE_OK, or the bus error.

◆ ina228_read_vshunt()

sense_err_t ina228_read_vshunt	(	ina228_t *	d,
		sense_value_t *	nv )

Read the shunt voltage.

Parameters

d	The driver.
nv	Receives the shunt voltage, in nV.

Returns: SENSE_OK, or the bus error.

◆ ina228_state()

sense_state_t ina228_state ( const ina228_t * d )

The part's state as of the last probe.

Parameters

d	The driver.

Returns: The sense_state_t of the part.

◆ ina228_step()

bool ina228_step	(	ina228_t *	d,
		uint32_t	now_ms )

Every tick: probes the part when it is due – at the first call, and SENSE_RETRY_MS after it was found absent, wrong, refused or offline.

A probe is 10 transactions, 1075µs of bus time at 400kHz without the controller's own time between them. Returns whether the part is online.

Parameters

d	The driver.
now_ms	The current time, in ms.

Returns: true when the part is online.

◆ ina228_vbus_uv()

int32_t ina228_vbus_uv ( int32_t code )

VBUS in µV, 195.3125µV a step (Table 7-10).

Parameters

code	The VBUS code.

Returns: The bus voltage in µV.

◆ ina228_verify()

sense_err_t ina228_verify	(	ina228_t *	d,
		bool *	lost )

ADC_CONFIG read back against the value written.

A part that resets itself answers with INA228_ADC_RESET at either range, and CONFIG with 0, which is also what ADCRANGE 0 writes: ADC_CONFIG is the register that tells. Such a part computes CURRENT at ADCRANGE 0, a quarter of the truth for a set-up at ADCRANGE 1. Another value than the one written is read a second time at once, so one corrupted read is no reset; when both differ the part is taken offline (sense_part_lost()), lost is set and SENSE_OK returned. A read of FFFFh, the bus that no part drives, takes it offline on that read without a second. lost is false otherwise. The readings are not checked for all ones: CURRENT FFFFFFh is code -1 and taken. One transaction, two on a first mismatch other than FFFFh: 120µs of bus time each at 400kHz.

Parameters

d	The driver.
lost	Set true when the part was taken offline.

Returns: SENSE_OK, or the bus error.

◆ ina228_vshunt_nv()

sense_value_t ina228_vshunt_nv	(	const ina228_cal_t *	cal,
		int32_t	code )

VSHUNT in nV: 312.5 nV a step at ADCRANGE 0, 78.125 nV at 1 (Table 7-9); a code at either end is a clip.

Parameters

cal	The calibration.
code	The VSHUNT code.

Returns: The shunt voltage in nV.

◆ probe()

sense_state_t probe ( ina228_t * d )

static

Probe the part: identity, then the set-up written and read back.

Parameters

d	The driver.

Returns: SENSE_PART_ABSENT, SENSE_PART_WRONG_ID, SENSE_PART_REFUSED or SENSE_PART_ONLINE.

◆ r_k()

uint64_t r_k ( const ina228_cal_t * cal )

static

R × 4 at ADCRANGE 1: the denominator every quantity scaled by CURRENT_LSB = SHUNT_CAL / (13107.2 × R[µΩ] × (4 at ADCRANGE 1)) shares.

Parameters

cal	The calibration.

Returns: The shunt resistance times 4 at ADCRANGE 1, in µΩ.

◆ read16()

bool read16	(	ina228_t *	d,
		uint8_t	reg,
		uint16_t *	v )

static

Read a 16-bit register.

Parameters

d	The driver.
reg	Register address.
v	Receives the value.

Returns: true when the read succeeded.

◆ read24()

sense_err_t read24	(	ina228_t *	d,
		uint8_t	reg,
		uint32_t *	raw )

static

Read a 24-bit register value, 3 bytes.

Parameters

d	The driver.
reg	Register address.
raw	Receives the value.

Returns: SENSE_OK, or the bus error.

◆ read40()

sense_err_t read40	(	ina228_t *	d,
		uint8_t	reg,
		uint64_t *	raw )

static

Read a 40-bit register value, 5 bytes.

Parameters

d	The driver.
reg	Register address.
raw	Receives the value.

Returns: SENSE_OK, or the bus error.

◆ read_reg16()

sense_err_t read_reg16	(	ina228_t *	d,
		uint8_t	reg,
		uint16_t *	raw )

static

Read a 16-bit register value, 2 bytes.

Parameters

d	The driver.
reg	Register address.
raw	Receives the value.

Returns: SENSE_OK, or the bus error.

◆ write16()

bool write16	(	ina228_t *	d,
		uint8_t	reg,
		uint16_t	v )

static

Write a 16-bit register.

Parameters

d	The driver.
reg	Register address.
v	The value to write.

Returns: true when the write succeeded.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ FS_NARROW_NV

◆ FS_WIDE_NV

Function Documentation

◆ clip20()

◆ ina228_adc_config()

◆ ina228_averages()

◆ ina228_calibrate()

◆ ina228_charge_uc()

◆ ina228_clear_totals()

◆ ina228_code20()

◆ ina228_ct_us()

◆ ina228_current_ua()

◆ ina228_cycle_us()

◆ ina228_dietemp_mdegc()

◆ ina228_energy_mj()

◆ ina228_identity_ok()

◆ ina228_init()

◆ ina228_power_uw()

◆ ina228_read_charge()

◆ ina228_read_current()

◆ ina228_read_diag()

◆ ina228_read_dietemp()

◆ ina228_read_energy()

◆ ina228_read_power()

◆ ina228_read_vbus()

◆ ina228_read_vshunt()

◆ ina228_state()

◆ ina228_step()

◆ ina228_vbus_uv()

◆ ina228_verify()

◆ ina228_vshunt_nv()

◆ probe()

◆ r_k()

◆ read16()

◆ read24()

◆ read40()

◆ read_reg16()

◆ write16()