max30001g.h

Go to the documentation of this file.

/******************************************************************************************************/
// Include file for the MAX30001G ECG and Bioimpedance module
//
// Urs Utzinger, maintainer for the code, July 2024 - present
// GPT-5.3 assisted development, review and testing, Spring 2026
/******************************************************************************************************/
 
#ifndef MAX30001G_H
#define MAX30001G_H
 
// Standard Libraries
#include <stdint.h>
#include <SPI.h>
 
// MAX30001G base data types
#include "max30001g_defs.h"                // Register addresses, bit masks, and other constants
#include "max30001g_regs_typedefs.h"       // Register value structures and unions
#include "max30001g_typedefs.h"            // Data structures for BIOZ and ECG configuration and scan results
#include "max30001g_globals.h"             // Global variables for device state and configuration
 
// SPI Settings (defined in max30001g_comm.cpp)
extern SPISettings SPI_SETTINGS;
 
class MAX30001G {
 
/******************************************************************************************************/
/******************************************************************************************************/
/******************************************************************************************************/
/******************************************************************************************************/
public:
 
  MAX30001G(uint8_t csPin, int intPin1 = -1, int intPin2 = -1);
 
  enum InterruptEvent : uint8_t {
    IRQ_ECG_FIFO = 0,
    IRQ_ECG_OVF,
    IRQ_ECG_FAST,
    IRQ_ECG_LEADOFF,
    IRQ_BIOZ_FIFO,
    IRQ_BIOZ_OVF,
    IRQ_BIOZ_OVER,
    IRQ_BIOZ_UNDER,
    IRQ_BIOZ_CGMON,
    IRQ_LEADS_ON,
    IRQ_RTOR,
    IRQ_PLL_UNLOCK,
    IRQ_EVENT_COUNT
  };
 
  typedef void (*InterruptCallback)(MAX30001G* device, uint32_t status, void* context);
 
  /* @brief Initialize the device state and read startup registers. */
  void begin(void);
 
  /* @brief Stop device operation, disable interrupts, and detach ISR pins. */
  void end(void);
 
  void start(void);
 
  void stop(void);
 
  bool update(bool reportRaw = false);
 
  bool updateRaw(void) { return update(true); }
 
  // ---------------------------------------------------------------------------------------
  // Setup Functions
  // ---------------------------------------------------------------------------------------
 
  void enableAFE(bool ECG, bool BIOZ, bool RtoR);
  
  void setupECG(
    uint8_t speed = 1, 
    uint8_t gain = 2, 
    bool threeleads = true);
  
  void setupBIOZ(
    uint8_t speed = 0, 
    uint8_t gain = 1,
    uint8_t ahpf = 1, 
    uint8_t dlpf = 1, 
    uint8_t dhpf = 0,
    uint32_t frequency = 40000, 
    uint32_t current = 8000, 
    float phase = 0.0f,
    bool leadbias = true, 
    bool leadsoffdetect = false, 
    bool fourleads = false
  );
 
  void setupECGandBIOZ(
    uint8_t ecg_speed = 1, 
    uint8_t ecg_gain = 2, 
    bool ecg_threeleads = true,
    uint8_t bioz_speed = 0, 
    uint8_t bioz_gain = 1,
    uint8_t bioz_dlpf = 1, 
    uint8_t bioz_dhpf = 0,
    uint32_t bioz_frequency = 8000, 
    uint32_t bioz_current = 8000, 
    float bioz_phase = 0.0f,
    bool leadbias = true, 
    bool leadsoffdetect = false, 
    bool bioz_fourleads = false
  ); // initialize AFE for ECG and BIOZ
 
  void setupECGSignalCalibration(uint8_t speed = 1, uint8_t gain = 2);
  
  void setupBIOZSignalCalibration(uint8_t speed = 0, uint8_t gain = 1);
 
  void setupBIOZImpedanceCalibration(
    uint8_t speed = 0, 
    uint8_t gain = 1,
    uint8_t ahpf = 1, 
    uint8_t dlpf = 1, 
    uint8_t dhpf = 0,
    uint32_t frequency = 40000, 
    uint32_t current = 8000, 
    float phase = 0.0f,
    uint32_t resistance = 5000, 
    uint8_t modulation = 0, 
    uint8_t modulation_frequency = 3
  );
 
  void setupBIOZExternalImpedanceCalibration(
    uint32_t frequency = 40000, float phase = 0.0f
  );
 
