INA.h

Go to the documentation of this file.

// clang-format off
#ifndef ARDUINO

#define ARDUINO 0
#endif
#if ARDUINO >= 100 /* Use old library if IDE is prior to V1.0 */
  #include "Arduino.h"
#else
  #include "WProgram.h"
#endif

#ifndef INA__Class_h

#define INA__Class_h

typedef struct {
  uint8_t  type : 4;           
  uint8_t  operatingMode : 4;  
  uint32_t address : 7;        
  uint32_t maxBusAmps : 10;    
  uint32_t microOhmR : 20;     
} inaEEPROM;                   // of structure
typedef struct inaDet : inaEEPROM {
  uint8_t  busVoltageRegister : 3;    
  uint8_t  shuntVoltageRegister : 3;  
  uint8_t  currentRegister : 3;       
  uint16_t shuntVoltage_LSB;          
  uint16_t busVoltage_LSB;            
  uint32_t current_LSB;               
  uint32_t power_LSB;                 
  inaDet();                           
  inaDet(inaEEPROM& inaEE);           
} inaDet;                             // of structure
enum ina_Type {
  INA219,
  INA226,
  INA228,
  INA230,
  INA231,
  INA260,
  INA3221_0,
  INA3221_1,
  INA3221_2,
  INA_UNKNOWN
};
enum ina_Mode {
  INA_MODE_SHUTDOWN,          
  INA_MODE_TRIGGERED_SHUNT,   
  INA_MODE_TRIGGERED_BUS,     
  INA_MODE_TRIGGERED_BOTH,    
  INA_MODE_POWER_DOWN,        
  INA_MODE_CONTINUOUS_SHUNT,  
  INA_MODE_CONTINUOUS_BUS,    
  INA_MODE_CONTINUOUS_BOTH    
};                            // of enumerated type
/************************************************************************************************
** Declare constants used in the class                                                         **
************************************************************************************************/
#ifndef INA_I2C_MODES                             // I2C related constants
#define INA_I2C_MODES                             
const uint32_t INA_I2C_STANDARD_MODE{100000};     
const uint32_t INA_I2C_FAST_MODE{400000};         
const uint32_t INA_I2C_FAST_MODE_PLUS{1000000};   
const uint32_t INA_I2C_HIGH_SPEED_MODE{3400000};  
#endif
const uint8_t  INA_CONFIGURATION_REGISTER{0};       
const uint8_t  INA_BUS_VOLTAGE_REGISTER{2};         
const uint8_t  INA_POWER_REGISTER{3};               
const uint8_t  INA_CALIBRATION_REGISTER{5};         
const uint8_t  INA_MASK_ENABLE_REGISTER{6};         
const uint8_t  INA_ALERT_LIMIT_REGISTER{7};         
const uint8_t  INA_MANUFACTURER_ID_REGISTER{0xFE};  
const uint8_t  INA_DIE_ID_REGISTER{0xFF};           
const uint16_t INA_RESET_DEVICE{0x8000};            
const uint16_t INA_CONVERSION_READY_MASK{0x0080};   
const uint16_t INA_CONFIG_MODE_MASK{0x0007};        
const uint16_t INA_ALERT_MASK{0x03FF};              
const uint8_t  INA_ALERT_SHUNT_OVER_VOLT_BIT{15};   
const uint8_t  INA_ALERT_SHUNT_UNDER_VOLT_BIT{14};  
const uint8_t  INA_ALERT_BUS_OVER_VOLT_BIT{13};     
const uint8_t  INA_ALERT_BUS_UNDER_VOLT_BIT{12};    
const uint8_t  INA_ALERT_POWER_OVER_WATT_BIT{11};   
const uint8_t  INA_ALERT_CONVERSION_RDY_BIT{10};    
const uint8_t  INA_DEFAULT_OPERATING_MODE{B111};    
const uint8_t  INA219_SHUNT_VOLTAGE_REGISTER{1};    
const uint8_t  INA219_CURRENT_REGISTER{4};          
const uint16_t INA219_BUS_VOLTAGE_LSB{400};         
const uint16_t INA219_SHUNT_VOLTAGE_LSB{100};       
const uint16_t INA219_CONFIG_AVG_MASK{0x07F8};      
const uint16_t INA219_CONFIG_PG_MASK{0xE7FF};       
const uint16_t INA219_CONFIG_BADC_MASK{0x0780};     
const uint16_t INA219_CONFIG_SADC_MASK{0x0038};     
const uint8_t  INA219_BRNG_BIT{13};                 
const uint8_t  INA219_PG_FIRST_BIT{11};             
const uint8_t  INA226_SHUNT_VOLTAGE_REGISTER{1};    
const uint8_t  INA226_CURRENT_REGISTER{4};          
const uint16_t INA226_BUS_VOLTAGE_LSB{125};         
const uint16_t INA226_SHUNT_VOLTAGE_LSB{25};        
const uint16_t INA226_CONFIG_AVG_MASK{0x0E00};      
const uint16_t INA226_DIE_ID_VALUE{0x2260};         
const uint16_t INA226_CONFIG_BADC_MASK{0x01C0};     
const uint16_t INA226_CONFIG_SADC_MASK{0x0038};     

