Empatica E4 wristband — read your own data

Read raw sensor data from an Empatica E4 wristband you own — accelerometer, skin temperature, electrodermal activity (EDA/GSR), and the raw photoplethysmogram. No cloud, no account, no firmware writes. Works offline on Linux, macOS, and Windows.

Use it in 30 seconds

1. Put the wristband on your wrist.

2. Short-press the wristband button until the LED turns blue.

3. Open a terminal in this folder and type:

   • Linux / macOS:   ./START
   • Windows:   double-click START.bat, or START.bat in cmd / .\START.bat in PowerShell

That's it. It records for 5 minutes, then saves your data as CSV files you can open in Excel / LibreOffice / pandas / R.

Requirements

• Python 3.11 or newer (the launcher will refuse to run otherwise).
• Bluetooth turned on:
  • Linux: BlueZ (sudo apt install bluez on Debian/Ubuntu).
  • macOS: Bluetooth in System Settings.
  • Windows 10+: Bluetooth in Settings → Devices → Bluetooth.

First run creates a Python virtual environment under _engine/.venv/ and installs bleak + pyusb (~40 MB, ~30 seconds). Every run after that just starts the program.

What you'll find in this folder

START          → Linux / macOS launcher  (./START)
START.bat      → Windows launcher        (START.bat or double-click)
START.py       → the cross-platform launcher both of the above call
README.md      → this file

recordings/    → all your wristband data, one folder per session:
                   recordings/2026-05-15_14-09-15/
                     ├── raw.sqlite     the truth source (BLE packets)
                     ├── raw.jsonl      same data, JSON-lines
                     ├── session.log    what happened during recording
                     └── csv/           Excel-friendly files (open these)

help/          → guides if you get stuck
_engine/       → program code (ignore unless you're coding)
_trash/        → debloated stuff. delete any time:  rm -rf _trash/
LICENSE        → MIT

More buttons

./START          → record 5 minutes (the normal thing)
./START find     → just find your wristband, don't record
./START check    → check Bluetooth and setup
./START report   → re-print the summary of your latest recording
./START make-csv → re-make the CSV files for your latest recording
./START --help   → all options

(Replace ./START with START.bat on Windows.)

You can target a specific recording:

./START report   --db recordings/SOME_FOLDER/raw.sqlite
./START make-csv --db recordings/SOME_FOLDER/raw.sqlite

The technical aliases still work: scan = find, doctor = check, stream = record, decode = make-csv, summary = report.

What's in a recording's csv/ folder

File	What it is
acc.csv	3-axis accelerometer. 32 Hz. x_g, y_g, z_g are in g.
temp.csv	Skin temperature in °C. 4 Hz.
gsr.csv	Electrodermal activity (skin conductance, raw counts). 4 Hz.
ppg.csv	Optical pulse sensor, raw 12-bit counts. 64 Hz. Packing is tentative — packet_hex preserved for re-decode.
bat.csv	Battery readings (very few per session).
unknown.csv	Anything we couldn't label yet.

Full column reference: help/02_what_is_in_your_data.md.

Privacy

Your recordings contain biometric data. The recordings/ folder stays on your laptop only — this program never uploads anything. The .gitignore excludes recordings/ from any git commit.

If something goes wrong

./START check        (or START.bat check on Windows)

This tests Bluetooth and the program setup and tells you what's broken. If it can't find the wristband, button-press it again so the LED is blue.

How this works under the hood

help/03_how_we_decoded_the_wristband.md documents the reverse engineering of the E4's GATT services, the streaming bootstrap sequence (recovered from the official Empatica Android SDK), and the per-channel packet layouts we know so far. All of it is verified against a wrist-worn capture, with citations.

License

MIT — see LICENSE. The code in this repo is original work.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Empatica Srl. "Empatica" and "E4" are trademarks of their respective owners and are used here only in a nominative sense to refer factually to the wristband hardware this tool reads. This project does not contact, depend on, or interact with any Empatica server.

The reverse engineering of the device's public BLE GATT interface falls under interoperability provisions of US copyright law (DMCA §1201(f)) and EU law (Software Directive 2009/24/EC Art. 6). See _engine/e4local/references/README.md for citations to the public materials we used as references; we do not redistribute any Empatica binaries.