Struct ina3221::INA3221

pub struct INA3221<I2C> {
    pub address: u8,
    /* private fields */
}

Device driver for the INA3221 current and power monitor

The INA3221 is a triple-channel shunt and bus voltage monitor that can be used to measure current and power consumption from up to three loads.

It is very similar to the INA219, but with a few additional features and a different register layout.

Configuration

The INA3221 can be configured to use different operating modes and alert thresholds.

It is important to note that the INA3221 will retain configuration settings unless the device is reset or power cycled. You can manually reset the device by calling the reset() method.

Channels

The INA3221 has three channels, each of which can be used to measure the current and power consumption of a load. The voltage should not exceed 26V and the maximum current draw should not exceed 3.2A (per-channel).

The INA3221 can be configured to enable or disable each channel individually. By default, all three channels are enabled.

The last measurements are retained in the device’s registers, even if the channel is disabled. This means that the last measurements will be returned when the channel is read.

Channel index is zero-based, so channel 1 is index 0, channel 2 is index 1, and channel 3 is index 2. Attempting to use a channel index outside of the range of 0-2 will use the third channel.

Shunt Resistor

The INA3221 requires a shunt resistor to be connected to each channel. The value of this resistor is used to calculate the current draw from the load. The shunt resistor should be as small as possible, but large enough to handle the maximum current draw of the load. The shunt resistor should be connected between the load and the INA3221’s shunt voltage measurement pin.

A common value for the shunt resistor is 0.1 ohms, which can handle up to 3.2A of current draw.

Current Calculation

Unlike the INA219, the INA3221 does not store the shunt resistor value in the device, and so the current draw must be calculated manually instead of using the device’s built-in current calculation and register.

The bonus of this is that the shunt resistor value can be changed without the need to calibrate the INA3221, only the firmware needs to be updated.

The current draw can be calculated using Ohm’s Law: I = V / R

The ohms crate is re-exported by this crate, so you can use the defined unit types to make the calculation easier to read and keep track of the denominator units.

Example

// Assume a shunt resistor value of 0.1 ohms
let shunt_resistor = 100u32.milli_ohms();
let shunt_voltage = ina.get_shunt_voltage(0).unwrap();
let current_milliamps = shunt_voltage.milli_volts() / shunt_resistor.ohms();

Power Calculation

Similar to the current calculation, the power draw can be calculated using Ohm’s Law: P = I * V

Again, it is important to be mindful of the units used when calculating the power draw.

Example

// Assume a shunt resistor value of 0.1 ohms
let shunt_resistor = 100u32.milli_ohms();
let shunt_voltage = ina.get_shunt_voltage(0).unwrap();
let bus_voltage = ina.get_bus_voltage(0).unwrap();

// Can use the '+' operator to add the shunt and bus voltage structs together
let load_voltage = bus_voltage + shunt_voltage;

let current_milliamps = shunt_voltage.milli_volts() / shunt_resistor.ohms();
let power_milliwatts = current_milliamps * load_voltage.volts();

Operating Mode

The INA3221 can be configured to operate in one of three modes:

• Power-down
• Triggered
• Continuous

The default operating mode is continuous, which means that the device will continuously measure the shunt and bus voltages and store the results in the device’s registers. Any disabled channels will not be measured and are skipped from the measurement cycle.

When triggered mode is set, the device will take a one-time measurement of the shunt and bus voltages, and then enter a power-down state. The device will remain in this state until the operating mode is changed to either continuous or triggered (again).

The power-down mode will disable all measurements and put the device into a low-power state. The last measurement results will be stored in the device’s registers and can be read even while powered down.

Alerts

The INA3221 can be configured to trigger various alerts based on the various measurements.

The following alerts are available:

• Over-current (Critical)
• Over-current (Warning)
• Under-voltage (PowerValid)
• Over-voltage (PowerValid)

The ohms crate is re-exported by this crate, so you can use the defined unit types to make the calculation easier to read and keep track of the denominator units.

Example

let max_current = 1u32.amps();  // 1A
let shunt_resistor = 100u32.ohms(); // 0.1 ohms

// Calculate the maximum voltage that can be measured on the shunt using Ohm's Law (V = I * R)
let max_voltage = max_current.milli_amps() * shunt_resistor.ohms(); // 100mV

// Set the critical alert limit for channel 1 to raise when exceeding 1A of current draw
ina.set_critical_alert_limit(0, max_voltage.milli_volts()).unwrap();

Note that these limits are based on the shunt voltage, not the load voltage.

Fields

address: u8

