ina3221 - Driver for INA3221 shunt and bus voltage monitor

group ina3221

ESP-IDF driver for Shunt and Bus Voltage Monitor INA3221.

Ported from esp-open-rtos

Copyright (c) 2016 Zaltora https://github.com/Zaltora Copyright (c) 2019 Ruslan V. Uss unclerus@gmail.com

MIT Licensed as described in the file LICENSE

Defines

INA3221_I2C_ADDR_GND

A0 to GND.

INA3221_I2C_ADDR_VS

A0 to Vs+.

INA3221_I2C_ADDR_SDA

A0 to SDA.

INA3221_I2C_ADDR_SCL

A0 to SCL.

INA3221_BUS_NUMBER

Number of shunt available.

INA3221_DEFAULT_CONFIG

Default register values after reset.

INA3221_DEFAULT_MASK
INA3221_DEFAULT_POWER_UPPER_LIMIT
INA3221_DEFAULT_POWER_LOWER_LIMIT
INA3221_MASK_CONFIG

Enums

enum ina3221_avg_t

Number of samples.

Values:

enumerator INA3221_AVG_1

Default.

enumerator INA3221_AVG_4
enumerator INA3221_AVG_16
enumerator INA3221_AVG_64
enumerator INA3221_AVG_128
enumerator INA3221_AVG_256
enumerator INA3221_AVG_512
enumerator INA3221_AVG_1024
enum ina3221_channel_t

Channel selection list.

Values:

enumerator INA3221_CHANNEL_1
enumerator INA3221_CHANNEL_2
enumerator INA3221_CHANNEL_3
enum ina3221_ct_t

Conversion time in us.

Values:

enumerator INA3221_CT_140
enumerator INA3221_CT_204
enumerator INA3221_CT_332
enumerator INA3221_CT_588
enumerator INA3221_CT_1100

Default.

enumerator INA3221_CT_2116
enumerator INA3221_CT_4156
enumerator INA3221_CT_8244

Functions

esp_err_t ina3221_init_desc(ina3221_t *dev, uint8_t addr, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)

Initialize device descriptor.

Parameters:
  • dev – Device descriptor

  • addr – Device I2C address

  • port – I2C port

  • sda_gpio – SDA GPIO

  • scl_gpio – SCL GPIO

Returns:

ESP_OK to indicate success

esp_err_t ina3221_free_desc(ina3221_t *dev)

Free device descriptor.

Parameters:

dev – Device descriptor

Returns:

ESP_OK to indicate success

esp_err_t ina3221_sync(ina3221_t *dev)

Write current config to device.

Sync internal config buffer and mask with external device register. (When struct is set manually).

Parameters:

dev – Device descriptor

Returns:

ESP_OK to indicate success

esp_err_t ina3221_trigger(ina3221_t *dev)

Trigger measurement.

Send current config register to trig a measurement in single-shot mode.

Parameters:

dev – Device descriptor

Returns:

ESP_OK to indicate success

esp_err_t ina3221_get_status(ina3221_t *dev)

Read status from device.

Get mask register from the device, used to read flags.

Parameters:

dev – Device descriptor

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_options(ina3221_t *dev, bool mode, bool bus, bool shunt)

Set options for bus and shunt.

