ina3221.h

Go to the documentation of this file.

/*
 * Copyright (C) 2019 Otto-von-Guericke-Universität Magdeburg
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */
 
#ifndef INA3221_H
#define INA3221_H
 
#include <stdint.h>
 
#include "periph/gpio.h"
#include "periph/i2c.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define INA3221_NUM_CH                  (3)         
#define INA3221_NUM_ALERTS              (4)         
typedef void (*ina3221_alert_cb_t)(void *arg);
 
typedef enum ina3221_ret_val {
    INA3221_OK,                                     
    INA3221_I2C_ERROR,                              
    INA3221_BAD_MANUF_ID,                           
    INA3221_BAD_DIE_ID,                             
    INA3221_RESET_FAILED,                           
    INA3221_CONFIG_FAILED                           
} ina3221_ret_val_t;
 
typedef enum ina3221_dev_addr {
    INA3221_ADDR_00 = 0x40,                         
    INA3221_ADDR_01 = 0x41,                         
    INA3221_ADDR_10 = 0x42,                         
    INA3221_ADDR_11 = 0x43,                         
} ina3221_dav_addr_t;
 
typedef enum ina3221_channel {
    INA3221_CH1 = (1 << 0),                         
    INA3221_CH2 = (1 << 1),                         
    INA3221_CH3 = (1 << 2)                          
} ina3221_channel_t;
 
typedef enum ina3221_alert {
    INA3221_ALERT_WRN   = 0,                        
    INA3221_ALERT_CRT   = 1,                        
    INA3221_ALERT_TC    = 2,                        
    INA3221_ALERT_PV    = 3                         
} ina3221_alert_t;
 
typedef 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    
} ina3221_mode_t;
#define INA3221_MODE_MASK               (0x0007)    
typedef 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        
} ina3221_conv_time_shunt_adc_t;
#define INA3221_CONV_TIME_SADC_MASK    (0x0038)     
typedef 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        
} ina3221_conv_time_bus_adc_t;
#define INA3221_CONV_TIME_BADC_MASK    (0x01C0)     
typedef 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            
} ina3221_num_samples_t;
#define INA3221_NUM_SAMPLES_MASK       (0x0E00)     
typedef enum ina3221_enable_ch {
    INA3221_ENABLE_CH1  = 0x4000,                   
    INA3221_ENABLE_CH2  = 0x2000,                   
    INA3221_ENABLE_CH3  = 0x1000                    
} ina3221_enable_ch_t;
#define INA3221_ENABLE_CH_MASK          (INA3221_ENABLE_CH1    \
                                         | INA3221_ENABLE_CH2  \
                                         | INA3221_ENABLE_CH3)  
typedef enum ina3221_channel_state {
    INA3221_CH_DISABLE,                             
    INA3221_CH_ENABLE                               
} ina3221_channel_state_t;
 
typedef enum ina3221_enable_sum_ch {
    INA3221_ENABLE_SUM_CH1  = 0x4000,               
    INA3221_ENABLE_SUM_CH2  = 0x2000,               
    INA3221_ENABLE_SUM_CH3  = 0x1000                
} ina3221_enable_sum_ch_t;
#define INA3221_ENABLE_SUM_CH_MASK     (INA3221_ENABLE_SUM_CH1     \
                                        | INA3221_ENABLE_SUM_CH2   \
                                        | INA3221_ENABLE_SUM_CH3)  
typedef enum ina3221_enable_latch {
    INA3221_ENABLE_WARN_LATCH   = 0x0800,           
    INA3221_ENABLE_CRIT_LATCH   = 0x0400            
} ina3221_enable_latch_t;
#define INA3221_ENABLE_LATCH_MASK      (INA3221_ENABLE_WARN_LATCH  \
                                        | INA3221_ENABLE_CRIT_LATCH)  
typedef struct {
    i2c_t i2c;                                      
    uint8_t addr;                                   
    union {
        struct {
            gpio_t pin_warn;                        
            gpio_t pin_crit;                        
            gpio_t pin_tc;                          
            gpio_t pin_pv;                          
        } pins;                                     
        struct {
            gpio_t alert_pins[INA3221_NUM_ALERTS];  
        } apins;                                    
    } upins;                                        
    /*
        For each pin 1 bit states whether to use internal pull up resistors.
        d = don´t care
        [d][d][d][d][pu PV][pu TC][pu CRT][pu WRN]
     */
    uint8_t gpio_config;                            
    uint16_t config;                                
    uint16_t rshunt_mohm[INA3221_NUM_CH];           
} ina3221_params_t;
 