I2C address of the INA3221

Implementations

impl<I2C, E> INA3221<I2C>where I2C: I2c<Error = E>,

pub fn new(i2c: I2C, address: u8) -> INA3221<I2C>

Create a new INA3221 driver instance from an I2C peripheral on a specific address

This is typically 0x40, 0x41, or 0x42 depending on the A0 pin setting

pub fn get_configuration(&self) -> Result<u16, E>

Gets the active configuration bits from the INA3221

pub fn get_mode(&self) -> Result<OperatingMode, E>

Gets the operating mode of the INA3221

pub fn set_mode(&mut self, mode: OperatingMode) -> Result<(), E>

Sets the operating mode of the INA3221

Setting the mode to OperatingMode::Triggered will trigger a measurement cycle

pub fn get_channels_enabled(&self, statuses: &mut [bool]) -> Result<(), E>

Gets the enabled status for all three channels, storing them in an array

This is useful for iterating over all channels without having to call is_channel_enabled multiple times

pub fn set_channels_enabled(&mut self, enabled: &[bool]) -> Result<(), E>

Sets the enabled status for all three channels

This is useful for enabling or disabling all channels at once without having to call set_channel_enabled multiple times

Disabling a channel prevents it from being measured, but it can still be read for the last measurement result

pub fn is_channel_enabled(&self, channel: u8) -> Result<bool, E>

Checks if a monitoring channel is enabled on the INA3221

A disabled channel can still be read, but will not be measured until it is re-enabled

pub fn set_channel_enabled(&mut self, channel: u8, enabled: bool) -> Result<(), E>

Enables or disables a monitoring channel on the INA3221

Disabling a channel prevents it from being measured, but it can still be read for the last measurement result

pub fn get_shunt_voltage(&self, channel: u8) -> Result<Voltage, E>

Gets the shunt voltage of a specific monitoring channel

pub fn get_bus_voltage(&self, channel: u8) -> Result<Voltage, E>

Gets the bus voltage of a specific monitoring channel

pub fn get_critical_alert_limit(&self, channel: u8) -> Result<Voltage, E>

Gets the critical alert limit of a specific monitoring channel

This is the shunt voltage limit that will trigger a critical alert on that channel

pub fn set_critical_alert_limit( &mut self, channel: u8, voltage_limit: Voltage ) -> Result<(), E>

Sets the critical alert limit for a specific monitoring channel

This is the shunt voltage limit that will trigger a critical alert on that channel

pub fn set_critical_alert_latch(&mut self, enabled: bool) -> Result<(), E>

Sets the critical alert latch behavior for the warning alert pin

If enabled, the critical alert pin will latch until the warning alert is cleared

pub fn get_warning_alert_limit(&self, channel: u8) -> Result<Voltage, E>

Gets the warning alert limit of a specific monitoring channel

This is the shunt voltage limit that will trigger a warning alert on that channel

pub fn set_warning_alert_limit( &mut self, channel: u8, voltage_limit: Voltage ) -> Result<(), E>

Sets the warning alert limit for a specific monitoring channel

This is the shunt voltage limit that will trigger a warning alert on that channel

pub fn set_warning_alert_latch(&mut self, enabled: bool) -> Result<(), E>

Sets the warning alert latch behavior for the warning alert pin

If enabled, the warning alert pin will latch until the warning alert is cleared

pub fn get_power_valid_limits(&self) -> Result<(Voltage, Voltage), E>

Gets the power valid limits of all enabled monitoring channels

These are the lower and upper limits (respectively) for the bus voltage that will trigger a power valid alert on all enabled channels

pub fn set_power_valid_limits( &mut self, lower_limit: Voltage, upper_limit: Voltage ) -> Result<(), E>

Sets the power valid limits for all enabled monitoring channels

These are the upper and lower limits for the bus voltage that will trigger a power valid alert on all enabled channels

pub fn read_alert_flags(&mut self, preserve: bool) -> Result<MaskEnableFlags, E>

Reads the alert flags from the INA3221

If preserve is set to true, the flags will not be cleared after reading

pub fn get_manufacturer_id(&self) -> Result<u16, E>

Gets the manufacturer ID from the INA3221

This value is always 0x5449 (‘TI’ in ASCII), or at least should be for genuine INA3221s

pub fn get_die_id(&self) -> Result<u16, E>

Gets the die ID from the INA3221

This value is always 0x3220, or at least should be for genuine INA3221s

pub fn reset(&mut self) -> Result<(), E>

Resets the INA3221

This clears all configuration bits and sets the default configuration