  void setupBIOZScan(uint8_t avg, bool fast, bool fourleads, bool fullRange);
 
  void setupBIOZScan(const BIOZScanConfig& config = BIOZScanConfig(), bool reuseCurrents = false);
 
  #if 0
  // LEGACY CODE
  void scanBIOZ(uint8_t avg = 2, bool fast = false, bool fourleads = false, bool fullRange = false);
  
  void scanBIOZ(const BIOZScanConfig& config, bool reuseCurrents = false);
#endif
 
  void startBIOZScan(void);
  
  void stopBIOZScan(void);
 
  void stepBIOZScan(void);
 
  // ---------------------------------------------------------------------------------------
  // Registers: max30001g_regs.cpp
  // ---------------------------------------------------------------------------------------
 
  /* @brief Read all known MAX30001G registers into global register mirrors. */
  void readAllRegisters(void);
  
  /* @brief Read INFO register into global mirror. */
  void readInfo(void);
  
  /* @brief Read status register(s) and refresh status flags. */
  void readStatusRegisters(void);
 
  /* @brief Save current register configuration into internal snapshot. */
  void saveConfig(void);
  
  /* @brief Restore register configuration from internal snapshot. */
  void restoreConfig(void);
  
  /* @brief Read and print saved/current configuration related registers. */
  void printConfig(void);
  
  /* @brief Print all known register mirrors for debugging. */
  void printAllRegisters(void);
 
  /* @brief Print focused BIOZ diagnostic register values for scan/calibration debugging. */
  void printBiozDiagnosticRegisters(const char* context = nullptr);
  
  /* @brief Print INFO register decode. */
  void printInfo(void);
  
  /* @brief Print STATUS register decode. */
  void printStatus(void);
 
  // ---------------------------------------------------------------------------------------
  // System: max30001g_system.h
  // ---------------------------------------------------------------------------------------
 
  /* @brief Issue synchronization command to align conversion timing. */
  void synch(void);
  
  /* @brief Issue software reset to device. */
  void swReset(void);
  
  void setFMSTR(uint8_t fmstr);
 
  HealthCheckResult healthCheck(void);
 
  // ---------------------------------------------------------------------------------------
  // Read Data: max30001g_readdata.cpp
  // ---------------------------------------------------------------------------------------
 
  void FIFOReset(void);
 
  void readECG_FIFO(bool reportRaw);
 
  void readBIOZ_FIFO(bool reportRaw);
  
  float readECG(bool reportRaw);
  
  void readRTOR(void);
 
  float readBIOZ(bool reportRaw);
 
  // ---------------------------------------------------------------------------------------
  // Interrupts: max30001g_interrupt.cpp
  // ---------------------------------------------------------------------------------------
 
  void serviceAllInterrupts(void);
 
  bool servicePendingInterrupts(void);
 
  void readAndClearFaults(void);
 
  void clearLatchedStatusFlags(void);
 
  bool setInterruptEventCallback(InterruptEvent event, InterruptCallback cb, void* context = nullptr);
 
  bool setInterruptAggregateCallback(InterruptCallback cb, void* context = nullptr, uint32_t statusMask = 0x00FFFFFFUL);
 
  void clearInterruptEventCallback(InterruptEvent event);
 
  void clearInterruptAggregateCallback(void);
 
  void clearAllInterruptCallbacks(void);
 
  void handleECGFifoInterrupt(bool reportRaw = false);
 
  void handleBIOZFifoInterrupt(bool reportRaw = false);
 
  void handleRtoRInterrupt(void);
 
  bool setInterrupt1(bool ecg, bool bioz, bool rtor, bool leadon, bool leadoff, bool bioz_fourwire = false) {
    return setInterrupt(MAX30001_EN_INT1, ecg, bioz, rtor, leadon, leadoff, bioz_fourwire);
  }
  
  bool setInterrupt2(bool ecg, bool bioz, bool rtor, bool leadon, bool leadoff, bool bioz_fourwire = false) {
    return setInterrupt(MAX30001_EN_INT2, ecg, bioz, rtor, leadon, leadoff, bioz_fourwire);
  }
 
  void setDefaultInterruptClearing(void);
 
  void setFIFOInterruptThreshold(uint8_t ecg, uint8_t bioz);
 
  // ---------------------------------------------------------------------------------------
  // ECG Configuration: max30001g_configure_ecg.cpp
  // ---------------------------------------------------------------------------------------
 