const uint8_t  INA228_DIE_ID_REGISTER{0x3F};        
const uint16_t INA228_DIE_ID_VALUE{0x2280};         
const uint8_t  INA228_BUS_VOLTAGE_REGISTER{0x5};    
const uint16_t INA228_BUS_VOLTAGE_LSB{195};           
const uint8_t  INA228_SHUNT_VOLTAGE_REGISTER{4};    
const uint8_t  xINA228_CURRENT_REGISTER{4};          
const uint16_t xINA228_CONFIG_AVG_MASK{0x0E00};      
const uint16_t xINA228_CONFIG_BADC_MASK{0x01C0};     
const uint16_t xINA228_CONFIG_SADC_MASK{0x0038};     

const uint8_t  INA260_SHUNT_VOLTAGE_REGISTER{0};    
const uint8_t  INA260_CURRENT_REGISTER{1};          
const uint16_t INA260_BUS_VOLTAGE_LSB{125};         
const uint16_t INA260_CONFIG_BADC_MASK{0x01C0};     
const uint16_t INA260_CONFIG_SADC_MASK{0x0038};     
const uint8_t  INA3221_SHUNT_VOLTAGE_REGISTER{1};   
const uint16_t INA3221_BUS_VOLTAGE_LSB{800};        
const uint16_t INA3221_SHUNT_VOLTAGE_LSB{400};      
const uint16_t INA3221_CONFIG_BADC_MASK{0x01C0};    
const uint8_t  INA3221_MASK_REGISTER{0xF};          
const uint8_t  I2C_DELAY{10};                       
// clang-format on

class INA_Class {
 public:
  INA_Class(uint8_t expectedDevices = 0);
  ~INA_Class();
  uint8_t     begin(const uint16_t maxBusAmps, const uint32_t microOhmR,
                    const uint8_t deviceNumber = UINT8_MAX);
  void        setI2CSpeed(const uint32_t i2cSpeed = INA_I2C_STANDARD_MODE) const;
  void        setMode(const uint8_t mode, const uint8_t deviceNumber = UINT8_MAX);
  void        setAveraging(const uint16_t averages, const uint8_t deviceNumber = UINT8_MAX);
  void        setBusConversion(const uint32_t convTime, const uint8_t deviceNumber = UINT8_MAX);
  void        setShuntConversion(const uint32_t convTime, const uint8_t deviceNumber = UINT8_MAX);
  uint16_t    getBusMilliVolts(const uint8_t deviceNumber = 0);
  uint32_t    getBusRaw(const uint8_t deviceNumber = 0);
  int32_t     getShuntMicroVolts(const uint8_t deviceNumber = 0);
  int32_t     getShuntRaw(const uint8_t deviceNumber = 0);
  int32_t     getBusMicroAmps(const uint8_t deviceNumber = 0);
  int64_t     getBusMicroWatts(const uint8_t deviceNumber = 0);
  const char* getDeviceName(const uint8_t deviceNumber = 0);
  uint8_t     getDeviceAddress(const uint8_t deviceNumber = 0);
  void        reset(const uint8_t deviceNumber = 0);
  bool        conversionFinished(const uint8_t deviceNumber = 0);
  void        waitForConversion(const uint8_t deviceNumber = UINT8_MAX);
  bool        alertOnConversion(const bool alertState, const uint8_t deviceNumber = UINT8_MAX);
  bool        alertOnShuntOverVoltage(const bool alertState, const int32_t milliVolts,
                                      const uint8_t deviceNumber = UINT8_MAX);
  bool        alertOnShuntUnderVoltage(const bool alertState, const int32_t milliVolts,
                                       const uint8_t deviceNumber = UINT8_MAX);
  bool        alertOnBusOverVoltage(const bool alertState, const int32_t milliVolts,
                                    const uint8_t deviceNumber = UINT8_MAX);
  bool        alertOnBusUnderVoltage(const bool alertState, const int32_t milliVolts,
                                     const uint8_t deviceNumber = UINT8_MAX);
  bool        alertOnPowerOverLimit(const bool alertState, const int32_t milliAmps,
                                    const uint8_t deviceNumber = UINT8_MAX);
  uint16_t    _EEPROM_offset = 0;  
  #if defined(ESP32) || defined(ESP8266)
  uint16_t _EEPROM_size = 512;  
  #endif
 private:
  int16_t    readWord(const uint8_t addr, const uint8_t deviceAddress) const;
  int32_t    read3Bytes(const uint8_t addr, const uint8_t deviceAddress) const;
  void       writeWord(const uint8_t addr, const uint16_t data, const uint8_t deviceAddress) const;
  void       readInafromEEPROM(const uint8_t deviceNumber);
  void       writeInatoEEPROM(const uint8_t deviceNumber);
  void       initDevice(const uint8_t deviceNumber);
  uint8_t    _DeviceCount{0};         
  uint8_t    _currentINA{UINT8_MAX};  
  uint8_t    _expectedDevices{0};     
  inaEEPROM* _DeviceArray;            
  inaEEPROM  inaEE;                   
  inaDet     ina;                     
  #if defined(__AVR__) || defined(CORE_TEENSY) || defined(ESP32) || defined(ESP8266) || \
      defined(__STM32F1__)
  #else
  inaEEPROM _EEPROMEmulation[32];  
  #endif
};  // of INA_Class definition
#endif