Public/connect_four_pico
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[update] Documentation

Browse Source
This commit is contained in:
Seppe De Loore
2026-03-27 15:39:21 +01:00
parent 49c5318ae6
commit f6c69a1f3e
1 changed files with 93 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+93 -70
View File
@@ -1,76 +1,81 @@
# Connect 4 - ESP32
# Connect Four - Pico 2W
A Connect 4 game with AI for the ESP32-C3 (Lolin C3 Mini), using an 8x8 NeoPixel LED matrix and rotary encoder.
A Connect Four game with AI for the Raspberry Pi Pico 2W, using a PicoResTouch-LCD-2.8 touchscreen display (2.8" TFT with resistive touch).
## Hardware
### Pin Mapping (Lolin C3 Mini)
### Requirements
| Component | ESP32-C3 Pin | Function |
| :------------------- | :----------- | :------------------- |
| **NeoPixel Matrix** | `GPIO 4` | Data Input (DIN) |
| **Rotary Encoder A** | `GPIO 0` | Directional CLK |
| **Rotary Encoder B** | `GPIO 1` | Directional DT |
| **Encoder Button** | `GPIO 2` | Selection/Abort (SW) |
- **Raspberry Pi Pico 2W** (RP2350, with headers soldered)
- **Waveshare Pico-ResTouch-LCD-2.8** (320x240 ST7789 TFT + XPT2046 resistive touch)
### LED Matrix Layout
The Pico 2W plugs directly into the display board's header socket. No additional wiring needed.
The 8x8 matrix (64 LEDs) is used as follows:
### Pin Mapping (PicoResTouch-LCD-2.8)
```
Row 0: [ col0 ] [ col1 ] [ col2 ] [ col3 ] [ col4 ] [ col5 ] [ col6 ] [ indicator ]
Row 1: [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ border ]
Row 2-7:[ game board: 7 columns x 6 rows ] [ border ]
```
| Component | GPIO | Function |
| :---------------- | :----- | :---------------- |
| **LCD SCLK** | `GP10` | SPI1 Clock |
| **LCD MOSI** | `GP11` | SPI1 TX |
| **LCD MISO** | `GP12` | SPI1 RX |
| **LCD CS** | `GP9` | Display select |
| **LCD DC** | `GP8` | Data/Command |
| **LCD RST** | `GP15` | Display reset |
| **LCD BL** | `GP13` | Backlight (PWM) |
| **Touch CS** | `GP16` | Touch select |
| **Touch IRQ** | `GP17` | Touch interrupt |
- **Row 0 (columns 0-6):** Interaction row. Shows the current column selection cursor and AI thinking animation (pulsing disc).
- **Row 0 (column 7):** Game mode indicator LED (dim). Yellow = player is yellow vs AI, Red = player is red vs AI, Blue = two player, Off = demo.
- **Row 1 + Column 7:** Blue border frame (toggleable via `SHOW_BORDER` build flag). Glows softly during demo and finished states.
- **Rows 2-7, Columns 0-6:** The 7x6 game board. Yellow and Red discs.
- **LED index formula:** `index = (y * 8) + x`
All display and touch peripherals share SPI1.
## Game Modes
Use the rotary encoder to select a mode, press the button to start:
Touch a menu item to start:
1. **Player vs AI (Yellow)** - Player plays yellow (first move), AI plays red.
2. **Player vs AI (Red)** - AI plays yellow (first move), player plays red.
3. **Two Player** - Two humans alternate turns. Yellow goes first.
1. **Play as Yellow** - Player plays yellow (first move), AI plays red.
2. **Play as Red** - AI plays yellow (first move), player plays red.
3. **Two Players** - Two humans alternate turns. Yellow goes first.
4. **Settings** - Adjust AI difficulty, blunder mode, view game log, recalibrate touch.
### Controls
- **Menu:** Touch a game mode or Settings to select.
- **During play:** Touch a column to drop a disc.
- **After game ends:** Touch anywhere to return to menu.
- **Demo mode:** Touch anywhere to return to menu.
### Demo Mode
When idle (no input for the configured timeout), the board enters demo mode where two AI players play against each other automatically. To make games more interesting, the two demo players are assigned different skill levels (asymmetric ply depths), so games frequently end in a win rather than a draw. Press the button or turn the encoder to exit demo mode and return to the menu.
When idle (no input for 60 seconds), the board enters demo mode where two AI players play against each other. The two demo players use asymmetric ply depths (randomized each game) so games frequently end in a win rather than a draw. Touch the screen to exit.
### Animations
- **Disc drop:** Discs fall from the top with accelerating speed.
- **Column movement:** Discs slide across the top row to the selected column.
- **AI thinking:** The disc in the selected column pulses while the AI calculates.
- **Win:** The winning four discs flash while the rest of the board dims. Displayed for 30 seconds.
- **Win:** The winning four discs flash while the rest of the board dims.
- **Draw:** All discs blink on and off.
## WiFi Admin Interface
## Settings Menu
The ESP32 creates a WiFi access point:
Accessible from the main menu. All settings are saved to flash (EEPROM) and persist across reboots.
- **Network:** Configured via `WIFI_SSID` build flag (default: `Connect4`)
- **Password:** Configured via `WIFI_PASSWORD` build flag (default: `youlose4`)
- **Admin page:** Connect to the network and open `http://192.168.4.1`
| Setting | Range | Description |
| :------------------- | :------- | :------------------------------------------------- |
| **AI Ply** | 1-10 | Search depth for the AI. Higher = stronger. |
| **Blunder** | ON/OFF | AI randomly picks a bad move at the configured %. |
| **Blunder %** | 5-100% | Chance of a blunder when enabled (step 5). |
### Settings (via web interface)
Additional options:
- **View Game Log** - Paginated list of all played games (type, level, winner, moves). Player wins highlighted in red. Option to clear the log.
- **Recalibrate Touch** - Re-run the two-point touch calibration.
| Setting | Description |
| :--------------- | :------------------------------------------------------- |
| **Base AI Ply** | Search depth for the AI (1-10). Higher = stronger. |
| **Brightness** | LED brightness (0-255). |
| **Idle Timeout** | Seconds of inactivity before demo mode starts. |
| **Blunders** | AI randomly picks a bad move at the configured chance %. |
## Game Log
Settings are saved to flash (NVS) and persist across reboots.
The last 100 games are stored in flash. Each entry records the game type (Yellow/Red/Two-player), AI level, winner, and the column sequence. The log is viewable on-device via Settings > View Game Log.
### Game Log
## Touch Calibration
The web interface shows a log of the last N games (configurable via `MAX_GAME_LOG` build flag). Each entry shows the game type, AI level, winner, and the sequence of columns played. Games where a player beats the computer are highlighted in red. The game log is persisted to flash and survives reboots.
On first boot, the display shows a two-point calibration screen (touch top-left, then bottom-right crosshairs). Calibration data is stored in EEPROM. To recalibrate:
- Hold the touchscreen during boot, **or**
- Use Settings > Recalibrate Touch.
## Build & Upload
@@ -80,46 +85,64 @@ Requires [PlatformIO](https://platformio.org/) CLI or VS Code with PlatformIO ex
# Build
pio run
# Upload to board
# Upload to board (hold BOOTSEL, plug in USB, release, then run)
pio run --target upload
# Or copy the UF2 file manually:
# Hold BOOTSEL, plug in USB. Copy .pio/build/rpipico2w/firmware.uf2 to the RPI-RP2 drive.
# Monitor serial output
pio device monitor
```
### Dependencies
- [FastLED](https://github.com/FastLED/FastLED) >= 3.6.0 - LED control
- [Encoder](https://github.com/PaulStoffregen/Encoder) >= 1.4.4 - Rotary encoder input
- Preferences (built-in) - Persistent settings storage
- WiFi / WebServer (built-in) - Admin interface
- [Adafruit ST7735/ST7789 Library](https://github.com/adafruit/Adafruit-ST7735-Library) - Display driver
- [Adafruit GFX Library](https://github.com/adafruit/Adafruit-GFX-Library) - Graphics primitives
- EEPROM (built-in) - Persistent settings storage
- SPI (built-in) - Hardware SPI communication
### Build Flags
All configurable parameters are defined as `-D` flags in `platformio.ini`:
Configurable parameters defined as `-D` flags in `platformio.ini`:
| Flag | Default | Description |
| :--------------------- | :--------- | :------------------------------------------------- |
| `LED_PIN` | `4` | GPIO pin for NeoPixel data line |
| `ENC_A` | `0` | GPIO pin for encoder CLK |
| `ENC_B` | `1` | GPIO pin for encoder DT |
| `ENC_SW` | `2` | GPIO pin for encoder button |
| `SENSITIVITY` | `4` | Encoder steps per detent (higher = less sensitive) |
| `SHOW_BORDER` | `1` | Show blue border frame (0 = off, 1 = on) |
| `DEFAULT_LOOK_AHEAD` | `8` | Default AI search depth (plies) |
| `DEFAULT_BRIGHTNESS` | `25` | Default LED brightness (0-255) |
| `DEFAULT_IDLE_TIMEOUT` | `45` | Seconds before demo mode activates |
| `DEMO_RESET_PAUSE` | `30000` | Milliseconds before finished game enters demo |
| `MAX_GAME_LOG` | `5` | Number of games stored in the game log |
| `WIFI_SSID` | `Connect4` | SSID for the WiFi access point |
| `WIFI_PASSWORD` | `youlose4` | Password for the WiFi access point |
| Flag | Default | Description |
| :--------------------- | :------ | :------------------------------------------------ |
| `DEFAULT_LOOK_AHEAD` | `8` | Default AI search depth (plies) |
| `DEFAULT_IDLE_TIMEOUT` | `60` | Seconds before demo mode activates |
| `DEMO_RESET_PAUSE` | `20000` | Milliseconds before finished game enters demo |
| `MAX_GAME_LOG` | `100` | Maximum number of games stored in the game log |
| `BLUNDER_ENABLED` | `0` | Default blunder mode (0 = off, 1 = on) |
| `BLUNDER_CHANCE` | `20` | Default blunder chance percentage |
## AI
The AI uses minimax search with alpha-beta pruning and a three-phase move strategy:
1. **Instant win/block** - Check all columns for an immediate win or opponent threat.
2. **Blunder** (optional) - Randomly pick a valid column instead of searching.
3. **Deep search** - Full minimax with alpha-beta pruning at the configured ply depth.
The board evaluation scores center column control and counts two/three-in-a-row patterns in all four directions. Column search order is center-first (`3, 2, 4, 1, 5, 0, 6`) for better alpha-beta pruning.
## Project Structure
```
src/main.cpp Single-file application (all game logic, AI, LED, web server)
platformio.ini Build configuration, pin mappings, and tunable parameters
README.md This file - technical and practical information
Background information.md How the AI works (suitable for all ages)
CLAUDE.md AI assistant project context
src/
config.h Pin definitions, layout constants, colors, game defaults
game.h / .cpp State enum, shared globals, board helpers, AI (minimax), game logic
touch.h / .cpp XPT2046 raw SPI reads, touch events, calibration
storage.h / .cpp EEPROM persistence (calibration, settings, game log)
display.h / .cpp All TFT drawing (board, menu, settings UI, game log UI)
main.cpp setup(), loop(), state dispatch
platformio.ini Build configuration and tunable parameters
connect_four.js / .html Browser edition (standalone, identical AI)
Background information.md How the AI works (suitable for all ages)
Achtergrondinformatie.md AI explanation (Dutch)
CLAUDE.md AI assistant project context
```
## Browser Edition
The `connect_four.js` / `connect_four.html` files contain a standalone browser version with identical AI logic. Open `connect_four.html` in any modern browser to play. Supports mouse, keyboard, and touch input.