Loading...
Searching...
No Matches

Device driver interface for Texas Instruments INA3221 three-channel, high-side current and bus voltage monitor. More...

Detailed Description

Device driver interface for Texas Instruments INA3221 three-channel, high-side current and bus voltage monitor.

The alert pins WRN, CRT, TC, PV are open drain output pins, so they should be pulled high with internal or external pull-ups. They pull low, if the alert condition becomes true. If they become pulled low, the configured input pins in ina3221_params_t will read a low flank and the related interrupt callback will be executed, if configured with ina3221_enable_alert. WRN condition: Any channel´s measured shunt voltage drop was higher than the configured value in INA3221_REG_CHx_WARN_ALERT_LIMIT, CRT condition: Any channel´s measured shunt voltage drop was higher than the configured value in INA3221_REG_CHx_CRIT_ALERT_LIMIT, or the sum of all channel´s voltage drops was higher than the configured value in INA3221_REG_SHUNT_VOLTAGE_SUM_LIMIT. Note that the sum of voltage drops only makes sense, if all channels are using the same shunt resistance value! TC condition: After a 1.2-V level is detected on channel 1, if the INA3221 does not detect a 1.2-V value or greater on the bus voltage measurement following four complete cycles of all three channels, the timing control TC alert pin pulls low. PV condition: If any channel´s measured bus voltage was not within the configured values in INA3221_REG_PV_LOWER_LIMIT and INA3221_REG_PV_UPPER_LIMIT, the PV pin is pulled low.

For the number of enabled channels $NCH$, number of samples $NS$, bus voltage conversion time $BCT$, and shunt voltage conversion time $SCT$, the time to complete a full measurement cycle can be calculated with: $ NCH \times NS \times (BCT + SCT) $.

See also
Datasheet: https://www.ti.com/lit/ds/symlink/ina3221.pdf
Author
Fabian Hüßler fabia.nosp@m.n.hu.nosp@m.essle.nosp@m.r@ov.nosp@m.gu.de

Definition in file ina3221.h.

#include <assert.h>
#include <errno.h>
#include <stdint.h>
#include <stdbool.h>
#include "kernel_defines.h"
#include "periph/gpio.h"
#include "periph/i2c.h"
+ Include dependency graph for ina3221.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ina3221_params_t
 INA3221 device parameters. More...
 
struct  ina3221_t
 INA3221 device handle struct. More...
 

Macros

#define INA3221_NUM_CH   (3)
 Number of channels.
 
#define INA3221_NUM_ALERTS   (4)
 Number of alerts.
 
#define INA3221_MODE_MASK   (0x0007)
 Device operation mode bit mask.
 
#define INA3221_CONV_TIME_SADC_MASK   (0x0038)
 ADC shunt voltage conversion times bit mask.
 
#define INA3221_CONV_TIME_BADC_MASK   (0x01C0)
 ADC bus voltage conversion times bit mask.
 
#define INA3221_NUM_SAMPLES_MASK   (0x0E00)
 Number of samples to calculate average shunt/bus voltage value bit mask.
 
#define INA3221_ENABLE_CH_MASK
 Enable channel bit mask.
 
#define INA3221_ENABLE_SUM_CH_MASK
 Enable shunt voltage sum calculation channel bit mask.
 
#define INA3221_ENABLE_LATCH_MASK
 Enable latch bit mask.
 
#define INA3221_DEFCONFIG   (0x7127)
 Default configuration register value.
 
#define INA3221_RESET   (0x8000)
 Reset configuration register value.
 
#define INA3221_FLAG_CRIT_ALERT_CH1   (0x0200)
 Critical alert channel 1 flag.
 
#define INA3221_FLAG_CRIT_ALERT_CH2   (0x0100)
 Critical alert channel 2 flag.
 
#define INA3221_FLAG_CRIT_ALERT_CH3   (0x0080)
 Critical alert channel 3 flag.
 
#define INA3221_FLAG_SHUNT_SUM_ALERT   (0x0040)
 Alert channel sum flag.
 
