Project Files of MAX30102 Sensor Library for Proteus V1.1 (Pulse Oximeter + Arduino)

MAX30102 PULSE OXIMETER SENSOR LIBRARY FOR PROTEUS - V1.1
Designed by The Engineering Projects
www.TheEngineeringProjects.com

IMPORTANT LINKS
Article (read it first - pictures, step by step, every feature explained):
  https://www.theengineeringprojects.com/2026/09/max30102-proteus-library.html
Report a bug or suggest a feature (our forum):
  https://www.theengineeringprojects.com/forum/category/max30102-proteus-library
The demo uses our TEP Serial Monitor Advance (included) instead of Proteus's
Virtual Terminal - its own article:
  https://www.theengineeringprojects.com/2026/10/serial-monitor-advance-proteus-library.html
Support us (the libraries are free):
  https://www.theengineeringprojects.com/donate

FILE STRUCTURE
MAX30102-TEP-v1.1/
|-- Proteus Library Files/
|   |-- ArduinoV3TEP.IDX                          0.8 KB   its index -> LIBRARY folder
|   |-- ArduinoV3TEP.LIB                         95.6 KB   TEP Arduino UNO (demo) -> LIBRARY folder
|   |-- TEPMAX30102.LIB                          44.2 KB   MAX30102 Simple + Advance (2 devices) -> LIBRARY
|   |-- TEPSERIALMON.LIB                         11.1 KB   TEP Serial Monitor Advance -> LIBRARY folder
|-- Proteus Model Files/
|   |-- TEPMAX30102.DLL                         537.0 KB   the TEP I2C sensor model -> MODELS
|   |-- TEPSERIALMON.DLL                        978.0 KB   Serial Monitor model -> MODELS folder
|-- Proteus Simulation/
|   |-- MAX30102_Demo.hex                        37.3 KB   both UNOs (the demo sketch v1.1)
|   |-- MAX30102-ArduinoUnoV3.pdsprj             22.8 KB   demo: UNO 1 + MAX30102 Simple, UNO 2 + Advance
|   |-- TEPMAX30102.DLL                         537.0 KB   copy of the model so the demo runs as is
|   |-- TEPSERIALMON.DLL                        978.0 KB   copy of the monitor model
|-- Arduino Code/
|   |-- MAX30102_Demo/MAX30102_Demo.ino           6.1 KB   sketch (source of the .hex)
|   |-- libraries/SparkFun_MAX3010x_Sensor_Library/   90.4 KB   SparkFun MAX3010x 1.1.2, MIT, 21 files
|-- README.txt                                  ~28.9 KB   this file
Total: 3.29 MB (unzipped). The C++ source code of the model is not included.

WHAT IS IT?
A simulation model of the Maxim (Analog Devices) MAX30102 pulse oximeter and
heart-rate sensor on the common purple GY-MAX30102 breakout, for Proteus 8. Your
Arduino talks to it over I2C exactly as to the real chip (address 0x57) and the
popular SparkFun MAX3010x library runs unmodified: begin, setup, check,
available, getFIFOIR / getFIFORed, nextSample, getIR / getRed,
setPulseAmplitudeRed / IR, setSampleRate, setFIFOAverage, enableFIFORollover,
clearFIFO, readTemperature, shutDown / wakeUp. The model has the MAX30102's
register map: the HR / SpO2 / multi-LED modes, the LED currents (0.2 mA per
step), the sample rate (50 .. 3200 Hz) and the sample averaging, the pulse
width with its ADC resolution (15 .. 18 bit), the ADC range, the 32-sample FIFO
with its pointers, overflow counter and rollover, the interrupts and the die
temperature sensor (29 ms per conversion). The light it sees is a fingertip's
pulse wave (v1.1): every heartbeat a fast systolic upstroke and peak, the dicrotic
shoulder (the diastolic wave) and a slow run-off - the raw counts dip at every beat,
as on a real sensor (more blood, less light back). You set the pulse rate (BPM), the SpO2 the red / IR ratio
stands for, whether a finger is on the sensor and the die temperature - with
sliders, presets (FINGER ON / OFF, REST 60, WALK 95, RUN 150, LOW SPO2) or by
clicking the pulse view above the board (finger on / off). Your sketch computes
the pulse and SpO2 from the samples itself, as with the real sensor.
The part looks like the GY-MAX30102: the purple board, the two big mounting
holes, the black MAX30102 with its window over the red and IR LEDs, the small
parts and the GY-MAX30102 print. Above the board sits an animated pulse
monitor: a heart that beats with the pulse, the BPM and SpO2 figures, the finger
state and the PPG trace - the IR samples the sensor makes, scrolling. On the
board: a red PWR LED, a blue I2C LED that flashes for every I2C transaction to
this sensor and an amber INT LED that lights while the INT pin is active - TEP
additions (the real board has no LED) - and the live I2C address (0x57).

