PiEEG Server: An Open-Source Real-Time EEG Streaming Platform for AI-Driven Brain-Computer Interfaces

1. Introduction

Electroencephalography remains the most widely accessible non-invasive modality for measuring human brain activity in real time. The sub-millisecond temporal resolution of EEG makes it uniquely suited for event-related potential (ERP) studies, oscillatory band-power analysis, and closed-loop neurofeedback—all of which are essential primitives in modern AI-driven BCI research. Yet despite a rich ecosystem of commercial headsets, the gap between raw hardware and production-ready AI pipelines remains wide: proprietary SDKs impose platform lock-in, data formats vary, and streaming middleware is either unavailable or expensive.

PiEEG shields address the hardware cost barrier by combining a Texas Instruments ADS1299 analog front-end with the ubiquitous Raspberry Pi single-board computer. The ADS1299 is a purpose-built, 24-bit, simultaneous-sampling ADC used in many clinical EEG amplifiers [1]. The PiEEG-16 variant chains two such chips for 16 channels; the IronBCI-32 extends coverage to 32 channels over a serial interface; and the IronBCI wireless headsets provide 8-channel acquisition over Bluetooth Low Energy, enabling completely untethered recording (Figure 1).

PiEEG Server is the software counterpart of this hardware family. It transforms PiEEG devices into a turnkey EEG streaming node—and, with the --mock flag, allows any developer to build and test AI EEG applications without any physical hardware at all. This paper describes the architecture, capabilities, and AI integration opportunities of PiEEG Server, and argues that its combination of zero-config streaming, built-in signal processing, broad ecosystem compatibility, and open licensing makes it the optimal middleware layer for EEG-based AI research and development in 2026.

2. Supported Hardware

PiEEG Server natively supports PiEEG devices [2], each leveraging the ADS1299 analog front-end (Table 1). All devices deliver data at 250/500 Hz—the standard clinical EEG acquisition rate that satisfies the Nyquist criterion for all five canonical EEG bands (Delta 0.5–4 Hz, Theta 4–8 Hz, Alpha 8–13 Hz, Beta 13–30 Hz, Gamma 30–100 Hz). The 24-bit ADC resolution translates to sub-microvolt sensitivity, sufficient for detecting single-trial ERPs and cortical oscillations.

3. System Architecture

PiEEG Server is structured as a layered publish-subscribe pipeline implemented in Python 3.10+ with asyncio. The overall data flow moves from hardware through signal conditioning into a fan-out distribution layer that feeds multiple concurrent subscribers, as described in the subsections below.

• Acquisition Layer

The hardware.py module initialises the SPI bus and configures the ADS1299 registers; ironbci.py performs BLE scanning, GATT notification subscription, and EEG packet parsing for wireless devices. Both converge on acquisition.py, which runs a background thread at 250 Hz, reads raw 24-bit ADC codes, converts them to microvolts (µV), and publishes each sample to an internal pub/sub queue.

• b. Signal Processing Layer

Two signal conditioning stages operate on every sample before downstream consumers receive it:

• Spike rejection (Special developed Filter): A two-layer spike rejection approach combining a hardware delta-threshold filter (for SPI glitches) with a per-channel Hampel median-absolute-deviation (MAD) filter applicable to all device types. The Hampel filter is configurable at runtime via WebSocket (window size, n_sigma).
• Butterworth bandpass: A cascaded second-order section (SOS) IIR Butterworth bandpass filter implemented via scipy, with per-channel state memory and configurable cut-off frequencies (default 1–40 Hz). The optional pieeg-core Rust accelerator raises throughput of this hot path from ~992 samples/s to over 1,000,000 samples/s—a ~1057× speedup enabling server-side filtering on 16-channel rigs.

c.

Distribution Layer

Processed samples are broadcast simultaneously to five independent subscriber modules via asyncio queues:

• server.py — WebSocket broadcast on ws://0.0.0.0:1616
• recorder.py — Timestamped CSV writer with optional duration limit and session annotations
• monitor.py — Rich terminal TUI with per-channel sparklines and µV readout
• osc_vrchat.py — VRChat OSC bridge over UDP
• lsl.py — Lab Streaming Layer outlet (float32, 250 Hz)

d.

Dashboard Layer

A React 19 / Vite 6 single-page application served on port 1617 provides browser-based interaction. Figure 2 shows the main dashboard view featuring 16-channel live waveforms, real-time FFT power spectrum with band annotations, topographic scalp map, and a live filter-response curve. The dashboard also provides an ADS1299 register editor, webhook rule management, recording controls, and a self-update mechanism.

Figure 3 illustrates the extended analysis view including the time-frequency spectrogram, per-channel signal statistics, and the Mental State panel displaying real-time focus and relaxation scores derived from the built-in cognitive-state detectors.

4. Websocket API and Data Format

The WebSocket interface is the primary integration point for AI applications. It requires no SDK—any language with a WebSocket library can connect to ws://<host>:1616 and receive plain UTF-8 JSON frames.

• EEG Frame