#define INA3221_FLAG_WARN_ALERT_CH1   (0x0020)
 Warning alert channel 1 flag.
 
#define INA3221_FLAG_WARN_ALERT_CH2   (0x0010)
 Warning alert channel 2 flag.
 
#define INA3221_FLAG_WARN_ALERT_CH3   (0x0008)
 Warning alert channel 3 flag.
 
#define INA3221_FLAG_POWER_VALID   (0x0004)
 Power valid flag.
 
#define INA3221_FLAG_TIMING_CONTROL   (0x0002)
 Timing Control flag.
 
#define INA3221_FLAG_CONV_READY   (0x0001)
 Conversion ready flag.
 
#define INA3221_FLAGS_MASK
 Flags bit mask.
 
#define INA3221_TRIGGER_SHUNT(dev)    ina3221_set_mode(dev, INA3221_MODE_TRIGGER_SHUNT_ONLY)
 Set operation mode to INA3221_MODE_TRIGGER_SHUNT_ONLY to trigger shunt voltage measurement.
 
#define INA3221_TRIGGER_BUS(dev)    ina3221_set_mode(dev, INA3221_MODE_TRIGGER_BUS_ONLY)
 Set operation mode to INA3221_MODE_TRIGGER_BUS_ONLY to trigger bus voltage measurement.
 
#define INA3221_TRIGGER_SHUNT_AND_BUS(dev)    ina3221_set_mode(dev, INA3221_MODE_TRIGGER_SHUNT_BUS)
 Set operation mode to INA3221_MODE_TRIGGER_SHUNT_BUS to trigger shunt and bus voltage measurement.
 

Typedefs

typedef void(* ina3221_alert_cb_t) (void *arg)
 INA3221 alert callback for alert pins CRT, WRN, TC, PV.
 
typedef enum ina3221_dev_addr ina3221_dev_addr_t
 I2C device addresses.
 
typedef enum ina3221_channel ina3221_channel_t
 Channel flags.
 
typedef enum ina3221_alert ina3221_alert_t
 Alert indices.
 
typedef enum ina3221_mode ina3221_mode_t
 Device operation modes.
 
typedef enum ina3221_conv_time_shunt_adc ina3221_conv_time_shunt_adc_t
 ADC shunt voltage conversion times.
 
typedef enum ina3221_conv_time_bus_adc ina3221_conv_time_bus_adc_t
 ADC bus voltage conversion times.
 
typedef enum ina3221_num_samples ina3221_num_samples_t
 Number of samples to calculate average shunt/bus voltage value.
 
typedef enum ina3221_enable_ch ina3221_enable_ch_t
 Enable channel flags.
 
typedef enum ina3221_enable_sum_ch ina3221_enable_sum_ch_t
 Enable shunt voltage sum calculation channel flags.
 
typedef enum ina3221_enable_latch ina3221_enable_latch_t
 Enable latch flags.
 
typedef unsigned ina3221_ch_t
 Flags ina3221_channel_t.
 

Enumerations

enum  ina3221_dev_addr { INA3221_ADDR_00 = 0x40 , INA3221_ADDR_01 = 0x41 , INA3221_ADDR_10 = 0x42 , INA3221_ADDR_11 = 0x43 }
 I2C device addresses. More...
 
enum  ina3221_channel { INA3221_CH1 = (1U << 0) , INA3221_CH2 = (1U << 1) , INA3221_CH3 = (1U << 2) }
 Channel flags. More...
 
enum  ina3221_alert { INA3221_ALERT_WRN = 0 , INA3221_ALERT_CRT = 1 , INA3221_ALERT_TC = 2 , INA3221_ALERT_PV = 3 }
 Alert indices. More...
 
enum  ina3221_mode {
  INA3221_MODE_POWER_DOWN = 0x0000 , INA3221_MODE_TRIGGER_SHUNT_ONLY = 0x0001 , INA3221_MODE_TRIGGER_BUS_ONLY = 0x0002 , INA3221_MODE_TRIGGER_SHUNT_BUS = 0x0003 ,
  INA3221_MODE_POWER_DOWN_ = 0x0004 , INA3221_MODE_CONTINUOUS_SHUNT_ONLY = 0x0005 , INA3221_MODE_CONTINUOUS_BUS_ONLY = 0x0006 , INA3221_MODE_CONTINUOUS_SHUNT_BUS = 0x0007
}
 Device operation modes. More...
 
