Project Showcase https://youtu.be/vnubYaI1xLQ
======================================
Play on Lichess using a real 4×4 membrane keypad on an Arduino Uno R3.
A small Python program sends your keypad moves to Lichess (Board API),
draws a simple chessboard in the terminal, and drives four status LEDs.
IMPORTANT
Upload and run the Arduino sketch first. Close the Arduino Serial Monitor
before starting the Python program.
WHAT’S INCLUDED
- Arduino sketch: keypad scan + PWM LEDs + line-based serial commands
- pyBridge.py: talks to Lichess, shows a terminal board, triggers LEDs
HARDWARE
- Arduino Uno R3
- 4×4 membrane keypad (HX-543)
- 4 LEDs with 220–1kΩ series resistors
- Breadboard + jumpers
WIRING (UNO)
LEDs on PWM pins for smooth brightness:
RED -> D3 (lose)
YELLOW -> D5 (check)
BLUE -> D6 (capture)
GREEN -> D9 (win)
Keypad:
Rows: D2, D4, D7, D8
Cols: A0, A1, A2, A3 (A0–A3 used as digital inputs)
Avoid D0/D1 (USB serial).
KEYPAD ENTRY
Enter four digits 1..8 for from/to squares, then press '#'.
Example: e2e4 -> 5 2 5 4 #
'*' clears the input buffer.
RUN ORDER
1) Arduino
- Open the sketch in mainArduinoCode/
- Confirm pins:
rowPins = {2, 4, 7, 8}
colPins = {A0, A1, A2, A3}
- Upload to the Uno.
- Close the Serial Monitor.
2) Python (Windows PowerShell)
- Install deps:
py -m pip install pyserial pyautogui berserk python-chess
- Create a Lichess token with scope: board:play
- Set the token in this terminal:
$env:LICHESS_TOKEN = "YOUR_TOKEN"
- (Optional) Better Unicode in console:
chcp 65001
- Run:
py .\pyBridge.py
CMD equivalents:
set LICHESS_TOKEN=YOUR_TOKEN
py pyBridge.py
WHAT THE PYTHON BRIDGE DOES
- Reads UCI moves from the Arduino (e.g., e2e4)
- Validates against the current position, sends to Lichess via Board API
- Renders a small Unicode board in the terminal
- Listens to game events and sends LED commands over serial:
CAP -> blue pulse (capture)
CHECK_ON -> yellow steady on
CHECK_OFF -> yellow off
WIN -> green pulse (win)
LOSE -> red pulse (loss)
Arduino hotkeys for testing:
A = WIN, B = LOSE, C = CAP, D = toggle CHECK
CONFIG SWITCHES (pyBridge.py)
USE_API_SEND = True # send moves via Lichess API (headless)
TYPE_MODE = False # fallback: type moves into active window
ANY_CHECK = False # yellow only when YOU are in check
# (set True to light yellow for either side)
TROUBLESHOOTING
- Port busy / no serial: close the Arduino Serial Monitor; replug USB.
- LED not changing: press D to toggle yellow (hardware check).
You should see lines like:
[SEND] -> CHECK_ON
Serial: RX: CHECK_ON
- Unicode board misaligned: use Cascadia Mono or Consolas; run chcp 65001.
- API auth: ensure LICHESS_TOKEN is set and includes board:play.
- Line endings on Windows: repo includes .gitattributes to keep LF.
PROJECT LAYOUT (SUGGESTED)
HackWesTX2025/
mainArduinoCode/
mainArduinoCode.ino
pyBridge.py
README.txt
.gitattributes