/* (  INA3221_ENABLE_CH_1
 | INA3221_ENABLE_CH_2
 | INA3221_ENABLE_CH_2
 | INA3221_NUM_SAMPLES_1
 | INA3221_CONV_TIME_BADC_1100US
 | INA3221_CONV_TIME_SADC_1100US
 | INA3221_MODE_CONTINUOUS_SHUNT_BUS ) */
#define INA3221_DEFCONFIG               (0x7127)    
#define INA3221_RESET                   (0x8000)    
#define INA3221_FLAG_CRIT_ALERT_CH1     (0x0200)    
#define INA3221_FLAG_CRIT_ALERT_CH2     (0x0100)    
#define INA3221_FLAG_CRIT_ALERT_CH3     (0x0080)    
#define INA3221_FLAG_SHUNT_SUM_ALERT    (0x0040)    
#define INA3221_FLAG_WARN_ALERT_CH1     (0x0020)    
#define INA3221_FLAG_WARN_ALERT_CH2     (0x0010)    
#define INA3221_FLAG_WARN_ALERT_CH3     (0x0008)    
#define INA3221_FLAG_POWER_VALID        (0x0004)    
#define INA3221_FLAG_TIMING_CONTROL     (0x0002)    
#define INA3221_FLAG_CONV_READY         (0x0001)    
#define INA3221_FLAGS_MASK              (INA3221_FLAG_CRIT_ALERT_CH1       \
                                         | INA3221_FLAG_CRIT_ALERT_CH2     \
                                         | INA3221_FLAG_CRIT_ALERT_CH3     \
                                         | INA3221_FLAG_SHUNT_SUM_ALERT    \
                                         | INA3221_FLAG_WARN_ALERT_CH1     \
                                         | INA3221_FLAG_WARN_ALERT_CH2     \
                                         | INA3221_FLAG_WARN_ALERT_CH3     \
                                         | INA3221_FLAG_POWER_VALID        \
                                         | INA3221_FLAG_TIMING_CONTROL     \
                                         | INA3221_FLAG_CONV_READY)      
typedef struct {
    ina3221_params_t params;                      
#if defined(MODULE_INA3221_ALERTS) || defined(DOXYGEN)
    union {
        struct {
            ina3221_alert_cb_t warn_cb;             
            ina3221_alert_cb_t crit_cb;             
            ina3221_alert_cb_t tc_cb;               
            ina3221_alert_cb_t pv_cb;               
        };
        struct {
            ina3221_alert_cb_t alert_callbacks[INA3221_NUM_ALERTS];  
        };
    };
    union {
        struct {
            void *arg_warn_cb;                      
            void *arg_crit_cb;                      
            void *arg_tc_cb;                        
            void *arg_pv_cb;                        
        };
        struct {
            void *alert_callback_arguments[INA3221_NUM_ALERTS]; 
        };
    };
#endif /* MODULE_INA3221_ALERTS */
} ina3221_t;
 
int ina3221_reset(ina3221_t *dev);
 
int ina3221_init(ina3221_t *dev, const ina3221_params_t *params);
 
#if defined(MODULE_INA3221_ALERTS) || defined(DOXYGEN)
 
int _ina3221_enable_alert(ina3221_t *dev, ina3221_alert_t alert,
                          ina3221_alert_cb_t cb, void *arg);
 
static inline int ina3221_enable_warning_alert(ina3221_t *dev,
                                               ina3221_alert_cb_t cb, void *arg)
{
    return _ina3221_enable_alert(dev, INA3221_ALERT_WRN, cb, arg);
}
 
static inline int ina3221_enable_critical_alert(ina3221_t *dev,
                                                ina3221_alert_cb_t cb,
                                                void *arg)
{
    return _ina3221_enable_alert(dev, INA3221_ALERT_CRT, cb, arg);
}
 
static inline int ina3221_enable_timing_control_alert(ina3221_t *dev,
                                                      ina3221_alert_cb_t cb,
                                                      void *arg)
{
    return _ina3221_enable_alert(dev, INA3221_ALERT_TC, cb, arg);
}
 
static inline int ina3221_enable_power_valid_alert(ina3221_t *dev,
                                                   ina3221_alert_cb_t cb,
                                                   void *arg)
{
    return _ina3221_enable_alert(dev, INA3221_ALERT_PV, cb, arg);
}
 
int _ina3221_disable_alert(ina3221_t *dev, ina3221_alert_t alert);
 
static inline int ina3221_disable_warning_alert(ina3221_t *dev)
{
    return _ina3221_disable_alert(dev, INA3221_ALERT_WRN);
}
 
static inline int ina3221_disable_critical_alert(ina3221_t *dev)
{
    return _ina3221_disable_alert(dev, INA3221_ALERT_CRT);
}
 
