Week 12

Download Design Files

• outputs.ino — Button user interface code with mode system
• camera_pins.h — Camera pin definitions header file
• outputs.zip — Complete project archive including all dependencies

20:04:48.612 -> Scanning...
20:04:48.644 -> I2C device found at address 0x3C  !
20:04:48.644 -> I2C device found at address 0x57  !
20:04:48.644 -> done

Download Design Files

• pulse_vo2_reads_fixing.ino — OLED GUI code for pulse oximeter readings
• pulse_gui.ino — WiFi readings GUI code with real-time data display
• pulse_gui_2.ino — WiFi plot GUI code with Chart.js visualization
• hello_world.ino — Hello World OLED test code
• i2cscan_generic.ino — I2C device scanner utility

I2C Scanner (i2cscan_generic.ino)

Utility code for scanning and detecting I2C devices on the bus, essential for troubleshooting connection issues.

How the Code Works (Pseudocode)

SETUP:
  Initialize I2C bus
  Initialize Serial communication
  Print "I2C Scanner" message

LOOP:
  Print "Scanning..." message
  Initialize device counter to 0
  
  FOR each address from 1 to 126:
    Begin I2C transmission to address
    Check transmission result
    
    IF transmission successful (error == 0):
      Print device found at address (hex format)
      Increment device counter
    ELSE IF unknown error (error == 4):
      Print unknown error at address
    
  IF no devices found:
    Print "No I2C devices found"
  ELSE:
    Print "done"
  
  Wait 5 seconds before next scan

Key Features

• Scans all 127 possible I2C addresses (0x01-0x7E)
• Detects and reports connected devices with hex address format
• Handles multiple error conditions (device not found, unknown errors)
• Continuous scanning mode with 5-second intervals
• Compatible with any I2C bus configuration (Wire, Wire1, etc.)

What You Need to Know

• I2C Address Range: Valid addresses are 0x08-0x77 (8-119 decimal); addresses 0x00-0x07 and 0x78-0x7F are reserved
• Common Addresses: OLED displays typically use 0x3C or 0x3D; sensors vary (MAX30102 uses 0x57)
• Troubleshooting: If no devices found, check wiring (SDA, SCL, power, ground), verify pull-up resistors, confirm device power
• Usage: Run this before connecting other devices to verify I2C bus is working correctly

Hello World OLED Display (hello_world.ino)

Basic OLED display test code that initializes the display and shows "Hello World" text, confirming I2C communication and display functionality.

How the Code Works (Pseudocode)

SETUP:
  Initialize Serial communication at 115200 baud
  Wait 500ms for Serial to stabilize
  
  Initialize I2C bus with SDA pin 5, SCL pin 6
  Print "Starting..." message
  
  Attempt to initialize OLED display:
    IF initialization fails:
      Print "OLED not found" error
      Enter infinite loop (halt)
  
  Clear display buffer
  Set text size to 2
  Set text color to white
  Set cursor position to (0, 20)
  Print "Hello" line
  Print "World!" line
  Update display (send buffer to hardware)

LOOP:
  Empty (runs once, then waits)

Key Features

• Simple OLED initialization and text display
• Custom I2C pin configuration for XIAO ESP32-S3 (SDA=5, SCL=6)
• Error handling with infinite loop if display not found
• Text size and cursor positioning for centered display
• One-time display update (no loop refresh needed for static text)

What You Need to Know

• I2C Pin Configuration: XIAO ESP32-S3 uses pins 5 (SDA) and 6 (SCL) by default; verify your board's pinout
• Display Address: SSD1306 OLED typically uses address 0x3C; some variants use 0x3D
• Display Update: Must call display.display() to send buffer to hardware; drawing functions only modify buffer
• Testing: Use this as first test after connecting OLED to verify wiring and I2C communication before adding complex features
• Libraries Required: Adafruit_GFX, Adafruit_SSD1306, Wire

Button User Interface (outputs.ino)

Mode-based navigation system using button press patterns (single, double, triple, hold) to control multiple output devices including OLED display, camera, sensors, and LED flashlight.

How the Code Works (Pseudocode)

SETUP:
  Initialize OLED display
  Initialize camera module
  Initialize sensors (MPU6050, HX711)
  Initialize button pin (INPUT_PULLUP)
  Initialize LED pin (OUTPUT)
  Set current mode to MENU
  Display menu screen

