First Power-On Procedure¶

Step 1: Verify GPIO Chip¶

The Pi 5 and Pi 4 use different GPIO chip paths. The software auto-detects, but verify:

# Pi 5:
ls /dev/gpiochip4  # Should exist

# Pi 4 and earlier:
ls /dev/gpiochip0  # Should exist

# List all GPIO chips:
gpiodetect

Step 2: Start Kirin in Physical Mode¶

cd build
./kirin --physical /dev/ttyUSB0

You should see:

Kirin Autonomous Chess System v0.3
Physical Board Mode

[DISPLAY] OLED initialized on /dev/i2c-1 address 0x3C
[BUTTONS] Start=GPIO20 Stop=GPIO21 Reset=GPIO24
Connecting to gantry on /dev/ttyUSB0...
Connected to gantry on /dev/ttyUSB0
Initializing board scanner...
[SCANNER] GPIO initialized successfully (6 muxes: 4 board + 2 storage)
  Select lines: GPIO 17, 27, 22, 23
  Board muxes:  GPIO 7, 8, 9, 10
  Storage muxes: GPIO 4 (black), 11 (white)
Board scanner initialized
Homing gantry...
Homing complete

Ready. Type 'help' for commands.

If the scanner fails to initialize, check your wiring and ensure -DHAS_GPIOD was used during compilation.

Step 3: Run Sensor Diagnostics¶

kirin> diag

This reads every sensor individually and prints the result. Walk through each square with a magnet (or chess piece) and verify:

Each channel maps to the correct square
“PIECE” appears when the magnet is present, “empty” when removed
No stuck sensors (always reading PIECE or always empty)
Storage zone sensors respond correctly

Step 4: Quick Scan¶

Place all 32 pieces on the board in the starting position, then:

kirin> scan

You should see:

Sensor Scan:
    a b c d e f g h
  8 # # # # # # # # 8
  7 # # # # # # # # 7
  6 . . . . . . . . 6
  5 . . . . . . . . 5
  4 . . . . . . . . 4
  3 . . . . . . . . 3
  2 # # # # # # # # 2
  1 # # # # # # # # 1
    a b c d e f g h
  Pieces detected: 32

If any squares are wrong, re-check the wiring for that mux/channel.

Step 5: Test the Gantry¶

kirin> test

This moves the gantry to e4, then d5, engages and disengages the magnet, and returns home. Watch for:

Smooth motion with no skipped steps
Correct positioning over the square centers
Magnet picks up and releases cleanly
No collisions with pieces or board edges

Step 6: Gantry Coordinate Calibration¶

If the gantry doesn’t align with the square centers, you need to adjust either the GRBL steps/inch settings or the software constants. Place a piece on a1 and command:

kirin> home

Then type test. The gantry should move to e4 (center of the board). If it’s offset, adjust A1_CENTER_X and A1_CENTER_Y in gantry_controller.h, or recalibrate your GRBL $100/$101 steps/inch settings.

Tip

Get a1 and h8 aligned first. Since the coordinate system is linear, if these two corners are correct, all 64 squares will be correct.