Troubleshooting

Self-Diagnostics

Run the built-in doctor command to check everything:

pieeg-server doctor

This checks:

• Raspberry Pi model and revision
• SPI enabled and accessible
• GPIO chip available
• Required Python packages installed
• DSP engine (native pieeg-core vs. pure-Python fallback)
• Ports 1616/1617 available
• Systemd service status

Common Issues

SPI not enabled

Error: SPI device not found

Fix: Enable SPI and reboot:

sudo raspi-config nonint do_spi 0
sudo reboot

Port already in use

Error: Address already in use (port 1616)

Fix: Stop the existing instance:

sudo systemctl stop pieeg-server
# or
kill $(lsof -t -i:1616)

No data from hardware

Symptoms: Dashboard shows flat lines or no frames.

PiEEG (SPI)

1. Shield properly seated on GPIO header
2. Electrodes connected
3. Correct device flag: --device pieeg8 or --device pieeg16
4. Run pieeg-server doctor for hardware diagnostics
5. On Pi 5, make sure --gpio-chip /dev/gpiochip4 is used (the default). On Pi 4 / 3 / 2, use --gpio-chip /dev/gpiochip0.

Pi 4 vs Pi 5 hardware profile

The server auto-detects the Raspberry Pi model and applies a matching hardware profile. If auto-detection picks the wrong one (e.g. on a custom image), force it explicitly:

pieeg-server --profile pi5    # Raspberry Pi 5
pieeg-server --profile pi4    # Pi 2 / 3 / 4 / 400

Symptoms of a profile mismatch:

• GPIO busy / Device or resource busy on Pi 5 in 8-channel mode — the kernel SPI driver already owns the CE line. Use --profile pi5 (or auto).
• Garbled samples / dropped frames on Pi 4 — the Pi 5 profile uses a slower 2 MHz SPI clock; force --profile pi4 to restore 4 MHz.

IronBCI / EAREEG (Bluetooth LE)

1. Bluetooth adapter enabled: bluetoothctl show should list a controller
2. Device powered on and in range
3. Correct flags: --device ironbci8 (optionally --ble-name or --ble-address)
4. BLE extra installed: pip install pieeg-server[ironbci]
5. If scan times out, try passing the MAC address directly with --ble-address
6. On Linux, ensure your user has permissions for Bluetooth (or run with sudo)

IronBCI-32 (USB serial)

1. Device enumerated by the OS: ls /dev/ttyACM* (Linux/macOS) or check Device Manager → Ports (Windows)
2. Correct flags: --device ironbci32 --serial-port /dev/ttyACM0 (or COM3 on Windows)
3. Serial extra installed: pip install pieeg-server[ironbci32]
4. On Linux, add your user to the dialout group for serial access: sudo usermod -aG dialout $USER (then log out/in)
5. If frames are dropped, check the dropped_frames counter — usually indicates a USB cable or hub issue at 921600 baud

Dashboard not loading

Check:

• Server is running: sudo systemctl status pieeg-server
• Correct URL: http://raspberrypi.local:1617
• Try IP directly: http://<pi-ip>:1617
• Firewall not blocking ports 1616/1617

WebSocket connection failed

Check:

• WebSocket port: ws://<host>:1616
• If using --auth, include the token: ?token=<ws-token>
• Browser console for connection errors
• CORS is not an issue (WebSocket doesn't enforce CORS)

Mock mode