max30102-esp32c3-oled-oximeter

KO | EN

gitlite — search

#javascript #llm #python #machine-learning #react #classification #cli #tailwindcss #linux #crypto #ai #windows

max30102-esp32c3-oled-oximeter

★ 11 Open GitHub ↗

MAX30102 Pulse Oximeter for ESP32-C3 OLED

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Arduino Build](https://github.com/atomic14/max30102-esp32c3-oled-oximeter/actions/workflows/arduino-build.yml/badge.svg)](https://github.com/atomic14/max30102-esp32c3-oled-oximeter/actions/workflows/arduino-build.yml)

# MAX30102 Pulse Oximeter (Current Fork)

[![YouTube Video](https://raw.githubusercontent.com/atomic14/max30102-esp32c3-oled-oximeter/main/docs/video-play.jpg)](https://www.youtube.com/watch?v=0OV5aCOnXBA)

This repository contains an Arduino/C++ pulse oximeter implementation for the MAX30102, based on the MAXIM reference code and the RF algorithm work preserved in `README_RF.md`.

The current code has been refactored to support:

- interrupt-driven sample acquisition
- rolling updates using a circular sample buffer
- a reusable median filter class (`median_filter.h`)
- smoothed HR/SpO2 output and OLED display updates

## Upstream Context

The original RF-focused project history and notes are kept in `README_RF.md`.

Primary upstream reference:

- https://github.com/aromring/MAX30102_by_RF

## What This Fork Changes

Compared with the batch-only flow, this fork updates results continuously while still feeding the algorithms a full chronological window:

- Samples are read from MAX30102 using the interrupt pin (`oxiInt`).
- New samples are written into ring buffers (no shifting of entire arrays).
- A chronological window is assembled from the ring buffer for each algorithm run.
- Results are updated every `UPDATE_STEP` samples instead of waiting for a full refill.
- HR/SpO2 smoothing uses a fixed-size median filter that stores invalid sentinels and ignores them when calculating the median.

## Sketch Layout

- Main sketch folder: `max30102_esp32c3_oled_oximeter/`
- Main entry sketch: `max30102_esp32c3_oled_oximeter/max30102_esp32c3_oled_oximeter.ino`
- Supporting code for the sketch is colocated in the same folder:
  - `median_filter.h`
  - `algorithm_by_RF.cpp/.h`
  - `algorithm.cpp/.h`
  - `max30102.cpp/.h`
- `README_RF.md` - archived upstream RF-specific README

## Runtime Flow

1. Read `UPDATE_STEP` fresh samples (interrupt-gated).
2. Write into circular red/IR buffers.
3. Once the ring has at least `BUFFER_SIZE` samples, build an ordered analysis window.
4. Run RF (and optional MAXIM) algorithm on that window.
5. Push results into median filters (invalid values are preserved as sentinels).
6. Output filtered values over Serial and to the display.

## Configuration Knobs

You will most likely tune these first:

- `UPDATE_STEP` in `max30102_esp32c3_oled_oximeter.ino`: update cadence (smaller = more responsive, noisier)
- `MEDIAN_HISTORY` in `max30102_esp32c3_oled_oximeter.ino`: smoothing window length
- `FS`, `ST`, and quality thresholds in `algorithm_by_RF.h`

Important: if you change `FS` or `ST`, keep related derived parameters in `algorithm_by_RF.h` consistent.

## Hardware Notes

- MAX30102 interrupt pin is expected on `oxiInt` (currently pin `2`).
- I2C pins are configured in `max30102_esp32c3_oled_oximeter.ino` and passed into `maxim_max30102_init(...)`.
- OLED uses U8g2 and is initialized in the sketch; verify pin mapping for your board.

![Connections](https://raw.githubusercontent.com/atomic14/max30102-esp32c3-oled-oximeter/main/docs/pinout.webp)

| ESP32-C3 | MAX30102 |
|----------|----------|
| V5       | VIN      |
| GD       | GND      |
| GPIO2    | INT      |
| GPIO5    | SDA      |
| GPIO6    | SCL      |

## Troubleshooting

If HR/SpO2 is unstable or stuck:

- verify INT wiring and polarity
- confirm red/IR channels are not swapped
- inspect raw PPG waveform quality before tuning algorithm constants
- reduce motion artifacts (finger pressure and movement matter a lot)
- start with smaller `UPDATE_STEP` and moderate `MEDIAN_HISTORY`

For historical debugging/reporting guidance, see `README_RF.md`.

max30102-esp32c3-oled-oximeter

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README