enum  ina3221_conv_time_shunt_adc {
  INA3221_CONV_TIME_SADC_140US = 0x0000 , INA3221_CONV_TIME_SADC_204US = 0x0008 , INA3221_CONV_TIME_SADC_332US = 0x0010 , INA3221_CONV_TIME_SADC_588US = 0x0018 ,
  INA3221_CONV_TIME_SADC_1100US = 0x0020 , INA3221_CONV_TIME_SADC_2116US = 0x0028 , INA3221_CONV_TIME_SADC_4156US = 0x0030 , INA3221_CONV_TIME_SADC_8244US = 0x0038
}
 ADC shunt voltage conversion times. More...
 
enum  ina3221_conv_time_bus_adc {
  INA3221_CONV_TIME_BADC_140US = 0x0000 , INA3221_CONV_TIME_BADC_204US = 0x0040 , INA3221_CONV_TIME_BADC_332US = 0x0080 , INA3221_CONV_TIME_BADC_588US = 0x00C0 ,
  INA3221_CONV_TIME_BADC_1100US = 0x0100 , INA3221_CONV_TIME_BADC_2116US = 0x0140 , INA3221_CONV_TIME_BADC_4156US = 0x0180 , INA3221_CONV_TIME_BADC_8244US = 0x01C0
}
 ADC bus voltage conversion times. More...
 
enum  ina3221_num_samples {
  INA3221_NUM_SAMPLES_1 = 0x0000 , INA3221_NUM_SAMPLES_4 = 0x0200 , INA3221_NUM_SAMPLES_16 = 0x0400 , INA3221_NUM_SAMPLES_64 = 0x0600 ,
  INA3221_NUM_SAMPLES_128 = 0x0800 , INA3221_NUM_SAMPLES_256 = 0x0A00 , INA3221_NUM_SAMPLES_512 = 0x0C00 , INA3221_NUM_SAMPLES_1024 = 0x0E00
}
 Number of samples to calculate average shunt/bus voltage value. More...
 
enum  ina3221_enable_ch { INA3221_ENABLE_CH1 = 0x4000 , INA3221_ENABLE_CH2 = 0x2000 , INA3221_ENABLE_CH3 = 0x1000 }
 Enable channel flags. More...
 
enum  ina3221_enable_sum_ch { INA3221_ENABLE_SUM_CH1 = 0x4000 , INA3221_ENABLE_SUM_CH2 = 0x2000 , INA3221_ENABLE_SUM_CH3 = 0x1000 }
 Enable shunt voltage sum calculation channel flags. More...
 
enum  ina3221_enable_latch { INA3221_ENABLE_WARN_LATCH = 0x0800 , INA3221_ENABLE_CRIT_LATCH = 0x0400 }
 Enable latch flags. More...
 

Functions

int ina3221_reset (ina3221_t *dev)
 Reset device, i.e.
 
int ina3221_init (ina3221_t *dev, const ina3221_params_t *params)
 Initialize device.
 
int ina3221_enable_alert (ina3221_t *dev, ina3221_alert_t alert, ina3221_alert_cb_t cb, void *arg)
 Enable alert and set callback and argument for alert alert.
 
static int ina3221_enable_warning_alert (ina3221_t *dev, ina3221_alert_cb_t cb, void *arg)
 Wrapper around ina3221_enable_alert, to enable warning alert.
 
static int ina3221_enable_critical_alert (ina3221_t *dev, ina3221_alert_cb_t cb, void *arg)
 Wrapper around ina3221_enable_alert, to enable critical alert.
 
static int ina3221_enable_timing_control_alert (ina3221_t *dev, ina3221_alert_cb_t cb, void *arg)
 Wrapper around ina3221_enable_alert, to enable timing control alert.
 
