Configuration
CLI Reference
pieeg-server [OPTIONS] [COMMAND]Commands
| Command | Description |
|---|---|
doctor | Diagnose hardware, software, and configuration |
record FILE | Record EEG to CSV (standalone, no server) |
monitor | Live terminal display (standalone, no server) |
Server Options
| Flag | Default | Description |
|---|---|---|
--device DEVICE | pieeg16 | pieeg8, pieeg16, or ironbci8 |
--host HOST | 0.0.0.0 | Bind address |
--port PORT | 1616 | WebSocket port |
--dashboard-port PORT | 1617 | Dashboard HTTP port |
--no-dashboard | — | Disable web dashboard |
--auth | — | Enable 6-digit access code |
--gpio-chip PATH | /dev/gpiochip4 | GPIO chip device |
--profile NAME | auto | Raspberry Pi hardware profile: auto, pi4, pi5 |
Hardware Profiles
Different Raspberry Pi models expose SPI/GPIO slightly differently. The
--profile flag selects platform-specific tunables (SPI clock, whether the
script manages the chip-select GPIO line directly).
| Profile | SPI clock | Notes |
|---|---|---|
pi4 | 4 MHz | Pi 2 / 3 / 4 / 400 — script toggles GPIO19 around chip-2 transactions |
pi5 | 2 MHz | Pi 5 — kernel SPI driver owns the CE line, GPIO19 is left to the driver in 8-channel mode |
auto (default) | — | Read /proc/device-tree/model (then compatible); fall back to pi4 on any unknown / non-Pi system so existing setups behave exactly as before |
In 16-channel mode the second ADS1299's CS is wired to GPIO19 on the shield, so the chip-select pin is always managed regardless of profile.
BLE Options (IronBCI)
| Flag | Default | Description |
|---|---|---|
--ble-name NAME | EAREEG | BLE advertised device name |
--ble-address ADDR | — | BLE MAC address — skip scan, connect directly |
BLE options only apply when --device ironbci8 is selected. Install the ironbci extra for Bluetooth support: pip install pieeg-server[ironbci].
Filter Options
| Flag | Default | Description |
|---|---|---|
--filter | — | Enable 1–40 Hz bandpass filter |
--lowcut HZ | 1.0 | Filter low cutoff |
--highcut HZ | 40.0 | Filter high cutoff |
Recording Options
| Flag | Default | Description |
|---|---|---|
--record FILE | — | Record to CSV while streaming |
--record-duration SEC | — | Stop recording after N seconds |
Integration Options
| Flag | Default | Description |
|---|---|---|
--monitor | — | Show terminal monitor alongside server |
--mock | — | Synthetic EEG (no hardware needed) |
--no-webhooks | — | Disable webhooks |
--osc | — | Enable VRChat OSC bridge |
--osc-host HOST | 127.0.0.1 | VRChat receiver |
--osc-port PORT | 9000 | VRChat OSC port |
--osc-mode MODE | both | chatbox, parameters, or both |
--osc-interval SEC | 0.25 | OSC update rate |
--lsl | — | Enable Lab Streaming Layer outlet |
--lsl-name NAME | PiEEG | LSL stream name |
-v, --verbose | — | Debug logging |
Systemd Service
The install script creates a systemd service that auto-starts on boot:
sudo systemctl status pieeg-server
sudo systemctl restart pieeg-server
journalctl -u pieeg-server -fThe systemd service runs with whatever flags were set during installation. Edit /etc/systemd/system/pieeg-server.service to change runtime options.
Environment
PiEEG Server has minimal dependencies:
| Package | Version | Purpose |
|---|---|---|
websockets | ≥12.0 | WebSocket streaming |
scipy | ≥1.10 | Butterworth filter |
rich | ≥13.0 | Terminal UI / monitor |
bleak | ≥0.21 | Bluetooth LE (IronBCI only, optional) |
Dashboard Environment Variables
These are build-time variables for the Vite dashboard (set them when building or deploying the dashboard separately, e.g. on Vercel).
| Variable | Default | Description |
|---|---|---|
VITE_SERVER_URL | (unset) | When set, the Session Lobby pre-fills this URL instead of auto-detecting from localhost. Also marks the session as demo mode (DEMO badge, auth bypassed). For Vercel: set to https://pieeg-server--mock.fly.dev. |
VITE_SERVER_URL only affects the initial value shown in the lobby. The user can always edit the URL before clicking Connect — there is no hidden override.