Phase 2 + 3: full chess rules + UX polish for RP2040 (with self-tests)

[semichcsc-byte]

Summary

Substantial gameplay upgrade for the official Concept-Bytes firmware on Arduino Nano RP2040 Connect: full chess rules (check, checkmate, castling, en-passant, draws, promotion choice), sensor debounce, AP shutdown, and a 10-test on-boot validation suite. +1107 / -282 lines, 9 files, 10/10 self-tests passing.

Builds on top of:

• Fix bot mode hang on WiFi connection (closes #5) #9 — WiFi AP→STA fix (required for AI mode)
• RP2040 quality pass: 5 correctness/robustness fixes #10 — 5 quality fixes (Stockfish parser, depth bug, etc.)

This PR depends on those landing first (or being squashed in together).

What changes for the user

Before	After
Pinned pieces could move and expose own king	Legal-move filter rejects them
No check / checkmate / stalemate display	King blinks red on check; full-board win/draw animations
No castling	Castling works (kingside + queenside, FIDE legal)
No en-passant	EP target highlighted pink, capture removes the right pawn
Pawn always auto-promoted to queen	Human vs Human: 4 LEDs let you pick Q/R/B/N. Bot mode: still auto-Q (Stockfish 'e7e8q' parsing TBD)
50-move / insufficient material never end the game	Auto-detected, draw animation plays
Sensor flicker when sliding pieces	Debounce: 3 consecutive scans required to flip state
AP OpenChessBoard stays up forever	Shut down when entering Chess Moves / Sensor Test (~100 mA saved)
No way to know if firmware is broken	10 self-tests at boot, red flash on failure

Engine architecture

New ChessEngine API, with board[] mutation centralised in applyMove so castling / EP / state updates can never be missed:

struct GameState { castling rights; enPassant{Row,Col}; halfMoveClock; lastMove; };

void  ChessEngine::getLegalMoves(board, state, row, col, &count, moves);
bool  ChessEngine::isLegalMove(board, state, fromR, fromC, toR, toC);
bool  ChessEngine::isInCheck(board, color);
bool  ChessEngine::isSquareAttacked(board, row, col, byColor);
bool  ChessEngine::hasAnyLegalMove(board, state, color);
GameResult ChessEngine::getGameResult(board, state, colorToMove);
void  ChessEngine::applyMove(board, state, fromR, fromC, toR, toC, promoteTo=0);
int   ChessEngine::runSelfTests();

getPossibleMoves is kept as the pseudo-legal generator (no own-check filter); it's still used internally by isSquareAttacked and getLegalMoves.

Self-tests (run at every boot)

=== ChessEngine self-tests ===
PASS T1: e2 pawn has 2 legal moves
PASS T2: b1 knight has 2 legal moves
PASS T3: no check at start
PASS T4: Fool's Mate detected
PASS T5: pinned rook stayed on file
PASS T6: both castlings legal
PASS T7: no castling in check
PASS T8: en-passant offered
PASS T9: K vs K is draw
PASS T10: kingside castle layout correct
=== Self-tests complete: 10/10 passed ===

These caught one real bug during development (a wrong test position that turned out to be a wrong test position rather than an engine bug — but the same pattern would catch a real regression).

Sensor debounce

Each readSensors() call updates a per-square "stable count". A reading must repeat for 3 consecutive scans before the public state flips. Tunable via SENSOR_DEBOUNCE_SCANS in board_driver.h.

This was visible in serial as flicker (q appearing/disappearing on d8 between scans during board setup) — gone now.

AP shutdown

When entering Chess Moves or Sensor Test, WiFi.end() is called to release the radio. The OpenChessBoard AP was drawing ~100 mA continuously and creating a persistent WiFi network nobody uses once a mode is selected. Bot mode is untouched because PR #9 already does the AP teardown internally.

Promotion choice (Human vs Human)

When a pawn reaches the back rank, four selector LEDs light up on the player's own back rank with distinct colours:

• a-file = Q (gold)
• b-file = R (red)
• c-file = B (blue)
• d-file = N (white)

Place any piece on one to choose. The selector then waits for you to lift the piece off the menu before re-arming the move detector.

Bot mode still auto-promotes to queen — the Stockfish API string e7e8q includes the promotion piece in its 5th character, but the existing parseMove only grabs the first 4 chars. That's a small follow-up, easy to bolt on but kept out of scope here to keep PR size manageable.

Verification

Sketch uses 150679 bytes (0%) of program storage space.
Global variables use 44640 bytes (16%) of dynamic memory.
10/10 self-tests passed.

Tested on Arduino Nano RP2040 Connect with WiFiNINA firmware 3.0.1:

• Boot clean, self-tests pass before WiFi setup
• Game selection works as before
• Chess Moves Human-vs-Human plays through opening + check + castling
• Chess Bot Human-vs-AI: WiFi connects via Fix bot mode hang on WiFi connection (closes #5) #9 patch, Stockfish responds, validated bot moves applied via applyMove
• Sensor flicker on board setup is gone

Trade-offs

• Sketch +5963 bytes vs the PR RP2040 quality pass: 5 correctness/robustness fixes #10 baseline (still 0% of the 16 MB flash) and +200 bytes RAM for GameState instances and debounce buffers
• The on-boot animation on a self-test failure is intentionally noisy — it's better than silently corrupting a game
• Promotion choice in bot mode left as a follow-up (5-char move parsing)
• 3-fold repetition not yet implemented (would need position hashing + history; bigger memory hit)