sfDevINA2XX.h

Go to the documentation of this file.

 
#pragma once
 
#include <stdint.h>
 
// SparkFun Toolkit core headers
#include <sfTk/sfToolkit.h>
#include <sfTk/sfTkII2C.h>
 
// ADC Operating Mode Enumeration
typedef enum sfe_ina2xx_mode_t : uint8_t
{
    INA2XX_MODE_SHUTDOWN = 0x0,       
    INA2XX_MODE_TRIG_BUS = 0x1,       
    INA2XX_MODE_TRIG_SHUNT = 0x2,     
    INA2XX_MODE_TRIG_BUS_SHUNT = 0x3, 
    INA2XX_MODE_TRIG_TEMP = 0x4,      
    INA2XX_MODE_TRIG_TEMP_BUS = 0x5,  
    INA2XX_MODE_TRIG_TEMP_SHUNT = 0x6, 
    INA2XX_MODE_TRIG_ALL = 0x7,       
    INA2XX_MODE_SHUTDOWN2 = 0x8,      
    INA2XX_MODE_CONT_BUS = 0x9,       
    INA2XX_MODE_CONT_SHUNT = 0xA,     
    INA2XX_MODE_CONT_BUS_SHUNT = 0xB, 
    INA2XX_MODE_CONT_TEMP = 0xC,      
    INA2XX_MODE_CONT_TEMP_BUS = 0xD,  
    INA2XX_MODE_CONT_TEMP_SHUNT = 0xE, 
    INA2XX_MODE_CONT_ALL = 0xF        
} sfe_ina2xx_mode_t;
 
// Conversion Time Enumeration
typedef enum sfe_ina2xx_conv_time_t : uint8_t
{
    INA2XX_CONV_50US = 0,   
    INA2XX_CONV_84US = 1,   
    INA2XX_CONV_150US = 2,  
    INA2XX_CONV_280US = 3,  
    INA2XX_CONV_540US = 4,  
    INA2XX_CONV_1052US = 5, 
    INA2XX_CONV_2074US = 6, 
    INA2XX_CONV_4120US = 7  
} sfe_ina2xx_conv_time_t;
 
// Averaging Count Enumeration
typedef enum sfe_ina2xx_avg_count_t : uint8_t
{
    INA2XX_AVG_1 = 0,    
    INA2XX_AVG_4 = 1,    
    INA2XX_AVG_16 = 2,   
    INA2XX_AVG_64 = 3,   
    INA2XX_AVG_128 = 4,  
    INA2XX_AVG_256 = 5,  
    INA2XX_AVG_512 = 6,  
    INA2XX_AVG_1024 = 7  
} sfe_ina2xx_avg_count_t;
 
// CONFIG Register Bitfield (Address 0x00)
union sfe_ina2xx_config_reg_t
{
    struct
    {
        uint16_t : 4;          
        uint16_t adcRange : 1; 
        uint16_t tempComp : 1; 
        uint16_t convDly : 8;  
        uint16_t rstAcc : 1;   
        uint16_t rst : 1;      
    };
    uint16_t word; 
};
 
// ADC_CONFIG Register Bitfield (Address 0x01)
union sfe_ina2xx_adc_config_reg_t
{
    struct
    {
        uint16_t avg : 3;    
        uint16_t vtct : 3;   
        uint16_t vshct : 3;  
        uint16_t vbusct : 3; 
        uint16_t mode : 4;   
    };
    uint16_t word; 
};
 
// DIAG_ALRT Register Bitfield (Address 0x0B)
union sfe_ina2xx_diag_alrt_reg_t
{
    struct
    {
        uint16_t memStat : 1;   
        uint16_t cnvrf : 1;     
        uint16_t pol : 1;       
        uint16_t busUL : 1;     
        uint16_t busOL : 1;     
        uint16_t shntUL : 1;    
        uint16_t shntOL : 1;    
        uint16_t tmpOL : 1;     
        uint16_t : 1;           
        uint16_t mathOF : 1;    
        uint16_t chargeOF : 1;  
        uint16_t energyOF : 1;  
        uint16_t apol : 1;      
        uint16_t slowAlert : 1; 
        uint16_t cnvr : 1;      
        uint16_t alatch : 1;    
    };
    uint16_t word; 
};
 
// Class Declaration
 
class sfDevINA2XX
{
  public:
    sfDevINA2XX() : _theBus{nullptr}, _currentLSB{0.0f}, _adcRange{false}, _shuntRes{0.0f}
    {
    }
 
    sfTkError_t begin(sfTkIBus *theBus = nullptr);
 
    void setCommunicationBus(sfTkIBus *theBus);
 
    // ========================= Identity & Reset =============================
 
    sfTkError_t getManufacturerID(uint16_t &id);
 
    sfTkError_t getDeviceID(uint16_t &id);
 
    sfTkError_t reset(void);
 
    sfTkError_t resetAccumulators(void);
 
    // ========================= CONFIG Register (0x00) =======================
 
    sfTkError_t setADCRange(bool reducedRange);
 
