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

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)

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