The INA3221. More...

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

Macros
#define	CODE13_MAX 4095
	Ends of the 13-bit range: 7FF8h and 8000h (§8.2.2).
#define	CODE13_MIN (-4096)

Functions
uint16_t	ina3221_config (uint8_t channels, uint8_t avg, uint8_t vbusct, uint8_t vshct, uint8_t mode)
	Configuration from its fields. `channels:` bit 0 CH1, bit 1 CH2, bit 2 CH3, which the register holds in bits 14, 13 and 12.
uint8_t	ina3221_channels (uint16_t config)
	The channels a configuration enables: bit 0 CH1 to bit 2 CH3.
uint32_t	ina3221_ct_us (uint8_t code)
	Conversion time of a VBUSCT or VSHCT code, µs, typical (Table 8-4; the maxima in §6.5 run 10% longer).
uint32_t	ina3221_cycle_us (uint16_t config)
	Time from one result to the next on every enabled channel, µs, with averaging at 1: per channel the shunt then the bus conversion, channels one after another (§7.3.1).
bool	ina3221_identity_ok (uint16_t maker, uint16_t die)
	Whether the manufacturer and die IDs name an INA3221.
int32_t	ina3221_code13 (uint16_t raw)
	The 13-bit value in bits 15-3 of a shunt or bus register: -4096 to 4095.
sense_value_t	ina3221_current_ua (uint32_t shunt_uohm, int32_t code)
	A shunt code as current, µA: 40µV a step over `shunt_uohm`.
int32_t	ina3221_end_ua (uint32_t shunt_uohm, sense_clip_t end)
	The current the end code of the range stands for, µA: code 4095 for SENSE_CLIP_HIGH (1.638A on 0.1Ω), code -4096 for SENSE_CLIP_LOW (-1.6384 A).
int32_t	ina3221_bus_mv (int32_t code)
	A bus code in mV, 8mV a step.
ina3221_setup_err_t	ina3221_init (ina3221_t d, sense_bus_t bus, uint8_t addr, uint32_t shunt_uohm, uint16_t config)
	A part at `addr` with one shunt value for its channels and a Configuration value (INA3221_CONFIG_BENCH_*).
ina3221_setup_err_t	ina3221_init_shunts (ina3221_t d, sense_bus_t bus, uint8_t addr, const uint32_t *shunt_uohm, uint16_t config)
	The same with a shunt for each channel, `shunt_uohm`[0] CH1's.
static bool	read16 (ina3221_t d, uint8_t reg, uint16_t v)
	Read a 16-bit register.
static sense_state_t	probe (ina3221_t *d)
	Probe the part: identity, then the Configuration written and read back.