static int ina3221_enable_power_valid_alert (ina3221_t *dev, ina3221_alert_cb_t cb, void *arg)
 Wrapper around ina3221_enable_alert, to enable power valid alert.
 
int ina3221_disable_alert (ina3221_t *dev, ina3221_alert_t alert)
 Disable alert alert.
 
static int ina3221_disable_warning_alert (ina3221_t *dev)
 Wrapper around ina3221_disable_alert, to disable warning alert.
 
static int ina3221_disable_critical_alert (ina3221_t *dev)
 Wrapper around ina3221_disable_alert, to disable critical alert.
 
static int ina3221_disable_timing_control_alert (ina3221_t *dev)
 Wrapper around ina3221_disable_alert, to disable timing control alert.
 
static int ina3221_disable_power_valid_alert (ina3221_t *dev)
 Wrapper around ina3221_disable_alert, to disable power valid alert.
 
static ina3221_ch_t ina3221_config_get_enabled_channels (uint16_t cfg)
 Get enabled measurement channels from configuration value.
 
static void ina3221_config_set_enabled_channels (uint16_t *cfg, ina3221_ch_t ch)
 Enable measurement channels in configuration value.
 
static ina3221_num_samples_t ina3221_config_get_num_samples (uint16_t cfg)
 Get number of samples from configuration value.
 
static void ina3221_config_set_num_samples (uint16_t *cfg, ina3221_num_samples_t ns)
 Set number of samples in configuration value.
 
static ina3221_conv_time_bus_adc_t ina3221_config_get_conv_time_bus (uint16_t cfg)
 Get bus voltage conversion time from configuration value.
 
static void ina3221_config_set_conv_time_bus (uint16_t *cfg, ina3221_conv_time_bus_adc_t bus)
 Set bus voltage conversion time in configuration value.
 
static ina3221_conv_time_shunt_adc_t ina3221_config_get_conv_time_shunt (uint16_t cfg)
 Get shunt voltage conversion time from configuration value.
 
static void ina3221_config_set_conv_time_shunt (uint16_t *cfg, ina3221_conv_time_shunt_adc_t shunt)
 Set shunt voltage conversion time in configuration value.
 
static ina3221_mode_t ina3221_config_get_mode (uint16_t cfg)
 Get operation mode from configuration value.
 
static void ina3221_config_set_mode (uint16_t *cfg, ina3221_mode_t mode)
 Set operation mode in configuration value.
 
int ina3221_set_config (ina3221_t *dev, uint16_t cfg)
 Write configuration register value to configuration register.
 
int ina3221_get_config (const ina3221_t *dev, uint16_t *cfg)
 Read currently saved configuration register value.
 
int ina3221_set_enable_channel (ina3221_t *dev, ina3221_ch_t ch)
 Enable channels.
 
static void ina3221_get_enable_channel (const ina3221_t *dev, ina3221_ch_t *ch)
 Read which channels are currently enabled.
 
int ina3221_set_num_samples (ina3221_t *dev, ina3221_num_samples_t ns)
 Update number of samples and write to configuration register.
 
static void ina3221_get_num_samples (const ina3221_t *dev, ina3221_num_samples_t *ns)
 Read currently applied number of samples.
 
int ina3221_set_conv_time_bus_adc (ina3221_t *dev, ina3221_conv_time_bus_adc_t ctb)
 Update conversion time of bus voltage ADC and write to configuration register.
 
static void ina3221_get_conv_time_bus_adc (const ina3221_t *dev, ina3221_conv_time_bus_adc_t *ctb)
 Read currently applied bus voltage ADC conversion time.
 
int ina3221_set_conv_time_shunt_adc (ina3221_t *dev, ina3221_conv_time_shunt_adc_t cts)
 Update conversion time of shunt voltage ADC and write to configuration register.
 
static void ina3221_get_conv_time_shunt_adc (const ina3221_t *dev, ina3221_conv_time_shunt_adc_t *cts)
 Read currently applied shunt voltage ADC conversion time.
 
