sfDevADE7953.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>
 
// PGA Gain Values
typedef enum sfe_ade7953_pga_gain_t : uint8_t
{
    ADE7953_PGA_GAIN_1 = 0,  
    ADE7953_PGA_GAIN_2 = 1,  
    ADE7953_PGA_GAIN_4 = 2,  
    ADE7953_PGA_GAIN_8 = 3,  
    ADE7953_PGA_GAIN_16 = 4, 
    ADE7953_PGA_GAIN_22 = 5  
} sfe_ade7953_pga_gain_t;
 
// Zero-Crossing Edge Selection
typedef enum sfe_ade7953_zx_edge_t : uint8_t
{
    ADE7953_ZX_EDGE_BOTH = 0,     
    ADE7953_ZX_EDGE_NEGATIVE = 1, 
    ADE7953_ZX_EDGE_POSITIVE = 2, 
    ADE7953_ZX_EDGE_BOTH_ALT = 3  
} sfe_ade7953_zx_edge_t;
 
// Current Clamp Presets
typedef enum sfe_ade7953_clamp_t : uint8_t
{
    ADE7953_CLAMP_ECS1030 = 0, 
    ADE7953_CLAMP_SCT013 = 1   
} sfe_ade7953_clamp_t;
 
// CONFIG Register Bitfield (Address 0x102)
union sfe_ade7953_config_reg_t
{
    struct
    {
        uint16_t intEnA : 1;    
        uint16_t intEnB : 1;    
        uint16_t hpfEn : 1;     
        uint16_t pfMode : 1;    
        uint16_t revpCF : 1;    
        uint16_t revpPulse : 1; 
        uint16_t zxLPF : 1;     
        uint16_t swRst : 1;     
        uint16_t crcEn : 1;     
        uint16_t : 2;           
        uint16_t zxI : 1;       
        uint16_t zxEdge : 2;    
        uint16_t : 1;           
        uint16_t commLock : 1;  
    };
    uint16_t word; 
};
 
// LCYCMODE Register Bitfield (Address 0x004)
union sfe_ade7953_lcycmode_reg_t
{
    struct
    {
        uint8_t aLWatt : 1;  
        uint8_t bLWatt : 1;  
        uint8_t aLVar : 1;   
        uint8_t bLVar : 1;   
        uint8_t aLVa : 1;    
        uint8_t bLVa : 1;    
        uint8_t rstRead : 1; 
        uint8_t : 1;         
    };
    uint8_t byte; 
};
 
// DISNOLOAD Register Bitfield (Address 0x001)
union sfe_ade7953_disnoload_reg_t
{
    struct
    {
        uint8_t disAP : 1;  
        uint8_t disVAR : 1; 
        uint8_t disVA : 1;  
        uint8_t : 5;        
    };
    uint8_t byte; 
};
 
// IRQ Register Bitfield
// Used with IRQENA/IRQSTATA (Channel A) and IRQENB/IRQSTATB (Channel B).
// Channel B interrupts use bits [13:0] only — bits [21:14] are Channel A / voltage only.
union sfe_ade7953_irq_reg_t
{
    struct
    {
        uint32_t aehf : 1;      
        uint32_t varehf : 1;    
        uint32_t vaehf : 1;     
        uint32_t aeof : 1;      
        uint32_t vareof : 1;    
        uint32_t vaeof : 1;     
        uint32_t apNoLoad : 1;  
        uint32_t varNoLoad : 1; 
        uint32_t vaNoLoad : 1;  
        uint32_t apSign : 1;    
        uint32_t varSign : 1;   
        uint32_t zxToI : 1;     
        uint32_t zxI : 1;       
        uint32_t oI : 1;        
        uint32_t zxToV : 1;     
        uint32_t zxV : 1;       
        uint32_t oV : 1;        
        uint32_t wSmp : 1;      
        uint32_t cycEnd : 1;    
        uint32_t sag : 1;       
        uint32_t reset : 1;     
        uint32_t crc : 1;       
        uint32_t : 10;          
    };
    uint32_t word; 
};
 
// Class Declaration
 
class sfDevADE7953
{
  public:
    sfDevADE7953() : _theBus{nullptr}
    {
    }
 
    sfTkError_t begin(sfTkIBus *theBus = nullptr);
 
    bool isConnected(void);
 
    // ========================= Identity & Setup ===========================
 
    sfTkError_t getVersion(uint8_t &version);
 
    sfTkError_t reset(void);
 
    sfTkError_t setWriteProtect(uint8_t protect);
 