    sfTkError_t getADCRange(bool &reducedRange);
 
    sfTkError_t setConversionDelay(uint8_t delay2ms);
 
    sfTkError_t getConversionDelay(uint8_t &delay2ms);
 
    sfTkError_t enableTempCompensation(bool enable);
 
    sfTkError_t getTempCompensation(bool &enabled);
 
    // ====================== ADC_CONFIG Register (0x01) ======================
 
    sfTkError_t setADCMode(sfe_ina2xx_mode_t mode);
 
    sfTkError_t getADCMode(sfe_ina2xx_mode_t &mode);
 
    sfTkError_t setBusVoltageConvTime(sfe_ina2xx_conv_time_t time);
 
    sfTkError_t getBusVoltageConvTime(sfe_ina2xx_conv_time_t &time);
 
    sfTkError_t setShuntVoltageConvTime(sfe_ina2xx_conv_time_t time);
 
    sfTkError_t getShuntVoltageConvTime(sfe_ina2xx_conv_time_t &time);
 
    sfTkError_t setTempConvTime(sfe_ina2xx_conv_time_t time);
 
    sfTkError_t getTempConvTime(sfe_ina2xx_conv_time_t &time);
 
    sfTkError_t setAveragingCount(sfe_ina2xx_avg_count_t count);
 
    sfTkError_t getAveragingCount(sfe_ina2xx_avg_count_t &count);
 
    // ================== Calibration Registers (0x02-0x03) ===================
 
    sfTkError_t setShuntCal(uint16_t calValue);
 
    sfTkError_t getShuntCal(uint16_t &calValue);
 
    sfTkError_t setShuntTempCoefficient(uint16_t ppmPerDegC);
 
    sfTkError_t getShuntTempCoefficient(uint16_t &ppmPerDegC);
 
    // ================== Diagnostics & Alert (0x0B) ==========================
 
    sfTkError_t getDiagnosticFlags(sfe_ina2xx_diag_alrt_reg_t &flags);
 
    sfTkError_t setAlertLatch(bool latched);
 
    sfTkError_t getAlertLatch(bool &latched);
 
    sfTkError_t setConversionReadyAlert(bool enable);
 
    sfTkError_t getConversionReadyAlert(bool &enabled);
 
    sfTkError_t setSlowAlert(bool enable);
 
    sfTkError_t getSlowAlert(bool &enabled);
 
    sfTkError_t setAlertPolarity(bool activeHigh);
 
    sfTkError_t getAlertPolarity(bool &activeHigh);
 
    sfTkError_t isEnergyOverflow(bool &overflow);
 
    sfTkError_t isChargeOverflow(bool &overflow);
 
    sfTkError_t isMathOverflow(bool &overflow);
 
    sfTkError_t isTempOverLimit(bool &overLimit);
 
    sfTkError_t isShuntOverVoltage(bool &overVoltage);
 
    sfTkError_t isShuntUnderVoltage(bool &underVoltage);
 
    sfTkError_t isBusOverVoltage(bool &overVoltage);
 
    sfTkError_t isBusUnderVoltage(bool &underVoltage);
 
    sfTkError_t isPowerOverLimit(bool &overLimit);
 
    sfTkError_t isConversionReady(bool &ready);
 
    sfTkError_t isMemoryValid(bool &valid);
 
    // ==================== Threshold Registers (0x0C-0x11) ===================
 
    sfTkError_t setShuntOverVoltageThreshold(int16_t threshold);
 
    sfTkError_t getShuntOverVoltageThreshold(int16_t &threshold);
 
    sfTkError_t setShuntUnderVoltageThreshold(int16_t threshold);
 
    sfTkError_t getShuntUnderVoltageThreshold(int16_t &threshold);
 
    sfTkError_t setBusOverVoltageThreshold(uint16_t threshold);
 
    sfTkError_t getBusOverVoltageThreshold(uint16_t &threshold);
 
    sfTkError_t setBusUnderVoltageThreshold(uint16_t threshold);
 
    sfTkError_t getBusUnderVoltageThreshold(uint16_t &threshold);
 
    sfTkError_t setTempLimitThreshold(int16_t threshold);
 
    sfTkError_t getTempLimitThreshold(int16_t &threshold);
 
    sfTkError_t setPowerLimitThreshold(uint16_t threshold);
 
    sfTkError_t getPowerLimitThreshold(uint16_t &threshold);
 
  protected:
    sfTkIBus *_theBus; 
    float _currentLSB; 
    bool _adcRange;    
    float _shuntRes;   
 
    sfTkError_t readRegister24(uint8_t reg, uint32_t &value);
 
    sfTkError_t readRegister40(uint8_t reg, uint64_t &value);
 
    // ===================== Shared Measurement Helpers =======================
    // The INA228 and INA237 share these measurement bodies. Each helper is templated (or
    // parameterized) only on what actually differs for that one operation, so the per-device
    // classes stay thin forwarders that pass their own types and constants. No single bundled
    // "traits" object is required.
 
    sfTkError_t calibrateImpl(float shuntResOhms, float maxCurrentA, float calScale,
                              float currentFullScale);
 
