# ina3221

INA3221 Triple Channel Shunt and Bus Votage Monitor library.

Author | Rob Jansen, Copyright © 2025..2025, all rights reserved.
Adapted-by |
Compiler | 2.5r9

Description

    Libray for the INA3221 Triple-Channel, High-Side Measurement,
                 Shunt and Bus Voltage Monitor. It is controlled using the IIC
                 interface at a maximum speed of 400 kHz.

Sources

    Datasheet Texas Instruments INA3221 Triple-Channel, High-Side
             Measurement, Shunt and Bus Voltage Monitor with I2C- and
             SMBUS-Compatible interface. SBOS576B –MAY 2012–REVISED MARCH 2016

Notes

    The main program must initialize the used - default - IIC interface
             with a maximum speed of 400 kHz and with a I2C_HARDWARE_TIMEOUT
             defined. Channels are numbered 1..3, but values 0..2 are used.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const bit*3 INA3221_CONV_TIME_2_MS = 0b101`
- `var byte _ina3221_iic_address`
- `var bit _ina3221_did_timeout`
- `const byte _INA3221_REGISTER_CH2_WARNING_ALERT_LIMIT = 0x0A`
- `const word _INA3221_MASK_WARNING_ALERT_2 = 0x0010`
- `const word _INA3221_MASK_CRITICAL_ALERT_2 = 0x0100`
- `const bit*3 INA3221_MODE_SHUNT_SINGLE = 0b001`
- `const byte _INA3221_REGISTER_CH3_SHUNT_VOLTAGE = 0x05`
- `const word _INA3221_MASK_SUMMATION_CHANNEL_3 = 0x1000`
- `const word _INA3221_MASK_CRITICAL_ALERT_LATCH = 0x0400`
- `const bit*3 INA3221_CONV_TIME_140_US = 0b000`
- `const word _INA3221_CONFIURATION_ENABLE_CHANNEL_1 = 0x4000`
- `const byte _INA3221_REGISTER_CH1_WARNING_ALERT_LIMIT = 0x08`
- `const bit*3 INA3221_AVG_SAMPLES_16 = 0b010`
- `const byte _INA3221_REGISTER_CH2_SHUNT_VOLTAGE = 0x03`
- `const byte _INA3221_REGISTER_CH3_BUS_VOLTAGE = 0x06`
- `const bit*3 INA3221_CONV_TIME_332_US = 0b010`
- `const word _INA3221_MASK_TIMING_CONTROL_ALERT = 0x0002`
- `const bit*3 INA3221_AVG_SAMPLES_1 = 0b000`
- `const byte _INA3221_REGISTER_CH2_CRITICAL_ALERT_LIMIT = 0x09`
- `const byte _INA3221_REGISTER_MANUFACTURER_ID = 0xFE`
- `const byte _INA3221_REGISTER_MASK_ENABLE = 0x0F`
- `const byte _INA3221_REGISTER_CH2_BUS_VOLTAGE = 0x04`
- `const word _INA3221_CONFIURATION_ENABLE_CHANNEL_2 = 0x2000`
- `const bit*3 INA3221_AVG_SAMPLES_4 = 0b001`
- `const byte _INA3221_REGISTER_POWER_VALID_LOWER_LIMIT = 0x11`
- `const bit*3 INA3221_AVG_SAMPLES_256 = 0b101`
- `const bit*3 INA3221_AVG_SAMPLES_1024 = 0b111`
- `const byte _INA3221_REGISTER_CH1_BUS_VOLTAGE = 0x02`
- `const word _INA3221_MASK_SUMMATION_CHANNEL_2 = 0x2000`
- `const word _INA3221_MASK_CRITICAL_ALERT_3 = 0x0080`
- `const word _INA3221_MASK_CRITICAL_ALERT_1 = 0x0200`
- `const word _INA3221_MASK_SUMMATION_CHANNEL_1 = 0x4000`
- `const byte _INA3221_REGISTER_CONFIGURATION = 0x00`
- `const bit*3 INA3221_CONV_TIME_4_MS = 0b110`
- `const byte _INA3221_REGISTER_CH3_CRITICAL_ALERT_LIMIT = 0x0B`
- `const bit*3 INA3221_AVG_SAMPLES_512 = 0b110`
- `const byte _INA3221_REGISTER_DIE_ID = 0xFF`
- `const bit*3 INA3221_MODE_BUS_CONTINUOUS = 0b110`
- `const bit*3 INA3221_CONV_TIME_1_MS = 0b100`
- `const bit*3 INA3221_MODE_SHUNT_BUS_SINGLE = 0b011`
- `const word _INA3221_CONFIURATION_RESET = 0x8000`
- `const bit*3 INA3221_CONV_TIME_588_US = 0b011`
- `const byte _INA3221_REGISTER_CH3_WARNING_ALERT_LIMIT = 0x0C`
- `const byte _INA3221_REGISTER_CH1_SHUNT_VOLTAGE = 0x01`
- `const byte INA3221_CHANNEL_1 = 0`
- `const bit*3 INA3221_CONV_TIME_204_US = 0b001`
- `const bit*3 INA3221_CONV_TIME_8_MS = 0b111`
- `const word _INA3221_MASK_POWER_VALID_ALERT = 0x0004`
- `const bit*3 INA3221_MODE_SHUNT_CONTINUOUS = 0b101`
- `const word _INA3221_CONFIURATION_ENABLE_CHANNEL_3 = 0x1000`
- `const word _INA3221_MASK_SUMMATION_ALERT = 0x0040`
- `const byte _INA3221_REGISTER_SHUNT_VOLTAGE_SUM = 0x0D`
- `const word _INA3221_MASK_CONVERSION_READY = 0x0001`
- `const byte INA3221_IIC_DEFAULT_ADDRESS = 0x40`
- `const byte _INA3221_REGISTER_CH1_CRITICAL_ALERT_LIMIT = 0x07`
- `const byte INA3221_CHANNEL_2 = 1`
- `const byte _INA3221_REGISTER_SHUNT_VOLTAGE_SUM_LIMIT = 0x0E`
- `const bit*3 INA3221_MODE_BUS_SINGLE = 0b010`
- `const word _INA3221_MASK_WARNING_ALERT_1 = 0x0020`
- `const word _INA3221_MASK_WARNING_ALERT_LATCH = 0x0800`
- `const bit*3 INA3221_AVG_SAMPLES_64 = 0b011`
- `const bit*3 INA3221_MODE_POWER_DOWN_1 = 0b000`
- `const bit*3 INA3221_MODE_SHUNT_BUS_CONTINUOUS = 0b111`
- `const bit*3 INA3221_MODE_POWER_DOWN_2 = 0b100`
- `const bit*3 INA3221_AVG_SAMPLES_128 = 0b100`
- `const word _INA3221_MASK_WARNING_ALERT_3 = 0x0008`
- `const byte _INA3221_REGISTER_POWER_VALID_UPPER_LIMIT = 0x10`
- `const byte INA3221_CHANNEL_3 = 2`
- `const byte INA3221_NR_OF_CHANNELS = 3`

### Procedures

- `ina3221_enable_warning_alert_latch()`
- `ina3221_disable_critical_alert_latch()`
- `ina3221_set_averaging_samples(bit*3 in samples)`
- `ina3221_disable_summation_channel(byte in channel)`
- `ina3221_set_shunt_voltage_conversion_time(bit*3 in time)`
- `ina3221_enable_summation_channel(byte in channel)`
- `ina3221_init()`
- `ina3221_set_iic_address(byte in address)`
- `ina3221_reset()`
- `ina3221_enable_critical_alert_latch()`
- `ina3221_disable_channel(byte in channel)`
- `ina3221_set_operating_mode(bit*3 in mode)`
- `ina3221_enable_channel(byte in channel)`
- `ina3221_set_bus_voltage_conversion_time(bit*3 in time)`
- `ina3221_disable_warning_alert_latch()`

Private

- `_ina3221_write_data_word(byte in register, word in data)`

### Functions

- `ina3221_critical_alert(word in flags, byte in channel) return bit`
- `ina3221_get_flags() return word`
- `ina3221_timeout_occured() return bit`
- `ina3221_timing_control_alert(word in flags) return bit`
- `get_manufacturer_id() return word`
- `ina3221_get_register_value(byte in register) return word`
- `ina3221_warning_alert(word in flags, byte in channel) return bit`
- `get_die_id() return word`
- `ina3221_power_valid_alert(word in flags) return bit`
- `ina3221_summation_alert(word in flags) return bit`
- `ina3221_get_iic_address() return byte`
- `ina3221_conversion_ready(word in flags) return bit`

Private

- `_ina3221_read_data_word(byte in register) return word`

## API details

### Global variables/contants

- `const bit*3 INA3221_CONV_TIME_2_MS = 0b101`

      2.116 ms.

- `var byte _ina3221_iic_address`

       Private variables -----------------------------------
      The IIC address can be changed.

- `var bit _ina3221_did_timeout`

      Keep track of occurence of timeout.

- `const byte _INA3221_REGISTER_CH2_WARNING_ALERT_LIMIT = 0x0A`

  No documentation found

- `const word _INA3221_MASK_WARNING_ALERT_2 = 0x0010`

  No documentation found

- `const word _INA3221_MASK_CRITICAL_ALERT_2 = 0x0100`

  No documentation found

- `const bit*3 INA3221_MODE_SHUNT_SINGLE = 0b001`

  No documentation found

- `const byte _INA3221_REGISTER_CH3_SHUNT_VOLTAGE = 0x05`

  No documentation found

- `const word _INA3221_MASK_SUMMATION_CHANNEL_3 = 0x1000`

  No documentation found

- `const word _INA3221_MASK_CRITICAL_ALERT_LATCH = 0x0400`

  No documentation found

- `const bit*3 INA3221_CONV_TIME_140_US = 0b000`

      Conversion time for bus voltage and shunt voltage.

- `const word _INA3221_CONFIURATION_ENABLE_CHANNEL_1 = 0x4000`

  No documentation found

- `const byte _INA3221_REGISTER_CH1_WARNING_ALERT_LIMIT = 0x08`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_16 = 0b010`

  No documentation found

