English | 简体中文
A MAX30102-based pulse oximetry and heart-rate module. It measures blood oxygen saturation (SpO2), heart rate and board temperature over I2C.
This repository collects the Arduino library, the Python examples for Raspberry Pi and Windows, the desktop GUI tool, and a browser-based version of it — The tutorials under docs/ are available in 11 languages.
| Path | Contents |
|---|---|
docs/<lang>/ |
Tutorials — the same four guides in each language tree. Images are stored only under docs/en/; every other language links to them. |
docs/<lang>/01-arduino/ |
Arduino tutorial |
docs/<lang>/02-raspberry-pi/ |
Raspberry Pi tutorial |
docs/<lang>/03-windows/ |
Windows tutorial |
docs/<lang>/04-gui-tool/ |
Desktop GUI tool user guide |
docs/index.html, docs/assets/ |
Web version of the GUI and the tutorial viewer, published to GitHub Pages |
JUXI_HeartRate_SPO2/ |
The Arduino library (src/), a complete sketch (examples/gainHeartbeatSPO2/), and the Python examples |
HeartRateOximeter/ |
Desktop GUI tool — source and a pre-built Windows bundle (dist/) |
The tutorials are available in 11 languages — the same four guides in each folder:
| Language | Folder |
|---|---|
| English | docs/en/ |
| Deutsch | docs/de/ |
| Español | docs/es/ |
| Français | docs/fr/ |
| Italiano | docs/it/ |
| 日本語 | docs/ja/ |
| 한국어 | docs/ko/ |
| Português (BR) | docs/pt-br/ |
| Português (PT) | docs/pt-pt/ |
| 简体中文 | docs/zh-hans/ |
| 繁體中文 | docs/zh-hant/ |
- Blood oxygen saturation (SpO2)
- Heart rate
- Board temperature
- I2C interface
| Sensor | Arduino |
|---|---|
| VCC | 5V / 3.3V |
| GND | GND |
| SDA | SDA / A4 |
| SCL | SCL / A5 |
| Sensor | USB-to-TTL |
|---|---|
| VCC | 5V (not 3.3V) |
| GND | GND |
| TX | RX (crossed) |
| RX | TX (crossed) |
TX and RX must be crossed.
Arduino — copy JUXI_HeartRate_SPO2/ into your Arduino libraries folder, restart the IDE, then open examples/gainHeartbeatSPO2/gainHeartbeatSPO2.ino. See the library README.
Raspberry Pi / Windows — see the platform tutorials linked above.
Desktop GUI tool — run HeartRateOximeter/dist/HeartRateOximeter.exe on Windows, or run the Python source directly. See the GUI user guide.
Web version — open the link in the next section; nothing to install.
The same GUI also runs in a browser through the Web Serial API — no Python, no .exe, and it works on macOS and Linux as well as Windows.
https://juxi-technology.github.io/JUXI_HeartRate_SPO2/
- Wire the module to a USB-to-TTL adapter and plug it in — the adapter driver (CH340, CP2102, FT232…) must be installed.
- Open the link in desktop Chrome, Edge or Opera. Safari and Firefox do not implement Web Serial.
- Click Connect and choose the USB serial device in the browser's own dialog.
- Start Collection (the module LED turns on), then Start Monitoring.
It speaks the same Modbus RTU protocol as the desktop tool (address 0x20, 9600 baud), so the readings are identical. The Docs tab serves the same 11-language tutorials. Two limits worth knowing: the page has to be loaded from the network each time, and the browser grants it one serial device at a time.
| Reading | Normal range | Note |
|---|---|---|
| SpO2 | 95 % – 100 % | Below 90 % warrants medical attention |
| Heart rate | 60 – 100 bpm | Adult resting range |
| Temperature | 25 – 35 °C | On-board sensor temperature, not body temperature |
Values of -1 right after start-up, or when a finger is not properly placed, are normal.
The MAX30102 driver and sample code are provided as-is for use with this module.