bool	ina3221_step (ina3221_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	ina3221_state (const ina3221_t *d)
	The part's state as of the last probe.
static uint8_t	channel_reg (const ina3221_t *d, uint8_t ch, uint8_t first, unsigned mode_bit)
	Channel `ch's` register (shunt or bus, by `first`) when the set-up converts it; 0 when it does not.
static sense_err_t	read_reg (ina3221_t d, uint8_t reg, uint16_t raw)
	Read a 16-bit register value, 2 bytes.
sense_err_t	ina3221_read_current (ina3221_t d, uint8_t ch, sense_value_t ua)
	Channel `ch` (1 to 3) current, µA.
sense_err_t	ina3221_read_bus (ina3221_t d, uint8_t ch, int32_t mv)
	Channel `ch` (1 to 3) bus voltage, mV, at IN-; the same refusals.
sense_err_t	ina3221_read_flags (ina3221_t d, uint16_t mask_enable)
	Mask/Enable as read; the read clears its flags.
sense_err_t	ina3221_verify (ina3221_t d, bool lost)
	The Configuration register read back against the value written.

Detailed Description

The INA3221.

See ina3221.h; tables and sections are TI SBOS576C's.

SPDX-License-Identifier: MIT

Function Documentation

◆ channel_reg()

uint8_t channel_reg	(	const ina3221_t *	d,
		uint8_t	ch,
		uint8_t	first,
		unsigned	mode_bit )

static

Channel ch's register (shunt or bus, by first) when the set-up converts it; 0 when it does not.

Parameters

d	The driver.
ch	Channel, 1 to 3.
first	Register of channel 1: the shunt or the bus register.
mode_bit	The Configuration mode bit that must be set: 1 for the shunt, 2 for the bus.

Returns: The register address, or 0 when the channel is out of range, not enabled, or its mode bit is clear.

◆ ina3221_bus_mv()

int32_t ina3221_bus_mv ( int32_t code )

A bus code in mV, 8mV a step.

Parameters

code	The bus code, from ina3221_code13().

Returns: The voltage in mV.

◆ ina3221_channels()

uint8_t ina3221_channels ( uint16_t config )

The channels a configuration enables: bit 0 CH1 to bit 2 CH3.

Parameters

config The Configuration register value.

Returns: Bit 0 CH1 to bit 2 CH3.

◆ ina3221_code13()

int32_t ina3221_code13 ( uint16_t raw )

The 13-bit value in bits 15-3 of a shunt or bus register: -4096 to 4095.

Parameters

raw	The register value.

Returns: The signed 13-bit code, -4096 to 4095.

◆ ina3221_config()

uint16_t ina3221_config	(	uint8_t	channels,
		uint8_t	avg,
		uint8_t	vbusct,
		uint8_t	vshct,
		uint8_t	mode )

Configuration from its fields. channels: bit 0 CH1, bit 1 CH2, bit 2 CH3, which the register holds in bits 14, 13 and 12.

Parameters

channels	Bit 0 CH1, bit 1 CH2, bit 2 CH3, which the register holds in bits 14, 13 and 12.
avg	Averaging code.
vbusct	Bus conversion time code.
vshct	Shunt conversion time code.
mode	Operating mode, an INA3221_MODE_* value.

Returns: The Configuration register value.

◆ ina3221_ct_us()

uint32_t ina3221_ct_us ( uint8_t code )

Conversion time of a VBUSCT or VSHCT code, µs, typical (Table 8-4; the maxima in §6.5 run 10% longer).

Parameters

code	The conversion time code.

Returns: The typical conversion time, in µs.

◆ ina3221_current_ua()

sense_value_t ina3221_current_ua	(	uint32_t	shunt_uohm,
		int32_t	code )

A shunt code as current, µA: 40µV a step over shunt_uohm.

A code at either end (4095, -4096) is a clip.

Parameters

shunt_uohm	Shunt resistance, in µΩ.
code	The shunt code, from ina3221_code13().

Returns: The current in µA.

◆ ina3221_cycle_us()

uint32_t ina3221_cycle_us ( uint16_t config )

Time from one result to the next on every enabled channel, µs, with averaging at 1: per channel the shunt then the bus conversion, channels one after another (§7.3.1).

0 for a mode that does not convert continuously.

Parameters

config The Configuration register value.

Returns: The cycle time, in µs; 0 for a mode that does not convert continuously.

◆ ina3221_end_ua()

int32_t ina3221_end_ua	(	uint32_t	shunt_uohm,
		sense_clip_t	end )

The current the end code of the range stands for, µA: code 4095 for SENSE_CLIP_HIGH (1.638A on 0.1Ω), code -4096 for SENSE_CLIP_LOW (-1.6384 A).

0 for SENSE_CLIP_NONE.

Parameters

shunt_uohm	Shunt resistance, in µΩ.
end	The clip the reading sits at.

Returns: The current in µA.

◆ ina3221_identity_ok()

bool ina3221_identity_ok	(	uint16_t	maker,
		uint16_t	die )

Whether the manufacturer and die IDs name an INA3221.

Parameters

maker	The manufacturer ID register value.
die	The die ID register value.

Returns: true when maker is 5449h and die is 3220h.

◆ ina3221_init()

ina3221_setup_err_t ina3221_init	(	ina3221_t *	d,
		sense_bus_t *	bus,
		uint8_t	addr,
		uint32_t	shunt_uohm,
		uint16_t	config )

A part at addr with one shunt value for its channels and a Configuration value (INA3221_CONFIG_BENCH_*).

On anything but INA3221_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, INA3221_ADDR_MIN to INA3221_ADDR_MAX.
shunt_uohm	Shunt resistance for every channel, in µΩ, at least INA3221_SHUNT_MIN_UOHM.
config	The Configuration register value.

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

◆ ina3221_init_shunts()

ina3221_setup_err_t ina3221_init_shunts	(	ina3221_t *	d,
		sense_bus_t *	bus,
		uint8_t	addr,
		const uint32_t *	shunt_uohm,
		uint16_t	config )

The same with a shunt for each channel, shunt_uohm[0] CH1's.

Each channel the configuration enables needs one of at least INA3221_SHUNT_MIN_UOHM (INA3221_SETUP_NO_SHUNT otherwise); a channel it leaves off keeps 0 whatever is given.

Parameters

d	The driver to set up.
bus	The sensor bus the part sits on.
addr	I2C address, INA3221_ADDR_MIN to INA3221_ADDR_MAX.
shunt_uohm	One shunt value per channel, in µΩ, CH1 first.
config	The Configuration register value.

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

◆ ina3221_read_bus()

sense_err_t ina3221_read_bus	(	ina3221_t *	d,
		uint8_t	ch,
		int32_t *	mv )

Channel ch (1 to 3) bus voltage, mV, at IN-; the same refusals.

Parameters

d	The driver.
ch	Channel, 1 to 3.
mv	Receives the bus voltage, in mV.

Returns: SENSE_OK, SENSE_BAD_ARG, or the bus error.

◆ ina3221_read_current()

sense_err_t ina3221_read_current	(	ina3221_t *	d,
		uint8_t	ch,
		sense_value_t *	ua )

Channel ch (1 to 3) current, µA.

A channel the configuration does not enable, or a mode that does not convert the shunt, is SENSE_BAD_ARG and nothing is sent. On anything but SENSE_OK ua is left as it was.

Parameters

d	The driver.
ch	Channel, 1 to 3.
ua	Receives the current, in µA.

Returns: SENSE_OK, SENSE_BAD_ARG, or the bus error.

◆ ina3221_read_flags()

sense_err_t ina3221_read_flags	(	ina3221_t *	d,
		uint16_t *	mask_enable )

Mask/Enable as read; the read clears its flags.

Parameters

d	The driver.
mask_enable	Receives the Mask/Enable value.

Returns: SENSE_OK, or the bus error.

◆ ina3221_state()

sense_state_t ina3221_state ( const ina3221_t * d )

The part's state as of the last probe.

Parameters

d	The driver.

Returns: The sense_state_t of the part.

◆ ina3221_step()

bool ina3221_step	(	ina3221_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 4 transactions, 455µ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.

◆ ina3221_verify()

sense_err_t ina3221_verify	(	ina3221_t *	d,
		bool *	lost )

The Configuration register read back against the value written.

A part that resets itself answers with INA3221_CONFIG_RESET: all three channels, 1.1ms conversions, a result every 6.6ms. 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: a shunt or bus register FFFFh 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.

◆ probe()

sense_state_t probe ( ina3221_t * d )

static

Probe the part: identity, then the Configuration written and read back.

Parameters

d	The driver.

Returns: SENSE_PART_ABSENT, SENSE_PART_WRONG_ID, SENSE_PART_REFUSED or SENSE_PART_ONLINE.

◆ read16()

bool read16	(	ina3221_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.

◆ read_reg()

sense_err_t read_reg	(	ina3221_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.

Macros

Functions

Detailed Description

Function Documentation

◆ channel_reg()

◆ ina3221_bus_mv()

◆ ina3221_channels()

◆ ina3221_code13()

◆ ina3221_config()

◆ ina3221_ct_us()

◆ ina3221_current_ua()

◆ ina3221_cycle_us()

◆ ina3221_end_ua()

◆ ina3221_identity_ok()

◆ ina3221_init()

◆ ina3221_init_shunts()

◆ ina3221_read_bus()

◆ ina3221_read_current()

◆ ina3221_read_flags()

◆ ina3221_state()

◆ ina3221_step()

◆ ina3221_verify()

◆ probe()

◆ read16()

◆ read_reg()