- `const byte _INA3221_REGISTER_CH2_SHUNT_VOLTAGE = 0x03`

  No documentation found

- `const byte _INA3221_REGISTER_CH3_BUS_VOLTAGE = 0x06`

  No documentation found

- `const bit*3 INA3221_CONV_TIME_332_US = 0b010`

  No documentation found

- `const word _INA3221_MASK_TIMING_CONTROL_ALERT = 0x0002`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_1 = 0b000`

      Averaging mode number of samples.

- `const byte _INA3221_REGISTER_CH2_CRITICAL_ALERT_LIMIT = 0x09`

  No documentation found

- `const byte _INA3221_REGISTER_MANUFACTURER_ID = 0xFE`

  No documentation found

- `const byte _INA3221_REGISTER_MASK_ENABLE = 0x0F`

  No documentation found

- `const byte _INA3221_REGISTER_CH2_BUS_VOLTAGE = 0x04`

  No documentation found

- `const word _INA3221_CONFIURATION_ENABLE_CHANNEL_2 = 0x2000`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_4 = 0b001`

  No documentation found

- `const byte _INA3221_REGISTER_POWER_VALID_LOWER_LIMIT = 0x11`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_256 = 0b101`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_1024 = 0b111`

  No documentation found

- `const byte _INA3221_REGISTER_CH1_BUS_VOLTAGE = 0x02`

  No documentation found