    sfTkError_t powerToWatts(float &watts, float powerLSBScale);
 
    sfTkError_t dieTemperatureToCelsius(float &celsius, uint8_t shift, float tempLSB);
 
    sfTkError_t readPowerRaw(uint32_t &value);
 
    template <typename T, bool Wide>
    sfTkError_t readSignedMeasurementRaw(uint8_t reg, T &value)
    {
        if (_theBus == nullptr)
            return ksfTkErrBusNotInit;
 
        if (Wide)
        {
            uint32_t raw = 0;
            sfTkError_t rc = readRegister24(reg, raw);
            if (rc != ksfTkErrOk)
                return rc;
 
            int32_t result = (int32_t)(raw >> 4);
            if (result & (1L << 19))
                result |= ~((1L << 20) - 1);
 
            value = (T)result;
            return ksfTkErrOk;
        }
        else
        {
            uint16_t raw = 0;
            sfTkError_t rc = _theBus->readRegister(reg, raw);
            value = (T)(int16_t)raw;
            return rc;
        }
    }
 
    template <typename T, bool Wide>
    sfTkError_t readUnsignedMeasurementRaw(uint8_t reg, T &value)
    {
        if (_theBus == nullptr)
            return ksfTkErrBusNotInit;
 
        if (Wide)
        {
            uint32_t raw = 0;
            sfTkError_t rc = readRegister24(reg, raw);
            if (rc != ksfTkErrOk)
                return rc;
 
            value = (T)(raw >> 4);
            return ksfTkErrOk;
        }
        else
        {
            uint16_t raw = 0;
            sfTkError_t rc = _theBus->readRegister(reg, raw);
            value = (T)raw;
            return rc;
        }
    }
 
    template <typename T, bool Wide>
    sfTkError_t shuntVoltageToMilliVolts(float &milliVolts, float lsbDefault, float lsbReduced)
    {
        T raw = 0;
        sfTkError_t rc = readSignedMeasurementRaw<T, Wide>(kRegVShunt, raw);
        if (rc != ksfTkErrOk)
            return rc;
 
        float lsb = _adcRange ? lsbReduced : lsbDefault;
        milliVolts = (float)raw * lsb * 1000.0f;
        return ksfTkErrOk;
    }
 
    template <typename T, bool Wide>
    sfTkError_t busVoltageToVolts(float &volts, float busLSB)
    {
        T raw = 0;
        sfTkError_t rc = readUnsignedMeasurementRaw<T, Wide>(kRegVBus, raw);
        if (rc != ksfTkErrOk)
            return rc;
 
        volts = (float)raw * busLSB;
        return ksfTkErrOk;
    }
 
    template <typename T, bool Wide>
    sfTkError_t currentToAmps(float &amps)
    {
        T raw = 0;
        sfTkError_t rc = readSignedMeasurementRaw<T, Wide>(kRegCurrent, raw);
        if (rc != ksfTkErrOk)
            return rc;
 
        amps = (float)raw * _currentLSB;
        return ksfTkErrOk;
    }
 
    // I2C Addressing
    static const uint8_t kI2CAddress = 0x40;
 
    // Register Addresses (shared between INA228 and INA237)
    static const uint8_t kRegConfig = 0x00;         
    static const uint8_t kRegAdcConfig = 0x01;      
    static const uint8_t kRegShuntCal = 0x02;       
    static const uint8_t kRegShuntTempCo = 0x03;    
    static const uint8_t kRegVShunt = 0x04;         
    static const uint8_t kRegVBus = 0x05;           
    static const uint8_t kRegDieTemp = 0x06;        
    static const uint8_t kRegCurrent = 0x07;        
    static const uint8_t kRegPower = 0x08;          
    static const uint8_t kRegEnergy = 0x09;         
    static const uint8_t kRegCharge = 0x0A;         
    static const uint8_t kRegDiagAlrt = 0x0B;       
    static const uint8_t kRegSOVL = 0x0C;           
    static const uint8_t kRegSUVL = 0x0D;           
    static const uint8_t kRegBOVL = 0x0E;           
    static const uint8_t kRegBUVL = 0x0F;           
    static const uint8_t kRegTempLimit = 0x10;      
    static const uint8_t kRegPowerLimit = 0x11;     
    static const uint8_t kRegManufacturerID = 0x3E; 
    static const uint8_t kRegDeviceID = 0x3F;       
 
    // Field masks
    static const uint16_t kShuntCalMask = 0x7FFF;     
    static const uint16_t kBusThresholdMask = 0x7FFF; 
    static const uint16_t kShuntTempCoMask = 0x3FFF;  
 
    // Device ID Constants
    static const uint16_t kINA228DeviceIDValue = 0x2280;  
    static const uint16_t kINA237DeviceIDValue = 0x2370;  
    static const uint16_t kINA238DeviceIDValue = 0x2380;  
    static const uint16_t kDeviceIDMask = 0xFFF0;         
    static const uint16_t kManufacturerIDValue = 0x5449;  
};