PulseSensor Playground (version. 2.5.0)

The PulseSensor Playground library makes it easy to get heart rate data into your projects. This page covers example sketches to get you started and the library functions you'll use to build your own projects. These ready-to-use examples are included with the library—open them in Arduino IDE via File → Examples → PulseSensor Playground.

📁 Example Sketches

Start Here

Example	What It Does	Best For
GettingStartedProject	Simplest possible setup. Reads PulseSensor and outputs to Serial Plotter.	First-time users, testing your sensor
Getting_BPM_to_Monitor	Shows BPM on Serial Monitor + blinks LED on each heartbeat.	Understanding BPM detection
PulseSensor_BPM	Standard BPM measurement with full library features.	Starting point for custom projects

Web-Based Tools

No extra software needed — these run right in your Chrome browser:

Tool	What It Does	Best For
PulseSensor WebSerial	Live pulse waveform and BPM visualization in your browser via USB.	Quick testing, no Processing install needed

Board-Specific Examples

Example	Board	Features
PulseSensor_ESP32	ESP32	Basic integration
PulseSensor_XIAO_ESP32S3_BPM	Seeed XIAO ESP32-S3	BPM measurement
PulseSensor_XIAO_ESP32S3_OLED	Seeed XIAO ESP32-S3	OLED display visualization
PulseSensor_XIAO_ESP32S3_WiFi	Seeed XIAO ESP32-S3	WiFi streaming
PulseSensor_XIAO_ESP32S3_WiFi_OLED	Seeed XIAO ESP32-S3	WiFi + OLED combined
PulseSensor_UNO_R4_WiFi_LEDmatrix_Heartbeat	Arduino UNO R4 WiFi	LED matrix heartbeat animation
PulseSensor_UNO_R4_WiFi_LEDmatrix_Plotter	Arduino UNO R4 WiFi	LED matrix waveform plotter
PulseSensor_ATtiny85_Serial	ATtiny85	With serial output
PulseSensor_ATtiny85_noSerial	ATtiny85	LED-only (no serial)
PulseSensor_nRF52	nRF52 series	BLE Heart Rate Service

Output & Actuator Examples

Example	What It Does
PulseSensor_Servo_Motor	Move a servo motor based on heart rate
PulseSensor_Speaker	Audio feedback synced to heartbeat

Advanced Examples

Example	What It Does
PulseSensor_Pulse_Transit_Time	Measure Pulse Transit Time (PTT) using two sensors
TwoPulseSensors_On_OneArduino	Run two PulseSensors simultaneously
SoftwareSerialDemo	Use software serial communication
PulseSensorLibrary_V2_System_Test	Diagnostic test for library V2

Installing the Library

Open Tools → Manage Libraries (or Sketch → Include Library → Manage Libraries)
Search for "PulseSensor Playground"
Click Install (or Update if you have an older version)

Tip: Always update to the latest version to get new examples and bug fixes. 👍

⚡ Playground Library Functions

Once you're comfortable with the examples, use these functions to build your own projects. They're organized by what you're trying to do.

Setup (Required)

Every PulseSensor sketch needs these:

PulseSensorPlayground pulseSensor;  // Create the library instance

void setup() {
  pulseSensor.analogInput(A0);      // Which pin is the sensor on?
  pulseSensor.begin();              // Start reading!
}

Function	What It Does
`PulseSensorPlayground pulseSensor;`	Creates the library instance. Put this at the top of your sketch.
`analogInput(pin)`	Tell the library which analog pin your PulseSensor is connected to.
`begin()`	Start reading data. Returns `true` if successful, `false` if there's a problem.

Getting Heart Data

These are the functions you'll use most often to get pulse data into your project:

Function	Returns	Use When
`getBeatsPerMinute()`	int (BPM value)	You need the current heart rate
`getInterBeatIntervalMs()`	int (milliseconds)	You need time between beats (for HRV, timing)
`getLatestSample()`	int (raw analog value)	You want the raw waveform data
`getPulseAmplitude()`	int (peak minus trough)	You need signal strength
`getLastBeatTime()`	unsigned long (sample #)	You need precise beat timing (2ms resolution)

Detecting Heartbeats

Use these to trigger actions on each heartbeat:

void loop() {
  if (pulseSensor.sawStartOfBeat()) {
    // This runs once per heartbeat!
    digitalWrite(LED_PIN, HIGH);
  }
}

Function	Returns	Use When
`sawStartOfBeat()`	`true` once per beat	You want to trigger something on each heartbeat
`isInsideBeat()`	`true` while signal is above threshold	You want to know if we're currently in a beat

Built-in LED Feedback

The library can automatically blink or fade an LED with your pulse:

Function	What It Does
`blinkOnPulse(pin)`	Blinks the specified pin on each heartbeat
`fadeOnPulse(pin)`	Fades the specified pin with your pulse (pin must support PWM)

Serial Output

For visualizing data in Arduino Serial Plotter or our Processing Visualizer:

Function	What It Does
`setSerial(Serial)`	Enable library serial output
`setOutputType(OUTPUT_TYPE)`	Set format: `SERIAL_PLOTTER` (default) or `PROCESSING_VISUALIZER`
`outputSample()`	Print the latest sample (format depends on outputType)
`outputBeat()`	Print BPM and IBI (Processing Visualizer format only)
`outputToSerial(char, int)`	Print data with prefix character (for Processing: 'S'=signal, 'B'=BPM, 'Q'=IBI)

Fine-Tuning

Function	What It Does	Default
`setThreshold(value)`	Set the signal level that triggers beat detection. Raise it to combat noise.	550

Pause & Resume

Useful when you need to do other time-sensitive tasks:

Function	What It Does
`pause()`	Stop reading PulseSensor data. Returns `true` when successful.
`resume()`	Start reading again after pause(). Returns `true` when successful.
`isPaused()`	Returns `true` if paused, `false` if running.

🔧 Advanced Topics

Sample Timing: Hardware vs Software

The PulseSensor needs to be read 500 times per second (every 2ms) for accurate BPM detection. The library handles this automatically using a hardware timer when your board supports it.

On boards without hardware timer support, the library falls back to software timing. You'll see a compiler warning when this happens. In software timing mode, you must call sawNewSample() frequently in your loop:

void loop() {
  if (pulseSensor.sawNewSample()) {
    // Process the new sample
  }
  // Don't add delays or slow code here!
}

Disabling Library Serial Management

By default, the library manages Serial output. If you need full control of the Serial port, edit PulseSensorPlayground.h and change:

// Change this:
#define USE_SERIAL true

// To this:
#define USE_SERIAL false

Then remove setSerial() and setOutputType() from your sketch. Access data directly with getBeatsPerMinute(), getLatestSample(), etc.

Other Preprocessor Options

In PulseSensorPlayground.h, you can also enable:

PULSE_SENSOR_TIMING_ANALYSIS — Debug timing accuracy
PULSE_SENSOR_MEMORY_USAGE — Monitor memory consumption

Questions? Check out our FAQ or contact support.