Troubleshooting
Start with pieeg-server doctor. It checks SPI, GPIO, Python packages and your settings in one go.
Power and hardware
| Problem | Fix |
|---|---|
| LED on the shield is off | Check the power bank is on and charged, and the shield is fully seated on all 40 pins. |
| Pi restarts or shows a lightning bolt | The power bank can't supply enough current. Use a 5 V / 3 A bank and a short, thick USB cable. See Power bank. |
| Shield is off by one pin | Shut down, remove and re-seat it. Pin 1 of the shield must match pin 1 of the Pi. |
SPI and GPIO
| Problem | Fix |
|---|---|
/dev/spidev0.0 not found | SPI is off. Run sudo raspi-config → Interface Options → SPI → Enable, then reboot. |
Permission denied on SPI or GPIO | Add your user to the groups and log in again: sudo usermod -aG spi,gpio $USER. |
Pi 5: gpiochip4 not found | Run gpiodetect and find the chip labelled pinctrl-rp1. Use that name in the script, or pass --gpio-chip /dev/gpiochipN to PiEEG Server. |
Pi 5: RPi.GPIO error | RPi.GPIO doesn't support the Pi 5. Install the drop-in pip install rpi-lgpio. |
pip install says externally-managed-environment | Use a virtual environment, as in Software. |
pip install gpiod==1.6.3 fails | That version is not on PyPI. Use sudo apt install python3-libgpiod with 1.8_ch_Pi5.py, or pip install gpiod==1.5.4 with 1.8_ch_Pi5_gpiod_1_5_4.py. |
AttributeError in a gpiod call | The script and the installed gpiod version don't match. See the script table in Software. |
PiEEG Server
| Problem | Fix |
|---|---|
| Dashboard shows 16 channels | Start with --device pieeg8, and add it to the service too. See How to Start. |
Address already in use | The service is already running. Stop it with sudo systemctl stop pieeg-server before starting the server by hand. |
| Can't open the dashboard from a laptop | Use http://<pi-ip>:1617, and check the laptop is on the same network. |
| Service logs | journalctl -u pieeg-server -f |
Signal
| Problem | Fix |
|---|---|
| All channels noisy at once | Check the reference and bias ear clips first. Clean the earlobes and clip them firmly. |
| One channel flat or very large | That electrode isn't touching the skin. Part the hair, press it in, or add gel. |
| Strong 50/60 Hz hum | Something is connected to the mains. Unplug every charger, run the monitor from the battery, move away from power strips and laptops on chargers. |
| Big slow spikes on the front channels | Blinks and eye movements. Ask the person to keep the eyes still or closed. |
| Bursts of high-frequency noise | Jaw, face or neck muscles. Relax the face, don't talk or chew. |
| Signal jumps when someone moves | Cable movement. Keep electrode cables short and still, and sit still. |
| Alpha doesn't rise with eyes closed | Check O1 and O2 are on the back of the head and touching the scalp. Keep the eyes closed for at least 10 seconds in a quiet room. |
Is it the board or the setup? Set all channels to input-shorted mode (CHnSET = 0x01). If the signal stays within a few µV, the hardware is fine. Follow the three tests in Noise elimination.
Quick noise checklist
- Everything runs from the power bank, nothing from the mains
- Wi-Fi and Bluetooth off on the Pi during recording (unless you use the dashboard remotely)
- Wired keyboard and mouse
- Short electrode cables
- Setup on an insulating surface, away from routers, phones and chargers
- Person sitting still, feet not on a metal surface
Still stuck?
Ask on Discord (opens in a new tab), open an issue on GitHub (opens in a new tab), or email pieeg@pieeg.com.