LOOP:
  Read button state
  
  IF button pressed:
    Record press start time
    Start press detection timer
  
  IF button released:
    Calculate press duration
    IF duration > HOLD_THRESHOLD:
      Activate flashlight mode
    ELSE:
      Increment press count
      Reset press timeout timer
  
  IF press timeout exceeded:
    Process accumulated press count:
      IF press count == 1: Switch to CAMERA mode
      IF press count == 2: Switch to SENSORS mode
      IF press count == 3: Switch to MENU mode
    Reset press count
  
  IF current mode == MENU:
    Display menu screen (button instructions)
  
  IF current mode == CAMERA:
    Capture camera frame
    Process image with dithering algorithm
    Display on OLED
    Run Edge Impulse inference (optional)
    Overlay results on display
  
  IF current mode == SENSORS:
    Read accelerometer/gyroscope data
    Read load cell data
    Display sensor readings on OLED
  
  Update display

Key Features

• Press pattern detection: single (1x), double (2x), triple (3x), and hold
• Mode-based navigation system (Menu, Camera, Sensors)
• Button debouncing with timeout-based pattern recognition
• Floyd-Steinberg dithering for camera-to-OLED video display
• Edge Impulse AI inference integration for face detection
• Multi-sensor integration (MPU6050 accelerometer/gyro, HX711 load cell)
• Flashlight mode activated by button hold

What You Need to Know

• Button Wiring: Use INPUT_PULLUP mode (button connects pin to GND when pressed, internal pull-up to 3.3V)
• Press Detection: Press count is accumulated until timeout (1 second); longer timeout allows slower multiple presses
• Mode Switching: Each mode has distinct display update logic; ensure proper initialization in setup()
• Camera Performance: Video streaming to OLED requires significant processing; frame rate depends on resolution and dithering complexity
• Dependencies: Requires camera_pins.h header file with XIAO ESP32-S3 camera pin definitions; see Ethical AI Use for development details
• Sensor Conflicts: Code uses preprocessor directives to resolve sensor_t type conflict between ESP32 camera and Adafruit MPU6050 libraries

OLED GUI for Pulse Oximeter (pulse_vo2_reads_fixing.ino)

Local OLED display interface showing real-time pulse oximeter readings including heart rate (BPM), blood oxygen saturation (SpO2), and raw IR/RED LED sensor values.

How the Code Works (Pseudocode)

SETUP:
  Initialize Serial communication
  Initialize I2C bus (SDA=5, SCL=6) at 400kHz
  Initialize MAX30102 sensor
  Configure sensor:
    Set LED mode to RED + IR
    Set ADC range to 16384
    Set sample rate to 100 Hz
    Set pulse width to 411 μs
    Set LED brightness to medium (0x3F)
  Initialize OLED display
  Clear and prepare display

LOOP:
  Read IR and RED LED values from sensor
  
  Heart Rate Detection:
    Check for heartbeat in IR signal using peak detection
    IF heartbeat detected:
      Calculate time since last beat
      Calculate BPM = 60 / (time_delta / 1000)
      Set beat flag for visual indicator
      Update last beat timestamp
  
  SpO2 Calculation (every 300ms):
    Add IR and RED values to circular buffer
    IF buffer has 50 samples:
      Calculate DC components (average)
      Calculate AC components (RMS)
      Calculate R ratio = (AC_RED/DC_RED) / (AC_IR/DC_IR)
      Estimate SpO2 = 110 - 25 * R
      Clamp SpO2 to 70-100% range
  
  Serial Output:
    Print IR, RED, BPM for Serial Plotter visualization
  
  OLED Display Update:
    Clear display buffer
    Display IR value (small text)
    Display RED value (small text)
    Display BPM value (large text, size 2)
    Display SpO2 percentage (small text)
    IF beat detected: Draw heartbeat indicator dot
    Update display hardware
  
  Delay 20ms (50 Hz update rate)

Key Features

• Real-time heart rate detection using peak detection algorithm on IR signal
• SpO2 calculation using ratio-of-ratios method with DC/AC component analysis
• Circular buffer system for storing 50 samples of IR/RED data
• Visual heartbeat indicator (flashing dot) when pulse detected
• Dual output: OLED display and Serial Plotter for real-time waveform visualization
• Optimized sensor configuration for reliable readings (100 Hz sample rate, medium brightness)

What You Need to Know

• Sensor Placement: Finger must cover sensor completely; proper contact ensures accurate readings
• I2C Address: MAX30102 uses address 0x57; verify with I2C scanner if sensor not detected
• Ground Isolation: RD and IRD pins must be isolated from main ground plane to prevent power issues (see Week 11 PCB design)
• SpO2 Accuracy: Calculation provides estimation; medical-grade accuracy requires calibration and FDA-approved algorithms
• Buffer Size: 50-sample buffer provides balance between calculation accuracy and response time
• Libraries Required: MAX30105 (SparkFun library), Adafruit_GFX, Adafruit_SSD1306, heartRate.h (beat detection)
• Troubleshooting: If sensor not detected, check power isolation, I2C wiring, and sensor initialization order

WiFi Readings GUI (pulse_gui.ino)

