-blue){kind=icon}
A bug-fix fork of Concept-Bytes/Open-Chess that actually works on the Arduino Nano RP2040 Connect with the Concept-Bytes PCB — same hardware that shipped to Kickstarter backers.
AI mode hangs at "Connecting to WiFi…"? Sensors flicker when you slide pieces? "Stockfish API failed" even with internet? No castling, en passant, or check detection in the official firmware?
🔥 Download v1.0.0-rp2040 (drag-and-drop
.uf2) — works in 60 seconds, no Arduino IDE required.Build documentation, BOM, and full user manual: semichcsc-byte/openchess.
- Quick start (60 seconds)
- What's fixed vs upstream
- What works now
- Self-tests
- Compile from source
- Where the hardware comes from
- Comparison with other forks
- Upstream PRs
- Contributing
- Changelog
- User manual — game modes, troubleshooting, WiFi setup
- License
-
Download
OpenChess-v1.0.0-rp2040.uf2(302 KB). -
Double-tap the white reset button on your Arduino Nano RP2040 Connect within ~500 ms.
-
The board mounts as a USB drive named
RPI-RP2. -
Drag the
.uf2file onto that drive. The board reboots automatically. -
Open Serial Monitor at 9600 baud. You should see:
================================================ OpenChess Starting Up Firmware: v1.0.0-rp2040 Fork: semichcsc-byte/Open-Chess ================================================ === ChessEngine self-tests === PASS T1..T10 === Self-tests complete: 10/10 passed === -
Four white LEDs light up in the centre of the board — place a piece on one to pick a mode. Full manual: docs/MANUAL.md.
⚠️ AI mode requires WiFi credentials. The pre-built.uf2does not include them. To use AI mode, compile from source. Human-vs-Human and Sensor Test work out of the box.
| Bug / missing in upstream | Fixed here |
|---|---|
| 🔴 AI mode hangs at "Connecting to WiFi…" | ✅ AP→STA tear-down before WiFi.begin() (PR #9) |
| 🔴 "API request was not successful" on success | ✅ Parser splits HTTP body from headers (PR #10) |
| 🔴 Easy and Medium AI are identical (same depth) | ✅ medium() now sends depth=10 (PR #10) |
| 🔴 Bot move applied without validation | ✅ Local engine rejects illegal API responses (PR #10) |
| 🔴 MODE_GAME_3 spam loop forever | ✅ Wait for piece-lift before re-arming menu (PR #10) |
| 🔴 No check / checkmate / stalemate detection | ✅ Full detection + on-board animation (PR #11) |
| 🔴 Pinned pieces could move (expose own king) | ✅ Legal-move filter |
| 🔴 No castling | ✅ Kingside + queenside, FIDE legal |
| 🔴 No en-passant | ✅ Pink LED hint, correct capture removal |
| 🔴 No 50-move rule / insufficient material | ✅ Auto-detected, draw animation |
| 🔴 Pawn always auto-promoted to Queen | ✅ Q/R/B/N choice via 4 LEDs (Human-vs-Human) |
| 🟡 Sensor flicker when sliding pieces | ✅ Debounce: 3 consecutive scans required |
🟡 OpenChessBoard AP stays up forever (~100 mA) |
✅ Shut down when not needed |
| 🟡 No way to know if firmware is broken | ✅ 10 self-tests at every boot, red flash on failure |
→ All upstream, see PRs #9, #10, #11.
- 👥 Human vs Human — castling, en passant, promotion choice (Q/R/B/N via 4 LEDs), check / checkmate / stalemate / 50-move / insufficient material
- 🤖 Human vs AI (Stockfish) — Easy/Medium/Hard/Expert via stockfish.online, bot moves locally validated before applying
- 🔍 Sensor Test — visual diagnostics for hall sensors and LED matrix
- 💡 Sensor debounce — slide pieces without false detections
- 🔋 AP shutdown when not needed (saves ~100 mA)
- 🆔 Versioned boot banner (
v1.0.0-rp2040) on serial - ✅ 10 self-tests before WiFi setup, with red-flash failure indicator
Every boot runs 10 deterministic chess engine tests and prints:
=== 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 ===
If any fail, the board flashes red 5 times across all 64 LEDs. Do not play a game with a broken engine — re-flash a clean release.
These tests caught a real bug during development (a wrong test fixture) and will catch any regression in the rule engine before it reaches a game.
# Install board support and libraries
arduino-cli core install arduino:mbed_nano
arduino-cli lib install "Adafruit NeoPixel"@1.14.0
arduino-cli lib install WiFiNINA
# Clone this fork
git clone https://github.com/semichcsc-byte/Open-Chess.git
cd Open-Chess
git checkout v1.0.0-rp2040
# Configure WiFi (skip for Human-vs-Human only)
cp arduino_secrets_template.h arduino_secrets.h
# edit arduino_secrets.h with your SSID and passwordarduino-cli compile --fqbn arduino:mbed_nano:nanorp2040connect .
# find your port:
arduino-cli board list
# replace usbmodemXXX with yours:
arduino-cli upload --fqbn arduino:mbed_nano:nanorp2040connect -p /dev/cu.usbmodemXXX .🔒
arduino_secrets.his in.gitignore— your WiFi password stays local.
| Part | Source |
|---|---|
| PCB | concept-bytes.com/products/openchess-pcb — originally Kickstarter campaign |
| 3D files (board, tiles, pieces) | MakerWorld — OpenChess Smart Chess Board by Concept_Bytes (CC BY 4.0) |
| Microcontroller | Arduino Nano RP2040 Connect |
| Magnets | 10×2 mm neodymium (32 pieces, south pole down for A3144 sensors) |
| Steel discs | 10×1 mm (64, one under each square) |
Full BOM with prices and Amazon links: openchess/docs/BOM.md (build documentation repo).
| Concept-Bytes (upstream) | This fork | joojoooo | |
|---|---|---|---|
| Status | 🔴 Abandoned (last commit Aug 2025) | 🟢 Active | 🟢 Active (16★) |
| Hardware | Nano RP2040 | Nano RP2040 (drop-in) | ESP32 (jumpers required) |
| Chess rules | Pseudo-legal only | Full FIDE | Full FIDE + 3-fold rep |
| AI mode | ❌ broken | ✅ Stockfish.online | ✅ Stockfish.online |
| Lichess online | ❌ | ⏳ v1.3 (speculative) | ✅ |
| Web UI | ❌ | ⏳ v1.2 planned | ✅ |
| OTA updates | ❌ | ❌ won't fix (no dual flash partition) | ✅ |
| Self-tests | ❌ | ✅ 10 at boot | ❌ |
If you have an ESP32 and don't mind re-soldering with jumper wires, joojoooo/OpenChess is the more powerful firmware. This fork exists because the Concept-Bytes Kickstarter campaign shipped the Nano RP2040 Connect — the official firmware for that exact MCU has been broken and unmaintained since Aug 2025, leaving backers without working AI mode.
→ Honest feature matrix: docs/COMPARISON.md.
All three patches are filed against Concept-Bytes/Open-Chess. The repo has 0 PRs ever merged so they're unlikely to be reviewed, but at least they're searchable:
- PR #9 — WiFi AP→STA fix (closes #5)
- PR #10 — 5 quality fixes (depth, parser, validation, MODE_GAME_3, max moves)
- PR #11 — Full chess rules + UX polish + 10 self-tests
If you want the patches in a single branch, use feat/rp2040-rules-and-ux (it's the basis for the v1.0.0-rp2040 tag).
See CONTRIBUTING.md. Bug reports and PRs welcome — please include hardware details, firmware version (printed on serial banner), and full serial output at 9600 baud from boot to the failure.
For build documentation issues (BOM, photos, instructions), open at semichcsc-byte/openchess instead.
- 5-char API move parsing so AI mode supports promotion choice (
e7e8q) - Difficulty selection at runtime (no recompile)
- Brightness control via EEPROM emulation
- Async LED animations (state-machine refactor)
- 3-fold repetition if RAM allows
The LittleFS partition is available on the mbed core and the existing wifi_manager.cpp AP/HTTP server can be extended. Realistic deliverables:
- Configure WiFi without editing
arduino_secrets.h+ recompiling 🙌 - Mode selection from browser
- Live board state + FEN export
- Difficulty selection
- Resign / Draw buttons
- Move history (in-RAM)
Won't match joojoooo's depth (no themes, no move sounds, no evaluation graphs) — just enough to remove the recompile-for-WiFi pain point.
Technically possible: Lichess Bot API uses NDJSON over HTTPS long-poll, which WiFiNINA can sustain. But fragile (heap fragmentation, TLS reconnect latency, token storage). Effort: 3-4 sessions + tuning. For Lichess on a physical board today, use joojoooo/OpenChess on an ESP32 — it's the right tool.
- OTA firmware updates — RP2040 has no dual flash partition + no
Update.h. The upstream mbed core tried (second_stage_otapatch) and reverted. Use the.uf2drag-and-drop workflow instead (5 seconds). - Web Flasher — no WebUSB on RP2040.
.uf2is the moral equivalent.
If you need OTA or Web Flasher, the answer is honest: migrate to ESP32 + joojoooo/OpenChess.
MIT — same as upstream Concept-Bytes/Open-Chess. The OpenChess PCB design and STL files are by Concept Bytes under CC BY 4.0.