    sfTkError_t getWriteProtect(uint8_t &protect);
 
    // ======================== PGA Gain Configuration ======================
 
    sfTkError_t setGainIA(sfe_ade7953_pga_gain_t gain);
 
    sfTkError_t getGainIA(sfe_ade7953_pga_gain_t &gain);
 
    sfTkError_t setGainIB(sfe_ade7953_pga_gain_t gain);
 
    sfTkError_t getGainIB(sfe_ade7953_pga_gain_t &gain);
 
    sfTkError_t setGainV(sfe_ade7953_pga_gain_t gain);
 
    sfTkError_t getGainV(sfe_ade7953_pga_gain_t &gain);
 
    sfTkError_t setDigitalGainIA(uint32_t gain);
 
    sfTkError_t setDigitalGainIA(float multiplier);
 
    sfTkError_t getDigitalGainIA(uint32_t &gain);
 
    sfTkError_t getDigitalGainIA(float &multiplier);
 
    sfTkError_t setDigitalGainIB(uint32_t gain);
 
    sfTkError_t setDigitalGainIB(float multiplier);
 
    sfTkError_t getDigitalGainIB(uint32_t &gain);
 
    sfTkError_t getDigitalGainIB(float &multiplier);
 
    // ======================= Current Measurement ==========================
 
    sfTkError_t getIRMSA(uint32_t &value);
 
    sfTkError_t getIRMSB(uint32_t &value);
 
    sfTkError_t getCurrentA(float &amps);
 
    sfTkError_t getCurrentB(float &amps);
 
    sfTkError_t getInstantaneousIA(int32_t &value);
 
    sfTkError_t getInstantaneousIB(int32_t &value);
 
    // =================== Current Conversion Calibration ===================
 
    sfTkError_t setCurrentClamp(sfe_ade7953_clamp_t clamp);
 
    sfTkError_t setCurrentClampA(sfe_ade7953_clamp_t clamp);
 
    sfTkError_t setCurrentClampB(sfe_ade7953_clamp_t clamp);
 
    void setCurrentClamp(float turnsRatio);
 
    void setCurrentClampA(float turnsRatio);
 
    void setCurrentClampB(float turnsRatio);
 
    void setCurrentTransformerRatio(float ratio);
 
    void setCurrentTransformerRatioA(float ratio);
 
    void setCurrentTransformerRatioB(float ratio);
 
    float getCurrentTransformerRatio(void);
 
    float getCurrentTransformerRatioA(void);
 
    float getCurrentTransformerRatioB(void);
 
    void setBurdenResistor(float ohms);
 
    float getBurdenResistor(void);
 
    sfTkError_t autoCalibrateA(uint16_t numSamples = 50);
 
    sfTkError_t autoCalibrateB(uint16_t numSamples = 50);
 
    void clearCalibration(void);
 
    // ======================== Peak Detection ==============================
 
    sfTkError_t getPeakIA(uint32_t &value);
 
    sfTkError_t getPeakIB(uint32_t &value);
 
    sfTkError_t readAndResetPeakIA(uint32_t &value);
 
    sfTkError_t readAndResetPeakIB(uint32_t &value);
 
    sfTkError_t setOvercurrentLevel(uint32_t level);
 
    sfTkError_t getOvercurrentLevel(uint32_t &level);
 
    // ====================== Calibration & Offset ==========================
 
    sfTkError_t setIRMSOffsetA(int32_t offset);
 
    sfTkError_t getIRMSOffsetA(int32_t &offset);
 
    sfTkError_t setIRMSOffsetB(int32_t offset);
 
    sfTkError_t getIRMSOffsetB(int32_t &offset);
 
    // ======================= Zero-Crossing (ZX_I) =========================
 
    sfTkError_t setZXISourceChannel(bool useChannelB);
 
    sfTkError_t getZXISourceChannel(bool &useChannelB);
 
    sfTkError_t setZXEdge(sfe_ade7953_zx_edge_t edge);
 
    sfTkError_t getZXEdge(sfe_ade7953_zx_edge_t &edge);
 
    sfTkError_t enableZXLPF(bool enable);
 
    sfTkError_t enableHPF(bool enable);
 
    sfTkError_t isHPFEnabled(bool &enabled);
 
    sfTkError_t getPeriod(uint16_t &period);
 
    // =========================== Interrupts ===============================
 
    sfTkError_t setInterruptEnableA(sfe_ade7953_irq_reg_t mask);
 
