Connect-four-Esp32/README.md

Connect 4 - ESP32

A Connect 4 game with AI for the ESP32-C3 (Lolin C3 Mini), using an 8x8 NeoPixel LED matrix and rotary encoder.

Hardware

Pin Mapping (Lolin C3 Mini)

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)

LED Matrix Layout

The 8x8 matrix (64 LEDs) is used as follows:

Row 0:  [ col0 ] [ col1 ] [ col2 ] [ col3 ] [ col4 ] [ col5 ] [ col6 ] [ indicator ]
Row 1:  [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ border    ]
Row 2-7:[ game board: 7 columns x 6 rows                               ] [ border    ]

• 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

Game Modes

Use the rotary encoder to select a mode, press the button 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.

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.

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.
• Draw: All discs blink on and off.

WiFi Admin Interface

The ESP32 creates a WiFi access point:

• 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

Settings (via web interface)

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 %.

Settings are saved to flash (NVS) and persist across reboots.

Game Log

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.

Build & Upload

Requires PlatformIO CLI or VS Code with PlatformIO extension.

# Build
pio run

# Upload to board
pio run --target upload

# Monitor serial output
pio device monitor

Dependencies

• FastLED >= 3.6.0 - LED control
• Encoder >= 1.4.4 - Rotary encoder input
• Preferences (built-in) - Persistent settings storage
• WiFi / WebServer (built-in) - Admin interface

Build Flags

All configurable parameters are 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

AI Strategy

The AI uses minimax with alpha-beta pruning and a heuristic evaluation function. Moves are selected in three phases:

1. Instant win/block — scan all columns for an immediate win first, then for an opponent threat to block.
2. Blunder (optional) — random move at a configurable chance, skipping the deep search.
3. Deep minimax search — full tree search with alpha-beta pruning up to the configured ply depth.

The heuristic evaluates leaf nodes by scoring all 69 possible four-cell windows on the board:

• Playable threats (3-in-a-row where the gap can be filled now): ±100
• Non-playable threats (gap is floating in the air): ±40
• Two-in-a-row setups: ±5
• Center column control: ±3 per piece
• Fork bonus (2+ simultaneous three-in-a-row threats): ±200

See Background information.md / Achtergrondinformatie.md for a detailed explanation accessible to all ages.

Project Structure

src/main.cpp                 ESP32 application (game logic, AI, LED, web server)
connect_four.js              JavaScript browser edition (canvas rendering)
connect_four.html            HTML wrapper for the JavaScript version
connect_four.py              Python terminal edition (Rich TUI)
platformio.ini               Build configuration, pin mappings, and tunable parameters
README.md                    This file - technical and practical information
Background information.md    How the AI works (English, suitable for all ages)
Achtergrondinformatie.md     How the AI works (Dutch, suitable for all ages)
CLAUDE.md                    AI assistant project context

All three implementations (C++, JavaScript, Python) share the same AI algorithm and heuristic.