Troubleshooting¶

Sensor Issues¶

Symptom	Solution
All sensors read empty	Check mux power (3.3V), verify EN pin is grounded, check select line wiring
One mux reads all empty	Check that mux’s SIG output wire to the Pi GPIO pin
One mux reads all full	That mux SIG line is being read LOW for every channel. Check for a short to ground, wrong SIG/common pin, EN/inhibit wiring, mux power/ground, and whether the listed GPIO pin matches the physical wire.
Random noise / flickering	Increase `DEBOUNCE_SCANS` (default 3) or `DEBOUNCE_DELAY_MS` (default 50ms) in `board_scanner.h`
Sensors read wrong squares	Your channel-to-square wiring doesn’t match the expected layout. Run `diag` and compare against the mapping table. Either re-wire or modify `toSquareIndex()`
Sensors trigger from gantry magnet	The gantry electromagnet is interfering with nearby hall sensors. Add shielding around the gantry magnet, increase debounce, or only scan when the gantry is idle
Scanner init fails	Verify `libgpiod-dev` is installed and the build used `-DHAS_GPIOD`. Check that the GPIO chip exists (`/dev/gpiochip4` on Pi 5, `/dev/gpiochip0` on Pi 4)

Common sensor issues

Gantry Issues¶

Symptom	Solution
“Failed to connect to gantry”	Check USB cable, verify serial port path (`ls /dev/ttyUSB*`), ensure user is in `dialout` group
Homing fails	Verify limit switches are connected and GRBL setting $22=1 (homing enabled)
Gantry moves to wrong position	Recalibrate GRBL steps/inch ($100, $101) or adjust `A1_CENTER_X`/`A1_CENTER_Y` in the software
Magnet doesn’t engage	Check GRBL coolant output wiring, test with `M8`/`M9` in a serial console
Pieces dragged/knocked over	Reduce `FEED_RATE` (default 1000 in/min), verify magnet strength is appropriate
GRBL alarm triggered	The software auto-resets on alarm. Check error description in terminal output. Common cause: soft limits exceeded (piece near board edge)

Common gantry issues

Move Detection Issues¶

Symptom	Solution
System doesn’t detect my move	Verify the sensor under the destination square works (`diag`). Check that you placed the captured piece in storage (required for capture detection).
System hangs waiting for move	If it’s a rare ambiguous capture (queen can capture two different pieces from the same square), fall back to typed input: press Ctrl+C and use `move` command.
“Board state not recognized” alert	You’ve left the board in a state that doesn’t correspond to any legal move for 10+ seconds. Fix piece placement.
Board mismatch after engine move	The gantry dropped a piece. The system will show which squares are wrong. Fix the pieces manually and type `continue`.

Common move detection issues