- `const word _INA3221_MASK_SUMMATION_CHANNEL_2 = 0x2000`

  No documentation found

- `const word _INA3221_MASK_CRITICAL_ALERT_3 = 0x0080`

  No documentation found

- `const word _INA3221_MASK_CRITICAL_ALERT_1 = 0x0200`

  No documentation found

- `const word _INA3221_MASK_SUMMATION_CHANNEL_1 = 0x4000`

  No documentation found

- `const byte _INA3221_REGISTER_CONFIGURATION = 0x00`

      Addresseds of the registers. Register are word oriented.

- `const bit*3 INA3221_CONV_TIME_4_MS = 0b110`

      4.156 ms.

- `const byte _INA3221_REGISTER_CH3_CRITICAL_ALERT_LIMIT = 0x0B`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_512 = 0b110`

  No documentation found

- `const byte _INA3221_REGISTER_DIE_ID = 0xFF`

  No documentation found

- `const bit*3 INA3221_MODE_BUS_CONTINUOUS = 0b110`

  No documentation found

- `const bit*3 INA3221_CONV_TIME_1_MS = 0b100`

      Default 1.1 ms.

- `const bit*3 INA3221_MODE_SHUNT_BUS_SINGLE = 0b011`

  No documentation found

- `const word _INA3221_CONFIURATION_RESET = 0x8000`

      Configuration register bits.

- `const bit*3 INA3221_CONV_TIME_588_US = 0b011`

  No documentation found

- `const byte _INA3221_REGISTER_CH3_WARNING_ALERT_LIMIT = 0x0C`

  No documentation found

- `const byte _INA3221_REGISTER_CH1_SHUNT_VOLTAGE = 0x01`

  No documentation found

- `const byte INA3221_CHANNEL_1 = 0`

  No documentation found

- `const bit*3 INA3221_CONV_TIME_204_US = 0b001`

  No documentation found

- `const bit*3 INA3221_CONV_TIME_8_MS = 0b111`

      8.244 ms.

- `const word _INA3221_MASK_POWER_VALID_ALERT = 0x0004`

  No documentation found

- `const bit*3 INA3221_MODE_SHUNT_CONTINUOUS = 0b101`

  No documentation found

- `const word _INA3221_CONFIURATION_ENABLE_CHANNEL_3 = 0x1000`

  No documentation found

- `const word _INA3221_MASK_SUMMATION_ALERT = 0x0040`

  No documentation found

- `const byte _INA3221_REGISTER_SHUNT_VOLTAGE_SUM = 0x0D`

  No documentation found

- `const word _INA3221_MASK_CONVERSION_READY = 0x0001`

      Mask/Enable register values.

- `const byte INA3221_IIC_DEFAULT_ADDRESS = 0x40`

      Default 7-bit IIC address of the ina3221 with A0 connected to GND.

- `const byte _INA3221_REGISTER_CH1_CRITICAL_ALERT_LIMIT = 0x07`

  No documentation found

- `const byte INA3221_CHANNEL_2 = 1`

  No documentation found

- `const byte _INA3221_REGISTER_SHUNT_VOLTAGE_SUM_LIMIT = 0x0E`

  No documentation found

- `const bit*3 INA3221_MODE_BUS_SINGLE = 0b010`

  No documentation found

- `const word _INA3221_MASK_WARNING_ALERT_1 = 0x0020`

  No documentation found

- `const word _INA3221_MASK_WARNING_ALERT_LATCH = 0x0800`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_64 = 0b011`

  No documentation found