TWO DEVICES IN ONE LIBRARY (search "MAX30102" in Pick Devices):
  MAX30102 Simple   device MAX30102TEP    "MAX30102 Pulse Oximeter Sensor - Simple"
                    On-Sheet Panel: a control panel on the schematic next to the
                    board - six presets, three sliders of v1.0 (drag them: PULSE
                    RATE, SPO2 TARGET, DIE TEMPERATURE; the finger is a preset /
                    a click on the pulse view) and what your sketch READ over I2C
                    (decoded by the model: "SKETCH READ: IR 50000 RED 49720 -> 72
                    BPM 98.0 %" - the pulse and SpO2 in the last 100 samples it
                    read), the set values and the mode, sample rate and LED
                    current your sketch chose. The red X in the panel's header
                    closes it, the PANEL button on the board opens it again. Your
                    v1.0 designs keep working with this device.
  MAX30102 Advance  device MAX30102ADVTEP "MAX30102 Pulse Oximeter Sensor - Advance"
                    Pop-Up Panel: only the board on the schematic; at Run a TEP
                    pop-up window opens - the same look as the TEP Serial Monitor
                    (move it by its header, resize it, minimise it). The tabs
                    Sensor and Test sit in the header; the gear and ? icons open
                    Settings and Help; the palette icon switches the theme:
                      Sensor    the live pulse view (the heart, the figures and the
                                PPG trace; click it to put the finger on or take it
                                off), the presets, a click-slider with - / + for
                                every input, the last sample as big tiles, and what
                                the Arduino read over I2C (the samples, the mode,
                                the FIFO, the die temperature, the I2C address and
                                the measured SCL clock)
                      Test      four tools measured on the model with your sketch:
                                I2C check, Timing, Step response, Pulse & SpO2 (see
                                THE TEST TOOLS below)
                      Settings  theme (TEP Dark / Light), text size, open at Run,
                                window size - remembered for your Windows user
                      Help      Help & Support like the TEP Serial Monitor: report a
                                bug, suggest a feature, article, user guide,
                                updates, donate, website, forum; Copy diagnostics
                                (the inputs, what was read, the registers, the last
                                transactions, the test results) for a bug report
                    The OPEN PANEL button on the board opens the window again
                    after you close it.
Both devices use the same model (TEPMAX30102.DLL) and the same properties.

NEW IN V1.1
* Two devices: MAX30102 Simple (panel on the sheet, close / open) and MAX30102
  Advance (pop-up window with the live pulse view, four test tools, settings
  and help) - see above.
* Board: the real GY-MAX30102's look (purple, two big holes, the sensor with
  its LED window) with an animated pulse monitor above it (beating heart, BPM,
  SpO2, finger, the scrolling PPG trace), PWR / I2C / INT LEDs (a TEP addition),
  the live I2C address, a PANEL / OPEN PANEL button and a SIMPLE / ADVANCE badge.
* Model - the samples your sketch takes out of the FIFO are recorded (the test
  tools compute the pulse and SpO2 from exactly those); counters for the
  samples made and read, the FIFO overflows and the temperature conversions.
  The FIFO, modes and timing of v1.0 are unchanged.