static inline int ina3221_disable_timing_control_alert(ina3221_t *dev)
{
    return _ina3221_disable_alert(dev, INA3221_ALERT_TC);
}
 
static inline int ina3221_disable_power_valid_alert(ina3221_t *dev)
{
    return _ina3221_disable_alert(dev, INA3221_ALERT_PV);
}
 
#endif /* MODULE_INA3221_ALERTS */
 
int _ina3221_set_config(ina3221_t *dev, uint16_t cfg);
 
static inline int ina3221_set_config(ina3221_t *dev,
                                     ina3221_enable_ch_t chs,
                                     ina3221_num_samples_t ns,
                                     ina3221_conv_time_bus_adc_t ctbadc,
                                     ina3221_conv_time_shunt_adc_t ctsadc,
                                     ina3221_mode_t mode)
{
    return _ina3221_set_config(dev, chs | ns | ctbadc | ctsadc | mode);
}
 
int _ina3221_get_config(const ina3221_t *dev, uint16_t *cfg);
 
static inline int ina3221_get_config(const ina3221_t *dev,
                                     ina3221_enable_ch_t *chs,
                                     ina3221_num_samples_t *ns,
                                     ina3221_conv_time_bus_adc_t *ctbadc,
                                     ina3221_conv_time_shunt_adc_t *ctsadc,
                                     ina3221_mode_t *mode)
{
    uint16_t cfg = 0;
    int ret = _ina3221_get_config(dev, &cfg);
 
    *chs = cfg & INA3221_ENABLE_CH_MASK;
    *ns = cfg & INA3221_NUM_SAMPLES_MASK;
    *ctbadc = cfg & INA3221_CONV_TIME_BADC_MASK;
    *ctsadc = cfg & INA3221_CONV_TIME_SADC_MASK;
    *mode = cfg & INA3221_MODE_MASK;
    return ret;
}
 
int _ina3221_set_enable_channel(ina3221_t *dev, ina3221_enable_ch_t ech);
 
static inline int ina3221_set_channel_state(ina3221_t *dev,
                                            ina3221_channel_state_t ch1,
                                            ina3221_channel_state_t ch2,
                                            ina3221_channel_state_t ch3)
{
    return _ina3221_set_enable_channel(dev,
                                       (ch1 ? INA3221_ENABLE_CH1 : 0) |
                                       (ch2 ? INA3221_ENABLE_CH2 : 0) |
                                       (ch3 ? INA3221_ENABLE_CH3 : 0));
}
 
int _ina3221_get_enable_channel(const ina3221_t *dev, ina3221_enable_ch_t *ech);
 
static inline int ina3221_get_channel_state(const ina3221_t *dev,
                                            ina3221_channel_state_t *ch1,
                                            ina3221_channel_state_t *ch2,
                                            ina3221_channel_state_t *ch3)
{
    ina3221_enable_ch_t ech = 0;
    int ret = _ina3221_get_enable_channel(dev, &ech);
 
    *ch1 = (ech & INA3221_ENABLE_CH1) ? INA3221_CH_ENABLE : INA3221_CH_DISABLE;
    *ch2 = (ech & INA3221_ENABLE_CH2) ? INA3221_CH_ENABLE : INA3221_CH_DISABLE;
    *ch3 = (ech & INA3221_ENABLE_CH3) ? INA3221_CH_ENABLE : INA3221_CH_DISABLE;
    return ret;
}
 
int ina3221_set_num_samples(ina3221_t *dev, ina3221_num_samples_t ns);
 
int ina3221_get_num_samples(const ina3221_t *dev, ina3221_num_samples_t *ns);
 
int ina3221_set_conv_time_bus_adc(ina3221_t *dev,
                                  ina3221_conv_time_bus_adc_t ctb);
 
int ina3221_get_conv_time_bus_adc(const ina3221_t *dev,
                                  ina3221_conv_time_bus_adc_t *ctb);
 
int ina3221_set_conv_time_shunt_adc(ina3221_t *dev,
                                    ina3221_conv_time_shunt_adc_t cts);
 
int ina3221_get_conv_time_shunt_adc(const ina3221_t *dev,
                                    ina3221_conv_time_shunt_adc_t *cts);
 
int ina3221_set_mode(ina3221_t *dev, ina3221_mode_t mode);
 
int ina3221_get_mode(const ina3221_t *dev, ina3221_mode_t *mode);
 
int _ina3221_set_enable_sum_channel(const ina3221_t *dev,
                                    ina3221_enable_sum_ch_t esch);
 