- `const bit*3 INA3221_MODE_POWER_DOWN_1 = 0b000`

      Operating modes.

- `const bit*3 INA3221_MODE_SHUNT_BUS_CONTINUOUS = 0b111`

      Default.

- `const bit*3 INA3221_MODE_POWER_DOWN_2 = 0b100`

  No documentation found

- `const bit*3 INA3221_AVG_SAMPLES_128 = 0b100`

  No documentation found

- `const word _INA3221_MASK_WARNING_ALERT_3 = 0x0008`

  No documentation found

- `const byte _INA3221_REGISTER_POWER_VALID_UPPER_LIMIT = 0x10`

  No documentation found

- `const byte INA3221_CHANNEL_3 = 2`

  No documentation found

- `const byte INA3221_NR_OF_CHANNELS = 3`

      Channel constants.

### Procedures

- `ina3221_enable_warning_alert_latch()`

      Enable the warning alert latch.

- `ina3221_disable_critical_alert_latch()`

      Disable the critical alert latch.

- `ina3221_set_averaging_samples(bit*3 in samples)`

      Set the averaging mode with the given number of samples.

- `ina3221_disable_summation_channel(byte in channel)`

      Disable the summation channel control for the given channel.
      Channel in range 0..2.

- `ina3221_set_shunt_voltage_conversion_time(bit*3 in time)`

      Set shunt voltage conversion time.

