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.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • addr: Device I2C address

  • port: I2C port

  • sda_gpio: SDA GPIO

  • scl_gpio: SCL GPIO

esp_err_t ina3221_free_desc(ina3221_t *dev)

Free device descriptor.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

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).

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

esp_err_t ina3221_trigger(ina3221_t *dev)

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

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

esp_err_t ina3221_get_status(ina3221_t *dev)

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

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

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

Set options for bus and shunt.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

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

  • bus: Enable/Disable bus measures

  • shunt: Enable/Disable shunt measures

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

Select channels.

Return

ESP_OK to indicate success

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)

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)

Return

ESP_OK to indicate success

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)

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

enable/disable latch on warning and critical alert pin

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

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

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

esp_err_t ina3221_set_average(ina3221_t *dev, ina3221_avg_t avg)

Set average (number of samples measured)

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • avg: Value of average selection

esp_err_t ina3221_set_bus_conversion_time(ina3221_t *dev, ina3221_ct_t ct)

Set conversion time for bus.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • ct: Value of conversion time selection

esp_err_t ina3221_set_shunt_conversion_time(ina3221_t *dev, ina3221_ct_t ct)

Set conversion time for shunt.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • ct: Value of conversion time selection

esp_err_t ina3221_reset(ina3221_t *dev)

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

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

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

Get Bus voltage (V)

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • channel: Select channel value to get

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

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)

Return

ESP_OK to indicate success

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)

esp_err_t ina3221_get_sum_shunt_value(ina3221_t *dev, float *voltage)

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

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

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

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.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • channel: Select channel value to set

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

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.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • channel: Select channel value to set

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

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.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

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

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.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • voltage: voltage to set (V)

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.

Return

ESP_OK to indicate success

Parameters
  • dev: Device descriptor

  • voltage: Voltage to set (V)

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 continious 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.