static inline int ina3221_set_enable_sum_channel(const ina3221_t *dev,
                                                 ina3221_channel_state_t ch1,
                                                 ina3221_channel_state_t ch2,
                                                 ina3221_channel_state_t ch3)
{
    return _ina3221_set_enable_sum_channel(dev,
                                           (ch1 ? INA3221_ENABLE_SUM_CH1 : 0) |
                                           (ch2 ? INA3221_ENABLE_SUM_CH2 : 0) |
                                           (ch3 ? INA3221_ENABLE_SUM_CH3 : 0));
}
 
int _ina3221_get_enable_sum_channel(const ina3221_t *dev,
                                    ina3221_enable_sum_ch_t *esch);
 
static inline int ina3221_get_enable_sum_channel(const ina3221_t *dev,
                                                 ina3221_channel_state_t *ch1,
                                                 ina3221_channel_state_t *ch2,
                                                 ina3221_channel_state_t *ch3)
{
    ina3221_enable_sum_ch_t esch = 0;
    int ret = _ina3221_get_enable_sum_channel(dev, &esch);
 
    *ch1 =
        (esch &
         INA3221_ENABLE_SUM_CH1) ? INA3221_CH_ENABLE : INA3221_CH_DISABLE;
    *ch2 =
        (esch &
         INA3221_ENABLE_SUM_CH2) ? INA3221_CH_ENABLE : INA3221_CH_DISABLE;
    *ch3 =
        (esch &
         INA3221_ENABLE_SUM_CH3) ? INA3221_CH_ENABLE : INA3221_CH_DISABLE;
    return ret;
}
 
int ina3221_set_latch(const ina3221_t *dev, ina3221_enable_latch_t latch);
 
int ina3221_get_latch(const ina3221_t *dev, ina3221_enable_latch_t *latch);
 
int ina3221_set_crit_alert_limit(const ina3221_t *dev, ina3221_channel_t ch,
                                 int32_t in_uv);
 
int ina3221_get_crit_alert_limit(const ina3221_t *dev, ina3221_channel_t ch,
                                 int32_t *out_uv);
 
int ina3221_set_warn_alert_limit(const ina3221_t *dev, ina3221_channel_t ch,
                                 int32_t in_uv);
 
int ina3221_get_warn_alert_limit(const ina3221_t *dev, ina3221_channel_t ch,
                                 int32_t *out_uv);
 
int ina3221_set_shunt_voltage_sum_alert_limit(const ina3221_t *dev,
                                              int32_t in_uv);
 
int ina3221_get_shunt_voltage_sum_alert_limit(const ina3221_t *dev,
                                              int32_t *out_uv);
 
int ina3221_set_power_valid_upper_limit(const ina3221_t *dev, int32_t in_mv);
 
int ina3221_get_power_valid_upper_limit(const ina3221_t *dev, int32_t *out_mv);
 
int ina3221_set_power_valid_lower_limit(const ina3221_t *dev, int32_t in_mv);
 
int ina3221_get_power_valid_lower_limit(const ina3221_t *dev, int32_t *out_mv);
 
int ina3221_read_flags(const ina3221_t *dev, uint16_t *flags);
 
int ina3221_read_shunt_sum_uv(const ina3221_t *dev, int32_t *out_uv,
                              uint16_t *flags);
 
int ina3221_read_shunt_uv(const ina3221_t *dev, ina3221_channel_t ch,
                          int32_t *out_uv, uint16_t *flags);
 
int ina3221_read_bus_mv(const ina3221_t *dev, ina3221_channel_t ch,
                        int16_t *out_mv, uint16_t *flags);
 
int ina3221_calculate_current_ua(const ina3221_t *dev, ina3221_channel_t ch,
                                 int32_t *in_uv, int32_t *out_ma);
 
int ina3221_calculate_power_uw(int16_t *in_mv, int32_t *in_ua, uint8_t num,
                               int32_t *out_mw);
 
void ina3221_ch_align(ina3221_channel_t ch, const void *in_res, void *out_res,
                      size_t res_val_size);
 
#define INA3221_TRIGGER_SHUNT(dev) \
    ina3221_set_mode(dev, INA3221_MODE_TRIGGER_SHUNT_ONLY)
 
#define INA3221_TRIGGER_BUS(dev)   \
    ina3221_set_mode(dev, INA3221_MODE_TRIGGER_BUS_ONLY)
 
#define INA3221_TRIGGER_SHUNT_AND_BUS(dev) \
    ina3221_set_mode(dev, INA3221_MODE_TRIGGER_SHUNT_BUS)
 
#ifdef __cplusplus
}
#endif
 
#endif /* INA3221_H */