Parameters:
  • dev – Device descriptor

  • mode – Selection of measurement (true : continuous // false : single-shot)

  • bus – Enable/Disable bus measures

  • shunt – Enable/Disable shunt measures

Returns:

ESP_OK to indicate success

esp_err_t ina3221_enable_channel(ina3221_t *dev, bool ch1, bool ch2, bool ch3)

Select channels.

Parameters:
  • dev – Device descriptor

  • ch1 – Enable/Disable channel 1 (true : enable // false : disable)

  • ch2 – Enable/Disable channel 2 (true : enable // false : disable)

  • ch3 – Enable/Disable channel 3 (true : enable // false : disable)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_enable_channel_sum(ina3221_t *dev, bool ch1, bool ch2, bool ch3)

Select channel to be sum (don’t impact enable channel status)

Parameters:
  • dev – Device descriptor

  • ch1 – Enable/Disable channel 1 (true : enable // false : disable)

  • ch2 – Enable/Disable channel 2 (true : enable // false : disable)

  • ch3 – Enable/Disable channel 3 (true : enable // false : disable)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_enable_latch_pin(ina3221_t *dev, bool warning, bool critical)

enable/disable latch on warning and critical alert pin

Parameters:
  • dev – Device descriptor

  • warning – Enable/Disable warning latch (true : Latch // false : Transparent)

  • critical – Enable/Disable critical latch (true : Latch // false : Transparent)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_average(ina3221_t *dev, ina3221_avg_t avg)

Set average (number of samples measured)

Parameters:
  • dev – Device descriptor

  • avg – Value of average selection

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_bus_conversion_time(ina3221_t *dev, ina3221_ct_t ct)

Set conversion time for bus.

Parameters:
  • dev – Device descriptor

  • ct – Value of conversion time selection

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_shunt_conversion_time(ina3221_t *dev, ina3221_ct_t ct)

Set conversion time for shunt.

Parameters:
  • dev – Device descriptor

  • ct – Value of conversion time selection

Returns:

ESP_OK to indicate success

esp_err_t ina3221_reset(ina3221_t *dev)

Reset device.

Device will be configured like POR (Power-On-Reset)

Parameters:

dev – Device descriptor

Returns:

ESP_OK to indicate success

esp_err_t ina3221_get_bus_voltage(ina3221_t *dev, ina3221_channel_t channel, float *voltage)

Get Bus voltage (V)

Parameters:
  • dev – Device descriptor

  • channel – Select channel value to get

  • voltage – Data pointer to get bus voltage (V)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_get_shunt_value(ina3221_t *dev, ina3221_channel_t channel, float *voltage, float *current)

Get Shunt voltage (mV) and current (mA)

Parameters:
  • dev – Device descriptor

  • channel – Select channel value to get

  • voltage – Data pointer to get shunt voltage (mV)

  • current – Data pointer to get shunt voltage (mA)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_get_sum_shunt_value(ina3221_t *dev, float *voltage)

Get Shunt-voltage (mV) sum value of selected channels.

Parameters:
  • dev – Device descriptor

  • voltage – Data pointer to get shunt voltage (mV)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_critical_alert(ina3221_t *dev, ina3221_channel_t channel, float current)

Set Critical alert.

Alert when measurement(s) is greater

Parameters:
  • dev – Device descriptor

  • channel – Select channel value to set

  • current – Value to set (mA) // max : 163800/shunt (mOhm)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_warning_alert(ina3221_t *dev, ina3221_channel_t channel, float current)

Set Warning alert.

Alert when average measurement(s) is greater

Parameters:
  • dev – Device descriptor

  • channel – Select channel value to set

  • current – Value to set (mA) // max : 163800/shunt (mOhm)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_sum_warning_alert(ina3221_t *dev, float voltage)

Set Sum Warning alert.

Compared to each completed cycle of all selected channels : Sum register

Parameters:
  • dev – Device descriptor

  • voltage – voltage to set (mV) // max : 655.32

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_power_valid_upper_limit(ina3221_t *dev, float voltage)

Set Power-valid upper-limit.

Used to determine if power conditions are met. Bus needs to be enabled. If bus voltage exceed the value set, PV pin will be set high.

Parameters:
  • dev – Device descriptor

  • voltage – voltage to set (V)

Returns:

ESP_OK to indicate success

esp_err_t ina3221_set_power_valid_lower_limit(ina3221_t *dev, float voltage)

Set Power-valid lower-limit.

Used to determine if power conditions are met. Bus needs to be enabled. If bus voltage drops below the value set, PV pin will be set low.

Parameters:
  • dev – Device descriptor

  • voltage – Voltage to set (V)

Returns:

ESP_OK to indicate success

union ina3221_config_t
#include <ina3221.h>

Config description register.

Public Members

uint16_t esht

Enable/Disable shunt measure // LSB.

uint16_t ebus

Enable/Disable bus measure.

uint16_t mode

Single shot measure or continuous mode.

uint16_t vsht

Shunt voltage conversion time.

uint16_t vbus

Bus voltage conversion time.

uint16_t avg

number of sample collected and averaged together

uint16_t ch3

Enable/Disable channel 3.

uint16_t ch2

Enable/Disable channel 2.

uint16_t ch1

Enable/Disable channel 1.

uint16_t rst

Set this bit to 1 to reset device // MSB.

struct ina3221_config_t::[anonymous] [anonymous]
uint16_t config_register
union ina3221_mask_t
#include <ina3221.h>

Mask/enable description register.

Public Members

uint16_t cvrf

Conversion ready flag (1: ready) // LSB.

uint16_t tcf

Timing control flag.

uint16_t pvf

Power valid flag.

uint16_t wf

Warning alert flag (Read mask to clear) (order : Channel1:channel2:channel3)

uint16_t sf

Sum alert flag (Read mask to clear)

uint16_t cf

Critical alert flag (Read mask to clear) (order : Channel1:channel2:channel3)

uint16_t cen

Critical alert latch (1:enable)

uint16_t wen

Warning alert latch (1:enable)

uint16_t scc3

channel 3 sum (1:enable)

uint16_t scc2

channel 2 sum (1:enable)

uint16_t scc1

channel 1 sum (1:enable)

uint16_t __pad0__

Reserved //MSB.

struct ina3221_mask_t::[anonymous] [anonymous]
uint16_t mask_register
struct ina3221_t
#include <ina3221.h>

Device descriptor.

Public Members

i2c_dev_t i2c_dev

I2C device descriptor.

uint16_t shunt[INA3221_BUS_NUMBER]

Memory of shunt value (mOhm)

ina3221_config_t config

Memory of ina3221 config.

ina3221_mask_t mask

Memory of mask_config.