int ina3221_set_mode (ina3221_t *dev, ina3221_mode_t mode)
 Update device operation mode.
 
static void ina3221_get_mode (const ina3221_t *dev, ina3221_mode_t *mode)
 Read currently applied device operation mode.
 
int ina3221_set_enable_sum_channel (const ina3221_t *dev, ina3221_ch_t ch)
 Enable channels for shunt voltage sum calculation.
 
int ina3221_get_enable_sum_channel (const ina3221_t *dev, ina3221_ch_t *ch)
 Read enabled channels for shunt voltage sum calculation.
 
int ina3221_set_latch (const ina3221_t *dev, bool warn, bool crit)
 Enable latches for critical/warning alert pins.
 
int ina3221_get_latch (const ina3221_t *dev, bool *warn, bool *crit)
 Read enabled latches for critical/warning alert pins.
 
ina3221_ch_t ina3221_set_crit_alert_limit (const ina3221_t *dev, ina3221_ch_t ch, int32_t in_uv)
 Set critical shunt voltage alert limit to in_uv for each channel in ch.
 
ina3221_ch_t ina3221_get_crit_alert_limit (const ina3221_t *dev, ina3221_ch_t ch, int32_t out_uv[INA3221_NUM_CH])
 Read critical shunt voltage alert limit for each channel in ch.
 
ina3221_ch_t ina3221_set_warn_alert_limit (const ina3221_t *dev, ina3221_ch_t ch, int32_t in_uv)
 Set warning shunt voltage alert limit to in_uv for each channel in ch.
 
ina3221_ch_t ina3221_get_warn_alert_limit (const ina3221_t *dev, ina3221_ch_t ch, int32_t out_uv[INA3221_NUM_CH])
 Read warning shunt voltage alert limit for each channel in ch.
 
int ina3221_set_shunt_voltage_sum_alert_limit (const ina3221_t *dev, int32_t in_uv)
 Set shunt voltage sum alert limit to in_uv.
 
int ina3221_get_shunt_voltage_sum_alert_limit (const ina3221_t *dev, int32_t *out_uv)
 Read shunt voltage sum alert limit.
 
int ina3221_set_power_valid_upper_limit (const ina3221_t *dev, int32_t in_mv)
 Set bus voltage power valid upper limit to in_mv.
 
int ina3221_get_power_valid_upper_limit (const ina3221_t *dev, int32_t *out_mv)
 Read bus voltage power valid upper limit.
 
int ina3221_set_power_valid_lower_limit (const ina3221_t *dev, int32_t in_mv)
 Set bus voltage power valid lower limit to in_mv.
 
int ina3221_get_power_valid_lower_limit (const ina3221_t *dev, int32_t *out_mv)
 Read bus voltage power valid lower limit.
 
int ina3221_read_flags (const ina3221_t *dev, uint16_t *flags)
 Read status flags.
 
int ina3221_read_shunt_sum_uv (const ina3221_t *dev, int32_t *out_uv, uint16_t *flags)
 Read sum of shunt voltages.
 
ina3221_ch_t ina3221_read_shunt_uv (const ina3221_t *dev, int32_t out_uv[INA3221_NUM_CH], uint16_t *flags)
 Read shunt voltages for each channel in ch.
 
ina3221_ch_t ina3221_read_bus_mv (const ina3221_t *dev, int16_t out_mv[INA3221_NUM_CH], uint16_t *flags)
 Read bus voltages for each channel in ch.
 
void ina3221_calculate_current_ua (ina3221_ch_t ch, const uint16_t in_mohm[INA3221_NUM_CH], const int32_t in_uv[INA3221_NUM_CH], int32_t out_ua[INA3221_NUM_CH])
 Calculate current for each channel in ch.
 
void ina3221_calculate_power_uw (ina3221_ch_t ch, const int16_t in_mv[INA3221_NUM_CH], const int32_t in_ua[INA3221_NUM_CH], int32_t out_mw[INA3221_NUM_CH])
 Calculate power from bus voltage and current values.