* Model - a real pulse wave instead of v1.0's sine: a systolic upstroke and
  peak, the dicrotic shoulder (the diastolic wave, at about a third of the
  pulse; it fades at a fast heart rate, as in real life) and a slow run-off;
  the raw IR / red counts dip at every beat. From the peak to the foot of the
  beat the wave only falls, so any threshold or peak detector counts exactly
  one beat per heartbeat at 40 .. 200 BPM. The red modulation is set so that
  the ratio of ratios (AC / mean) gives the set SpO2. The board and the pop-up
  show the wave inverted, like a pulse oximeter (up = more blood).
  With the demo the estimates stay within 2 BPM and 1 % at 40 .. 180 BPM and
  SpO2 98 / 92 / 88 / 85 % (worst 1.4 BPM, 0.1 %), also at half the LED current.
  Maxim's reference algorithm (SparkFun spo2_algorithm) is within one sample of
  its peak interval (it averages whole samples: 90 BPM reads 88 or 93, 120
  reads 125, 180 reads 187). It has one quirk of its own: its last 4 samples
  are not averaged, so now and then it reports a "valley" at sample 95 .. 99
  where the IR has none (the next or the last beat's slope) and the BPM of that
  window comes out high (e.g. 75 BPM reads 88) - the next windows are right
  again. That is the algorithm, not the model: it does the same with a real
  MAX30102.
* Model - a full FIFO is reported: when the sketch does not read for more than
  32 samples (1.28 s at 25 samples / s), FIFO_WR_PTR = FIFO_RD_PTR and a reader
  that compares the pointers (the SparkFun library) sees no new samples until
  the FIFO is cleared - the banner says FIFO FULL and the I2C check marks it.
* Model - an I2C transaction log (every read / write decoded: "read FIFO_DATA ->
  00 BD 2A 00 B8 08", "write LED2_PA (IR) = 3C") and the measured SCL clock.
* The demo: ONE project with two UNOs - UNO 1 with MAX30102 Simple, UNO 2 with
  MAX30102 Advance - each with the TEP Serial Monitor Advance instead of the
  Virtual Terminal (U3 = UNO 1, U4 = UNO 2, quick buttons) and an LED on A0.
* The demo sketch (v1.1) keeps every v1.0 line and adds: a heartbeat LED on A0
  (it flashes with every beat in the samples), and the Serial Monitor commands
  HELP, STATUS, LED, TEMP, RAW ON / OFF. It prints nothing periodically except
  the readings (and the v1.0 "No finger" notice).
* Version 1.1 everywhere; the C++ source code is no longer included (and
  neither is the Arduino AVR core archive - its GitHub link is below).

TEST STATUS
v1.1: verified in Proteus 8.5 on 8 Oct 2026 (the demo run from this package's
Proteus Simulation folder): the start-up lines, then "Pulse estimate: 71.4 BPM |
SpO2 estimate: 98.0 % | Die temp: 25.0 C" and 72.3; RUN 150 (the panel's
SKETCH READ 150 BPM 95.0 %); FINGER OFF "No finger / low optical signal."; the
I2C check (PART_ID 15, SPO2_CONFIG 27, FIFO_CONFIG 50, LED 3C / 3C, 0 NACKs, SCL
85 kHz); Timing (75 samples every 40.00 ms, 75 reads every 40.0 ms, data age 3.9 /
6.8 ms); Pulse & SpO2 (60 / 98, 90 / 97, 120 / 95 exact). That run found two
things, fixed afterwards (PC-tested, to be re-checked in Proteus): the Step response stopped
collecting after its first step when the sensor gave many samples (now every
step collects; the pulse-rate steps last 9 s), and the light was a pure sine (now
the real pulse wave above). The re-check in Proteus (8 Oct) found one more: the
Pulse & SpO2 tool read Low SpO2 75 / 88 as 164.7 BPM - round 2's wave had a
diastolic bump up to half the pulse that a midpoint counter could take for a
second beat. Fixed (PC-tested, to be re-checked in Proteus): the wave's diastolic
part is now a shoulder that never rises again, and the tool counts the systolic
upstroke only (hysteresis + 0.25 s minimum). The PC tests now sweep the demo's
estimate and Maxim's algorithm over 14 rates x 4 SpO2 (and half the LED
current) and run the Pulse & SpO2 tool end to end 8 times from different
starting phases (one at half the LED current) - 5 / 5 OK every time. Also
new: the Step response waits until the readings sit at the start value before
step 1.
PC tests (8 Oct 2026, this package's DLL / LIB / sketch):
  1913 automatic checks on a PC, 0 failed, plus the v1.0 test, unchanged and
  passing with the v1.1 model (MAX30102: SparkFun driver and Maxim algorithm,
  FIFO frames, three pulse rates, temperature and shutdown); 15 chip checks for
  v1.1 (the sample rate with averaging, FIFO reads, overflow / rollover and the
  full-FIFO stall, the die temperature timing, shutdown, other sample rates, one
  counted beat per heartbeat at 40 .. 200 BPM (the pulse wave only falls from
  peak to foot; the demo detector and the Maxim peak search from 16 sampling
  phases)); 71 on the complete Proteus model (the LIB (pins, properties, both
  devices), power, the PWR / I2C / INT LEDs, the panel, red X / PANEL, OPEN
  PANEL, the pop-up pages and links, the FIFO samples decoded, the finger, the
  pulse / SpO2 in the samples read, the pulse counter of the tool on 1056
  windows (40 .. 200 BPM, 16 phases, 12 / 6 mA), the die temperature, a FIFO
  overflow and a full FIFO, the presets, the scene click, the four tools, a
  design with the v1.0 symbol); 39 with the real v1.1 demo sketch and the
  unmodified driver library on two UNOs (every v1.0 output line, the heartbeat
  LED, every Serial Monitor command, the demo estimate and the Maxim algorithm
  at 14 rates (40 .. 180 BPM) x 4 SpO2 (98 .. 85 %) and at half the LED current,
  the Timing / Step response / Pulse & SpO2 tools with the real sketch (Pulse &
  SpO2 from 8 starting phases, 5 / 5 each)); 1788 on the rendered boards and
  pop-up windows (every page fits in TEP Dark and Light, at Large text and 150 %
  DPI; every tool's hint lines and every header state fit).
v1.0 (29 Sep 2026): the v1.0 demo was run in Proteus 8.5 and confirmed working
  by the owner (the pulse and SpO2 estimates on the serial output); the v1.0
  tests (the unmodified SparkFun library and Maxim's algorithm over the
  bit-level I2C slave: FIFO frames, three pulse rates, temperature, shutdown)
  still pass with the v1.1 model.

INSTALLATION (about 2 minutes)
1. Close Proteus. Extract the WHOLE ZIP to a normal folder (e.g. Desktop).
2. Copy everything in "Proteus Library Files" (TEPMAX30102.LIB with both
   devices, TEPSERIALMON.LIB and the TEP Arduino UNO V3 library ArduinoV3TEP.LIB
   / .IDX used by the demo) to the LIBRARY folder of Proteus, for example:
     C:\Program Files (x86)\Labcenter Electronics\Proteus 8 Professional\LIBRARY
   (on some PCs: C:\ProgramData\Labcenter Electronics\Proteus 8 Professional\
   LIBRARY - use the folder that already holds Proteus's own .LIB files).
3. Copy TEPMAX30102.DLL and TEPSERIALMON.DLL from "Proteus Model Files" to the
   MODELS folder (...\Proteus 8 Professional\MODELS).
4. Updating from v1.0: replace TEPMAX30102.LIB and TEPMAX30102.DLL, and
   delete TEPMAX30102.IDX if there is one in the LIBRARY folder. A v1.0 design
   keeps its v1.0 symbol: it runs with the new model and shows the v1.0 panel
   (without the v1.1 board parts and the red X) - re-pick the part to get the
   v1.1 symbol.
5. Start Proteus. In Pick Devices (P) search "MAX30102": you get the Simple and
   the Advance device (category Sensors > Optical, as in v1.0).
The model DLL is the TEP I2C sensor family model: TEPMPU6050.DLL, TEPBMP280.DLL,
TEPMAX30102.DLL, TEPVL53L0X.DLL, TEPSHT31.DLL and TEPTCS34725.DLL are identical
files under the v1.0 names, so every v1.0 design finds its model.

RUN THE DEMO
"Proteus Simulation\MAX30102-ArduinoUnoV3.pdsprj" - keep MAX30102_Demo.hex and
the two DLLs beside the project.
  UNO 1 (ARD1): MAX30102 Simple (U1), Serial Monitor U3.
  UNO 2 (ARD2): MAX30102 Advance (U2), Serial Monitor U4.
  Both UNOs run MAX30102_Demo.hex. An LED (D1 / D2) with 220 ohm on A0 of each
  UNO: the heartbeat LED.
  1. Press Run. Both monitor windows open (9600 baud) and so does U2's pop-up.
     U3 and U4 show "TEP MAX30102 - simulated red/IR pulse waveform.", "First
     estimate appears after about four seconds." and "TEP MAX30102 Demo v1.1 -
     type HELP in the Serial Monitor"; the PPG trace starts scrolling and the
     LED on A0 flashes with every beat. Every 4 s (100 samples):
       Pulse estimate: 72.3 BPM | SpO2 estimate: 98.0 % | Die temp: 25.0 C
     (the estimate moves between about 71 and 73 BPM: the sketch counts whole
     samples in its 4 s window). The blue I2C LED flashes with every FIFO read.
  2. U1: click RUN 150 on the panel - the heart beats faster and two windows
     later U3 prints "Pulse estimate: 150.0 BPM | SpO2 estimate: 95.0 % ...".
     FINGER OFF (or click the pulse view): "No finger / low optical signal."
     once a second, the LED stays dark. LOW SPO2: about 85 %. Close the panel
     with its red X and open it with PANEL.
  3. U3 / U4 quick buttons: STATUS, LED 10 (10 mA LED current: the samples
     drop), TEMP (the die temperature now), HELP. Type LED 20 - the samples get
     too big for the demo's 16-bit buffer: "Reduce LED power for this UNO
     demo." - LED 12 brings it back. RAW ON prints every sample as IR,RED.
  4. U2 (Advance): the Sensor page shows the same inputs and what the sketch
     read; the Test page has the four tools (below).
  5. Close U2's window and open it again with OPEN PANEL on the board.
Closed a monitor window? Click OPEN MONITOR on the monitor part.

WIRING (as in the v1.0 demo)
VIN -> supply, GND -> GND, SCL -> A5, SDA -> A4; INT not connected (it is
optional: it drives the INT LED and can go to D2 for attachInterrupt).
In the sketch: MAX30105 sensor;  sensor.begin(Wire, I2C_SPEED_STANDARD);
sensor.setup(60, 4, 2, 100, 411, 4096);  Serial 9600.
Serial Monitor RXD <- Arduino D1 (TX), Serial Monitor TXD -> Arduino D0 (RX),
Serial Monitor GND -> ground. RXD2 is not needed: I2C has no serial line to
watch. The heartbeat LED + 220 ohm from A0 to GND.
Pin order in Proteus: VIN GND SCL SDA INT (v1.0, the same order as the purple
board's header).
REAL HARDWARE:
 * Supply: the GY-MAX30102 has its own 1.8 V and 3.3 V regulators - feed VIN
   with 3.3 V or 5 V from the Arduino.
 * I2C pull-ups: the board has 4.7 k pull-ups, on many purple boards to 1.8 V.
   If a 5 V UNO cannot read the sensor, add 4.7 k pull-ups from SDA / SCL to
   3.3 V (or use a level shifter); 3.3 V boards (ESP32 ...) are easier.
 * Address: 0x57, fixed. INT is active low, open drain.
 * A real finger gives a much smaller pulse (about 1 % of the light, not 10 %)
   with noise and motion artefacts; keep the finger still, shield it from
   ambient light, and use a proper algorithm (e.g. SparkFun's heartRate.h or
   Maxim's spo2_algorithm). The SpO2 of a hobby sensor is not a medical
   measurement.

THE TEST TOOLS (MAX30102 Advance, Test tab) - what they really measure
Every tool runs on the live model with your sketch: it changes the sensor's
inputs (and restores them) and watches the I2C reads your Arduino really makes -
it never talks to your Arduino. Each tool shows one "Good for:" line and one
line on how it measures.
  I2C check       Good for: checking that the MAX30102 answers and what your
                  sketch really wrote into it. The registers read live and
                  decoded (PART_ID 0x15, MODE_CONFIG, SPO2_CONFIG: sample rate,
                  pulse width, ADC bits and range, FIFO_CONFIG: averaging and
                  rollover, the LED currents, the FIFO pointers and the overflow
                  counter - marked when samples are lost or the FIFO is full -,
                  the interrupts, TEMP_CONFIG), transactions, bytes, NACKs, the
                  measured SCL clock and the last transactions decoded (repeats
                  folded). With the demo: "write MODE_CONFIG = 03" (SpO2), "read
                  FIFO_DATA -> ..." (6 bytes per sample).
  Timing          Good for: seeing how often new data exists and whether your
                  sketch reads it in time. Records for 1, 3 or 10 s every FIFO
                  sample the MAX30102 makes and every burst your sketch reads:
                  the sample period (avg / min / max), the sketch's read period,
                  the data age at each read, and the datasheet formula with your
                  registers (samples / s = sample rate / averaging; the FIFO
                  holds 32 samples). With the demo: a sample every 40.0 ms, the
                  sketch empties the FIFO every 40 ms (75 reads in 3 s).
  Step response   Good for: seeing how quickly a change reaches your sketch -
                  sample rate, FIFO and the sketch's own window together. Steps
                  the finger (off -> on), the pulse rate (72 -> 120 BPM) or the
                  die temperature (25 -> 40 C) 1, 3 or 5 times and plots every
                  reading; per step: the first reading that shows it (10 %), 90 %
                  and settled (2 %). With the demo: the finger shows in the next
                  sample (40 ms); the pulse rate (9 s per step) reaches 90 % after
                  about 3.0 - 3.4 s and settles after about 3.9 s -
                  the pulse is counted over the last 100 samples (4 s).
  Pulse & SpO2    Good for: checking your pulse and SpO2 maths on clean signals
                  before you try a real finger. Holds five set points (rest 60
                  BPM / 98 %, walk 90 / 97, jog 120 / 95, run 150 / 92, low SpO2
                  75 / 88) for 7 s each and computes the pulse (one count per
                  systolic upstroke: the IR falling through the middle,
                  re-armed only when it is back near the top, never two counts
                  closer than 0.25 s) and the SpO2 (ratio of ratios, -45.060 R^2
                  + 30.354 R + 94.845 from Maxim's reference code) from the
                  samples your sketch read in the second half - with the live IR
                  waveform. With the demo: 5 / 5 within 0.1 BPM and 0.1 %.

THE DEMO SKETCH ON THE SERIAL MONITOR (MAX30102_Demo v1.1)
  HELP                    the command list
  STATUS                  mode, samples / s, LED current, finger, the last
                          estimate
  LED mA                  red and IR LED current, 0 .. 50 mA (default 12; above
                          about 14 mA the samples overflow the demo's 16-bit
                          buffer)
  TEMP                    the die temperature now
  RAW ON | OFF            print every sample as IR,RED (25 lines / s)
Monitor quick buttons in the demo: STATUS, LED 10, TEMP, HELP.
Every line the sketch prints has at most 80 characters (it fits the Serial Monitor's
Simple interface); longer answers are split, the second line indented.

EXPECTED MONITOR OUTPUT (U3 and U4)
  TEP MAX30102 - simulated red/IR pulse waveform.
  First estimate appears after about four seconds.
  TEP MAX30102 Demo v1.1 - type HELP in the Serial Monitor
  Pulse estimate: 72.3 BPM | SpO2 estimate: 98.0 % | Die temp: 25.0 C
After RUN 150 on the panel (two windows later):
  Pulse estimate: 150.0 BPM | SpO2 estimate: 95.0 % | Die temp: 25.0 C
After FINGER OFF:
  No finger / low optical signal.
After STATUS:
  Status: SpO2 mode (red + IR), 100 Hz / 4 = 25 samples/s, LED 12.0 mA
    finger ON, last estimate 72.3 BPM 98.0 %

PROPERTIES (double-click the sensor > Edit Properties; the same on Simple and
Advance - the v1.0 properties)
  PULSE           pulse rate in BPM, 30 .. 220 (default 72)
  OXYGEN          the SpO2 the red / IR ratio stands for, 70 .. 100 % (default 98)
  FINGER          1 = a finger on the sensor, 0 = none (default 1)
  TEMPERATURE     die temperature in C, -40 .. 85 (default 25)
The panel style is chosen by the device (Simple / Advance), not by a property.
The Advance window settings (theme, text size, open at Run, size) are on its
Settings page. The demo's Serial Monitors: BAUD 9600, THEME TEPDARK, AUTOOPEN
YES, QUICK1-4 as above (see the Serial Monitor's article for all its
properties).

LINKS.INI (OPTIONAL)
The Help page cards of the Advance device open web pages. To point them
somewhere else without a new DLL, put a text file named links.ini next to
TEPMAX30102.DLL with lines KEY=URL, for example:
  ARTICLE=https://www.theengineeringprojects.com/...
Keys: WEBSITE
…