E4 Python Server: Empatica E4 Data Acquisition Tool (without Empatica Server)

This project provides a Python script to connect to an Empatica E4 wristband via Bluetooth LE, stream physiological data in real-time, and save it for analysis. It is a lightweight, command-line tool designed for researchers and developers who need direct access to raw E4 data without relying on Empatica's official software.

Warning

DISCLAIMER: This code is mostly written by Gemini 2.5 Pro with human supervision and verification of the code. However the output data has to be verified independently if it is accurate or still requires preprocessing. There is also a partly working Gadgetbridge integration at ismaelwarnants/Gadgetbridge-EmpaticaE4. With this integration it is possible to get the same data using an Android device (but for now only visible in the logs).

Features

• Direct BLE Connection: Connects directly to any nearby Empatica E4 device.
• Real-time Data Streaming: Captures BVP, GSR (EDA), Accelerometer, and Temperature data.
• Console Output: Print live sensor data directly to the terminal for monitoring.
• CSV Data Logging: Save complete session data into timestamped folders, with each sensor's data in a separate .csv file.
• Post-Session Graphing: Automatically generate and save a summary image with plots of all sensor data from a saved session.

Requirements

• Python 3.8+
• A Bluetooth-enabled computer (tested on Ubuntu 24.04 LTS)
• An Empatica E4 device

Installation with uv

This project uses uv, a fast, modern Python package installer and resolver.

1. Install uv: The recommended way to install uv is using its standalone installers.

   • On macOS and Linux:

     curl -LsSf https://astral.sh/uv/install.sh | sh

   • On Windows:

     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the Repository:

   git clone https://github.com/ismaelwarnants/e4-python-server.git
   cd e4-python-server

3. Create the Virtual Environment and Install Dependencies: uv will create a local virtual environment (.venv) and install all the packages listed in pyproject.toml.

   # This single command creates the .venv folder and installs everything.
   uv sync

4. (Ubuntu/Debian) Install Tkinter: The graphing functionality depends on the Tkinter GUI toolkit, which is a system-level package.

   sudo apt-get update
   sudo apt-get install python3-tk

Usage with uv

All commands should be run from within the project's root directory (e4-python-server).

Activating the Environment

Before running the script, you must first activate the virtual environment created by uv.

• On macOS and Linux:

  source .venv/bin/activate

• On Windows:

  .venv\Scripts\activate

You'll know the environment is active when you see (.venv) at the beginning of your terminal prompt.

Running the Script

Once the environment is activated, you can run the main.py script using the standard python command.

Note on uv run: The uv run command is designed for running tools like formatters or linters without activating the environment. For a long-running application like this one, especially one that may generate graphical plots, the most reliable method is to activate the environment first and then use the standard python command.

• To Print Data to Console:

  python main.py --print

• To Save Data to CSVs:

  python main.py --save

• To Save Data and Also Print it:

  python main.py --save --print

• To Save Data and Generate Graphs at the End:

  python main.py --save --graph

Deactivating the Environment

When you're finished, you can deactivate the virtual environment.

deactivate

Output File Structure

When using the --save option, your output directory will be populated as follows:

output/
└── 2025-10-21_21-30-00/      <-- Session Folder
    ├── ACC.csv             <-- 3-axis Accelerometer data (raw integer values)
    ├── BVP.csv             <-- Blood Volume Pulse data
    ├── EDA.csv             <-- Electrodermal Activity data (in µS)
    ├── TEMP.csv            <-- Temperature data (in °C)
    └── summary_graphs.png  <-- (Optional) Generated if --graph is used

The format of the .csv files is designed to be compatible with standard data analysis tools.