Each sample is broadcast as a compact JSON object at 250 Hz:

{“t”: 1711234567.123, “n”: 42, “channels”: [12.34, -5.67, 8.90, ...]}

where t is a Unix timestamp (seconds), n is a monotonic sample counter for gap detection, and channels is an array of floating-point values in µV (8, 16, or 32 elements depending on device).

• b. Commands

Clients send JSON commands to configure the server in real time. Key commands include:

• set_filter (enable/disable and tune the bandpass filter)
• start_record
• stop_record, lsl_start
• lsl_stop, osc_start
• osc_configure, webhook_create
• webhook_update
• webhook_delete
• hampel_config, reg_write (ADS1299 register programming),
• noise_test.

All commands return acknowledgement messages with the updated server state.

• c. Authentication

When launched with --auth, the server issues a 6-digit code for session-based authentication. WebSocket connections require a short-lived HMAC-validated token obtained via a REST endpoint, protecting the data stream from unauthorised access on shared networks. Rate limiting and HttpOnly cookies are applied automatically.

5. AI and BCI Capabilities

PiEEG Server is purpose-built to serve as the data acquisition front-end for AI and BCI applications. This section enumerates the capabilities that make it particularly well-suited for this role.

• Real-Time Cognitive State Detectors

The browser-side React SDK ships four production-ready EEG processing hooks operating on ref-based state to avoid React re-renders, enabling high-frequency polling in animation loops (Table 2). All four detectors include calibration support, configurable update rates, and exponential smoothing, integrating directly into real-time game loops, Three.js scenes, and WebXR experiences.

• b. Single-Channel Deep Inspection

For debugging and per-electrode validation, the dashboard provides a dedicated single-channel analysis panel (Figure 4). The panel displays a 256-point Hanning-windowed FFT power spectrum, a relative band-power distribution bar chart, an amplitude histogram, and a real-time signal metrics table (RMS, peak-to-peak, mean, zero-crossing rate) alongside the raw time-domain waveform.

• c. Experiences Gallery and Neurofeedback Applications

PiEEG Server ships an experiences gallery—a curated set of interactive BCI demonstrations accessible directly from the dashboard (Figure 5). Each experience is a self-contained neurofeedback or BCI application built on the detector hooks described above. The gallery spans VR/3D visualisation, gaze estimation, neural sonification, focus-driven games, and webhook-powered automation.

• d. Lab Streaming Layer Integration

LSL has become the de facto standard for synchronised multi-modal data acquisition in neuroscience and BCI research. PiEEG Server exposes a native LSL outlet (name: PiEEG, type: EEG, float32, 250 Hz) discoverable by the full LSL ecosystem: OpenViBE [3], MNE-Python [4], BCI2000, NeuroPype, and LabRecorder. This single integration unlocks the entire scientific EEG toolchain for PiEEG data, including MNE’s extensive preprocessing, source localisation, and machine learning pipelines.

• e. Jupyter Notebook Integration

For exploratory AI development, PiEEG Server connects directly to Jupyter notebooks via WebSocket. Researchers can stream live EEG data into pandas DataFrames, NumPy arrays, or MNE RawArray objects, apply custom signal processing, train classifiers, and close the loop back to the device—all from a single notebook without any additional driver or SDK installation.

• f. Webhook Automation and Event-Driven AI

The webhook engine allows researchers and developers to define event rules based on band-power thresholds (e.g., fire when alpha power exceeds 20 µV²/Hz) and route HTTP POST requests to any endpoint with configurable headers, methods, and per-rule cooldowns. Native presets for IFTTT and Zapier mean that EEG events can trigger actions in thousands of connected services—smart home devices, notification systems, cloud AI workflows—without any custom server code.

• g. VRChat and Extended Reality

The VRChat [5] OSC bridge transmits rolling-normalised band powers as avatar parameters over UDP. This enables direct neural control of avatar expressions, environment shaders, and interactive elements in VRChat worlds, opening a research pathway for embodied BCI in social virtual reality that was previously inaccessible with consumer-grade hardware.

• h. Mock Mode for Algorithm Development

The --mock flag generates synthetic EEG with realistic alpha rhythm bursts, broadband noise, drift, and ocular blink artefacts. This allows AI researchers to develop, debug, and validate data pipelines, classifiers, and BCI interfaces on any machine without purchasing hardware, then deploy to physical devices with zero code changes.

• e. Built-In Documentation

PiEEG Server embeds a full copy of its documentation directly within the dashboard interface (Figure 6), enabling offline reference without leaving the application. The documentation panel covers installation, API reference, integration guides, and troubleshooting—reducing the context-switching overhead for researchers working in the field.

Figure 7. Built-in documentation panel accessible directly from the PiEEG Server dashboard, providing offline access to the full API reference, integration guides, and getting-started documentation without requiring an external browser connection.

Figure 7. Built-in documentation panel accessible directly from the PiEEG Server dashboard, providing offline access to the full API reference, integration guides, and getting-started documentation without requiring an external browser connection.

6. Signal Processing Performance

