ina3221.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2019 Otto-von-Guericke-Universität Magdeburg
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once

 
#include <assert.h>
#include <errno.h>
#include <stdint.h>
#include <stdbool.h>
 
#include "kernel_defines.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_dev_addr {
    INA3221_ADDR_00 = 0x40,                         
    INA3221_ADDR_01 = 0x41,                         
    INA3221_ADDR_10 = 0x42,                         
    INA3221_ADDR_11 = 0x43,                         
} ina3221_dev_addr_t;

typedef enum ina3221_channel {
    INA3221_CH1 = (1U << 0),                        
    INA3221_CH2 = (1U << 1),                        
    INA3221_CH3 = (1U << 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_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 unsigned ina3221_ch_t;

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 IS_USED(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 IS_USED(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 */

static inline ina3221_ch_t ina3221_config_get_enabled_channels(uint16_t cfg)
{
    return ((cfg & INA3221_ENABLE_CH1) ? INA3221_CH1 : 0) |
           ((cfg & INA3221_ENABLE_CH2) ? INA3221_CH2 : 0) |
           ((cfg & INA3221_ENABLE_CH3) ? INA3221_CH3 : 0);
}

static inline void ina3221_config_set_enabled_channels(uint16_t *cfg, ina3221_ch_t ch)
{
    assert(cfg);
    uint16_t u16 = ((ch & INA3221_CH1) ? INA3221_ENABLE_CH1 : 0) |
                   ((ch & INA3221_CH2) ? INA3221_ENABLE_CH2 : 0) |
                   ((ch & INA3221_CH3) ? INA3221_ENABLE_CH3 : 0);
    *cfg &= ~INA3221_ENABLE_CH_MASK;
    *cfg |= (u16 & INA3221_ENABLE_CH_MASK);
}

static inline ina3221_num_samples_t ina3221_config_get_num_samples(uint16_t cfg)
{
    return (ina3221_num_samples_t)(cfg & INA3221_NUM_SAMPLES_MASK);
}

static inline void ina3221_config_set_num_samples(uint16_t *cfg,
                                                  ina3221_num_samples_t ns)
{
    assert(cfg);
    uint16_t u16 = (uint16_t)ns;
    *cfg &= ~INA3221_NUM_SAMPLES_MASK;
    *cfg |= (u16 & INA3221_NUM_SAMPLES_MASK);
}

static inline ina3221_conv_time_bus_adc_t ina3221_config_get_conv_time_bus(uint16_t cfg)
{
    return (ina3221_conv_time_bus_adc_t)(cfg & INA3221_CONV_TIME_BADC_MASK);
}

static inline void ina3221_config_set_conv_time_bus(uint16_t *cfg,
                                                    ina3221_conv_time_bus_adc_t bus)
{
    assert(cfg);
    uint16_t u16 = (uint16_t)bus;
    *cfg &= ~INA3221_CONV_TIME_BADC_MASK;
    *cfg |= (u16 & INA3221_CONV_TIME_BADC_MASK);
}

static inline ina3221_conv_time_shunt_adc_t ina3221_config_get_conv_time_shunt(uint16_t cfg)
{
    return (ina3221_conv_time_shunt_adc_t)(cfg & INA3221_CONV_TIME_SADC_MASK);
}

static inline void ina3221_config_set_conv_time_shunt(uint16_t *cfg,
                                                      ina3221_conv_time_shunt_adc_t shunt)
{
    assert(cfg);
    uint16_t u16 = (uint16_t)shunt;
    *cfg &= ~INA3221_CONV_TIME_SADC_MASK;
    *cfg |= (u16 & INA3221_CONV_TIME_SADC_MASK);
}

static inline ina3221_mode_t ina3221_config_get_mode(uint16_t cfg)
{
    return (ina3221_mode_t)(cfg & INA3221_MODE_MASK);
}

static inline void ina3221_config_set_mode(uint16_t *cfg,
                                           ina3221_mode_t mode)
{
    assert(cfg);
    uint16_t u16 = (uint16_t)mode;
    *cfg &= ~INA3221_MODE_MASK;
    *cfg |= (u16 & INA3221_MODE_MASK);
}

int ina3221_set_config(ina3221_t *dev, uint16_t cfg);

int ina3221_get_config(const ina3221_t *dev, uint16_t *cfg);

int ina3221_set_enable_channel(ina3221_t *dev, ina3221_ch_t ch);

static inline void ina3221_get_enable_channel(const ina3221_t *dev,
                                              ina3221_ch_t *ch)
{
    *ch = ina3221_config_get_enabled_channels(dev->params.config);
}

int ina3221_set_num_samples(ina3221_t *dev, ina3221_num_samples_t ns);

static inline void ina3221_get_num_samples(const ina3221_t *dev,
                                           ina3221_num_samples_t *ns)
{
    *ns = ina3221_config_get_num_samples(dev->params.config);
}

int ina3221_set_conv_time_bus_adc(ina3221_t *dev,
                                  ina3221_conv_time_bus_adc_t ctb);

static inline void ina3221_get_conv_time_bus_adc(const ina3221_t *dev,
                                                 ina3221_conv_time_bus_adc_t *ctb)
{
    *ctb = ina3221_config_get_conv_time_bus(dev->params.config);
}

int ina3221_set_conv_time_shunt_adc(ina3221_t *dev,
                                    ina3221_conv_time_shunt_adc_t cts);

static inline void ina3221_get_conv_time_shunt_adc(const ina3221_t *dev,
                                                   ina3221_conv_time_shunt_adc_t *cts)
{
    *cts = ina3221_config_get_conv_time_shunt(dev->params.config);
}

int ina3221_set_mode(ina3221_t *dev, ina3221_mode_t mode);

static inline void ina3221_get_mode(const ina3221_t *dev, ina3221_mode_t *mode)
{
    *mode = ina3221_config_get_mode(dev->params.config);
}

int ina3221_set_enable_sum_channel(const ina3221_t *dev, ina3221_ch_t ch);

int ina3221_get_enable_sum_channel(const ina3221_t *dev, ina3221_ch_t *ch);

int ina3221_set_latch(const ina3221_t *dev, bool warn, bool crit);

int ina3221_get_latch(const ina3221_t *dev, bool *warn, bool *crit);

ina3221_ch_t ina3221_set_crit_alert_limit(const ina3221_t *dev,
                                          ina3221_ch_t ch, int32_t in_uv);

ina3221_ch_t ina3221_get_crit_alert_limit(const ina3221_t *dev, ina3221_ch_t ch,
                                          int32_t out_uv[INA3221_NUM_CH]);

ina3221_ch_t ina3221_set_warn_alert_limit(const ina3221_t *dev,
                                          ina3221_ch_t ch, int32_t in_uv);

ina3221_ch_t ina3221_get_warn_alert_limit(const ina3221_t *dev, ina3221_ch_t ch,
                                          int32_t out_uv[INA3221_NUM_CH]);

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

ina3221_ch_t ina3221_read_shunt_uv(const ina3221_t *dev,
                                   int32_t out_uv[INA3221_NUM_CH],
                                   uint16_t *flags);

ina3221_ch_t ina3221_read_bus_mv(const ina3221_t *dev,
                                 int16_t out_mv[INA3221_NUM_CH],
                                 uint16_t *flags);

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]);

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]);

#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