- `ina3221_enable_summation_channel(byte in channel)`

      Enable the summation channel control for the given channel.
      Channel in range 0..2.

- `ina3221_init()`

      Initialize the library. The shunt resistor is set to 0.1 Ohm.
      The device is reset.

- `ina3221_set_iic_address(byte in address)`

      Set the 7-bit IIC address of the INA3221 to the given address.
      The default address: INA3221_IIC_DEFAULT_ADDRESS (A0 connected to GND.)

- `ina3221_reset()`

      Reset the INA3221.

- `ina3221_enable_critical_alert_latch()`

      Enable the critical alert latch.

- `ina3221_disable_channel(byte in channel)`

      Disable the given channel. Channel in range 0..2.

- `ina3221_set_operating_mode(bit*3 in mode)`

      Set operating mode.

- `ina3221_enable_channel(byte in channel)`

      Enable the given channel. Channel in range 0..2.

- `ina3221_set_bus_voltage_conversion_time(bit*3 in time)`

      Set bus voltage conversion time.

- `ina3221_disable_warning_alert_latch()`

      Disable the warning alert latch.

Private

- `_ina3221_write_data_word(byte in register, word in data)`

      Write a word to the given register of the ina3221 via the IIC interface.
      In case of an error the timeout flag is set.

### Functions

- `ina3221_critical_alert(word in flags, byte in channel) return bit`

      Returns TRUE if the critical alert for the given channel is active.
      Channel in range 0..2. Channel must be active for the alert.

- `ina3221_get_flags() return word`

      Get the flags from the mask/enable register. This call will clear the flags
      if a condition is no longer active. For that reason reading the flags from
      the mask enable/disable regsiter once makes it possible to check later
      which alert flags are active.

- `ina3221_timeout_occured() return bit`

      Returns TRUE if a timeout occured in one of the read functions or in case of
      timeout on the IIC bus if the IIC timeout is defined. Value is cleared after
      a call to this function.

- `ina3221_timing_control_alert(word in flags) return bit`

      Returns TRUE if the timing control alert is active.

- `get_manufacturer_id() return word`

      Get the ID of the manufacturer. Should be 0x5449.

- `ina3221_get_register_value(byte in register) return word`

      Get the contents of the given register.

- `ina3221_warning_alert(word in flags, byte in channel) return bit`

      Returns TRUE if the warning alert for the given channel is active.
      Channel in range 0..2. Channel must be active for the alert.

- `get_die_id() return word`

      Get the ID of the DIE. Should be 0x3220.

- `ina3221_power_valid_alert(word in flags) return bit`

      Returns TRUE if the power valid alert is active.

- `ina3221_summation_alert(word in flags) return bit`

      Returns TRUE if the summation alert is active.

- `ina3221_get_iic_address() return byte`

      Get the 7-bit IIC address of the INA3221 module.

- `ina3221_conversion_ready(word in flags) return bit`

      Returns TRUE if the conversion is ready.

Private

- `_ina3221_read_data_word(byte in register) return word`

      Read a word from the given register of the ina3221 via the IIC interface.
      In case of an error the timeout flag is set.

## Related samples

Here are the list of samples which use this library:

16f1825 | 16f1825_ina3221.jal