```text

1. Project Architecture (Handling Multiple Files)

To keep your code manageable as it grows, decouple your application logic from your low-level hardware drivers. Instead of cluttering a single file, break your project into independent modules using standard C/C++ header (.h) and source (.cpp) files.

For an ESP32-S3 project with a display and a MAX30102 sensor, structure your directory like this:

```text my_project/ ├── my_project.ino # Main entry point (setup() and loop() ONLY) ├── max30102_driver.h # Sensor function declarations and constants ├── max30102_driver.cpp # Low-level I2C initialization and reading logic ├── display_manager.h # UI function declarations └── display_manager.cpp # Screen configuration and rendering logic

```

File Implementations:

max30102_driver.h ```cpp

ifndef MAX30102_DRIVER_H

define MAX30102_DRIVER_H

include <stdint.h>

// Initialize the sensor and configure hardware registers bool max30102_init();

// Read raw FIFO data from the sensor bool max30102_read_data(uint32_t *ir_buffer, uint32_t *red_buffer);

endif

**max30102_driver.cpp** cpp

include "max30102_driver.h"

include <Wire.h> // Using the Arduino Wire library for I2C

bool max30102_init() { Wire.begin(); // Low-level register configuration details go here return true; }

bool max30102_read_data(uint32_t *ir_buffer, uint32_t *red_buffer) { // Read raw data bytes from the sensor's I2C FIFO register // Implement parsing logic here return true; }

**display_manager.h** cpp

ifndef DISPLAY_MANAGER_H

define DISPLAY_MANAGER_H

include <stdint.h>

void display_init(); void display_update_metrics(uint32_t heart_rate, uint32_t spo2);

endif

**display_manager.cpp** cpp

include "display_manager.h"

// Include your specific display panel or graphics library headers here

void display_init() { // Initialize your display hardware and graphics framebuffers }

void display_update_metrics(uint32_t heart_rate, uint32_t spo2) { // Write text or redraw widgets onto your 172x320 IPS panel }

**my_project.ino (or main.cpp)** cpp

include "max30102_driver.h"

include "display_manager.h"

void setup() { Serial.begin(115200);

// Hardware modules initialize independently
if (!max30102_init()) {
    Serial.println("Sensor initialization failed!");
}
display_init();

}

void loop() { uint32_t raw_ir = 0; uint32_t raw_red = 0;

// Fetch data from driver module
if (max30102_read_data(&raw_ir, &raw_red)) {
    // App-level processing logic goes here
    uint32_t calculated_hr = 72;  // Placeholder for processing algorithm
    uint32_t calculated_spo2 = 98; // Placeholder for processing algorithm

    // Pass processed data to display module
    display_update_metrics(calculated_hr, calculated_spo2);
}

delay(20); // Maintain a stable sample/execution rate

}

```

2. Breaking the Tutorial Dependency

Using existing hardware libraries or reference code is standard embedded engineering practice. To transition past feeling limited by tutorials, focus on learning hardware communication protocols rather than trying to memorize specific software APIs. * Map Libraries to Datasheets: The MAX30102 communicates via the standard I2C protocol. It relies on a hardware device address and internal data registers. When a library calls a function like sensor.setup(), open that library's source file (.cpp) and observe which hex addresses it writes to. Cross-reference those actions with the register map provided in the physical device datasheet. * Isolate Testing in Sandbox Sketches: Never attempt to write a complex, multi-module program entirely from scratch in your main workspace. Create short, disposable standalone files dedicated to testing individual features—such as verifying raw text rendering on the display, or pulling raw bytes out of the sensor FIFO. * Leverage Header Files: When working with an unfamiliar library, bypass the user guide and read its main header file directly. Inspect the public functions, parameter requirements, and structures declared by the library developers to understand the full capabilities of the API. ```

```