SparkFun MAX3010x: heart rate and SpO2 from a MAX30102
Yes. You can use the SparkFun MAX3010x Pulse and Proximity Sensor Library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (MAX30102 pulse oximeter). The example below, "Pulse oximeter", runs on the Arduino Uno R3.
Built in on Mokxi: #include <MAX30105.h> and it builds, with nothing to install. Free, and no account needed.
What SparkFun MAX3010x Pulse and Proximity Sensor Library does
The MAX30102 is the small pulse oximeter module with a red and an infrared LED behind a window. A fingertip on it reflects some of that light back to a photodiode, and each heartbeat changes the amount a little. SparkFun wrote this library for the MAX30105 particle sensor, but the MAX30102 shares its registers, so tutorials include MAX30105.h for both and talk to the chip at 0x57.
Most of the library is about getting samples out cleanly. setup() chooses the LED current, the averaging, which LEDs run, the sample rate and the pulse width, and samples queue in the chip’s 32-entry FIFO. getIR() and getRed() give the newest one; check(), available(), getFIFOIR() and nextSample() walk through every sample in order, which an algorithm that needs evenly spaced data has to do.
Two helpers come with it. heartRate.h’s checkForBeat() takes each IR sample and returns true on a beat; spo2_algorithm.h’s maxim_heart_rate_and_oxygen_saturation() takes 100 red and 100 IR samples and estimates SpO2 and heart rate. In Mokxi both are Mokxi’s own simple versions, written for learning and not for medical use. The max30102 part sets the finger, heart rate and SpO2 on sliders, and its third LED slot reads 0 because the MAX30102 has no green LED.
| Library Manager name | SparkFun MAX3010x Pulse and Proximity Sensor Library |
|---|---|
| Author | SparkFun |
| Include | #include <MAX30105.h>#include <heartRate.h>#include <spo2_algorithm.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | MAX30102 pulse oximeter |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <MAX30105.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "SparkFun MAX3010x Pulse and Proximity Sensor Library" by SparkFun from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add SparkFun MAX3010x Pulse and Proximity Sensor Library to lib_deps in PlatformIO. Mokxi follows the calls of release 1.1.2, so a sketch written here builds there too.
What to know in the simulator: checkForBeat() and the SpO2 estimate are Mokxi’s own simple versions, for learning, not medical use. The MAX30102 part has no green LED, so the third slot reads 0.
- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- Raspberry Pi Pico
- Raspberry Pi Pico W
- Seeed XIAO SAMD21
- STM32
- STM32 Nucleo-F411RE
- STM32 Blue Pill
- micro:bit V2
- Arduino Uno R4
- ESP32 DevKit
- ESP32-S3-DevKitC-1
- ESP8266 NodeMCU
- Arduino Pro Mini 3.3 V
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- Seeed XIAO ESP32-S3
- Arduino Nano ESP32
- Arduino Nano RP2040 Connect
- Seeed XIAO RP2040
- Waveshare RP2040-Zero
- Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
MAX30105 particleSensor
Creates the driver; the same class reads the MAX30102.
particleSensor.begin(Wire, I2C_SPEED_FAST)
Checks the part ID at 0x57 with the bus at 400 kHz and returns false when the sensor is not there.
particleSensor.setup(20, 4, 2, 100, 411, 4096)
LED power, samples averaged, LED mode (2 is red and IR), sample rate, pulse width and ADC range. With no arguments it runs every LED at full power and 400 samples a second.
particleSensor.getIR()
The newest infrared sample, up to 18 bits. A low value means no finger is over the window.
checkForBeat(irValue)
Feed it every IR sample; it returns true once per beat. The time between beats gives beats per minute.
long irValue = particleSensor.getIR();
if (checkForBeat(irValue)) {
long delta = millis() - lastBeat;
lastBeat = millis();
Serial.println(60000 / delta);
}particleSensor.check()
Pulls new samples from the FIFO into the library’s buffer. available() says how many are waiting, getFIFORed() and getFIFOIR() read the oldest, nextSample() moves on.
maxim_heart_rate_and_oxygen_saturation(irBuffer, 100, redBuffer, &spo2, &spo2Valid, &heartRate, &heartRateValid)
Estimates SpO2 and heart rate from 100 samples of each light. The two valid flags say whether to trust each result; an invalid one is set to -999.
particleSensor.setPulseAmplitudeRed(0x0A)
Sets the red LED current from 0 to 255. Turning red down to a glow is the usual way to show the sensor is running.
Example: Pulse oximeter
On the Arduino Uno R3. It runs in the browser exactly as printed.
// Pulse oximeter: a MAX30102 shines red and infrared light into a fingertip
// and measures what comes back, read with the SparkFun MAX3010x library.
//
// MAX30102 VIN -> 5 V GND -> GND SDA -> A4 SCL -> A5
//
// Each heartbeat pushes a little more blood into the finger, which absorbs a
// little more light, so both readings dip once a beat: the spacing of the dips
// is the heart rate. Blood rich in oxygen absorbs less red than blood poor in
// it, so how deep the red dip is compared with the infrared one tells the
// oxygen level: R = (red swing / red level) / (IR swing / IR level), and
// SpO2 is about 110 - 25 R.
//
// The LEDs run at 4 mA so that a reading fits the 16 bits the Uno has room
// to store a hundred of. This is for learning how it works, not a medical
// measurement.
//
// Drag the sliders on the sensor, and press F to take the finger off.
#include <Wire.h>
#include "MAX30105.h"
#include "spo2_algorithm.h"
MAX30105 sensor;
uint16_t irBuffer[100];
uint16_t redBuffer[100];
void setup() {
Serial.begin(9600);
if (!sensor.begin(Wire, I2C_SPEED_FAST)) {
Serial.println("MAX30105 was not found. Please check wiring/power.");
while (1) {
}
}
// 4 mA, 4 samples averaged, red and IR, 100 a second, 411 us, 4096 nA:
// 25 samples a second reach the FIFO, the rate the algorithm expects.
sensor.setup(20, 4, 2, 100, 411, 4096);
Serial.println("Pulse oximeter ready");
}
void loop() {
for (byte i = 0; i < 100; i++) {
while (sensor.available() == 0) {
sensor.check();
}
redBuffer[i] = sensor.getFIFORed();
irBuffer[i] = sensor.getFIFOIR();
sensor.nextSample();
}
int32_t spo2;
int8_t spo2Valid;
int32_t heartRate;
int8_t heartRateValid;
maxim_heart_rate_and_oxygen_saturation(irBuffer, 100, redBuffer, &spo2, &spo2Valid, &heartRate, &heartRateValid);
if (!heartRateValid && !spo2Valid) {
Serial.println("Place your finger on the sensor");
return;
}
Serial.print("heart rate ");
if (heartRateValid) {
Serial.print(heartRate);
Serial.print(" bpm");
} else {
Serial.print("--");
}
Serial.print(", SpO2 ");
if (spo2Valid) {
Serial.print(spo2);
Serial.println(" %");
} else {
Serial.println("--");
}
}Open it in the editor, wired and ready to run · Pulse oximeter: the project page
Common errors and how to fix them
MAX30105 was not found. Please check wiring/power.
begin() found no part ID at 0x57. Check the SDA and SCL wires and the module’s VIN, then run an I2C scanner to see whether 0x57 appears at all.
The heart rate jumps between very low and very high values
checkForBeat() needs a still finger and every sample, so a delay() or a long print in loop() hides beats. Average the last few beat intervals before showing a rate, as SparkFun’s example does.
SpO2 always comes back as -999
The estimate marks itself invalid when the signal is too flat or has too few peaks, usually with no finger or one pressing hard. Rest the finger lightly and let a full buffer of 100 samples fill.
The SpO2 sketch runs out of RAM on an Uno
Two buffers of 100 uint32_t take 800 bytes of the Uno’s 2 KB. Use uint16_t buffers with a low LED current so samples fit in 16 bits, as the pulse oximeter project does.
Questions and answers
Can this project be used as a medical oximeter?
No. In Mokxi the beat detector and the SpO2 estimate are simple teaching versions, and even on hardware a hobby module is not a calibrated medical device.
Why does the oximeter project pass 4 mA to setup()?
At that current each reading fits in 16 bits, so the Uno can hold a hundred of each in uint16_t buffers, the number the SpO2 call works on.
Projects that use SparkFun MAX3010x Pulse and Proximity Sensor Library
Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.
Keep going
Try SparkFun MAX3010x Pulse and Proximity Sensor Library without installing anything
Open the example, change the sketch, and keep your version in a free account.