    sfTkError_t getInterruptEnableA(sfe_ade7953_irq_reg_t &mask);
 
    sfTkError_t getInterruptStatusA(sfe_ade7953_irq_reg_t &status);
 
    sfTkError_t readAndResetInterruptStatusA(sfe_ade7953_irq_reg_t &status);
 
    sfTkError_t setInterruptEnableB(sfe_ade7953_irq_reg_t mask);
 
    sfTkError_t getInterruptEnableB(sfe_ade7953_irq_reg_t &mask);
 
    sfTkError_t getInterruptStatusB(sfe_ade7953_irq_reg_t &status);
 
    sfTkError_t readAndResetInterruptStatusB(sfe_ade7953_irq_reg_t &status);
 
    // ========================= No-Load Detection ==========================
 
    sfTkError_t setNoLoadDisable(sfe_ade7953_disnoload_reg_t mask);
 
    sfTkError_t getNoLoadDisable(sfe_ade7953_disnoload_reg_t &mask);
 
    // ====================== Line Cycle Accumulation =======================
 
    sfTkError_t setLineCycleMode(sfe_ade7953_lcycmode_reg_t mode);
 
    sfTkError_t getLineCycleMode(sfe_ade7953_lcycmode_reg_t &mode);
 
    sfTkError_t setLineCycleCount(uint16_t halfCycles);
 
    sfTkError_t getLineCycleCount(uint16_t &halfCycles);
 
    // ========================= Sag Detection ==============================
 
    sfTkError_t setSagCycles(uint8_t cycles);
 
    sfTkError_t getSagCycles(uint8_t &cycles);
 
    sfTkError_t setSagLevel(uint32_t level);
 
    sfTkError_t getSagLevel(uint32_t &level);
 
    // ========================== Diagnostics ===============================
 
    sfTkError_t getLastOperation(uint8_t &op);
 
    sfTkError_t getLastAddress(uint16_t &address);
 
    sfTkError_t getLastData8(uint8_t &data);
 
    sfTkError_t getLastData16(uint16_t &data);
 
    sfTkError_t getLastData32(uint32_t &data);
 
  protected:
    sfTkError_t applyDefaultConfig(void);
 
    static float pgaGainToMultiplier(sfe_ade7953_pga_gain_t gain);
 
    static void clampPreset(sfe_ade7953_clamp_t clamp, float &ratio, sfe_ade7953_pga_gain_t &gain);
 
    static float removeBaseline(uint32_t reading, uint32_t baseline);
 
    sfTkIBus *_theBus; 
 
    // --- Current-to-amps conversion parameters (sensible defaults for the Qwiic board) ---
    float _ctRatioA = 2000.0f;         
    float _ctRatioB = 2000.0f;         
    float _burdenResistor = 5.6f;      
    float _fullScaleCode = 5928256.0f; 
    float _fullScaleVRMS = 0.35355f;   
 
    // --- Software no-load baselines set by autoCalibrate, removed in the squared domain ---
    uint32_t _baselineA = 0; 
    uint32_t _baselineB = 0; 
 
    // I2C Addressing
    static const uint8_t kI2CAddress = 0x38; 
 
    // 8-Bit Register Addresses (0x0xx)
    static const uint16_t kRegSagCyc = 0x000;       
    static const uint16_t kRegDisNoLoad = 0x001;    
    static const uint16_t kRegLCycMode = 0x004;     
    static const uint16_t kRegPgaV = 0x007;         
    static const uint16_t kRegPgaIA = 0x008;        
    static const uint16_t kRegPgaIB = 0x009;        
    static const uint16_t kRegWriteProtect = 0x040; 
    static const uint16_t kRegLastOp = 0x0FD;       
    static const uint16_t kRegLastRwData8 = 0x0FF;  
    static const uint16_t kRegVersion = 0x702;      
    static const uint16_t kRegExRef = 0x800;        
    static const uint16_t kRegUnlock = 0x0FE;       
 
    // 16-Bit Register Addresses (0x1xx)
    static const uint16_t kRegZXTout = 0x100;       
    static const uint16_t kRegLineCyc = 0x101;      
    static const uint16_t kRegConfig = 0x102;       
    static const uint16_t kRegCF1Den = 0x103;       
    static const uint16_t kRegCF2Den = 0x104;       
    static const uint16_t kRegCFMode = 0x107;       
    static const uint16_t kRegPhCalA = 0x108;       
    static const uint16_t kRegPhCalB = 0x109;       
    static const uint16_t kRegPFA = 0x10A;          
    static const uint16_t kRegPFB = 0x10B;          
    static const uint16_t kRegAngleA = 0x10C;       
    static const uint16_t kRegAngleB = 0x10D;       
    static const uint16_t kRegPeriod = 0x10E;       
    static const uint16_t kRegAltOutput = 0x110;    
    static const uint16_t kRegOptimize = 0x120;     
    static const uint16_t kRegLastAdd = 0x1FE;      
    static const uint16_t kRegLastRwData16 = 0x1FF; 
 