  void setECGSamplingRate(uint8_t ECG);
 
  void setECGfilter(uint8_t lpf, uint8_t hpf);
  
  void setECGgain(uint8_t gain);
  
  void setECGLeadPolarity(bool inverted, bool open);
  
  void setECGAutoRecovery(int threshold_voltage);
  
  /* @brief Disable ECG fast-recovery mode and return to normal operation. */
  void setECGNormalRecovery(void);
  
  /* @brief Enter manual ECG fast-recovery mode. */
  void startECGManualRecovery(void);
  
  /* @brief Exit manual ECG fast-recovery mode. */
  void stopECGManualRecovery(void);
 
  // ---------------------------------------------------------------------------------------
  // BIOZ Configuration: max30001g_configure_bioz.cpp
  // ---------------------------------------------------------------------------------------
 
  void setBIOZSamplingRate(uint8_t speed_select);
 
  void setBIOZgain(uint8_t gain, bool lowNoise);
 
  void setBIOZModulationFrequencyByFrequency(uint32_t frequency_hz);
 
  void setBIOZModulationFrequencybyIndex(uint8_t frequency_selector);
 
  void setBIOZmag(uint32_t current_nA);
 
   void setBIOZPhaseOffsetbyIndex(uint8_t selector);
 
  void setBIOZPhaseOffsetbyPhase(float phase_deg);
 
  void setBIOZPhaseOffsetbyPhase(uint32_t frequency_hz, float phase_deg);
 
  void setBIOZfilter(uint8_t ahpf, uint8_t lpf, uint8_t hpf);
 
  void setBIOZmodulation(uint8_t mode);
 
  void setBIOZCurrentMonitor(bool enable);
 
  // ---------------------------------------------------------------------------------------
  // Leads Configuration: max30001g_configure_leads.cpp
  // ---------------------------------------------------------------------------------------
 
  void setLeadsOnDetection(bool enable);
 
  void setLeadsOffDetection(bool enable, bool bioz_4, uint8_t electrode_impedance);
 
  void setLeadsBias(bool enable, uint8_t resistance);
 
  // ---------------------------------------------------------------------------------------
  // RtoR Configuration: max30001g_configure_rtor.cpp
  // ---------------------------------------------------------------------------------------
 
  void setDefaultRtoR(void);
 
   void setDefaultNoRtoR(void);
 
  void setRtoR(bool enable, uint8_t ptsf, uint8_t pavg, uint8_t gain, uint8_t wndw, uint8_t hoff, uint8_t ravg, uint8_t rhsf);
 
  // ---------------------------------------------------------------------------------------
  // Test Signal and Calibration: max30001g_calibration.cpp
  // ---------------------------------------------------------------------------------------
 
  void setDefaultNoTestSignal(void);
  
  void setDefaultECGTestSignal(void);
  
  void setDefaultBIOZTestSignal(void);
  
  void setDefaultECGandBIOZTestSignal(void);
 
  void setTestSignal(
    bool enableECGCalSignal,
    bool enableBIOZCalSignal,
    bool unipolar,
    bool cal_vmag,
    uint8_t freq,
    uint8_t dutycycle
  );
 
  void setDefaultBIOZTestImpedance(void);
 
  void setDefaultNoBIOZTestImpedance(void);
 
  void setBIOZTestImpedance(
    bool enable,
    bool useHighResistance,
    bool enableModulation,
    uint8_t rnomValue,
    uint8_t rmodValue,
    uint8_t modFreq
  );
 
/******************************************************************************************************/
/******************************************************************************************************/
/******************************************************************************************************/
/******************************************************************************************************/
private:
 
  // ---------------------------------------------------------------------------------------
  // Register related: max30001g_regs.cpp
  // ---------------------------------------------------------------------------------------
  
  void printEN_INT(max30001_en_int_reg_t en_int);
  
  /* @brief Print EN_INT1 register decode. */
  void printEN_INT1(void) { printEN_INT(en_int1); }
  
  /* @brief Print EN_INT2 register decode. */
  void printEN_INT2(void) { printEN_INT(en_int2); }
  
  /* @brief Print MNGR_INT register decode. */
  void printMNGR_INT(void);
  
  /* @brief Print MNGR_DYN register decode. */
  void printMNGR_DYN(void);
 
  /* @brief Print CNFG_GEN register decode. */
  void printCNFG_GEN(void);
  
