Week 09 – Input Devices

          #include   // Include I2C communication library

          void setup() {

            Serial.begin(115200);  
            // Start serial communication at 115200 baud rate

            pinMode(22, INPUT_PULLUP);  
            // Enable internal pull-up resistor on SDA pin (GPIO22)

            pinMode(23, INPUT_PULLUP);  
            // Enable internal pull-up resistor on SCL pin (GPIO23)

            Wire.begin(22, 23);  
            // Initialize I2C communication, SDA = GPIO22, SCL = GPIO23

            Serial.println("Scanning I2C bus...");  

            // Loop through all valid I2C addresses (1 to 126)
            for (byte addr = 1; addr < 127; addr++) {

              Wire.beginTransmission(addr);  
              // Start communication with device at this address

              if (Wire.endTransmission() == 0) {  
                // endTransmission() returns 0 if device responds (ACK)

                Serial.print("Device found at 0x");  

                Serial.println(addr, HEX);  
                // Print address in hexadecimal format (common for I2C)
              }
            }

            Serial.println("Done.");  // Indicate scan is complete
          }

          void loop() {
          }
        

          #include   
          // Include I2C library for communication

          #define MAX3010x_ADDRESS  0x57  
          // I2C address of MAX3010x sensors (MAX30100, MAX30102, etc.)

          #define PART_ID_REG       0xFF  
          // Register address that stores the chip's Part ID

          // Function to read 1 byte from a specific register of a device
          uint8_t readRegister(uint8_t address, uint8_t reg) {

            Wire.beginTransmission(address);  
            // Start communication with device at given I2C address

            Wire.write(reg);  
            // Tell the device which register we want to read

            Wire.endTransmission(false);        
            // Send the register address but KEEP connection active
            // 'false' = repeated start (important for proper I2C read sequence)

            Wire.requestFrom(address, (uint8_t)1);  
            // Request 1 byte of data from the device

            if (Wire.available()) {  
              // Check if data is available to read

              return Wire.read();  
              // Read and return the byte from the register
            }

            return 0x00;  
            // If no data received, return 0 (indicates failure/no response)
          }

          void setup() {

            Serial.begin(115200);  
            // Start serial communication for debugging output

            delay(1000);  
            // Small delay to allow Serial Monitor to initialize

            pinMode(22, INPUT_PULLUP);          
            // Enable internal pull-up resistor on SDA (GPIO22)

            pinMode(23, INPUT_PULLUP);          
            // Enable internal pull-up resistor on SCL (GPIO23)

            Wire.begin(22, 23);  
            // Initialize I2C with SDA = 22, SCL = 23

            Serial.println("Reading MAX3010x Part ID register (0xFF)...");  
            Serial.println("------------------------------------------");

            // Read the Part ID register (0xFF) from sensor at address 0x57
            uint8_t partID = readRegister(MAX3010x_ADDRESS, PART_ID_REG);

            Serial.print("Raw Part ID value: 0x");
            Serial.println(partID, HEX);  
            // Print the value in hexadecimal format

            Serial.println();

            // Check which chip is connected based on Part ID
            if (partID == 0x11) {
              Serial.println("Chip identified: MAX30100");
              Serial.println("Note: MAX30100 is discontinued.");
              Serial.println("Use library: oxullo/MAX30100lib");
            }

            else if (partID == 0x15) {
              Serial.println("Chip identified: MAX30102");
              Serial.println("Note: MAX30102 is the current active chip.");
              Serial.println("Use library: SparkFun MAX3010x");
            }

            else if (partID == 0x00) {
              Serial.println("No response from sensor.");
              Serial.println("Check wiring — SDA, SCL, VCC, GND.");
            }

            else {
              Serial.print("Unknown Part ID: 0x");
              Serial.println(partID, HEX);
              Serial.println("Could be MAX30101 or a clone IC.");
            }

            Serial.println("------------------------------------------");
          }

          void loop() {
            
          }
        

          #include   
          // I2C communication library

          #include "MAX30100_PulseOximeter.h"  
          // Library that handles MAX30100 sensor (heart rate + SpO2)

          // ── Tuning parameters ────────────────────────────────────────────
          #define REPORTING_PERIOD_MS   2000    
          // Print results every 2 seconds

          #define FINGER_THRESHOLD      3000    
          // If IR value is below this → no finger detected

          #define LED_CURRENT           MAX30100_LED_CURR_11MA   
          // LED brightness (affects signal strength)

          #define SAMPLING_RATE         MAX30100_SAMPRATE_100HZ  
          // Sensor sampling rate (100 samples/sec)
          // ─────────────────────────────────────────────────────────────────

          // Create PulseOximeter object
          PulseOximeter pox;

          // Store last time data was printed
          uint32_t tsLastReport = 0;

          // Count number of detected heartbeats
          uint32_t beatCount    = 0;

          // Track whether finger is placed on sensor
          bool     fingerOn     = false;

          // Callback function: called automatically when a heartbeat is detected
          void onBeatDetected() {
            beatCount++;  
            // Increase beat counter

            Serial.println("  [BEAT " + String(beatCount) + "]");  
            // Print beat number
          }

          void setup() {

            Serial.begin(115200);  
            // Start serial communication

            delay(2000);                         
            // Wait 2 seconds → allow sensor to stabilize after power ON

            pinMode(22, INPUT_PULLUP);  
            // Enable pull-up resistor on SDA

            pinMode(23, INPUT_PULLUP);  
            // Enable pull-up resistor on SCL

            Wire.begin(22, 23);  
            // Initialize I2C (SDA=22, SCL=23)

            Wire.setClock(100000);               
            // Set I2C speed to 100kHz (more stable than 400kHz)

            Serial.println("Initializing MAX30100...");

            if (!pox.begin()) {
              // Try to initialize sensor

              Serial.println("ERROR: MAX30100 not found. Check wiring.");

              while (1);  
              // Stop program if sensor not detected
            }

            // ── Sensor configuration ───────────────────────────────────────
            pox.setIRLedCurrent(LED_CURRENT);  
            // Set IR LED brightness

            pox.setSamplingRate(SAMPLING_RATE);  
            // Set how fast sensor collects data

            pox.setLEDsPulseWidth(MAX30100_SPC_PW_1600US_16BITS);  
            // Set pulse width → longer pulse = better signal

            pox.setHighresModeEnabled(true);  
            // Enable 16-bit resolution (higher accuracy)
            // ──────────────────────────────────────────────────────────────

            pox.setOnBeatDetectedCallback(onBeatDetected);  
            // Register callback → triggers when heartbeat detected

            Serial.println("MAX30100 ready. Place finger GENTLY on sensor.");
            Serial.println("────────────────────────────────────────────────");
          }

          void loop() {

            pox.update();                        
            // VERY IMPORTANT:
            // Continuously processes sensor data
            // Must run as fast as possible (no delay here)

            // ── Finger detection ──────────────────────────────────────────
            bool currentlyOn = (pox.getIR() > FINGER_THRESHOLD);
            // Check IR value → if high, finger is present

            if (currentlyOn != fingerOn) {
              // If finger status changed (placed or removed)

              fingerOn = currentlyOn;

              if (fingerOn) {
                Serial.println("Finger detected — warming up (~5 sec)...");
                beatCount = 0;  
                // Reset beat count when finger placed
              } else {
                Serial.println("Finger removed.");
              }
            }
            // ─────────────────────────────────────────────────────────────

            // ── Periodic report ──────────────────────────────────────────
            if (millis() - tsLastReport > REPORTING_PERIOD_MS) {
              // Check if 2 seconds have passed

              tsLastReport = millis();  
              // Update last report time

              if (!fingerOn) {
                Serial.println("No finger detected. Place fingertip on sensor.");
                return;  
                // Skip rest if no finger
              }

              float bpm  = pox.getHeartRate();  
              // Get calculated heart rate

              uint8_t sp = pox.getSpO2();  
              // Get oxygen saturation %

              // Sanity filter — discard clearly wrong readings
              if (bpm < 40 || bpm > 200) {
                Serial.println("Reading unstable — keep finger still...");
                return;  
                // Ignore unrealistic values
              }

              Serial.print("Heart rate : ");
              Serial.print(bpm, 1);  
              // Print BPM with 1 decimal

              Serial.print(" bpm  |  SpO2 : ");
              Serial.print(sp);  
              // Print oxygen %

              Serial.print(" %  |  IR raw : ");
              Serial.println(pox.getIR());  
              // Print raw IR signal value
            }
            // ─────────────────────────────────────────────────────────────
          }
        

          #include                         // Arduino I2C library — handles SDA/SCL communication
          #include "MAX30100_PulseOximeter.h"      // oxullo MAX30100 library — provides PulseOximeter class

          // ── Timing constants ──────────────────────────────────────────────────────────
          #define SAMPLE_PERIOD_MS    20           // call pox.update() and sample BPM every 20ms
          #define REPORT_PERIOD_MS    1000         // print to Serial Plotter once every 1 second
          #define WARMUP_MS           10000        // wait 10 seconds after finger detected before trusting readings

          // ── Smoothing constant ────────────────────────────────────────────────────────
          #define SMOOTH_FACTOR       0.15         // controls how fast display reacts to BPM changes
                                                  // 0.0 = never changes, 1.0 = no smoothing (jumpy)
                                                  // 0.15 = gentle smoothing — stable but still responsive

          // ── Beat-based BPM calculation ────────────────────────────────────────────────
          #define MIN_BEAT_INTERVAL_MS  300        // ignore beats faster than 300ms apart (> 200 BPM) — noise rejection
          #define MAX_BEAT_INTERVAL_MS  1500       // ignore beats slower than 1500ms apart (< 40 BPM) — noise rejection
          #define BEAT_HISTORY_SIZE     8          // number of recent beat intervals to average — more = smoother

          // ── Global objects ────────────────────────────────────────────────────────────
          PulseOximeter pox;                       // main interface object to MAX30100 sensor

          // ── Timing variables ──────────────────────────────────────────────────────────
          uint32_t tsLastSample    = 0;            // timestamp of last 20ms sample
          uint32_t tsLastReport    = 0;            // timestamp of last 1 second Serial print
          uint32_t tsFingerOn      = 0;            // timestamp of when finger was first placed on sensor
          uint32_t tsLastBeat      = 0;            // timestamp of last valid heartbeat detected

          // ── BPM calculation variables ─────────────────────────────────────────────────
          float    smoothedBPM     = 0;            // exponentially smoothed BPM — what gets printed to plotter
          float    beatIntervals[BEAT_HISTORY_SIZE]; // circular buffer storing last 8 beat-to-beat intervals in ms
          uint8_t  beatIndex       = 0;            // current write position in circular buffer (0 to 7)
          uint8_t  beatsFilled     = 0;            // how many slots in buffer have valid data (0 to 8)
          bool     fingerPresent   = false;        // true when finger is detected on sensor
          bool     warmedUp        = false;        // true after 10 second warmup period has passed

          // ── Beat callback — called automatically by library on every detected heartbeat
          void onBeatDetected() {
            uint32_t now      = millis();          // get current time in milliseconds
            uint32_t interval = now - tsLastBeat;  // calculate time since last beat in milliseconds

            if (tsLastBeat == 0) {                 // first beat ever — no previous timestamp to compare
              tsLastBeat = now;                    // just store timestamp, skip interval calculation
              return;                              // exit early — need at least 2 beats to get an interval
            }

            if (interval < MIN_BEAT_INTERVAL_MS || interval > MAX_BEAT_INTERVAL_MS) {
                                                  // interval is outside valid human heart rate range
                                                  // likely noise, motion artifact, or false detection
              tsLastBeat = now;                    // update timestamp but discard this interval
              return;                              // exit early — don't add bad data to buffer
            }

            beatIntervals[beatIndex] = interval;   // store valid interval in circular buffer at current position
            beatIndex  = (beatIndex + 1) % BEAT_HISTORY_SIZE;  
                                                  // advance write position — wraps back to 0 after reaching size 8
            if (beatsFilled < BEAT_HISTORY_SIZE) { // if buffer not yet completely filled
              beatsFilled++;                       // increment filled count until we reach BEAT_HISTORY_SIZE
            }

            tsLastBeat = now;                      // update last beat timestamp for next interval calculation
          }

          // ── Calculate BPM from stored beat intervals ──────────────────────────────────
          float calculateBPM() {
            if (beatsFilled == 0) return 0;        // no beats collected yet — return 0 (no reading)

            float sum = 0;                         // will accumulate sum of all valid intervals
            for (uint8_t i = 0; i < beatsFilled; i++) {  
                                                  // loop through all filled slots in buffer
              sum += beatIntervals[i];             // add each interval to sum
            }

            float avgInterval = sum / beatsFilled; // average interval in milliseconds between beats
            return 60000.0 / avgInterval;          // convert ms interval to BPM
                                                  // 60000ms = 1 minute, divide by avg interval = beats per minute
          }

          void setup() {
            Serial.begin(115200);                  // start Serial at 115200 baud — must match Serial Plotter baud rate
            delay(3000);                           // wait 3 seconds — gives MAX30100 stable power before init attempt

            Wire.begin(22, 23);                    // initialise I2C bus — GPIO22 = SDA, GPIO23 = SCL on XIAO ESP32-C6
            Wire.setClock(100000);                 // set I2C to 100kHz standard mode — reliable for this module

            while (!pox.begin()) {                 // keep retrying until MAX30100 responds — prevents silent failure
              Serial.println("MAX30100 not found — retrying...");  // inform user of retry
              delay(1000);                         // wait 1 second between retries
            }

            pox.setIRLedCurrent(MAX30100_LED_CURR_27_1MA);  
                                                  // set IR LED current to 27.1mA
                                                  // higher = stronger signal through finger tissue
                                                  // 27.1mA is optimal balance for most fingers

            pox.setOnBeatDetectedCallback(onBeatDetected);   
                                                  // register onBeatDetected() as beat callback
                                                  // library calls this function every time it detects a heartbeat peak

            Serial.println("MAX30100 ready — place finger gently on sensor");
          }

          void loop() {
            pox.update();                          // MUST be called every loop iteration — no delay() anywhere in loop
                                                  // reads new samples from MAX30100 hardware FIFO buffer
                                                  // runs peak detection algorithm on each sample
                                                  // triggers onBeatDetected() callback when beat found
                                                  // any delay() here starves algorithm and causes missed beats

            // ── Finger presence detection ──────────────────────────────────────────────
            float rawBPM = pox.getHeartRate();     // get library's raw BPM estimate — used only for finger detection here
            bool  currentFinger = (rawBPM > 0);   // if library returns any BPM > 0, finger is present on sensor

            if (currentFinger && !fingerPresent) { // finger just placed — was absent, now present
              fingerPresent = true;                // update finger state to present
              tsFingerOn    = millis();            // record time finger was placed — used for warmup countdown
              warmedUp      = false;               // reset warmup flag — need fresh 10 second warmup
              beatsFilled   = 0;                   // clear beat history — old data from previous session is invalid
              beatIndex     = 0;                   // reset circular buffer write position to start
              smoothedBPM   = 0;                   // reset smoothed value — start fresh for new session
              tsLastBeat    = 0;                   // reset last beat timestamp — first beat will set this
              Serial.println("Finger detected — warming up 10 seconds...");
            }

            if (!currentFinger && fingerPresent) { // finger just removed — was present, now absent
              fingerPresent = false;               // update finger state to absent
              warmedUp      = false;               // reset warmup — next placement needs fresh warmup
              Serial.println("Finger removed.");
            }

            // ── Check warmup completion ────────────────────────────────────────────────
            if (fingerPresent && !warmedUp) {      // finger is on but warmup not yet complete
              if (millis() - tsFingerOn > WARMUP_MS) {  
                                                  // check if 10 seconds have passed since finger was placed
                warmedUp = true;                   // warmup complete — readings are now trustworthy
                Serial.println("Warmup complete — reading BPM...");
              }
            }

            // ── Sample and smooth BPM every 20ms ──────────────────────────────────────
            if (millis() - tsLastSample > SAMPLE_PERIOD_MS) {  
                                                  // check if 20ms has passed since last sample
              tsLastSample = millis();             // reset 20ms sample timer

              if (fingerPresent && warmedUp) {     // only update smoothed value if finger on AND warmed up
                float bpm = calculateBPM();        // calculate BPM from our own beat interval buffer

                if (bpm > 40 && bpm < 200) {       // only accept physiologically valid BPM values
                  if (smoothedBPM == 0) {          // first valid reading after warmup
                    smoothedBPM = bpm;             // initialise smoothed value directly — no history to blend with
                  } else {
                    smoothedBPM = smoothedBPM + SMOOTH_FACTOR * (bpm - smoothedBPM);
                                                  // exponential moving average formula:
                                                  // new smoothed = old smoothed + 0.15 * (new reading - old smoothed)
                                                  // blends new reading gently into running average
                                                  // reduces effect of single noisy samples on displayed value
                  }
                }
              }
            }

            // ── Print to Serial Plotter every 1 second ────────────────────────────────
            if (millis() - tsLastReport > REPORT_PERIOD_MS) {  
                                                  // check if 1 second has passed since last print
              tsLastReport = millis();             // reset 1 second report timer

              if (!fingerPresent) {                // no finger on sensor
                Serial.println("BPM:0");          // print 0 — tells plotter signal is absent
                                                  // NOTE: this will show as a dip on plotter — expected behaviour
              } else if (!warmedUp) {              // finger present but still in warmup period
                uint32_t remaining = (WARMUP_MS - (millis() - tsFingerOn)) / 1000;
                                                  // calculate remaining warmup seconds
                Serial.print("BPM:0 — warming up, ");   // print 0 during warmup
                Serial.print(remaining);           // print remaining seconds
                Serial.println("s remaining...");  // complete the message
              } else {                             // finger present, warmed up, valid reading available
                Serial.print("BPM:");             // label for Serial Plotter line
                Serial.println(smoothedBPM, 1);   // print smoothed BPM with 1 decimal place
                                                  // println adds newline — tells plotter this data point is complete
              }
            }
          }