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)

doctor

pieeg-server doctor          # full diagnostics with formatted output
pieeg-server doctor --quiet  # only return exit code (0=ok, 1=warnings, 2=errors)

record

pieeg-server record session.csv                              # record until Ctrl-C
pieeg-server record session.csv --duration 300               # 5 minutes
pieeg-server record session.csv --device pieeg8 --mock       # 8-ch synthetic
pieeg-server record session.csv --device ironbci8 --ble-name MyBoard
pieeg-server record session.csv --device ironbci32 --serial-port /dev/ttyACM0

Supported flags: --device, --duration, --mock, --gpio-chip, --profile, --ble-name, --ble-address, --serial-port, --verbose

monitor

pieeg-server monitor                    # live terminal display
pieeg-server monitor --mock             # synthetic data
pieeg-server monitor --device ironbci8  # IronBCI via BLE

Supported flags: --device, --mock, --gpio-chip, --profile, --ble-name, --ble-address, --serial-port, --verbose

Server Options

Flag	Default	Description
`--device DEVICE`	`pieeg16`	`pieeg8`, `pieeg16`, `ironbci8`, or `ironbci32`
`--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].

Serial Options (IronBCI-32)

Flag	Default	Description
`--serial-port PORT`	—	Serial device (e.g. `COM3`, `/dev/ttyACM0`)

--serial-port is required when --device ironbci32 is selected. IronBCI-32 uses USB serial (921600 baud, FreeEEG wire protocol) for 32-channel streaming at ~500 SPS.

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
`--osc-regions-setup`	—	Interactive wizard for OSC/LSL channel regions
`--lsl`	—	Enable Lab Streaming Layer outlet
`--lsl-name NAME`	`PiEEG`	LSL stream name
`-v, --verbose`	—	Debug logging

Use --osc-regions-setup to define custom channel groups (e.g., EEG vs EOG). The wizard creates ~/.pieeg/lsl_groups.json that both OSC and LSL integrations can use for region-specific streaming.

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 -f

The 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.

Quick Start Uninstall & Purge