  /* @brief Print CNFG_CAL register decode. */
  void printCNFG_CAL(void);
  
  /* @brief Print CNFG_EMUX register decode. */
  void printCNFG_EMUX(void);
  
  /* @brief Print CNFG_ECG register decode. */
  void printCNFG_ECG(void);
  
  /* @brief Print CNFG_BMUX register decode. */
  void printCNFG_BMUX(void);
  
  /* @brief Print CNFG_BIOZ register decode. */
  void printCNFG_BIOZ(void);
  
  /* @brief Print CNFG_BIOZ_LC register decode. */
  void printCNFG_BIOZ_LC(void);
  
  /* @brief Print CNFG_RTOR1 register decode. */
  void printCNFG_RTOR1(void);
  
  /* @brief Print CNFG_RTOR2 register decode. */
  void printCNFG_RTOR2(void);
 
  // ---------------------------------------------------------------------------------------
  // System: max30001g_system.h
  // ---------------------------------------------------------------------------------------
 
  // Read registers and update global variables based on register values
  
  void updateGlobalECG_samplingRate(void);
  
  void updateGlobalBIOZ_samplingRate(void);
  
  /* @brief Update calibration frequency global from current registers. */
  void updateGlobalCAL_fcal(void);
  
  /* @brief Update ECG latency global from current timing/filter state. */
  void updateGlobalECG_latency(void);
  
  /* @brief Update BIOZ modulation-frequency global from current registers. */
  void updateGlobalBIOZ_frequency(void);
  
  /* @brief Update BIOZ test-impedance globals from current registers. */
  void updateGlobalBIOZ_test_impedance(void);
  
  /* @brief Update ECG LPF frequency global from current registers. */
  void updateGlobalECG_lpf(void);
  
  /* @brief Update BIOZ DLPF frequency global from current registers. */
  void updateGlobalBIOZ_dlpf(void);
 
  /* @brief Update RCAL modulation-frequency global from current registers. */
  void updateGlobalRCAL_freq(void);
 
  /* @brief Recompute timing-dependent globals from current register state. */
  void refreshTimingGlobals(void);
 
  // ---------------------------------------------------------------------------------------
  // Read Data: max30001g_readdata.cpp (internal single-sample helpers)
  // ---------------------------------------------------------------------------------------
 
  // ---------------------------------------------------------------------------------------
  // Interrupts: max30001g_interrupt.cpp
  // ---------------------------------------------------------------------------------------
 
  bool setInterrupt(uint8_t interrupt, bool ecg, bool bioz, bool rtor, bool leadon, bool leadoff, bool bioz_fourwire);
 
  void latchStatusFlags(uint32_t statusWord);
 
  uint32_t readStatusAndLatchFlags(void);
 
  // ---------------------------------------------------------------------------------------
  // SPI Communication: max30001g_comm.cpp
  // ---------------------------------------------------------------------------------------
  void writeRegister(uint8_t address, uint32_t data);
 
  uint32_t readRegister24(uint8_t address);
 
  uint32_t readRegister(uint8_t address) { return readRegister24(address); }
 
  uint8_t readRegisterByte(uint8_t address);
 
  uint8_t readRegister8(uint8_t address) { return readRegisterByte(address); };
 
  bool verifyWrite(uint8_t address, uint32_t expectedValue);
 
  bool verifRegister(uint8_t address, uint32_t expectedValue) { return verifyWrite(address, expectedValue); }
 
  bool spiCheck();
 
  // ---------------------------------------------------------------------------------------
  // BIOZ: Impedance spectroscopy helper functions
  // ---------------------------------------------------------------------------------------
 
  int32_t closestCurrent(int32_t current);
 
  float impedanceCosineModel(float theta, float magnitude, float phase);
  float impedanceTriangularModel(float theta, float magnitude, float phase);
 
  ImpedanceModel fitImpedanceCosine(const float* phases, const float* impedances, int num_points);
  ImpedanceModel fitImpedanceTriangular(const float* phases, const float* impedances, int num_points);
 
  uint8_t biozScanPhaseCountForFreq(uint8_t freq_idx) const;
  uint8_t biozScanPhaseSelectorForStep(uint8_t freq_idx, uint8_t phase_step_idx) const;
  uint8_t biozScanSelectAHPF(uint8_t freq_idx) const;
  int32_t biozScanMaxHighCurrentForFreq(uint8_t freq_idx);
  int32_t biozScanClampCurrentForFreq(uint8_t freq_idx, int32_t requested_nA);
  float   biozScanRobustMeanFromBuffer(uint8_t outlier_min_samples, float outlier_sigma, bool& hasSamples);
 