WiFi-enabled web interface providing remote access to pulse oximeter data through HTTP server with JSON API endpoint for real-time data updates.

How the Code Works (Pseudocode)

SETUP:
  Initialize Serial communication
  Initialize I2C bus
  Initialize MAX30102 sensor
  Configure sensor (LED mode, sample rate, pulse width)
  Initialize OLED display
  Initialize WiFi:
    Connect to network (SSID, password)
    Wait for connection
    Print IP address
  Initialize HTTP server:
    Route "/" → serve GUI HTML page
    Route "/gui" → serve GUI HTML page
    Route "/metrics" → serve JSON data
  Start web server

LOOP:
  Handle incoming HTTP client requests
  
  Read IR and RED values from sensor
  
  Heart Rate Calculation:
    Check for heartbeat in IR signal
    IF heartbeat detected:
      Calculate BPM from time delta
      Update global BPM variable
  
  SpO2 Calculation:
    Add IR/RED to circular buffer
    IF buffer full (50 samples):
      Calculate SpO2 using ratio-of-ratios
      Update global SpO2 variable
  
  Update global variables (g_ir, g_red, g_bpm, g_spo2)
  
  OLED Display Update:
    Display IR, RED, BPM, SpO2 values
    Update display hardware

Key Features

• Dual interface: OLED display (local) and WiFi web interface (remote)
• HTTP server with embedded HTML page stored in PROGMEM
• JSON API endpoint (/metrics) for real-time data retrieval
• Automatic WiFi connection with connection status feedback
• IP address display for easy access
• Simultaneous sensor reading and web server operation
• Global variable system for data sharing between sensor reading and HTTP handlers

What You Need to Know

• WiFi Configuration: Update SSID and password in code; for MIT network, use generated device password from wifi.mit.edu
• Network Access: Web interface accessible only from devices on same WiFi network; IP address printed to Serial Monitor
• HTML Storage: GUI HTML page stored in PROGMEM (program memory) to conserve RAM; use PROGMEM for large strings
• Server Handling: Must call server.handleClient() frequently in loop() for responsive web interface
• Data Refresh: Client-side JavaScript polls /metrics endpoint every 300ms for real-time updates
• Power Consumption: WiFi significantly increases power draw compared to OLED-only mode; consider power management for battery operation
• Libraries Required: WiFi, WebServer, MAX30105, Adafruit_SSD1306

WiFi Plot GUI (pulse_gui_2.ino)

Enhanced WiFi web interface with real-time plotting capabilities using Chart.js library, displaying live line charts for BPM and SpO2 values with automatic scrolling and data management.

How the Code Works (Pseudocode)

SETUP:
  (Same as pulse_gui.ino)
  Initialize WiFi, sensor, OLED, HTTP server

LOOP:
  (Same as pulse_gui.ino)
  Handle HTTP requests, read sensor, calculate BPM/SpO2

GUI HTML PAGE (embedded in PROGMEM):
  Load Chart.js library from CDN
  Create two Chart.js line chart instances:
    - BPM chart (y-axis: 40-160 BPM)
    - SpO2 chart (y-axis: 70-100%)
  Initialize data arrays for each chart
  
  JavaScript Update Function (runs every 300ms):
    Fetch JSON data from /metrics endpoint
    Update numerical displays (BPM, SpO2, IR, RED)
    Add new BPM value to BPM data array
    Add new SpO2 value to SpO2 data array
    IF array length > maxPoints (100):
      Remove oldest value (shift)
    Update chart labels (array indices)
    Update chart datasets with new data
    Call chart.update() to refresh display
  
  Set interval to call update function every 300ms

Key Features

• Real-time line chart visualization using Chart.js library
• Dual chart display: BPM and SpO2 trends over time
• Automatic data scrolling: maintains 100 most recent data points
• Numerical displays alongside charts for precise values
• Responsive design with dark theme for OLED-style aesthetic
• Automatic chart scaling with fixed y-axis ranges for consistent visualization
• CDN-based Chart.js loading for minimal memory footprint

What You Need to Know

• Chart.js CDN: Library loaded from jsdelivr.net CDN; requires internet connection on client device
• Data Management: Arrays limited to 100 points to prevent memory overflow; older data automatically discarded
• Update Rate: 300ms refresh rate balances responsiveness with server load; adjust based on network conditions
• Chart Configuration: Y-axis ranges fixed (BPM: 40-160, SpO2: 70-100) for consistent scaling; modify in JavaScript if needed
• Browser Compatibility: Requires modern browser with JavaScript enabled; tested on Chrome, Firefox, Safari
• Performance: Chart updates are lightweight; multiple simultaneous clients may impact ESP32 performance
• Offline Operation: Charts won't load if client device lacks internet (Chart.js CDN unavailable); consider local hosting for offline use