A critical design requirement for real-time BCI is that the DSP pipeline must keep pace with acquisition. At 250 Hz with 16 channels, the server must process 4,000 samples per second. Table 3 reports benchmark results for the pure-Python and pieeg-core Rust implementations on a Windows host (5 s @ 250 Hz × 16 ch):

The pure-Python MultichannelFilter throughput of 992 samples/s falls below the 4,000 samples/s real-time requirement for 16-channel server-side filtering. Installation of pieeg-core (pip install ‘pieeg-server[fast]’) resolves this transparently via a Rust extension wheel with no configuration changes required. The server auto-detects the active engine at startup and reports it in the WebSocket connected message and pieeg-server doctor output. For 8-channel rigs or deployments where server-side filtering is disabled, the pure-Python implementation is fully sufficient.

7. Research and Development Workflow

For users application need just launch pieeg server.

For researchers: typical AI/BCI research workflow with PiEEG Server proceeds in five stages:

Step 1 — Install and launch:

           

Step 2 — Stream to Jupyter for exploratory analysis:

           

Step 3 — Label and record training data:

Use the dashboard or CLI to start timestamped CSV recordings with session annotation markers, then load them directly into MNE or scikit-learn for feature extraction and classifier training.

Step 4 — Close the loop:

Trigger webhooks or OSC messages based on classifier predictions, driving external actuators, applications, or virtual environments in real time.

Step 5 — Collaborate and archive:

Export LSL streams for multi-site recordings synchronised with stimuli, eyetracking, EMG, or other physiological channels via LabRecorder, producing interoperable XDF archives.

8. Security and Deployment Considerations

For laboratory deployments on isolated networks, the default unauthenticated mode is sufficient. For public-facing or shared-network deployments, the --auth flag enables session-based authentication with a 6-digit code, HMAC timing-safe token verification, rate limiting, and HttpOnly cookies.

For cloud-hosted mock-mode demonstrations, a Dockerfile and Fly.io configuration are included in the repository, enabling zero-infrastructure live demos accessible from any browser. The platform includes a self-diagnostic command (pieeg-server doctor) that checks Raspberry Pi model compatibility, SPI and GPIO availability, port conflicts, dependency versions, and systemd service status—reducing deployment friction for non-expert users.

A systemd service unit is generated automatically during installation, enabling pieeg-server to start at boot and be managed with standard systemctl commands, making it suitable for always-on laboratory recording nodes. The zero-dependency GPIO implementation uses direct Linux chardev v1 ioctl calls—a stable ABI since Linux 4.8—eliminating fragile third-party GPIO library dependencies.

9. Discussion

The democratisation of EEG hardware through devices like PiEEG and IronBCI creates a significant opportunity for AI-driven neuroscience outside well-funded laboratory settings. However, hardware accessibility alone is insufficient; researchers and developers also need accessible, well-documented software middleware that handles the full stack from acquisition to AI integration.

PiEEG Server addresses this gap by providing a production-ready platform that scales from rapid prototyping (mock mode, Jupyter integration) to production BCI deployments (systemd service, authentication, LSL). The optional pieeg-core Rust accelerator ensures that computational constraints do not become a bottleneck even on resource-constrained single-board computers.

The webhook and IFTTT/Zapier integrations enable a new class of neuroadaptive applications that require no custom server infrastructure. A developer can define an alpha-band relaxation threshold rule and trigger a smart home scene change, a Spotify playlist switch, or a Slack notification entirely from the dashboard—in minutes. The experiences gallery (Figure 5) demonstrates the breadth of application domains already accessible with the current platform, from embodied VR control to adaptive podcast playback.

The VRChat OSC bridge represents a particularly novel contribution: it opens a direct pathway from sub-

$100 EEG hardware to social virtual reality, enabling research on embodied neural interfaces at a scale and cost previously inaccessible to the research community.

Future development directions include multi-device synchronised acquisition, on-device model inference via TensorFlow Lite or ONNX Runtime, adaptive artefact rejection using independent component analysis (ICA), and deeper integration with cloud AI platforms for real-time neural decoding at scale.

10. Conclusions

PiEEG Server is a comprehensive, open-source EEG streaming platform that addresses the full pipeline from ADS1299-based hardware acquisition to AI and BCI application integration. Its language-agnostic WebSocket API with plain JSON frames enables connection from Python, JavaScript, Julia, MATLAB, or any other language in a few lines of code. Its built-in cognitive state detectors, single-channel deep inspection, experiences gallery, LSL compatibility, webhook automation, VRChat OSC bridge, embedded documentation, and native Rust DSP accelerator collectively make it the most feature-complete open-source EEG middleware available for the PiEEG hardware family.

By lowering the barrier to entry for EEG-based AI research—through zero-config streaming, mock-mode hardware simulation, pip-based installation, and extensive embedded documentation—PiEEG Server enables researchers, students, makers, and entrepreneurs to focus on neuroscience and AI innovation rather than infrastructure engineering.

Contributions, issue reports, and feature requests are welcomed at https://github.com/pieeg-club/PiEEG-server.