  // ---------------------------------------------------------------------------------------
  // Device
  // ---------------------------------------------------------------------------------------
  enum SetupProfile : uint8_t {
    PROFILE_NONE = 0,
    PROFILE_ECG,
    PROFILE_ECG_CAL,
    PROFILE_BIOZ,
    PROFILE_BIOZ_CAL,
    PROFILE_BIOZ_IMP_CAL,
    PROFILE_ECG_AND_BIOZ,
    PROFILE_BIOZ_SCAN
  };
 
  enum BiozScanState : uint8_t {
    BIOZ_SCAN_IDLE = 0,
    BIOZ_SCAN_INIT,
    BIOZ_SCAN_CONFIG_FREQ,
    BIOZ_SCAN_CONFIG_CURRENT,
    BIOZ_SCAN_CONFIG_PHASE,
    BIOZ_SCAN_BEGIN_POINT,
    BIOZ_SCAN_DISCARD_POINT,
    BIOZ_SCAN_COLLECT_POINT,
    BIOZ_SCAN_PROCESS_POINT,
    BIOZ_SCAN_NEXT_PHASE,
    BIOZ_SCAN_EVALUATE_ATTEMPT,
    BIOZ_SCAN_FINALIZE_FREQ,
    BIOZ_SCAN_FINISH
  };
 
  int _csPin;   // chip select for SPI
  int _intPin1; // interrupt pin INTB (EN_INT1)
  int _intPin2; // interrupt pin INT2B (EN_INT2), optional
 
  static void onAFE_IRQ1(void);
  static void onAFE_IRQ2(void);
 
  SetupProfile _profile;
  bool _configured;
  bool _running;
 
  bool _useECG;
  bool _useBIOZ;
  bool _useRTOR;
 
  bool _drainECGOnUpdate;
  bool _drainBIOZOnUpdate;
  bool _readRTOROnUpdate;
 
  bool _applyLeadSettingsOnStart;
  bool _leadBiasEnable;
  uint8_t _leadBiasResistance;
  bool _leadOffEnable;
  bool _leadOffBioz4;
  uint8_t _leadOffElectrodeImpedance;
  bool _leadOnEnable;
 
  ConfigSnapshot _savedConfig;
 
  // BIOZ scan current profile cache (for reuse across scans)
  bool _scanCurrentProfileValid;
  int32_t _scanCurrentProfile[MAX30001_BIOZ_NUM_FREQUENCIES];
  uint8_t _scanProfileFreqStart;
  uint8_t _scanProfileFreqEnd;
  bool _scanProfileFast;
 
  BIOZScanConfig _scanRuntimeConfig;
  bool _scanReuseCurrents;
  bool _scanInProgress;
  bool _scanCompleted;
 
  BiozScanState _BIOZScanState;
  uint8_t _scanFreqIndex;
  uint8_t _scanPhaseIndex;
  uint8_t _scanAttempt;
  uint8_t _scanNumPhaseMeasurements;
  uint8_t _scanDiscardSamplesSeen;
  uint8_t _scanDiscardSamplesTarget;
  uint8_t _scanCollectSamplesTarget;
  bool _scanCurrentChangedForAttempt;
  uint32_t _scanFifoTimeoutMs;
  uint32_t _scanWaitDeadlineMs;
 
  float _scanThresholdMin;
  float _scanThresholdMax;
  float _scanAdcTarget;
 
  bool _scanSawValid;
  bool _scanSawInvalidOrRange;
  bool _scanAnyAboveTarget;
  bool _scanAnyInTarget;
  float _scanMaxAbsRaw;
 
  int32_t _scanCurrent[MAX30001_BIOZ_NUM_FREQUENCIES];
  float _scanFrequency[MAX30001_BIOZ_NUM_FREQUENCIES];
  float _scanImpedance[MAX30001_BIOZ_NUM_FREQUENCIES][MAX30001_BIOZ_NUM_PHASES];
  float _scanPhaseDeg[MAX30001_BIOZ_NUM_FREQUENCIES][MAX30001_BIOZ_NUM_PHASES];
};
 
 
#endif // MAX30001G_H