    // 32-Bit Register Addresses (0x3xx) -- valid data in lower 24 bits, upper 8 sign-extended
    static const uint16_t kRegSagLvl = 0x300;    
    static const uint16_t kRegAccMode = 0x301;   
    static const uint16_t kRegApNoLoad = 0x303;  
    static const uint16_t kRegVarNoLoad = 0x304; 
    static const uint16_t kRegVaNoLoad = 0x305;  
    static const uint16_t kRegAVA = 0x310;       
    static const uint16_t kRegBVA = 0x311;       
    static const uint16_t kRegAWatt = 0x312;     
    static const uint16_t kRegBWatt = 0x313;     
    static const uint16_t kRegAVar = 0x314;      
    static const uint16_t kRegBVar = 0x315;      
    static const uint16_t kRegIA = 0x316;        
    static const uint16_t kRegIB = 0x317;        
    static const uint16_t kRegV = 0x318;         
    static const uint16_t kRegIRMSA = 0x31A;     
    static const uint16_t kRegIRMSB = 0x31B;     
    static const uint16_t kRegVRMS = 0x31C;      
    static const uint16_t kRegAEnergyA = 0x31E;  
    static const uint16_t kRegAEnergyB = 0x31F;  
    static const uint16_t kRegREnergyA = 0x320;  
    static const uint16_t kRegREnergyB = 0x321;  
    static const uint16_t kRegApEnergyA = 0x322; 
    static const uint16_t kRegApEnergyB = 0x323; 
    static const uint16_t kRegOvLvl = 0x324;     
    static const uint16_t kRegOiLvl = 0x325;     
    static const uint16_t kRegVPeak = 0x326;     
    static const uint16_t kRegRstVPeak = 0x327;  
    static const uint16_t kRegIAPeak = 0x328;    
    static const uint16_t kRegRstIAPeak = 0x329; 
    static const uint16_t kRegIBPeak = 0x32A;    
    static const uint16_t kRegRstIBPeak = 0x32B; 
    static const uint16_t kRegIrqEnA = 0x32C;    
    static const uint16_t kRegIrqStatA = 0x32D;  
    static const uint16_t kRegRstIrqStatA = 0x32E; 
    static const uint16_t kRegIrqEnB = 0x32F;    
    static const uint16_t kRegIrqStatB = 0x330;  
    static const uint16_t kRegRstIrqStatB = 0x331; 
    static const uint16_t kRegCRC = 0x37F;       
    static const uint16_t kRegAIGain = 0x380;    
    static const uint16_t kRegAVGain = 0x381;    
    static const uint16_t kRegAWGain = 0x382;    
    static const uint16_t kRegAVarGain = 0x383;  
    static const uint16_t kRegAVaGain = 0x384;   
    static const uint16_t kRegAIRMSOS = 0x386;   
    static const uint16_t kRegVRMSOS = 0x388;    
    static const uint16_t kRegAWattOS = 0x389;   
    static const uint16_t kRegAVarOS = 0x38A;    
    static const uint16_t kRegAVaOS = 0x38B;     
    static const uint16_t kRegBIGain = 0x38C;    
    static const uint16_t kRegBWGain = 0x38E;    
    static const uint16_t kRegBVarGain = 0x38F;  
    static const uint16_t kRegBVaGain = 0x390;   
    static const uint16_t kRegBIRMSOS = 0x392;   
    static const uint16_t kRegBWattOS = 0x395;   
    static const uint16_t kRegBVarOS = 0x396;    
    static const uint16_t kRegBVaOS = 0x397;     
    static const uint16_t kRegLastRwData32 = 0x3FF; 
 
    // Magic Values
    static const uint8_t kUnlockKey = 0xAD;             
    static const uint16_t kOptimizeValue = 0x0030;      
    static const uint32_t kDigitalGainUnity = 0x400000; 
    static const uint32_t kDigitalGainMax = 0x7FFFFF;   
    static const uint8_t kLastOpRead = 0x35;            
    static const uint8_t kLastOpWrite = 0xCA;           
};