Electronic Chessboard Project

An intelligent electronic chessboard that detects piece movements in real-time using Raspberry Pi and MCP23017 GPIO expanders, with integrated chess engine and game management features.

🎯 Features

• Real-time Piece Detection: Hardware-based piece movement detection using MCP23017 GPIO expanders
• Chess Engine Integration: Full chess rule validation using the python-chess library
• Game Management: Automatic PGN export with timestamps and game metadata
• LCD Display Support: Real-time game state display with menu system
• Move Parsing: Intelligent parsing of piece up/down events to determine valid chess moves
• Event Stack Processing: Advanced event processing with RpiChessStack for complex move sequences
• Special Move Support: Handles castling, captures, promotions, and piece dragging
• Move Reversion: Automatic move reversion when pieces are returned to original positions
• Modular Design: Clean separation between chess engine and hardware interface

🏗️ Architecture

echess/
├── src/                    # Source code directory
│   ├── engine/             # Chess engine module
│   │   ├── board.py        # Core chess engine with electronic board support
│   │   └── stack.py        # Event processing stack for piece movements
│   └── rpi/                # Raspberry Pi hardware interface
│       ├── main.py         # Main hardware interface and game loop
│       ├── i2c_lcd.py      # I2C LCD display driver
│       └── menu.py         # Menu system for LCD
├── tests/                  # Test suites
│   ├── engine/             # Chess engine tests
│   └── rpi/                # Hardware interface tests
├── pgn/                    # Sample PGN games
├── exports/                # Generated PGN game exports
├── pyproject.toml          # Project configuration and dependencies
└── Makefile               # Development and build commands

🚀 Quick Start

Prerequisites

• Python 3.11+
• Raspberry Pi (for hardware interface)
• MCP23017 GPIO expanders
• I2C LCD display (optional)

Installation

1. Install uv (if not already installed)

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository

   git clone <repository-url>
   cd echess

3. Install dependencies

   # Core dependencies only (works on any platform)
   make install
   # or directly: uv sync
   
   # With hardware support (Raspberry Pi only)
   make install-hardware
   # or directly: uv sync --extra hardware

4. Set up development environment (optional)

   # Development tools only
   make setup-dev
   # or directly: uv sync --extra dev
   
   # Full environment with hardware support
   make setup-full
   # or directly: uv sync --extra hardware --extra dev

5. Install pre-commit hooks (recommended)

   make pre-commit-install
   # or directly: uv run pre-commit install

Running the Project

• Test chess engine: make run-chess
• Run on Raspberry Pi: make run-rpi (requires hardware)
• Test LCD display: make test-lcd

🧪 Testing

The project includes comprehensive tests for both the chess engine and hardware interface:

# Run all tests
make test

# Run specific test suites
make test-chess    # Chess engine tests
make test-rpi      # Raspberry Pi tests

Test Coverage

• Chess Engine Tests: Move validation, game state management, PGN export
• Event Stack Tests: Comprehensive testing of RpiChessStack with 20+ test cases covering:
  • Basic moves and captures
  • Move reversion and intermediate events
  • Complex move sequences and edge cases
  • Castling, promotion, and special moves
• Hardware Interface Tests: GPIO parsing, event queue processing
• Integration Tests: End-to-end game scenarios including special moves

🔧 Development

Code Quality

# Format code with ruff
make format

# Run linting with ruff and mypy
make lint

# Install pre-commit hooks
make pre-commit-install

# Run pre-commit on all files
make pre-commit-run

# Update pre-commit hooks
make pre-commit-update

# Full pre-commit checks
make pre-commit

Project Structure

• src/engine/board.py: Core chess engine with electronic board support (ChessBoard class)
• src/engine/stack.py: Event processing stack for piece movements (RpiChessStack class)
• src/rpi/main.py: Hardware interface and main game loop
• src/rpi/i2c_lcd.py: I2C LCD display driver
• src/rpi/menu.py: Menu system for LCD navigation

🎮 How It Works

Piece Detection

1. Hardware Interface: MCP23017 GPIO expanders monitor each square
2. Event Processing: Piece up/down events are captured and processed by RpiChessStack
3. Move Parsing: Events are intelligently parsed to determine valid chess moves
4. Validation: Moves are validated against chess rules using python-chess
5. Move Reversion: Automatic reversion when pieces are returned to original positions

Game Flow

1. Initialization: Board state is read from hardware matrix and ChessBoard is created
2. Event Loop: Continuous monitoring for piece movements via RpiChessStack
3. Move Processing: Events are intelligently parsed and moves are executed on ChessBoard
4. Game Management: Game state is tracked and displayed on LCD
5. Export: Games are automatically saved as PGN files with timestamps

Special Features

• Piece Dragging: Supports piece dragging with intermediate positions
• Capture Detection: Handles complex capture sequences
• Castling: Automatic castling detection and validation
• Promotion: Automatic queen promotion (configurable)
• Game Over Detection: Checkmate, stalemate, and draw detection

📊 Hardware Requirements

Required Components

• Raspberry Pi (3B+ or 4 recommended)
• MCP23017 GPIO expander chips
• Electronic chessboard with piece detection
• I2C LCD display (16x2 or 20x4)

Wiring

• MCP23017 chips connected via I2C
• Each square connected to GPIO pins
• Pull-up resistors for reliable detection
• I2C LCD display for game state

📝 Configuration

Hardware Configuration

Edit src/rpi/main.py to configure:

• Number of MCP23017 chips (NUM_MCP)
• I2C device addresses (DEVICE)
• GPIO pin assignments

Chess Engine Configuration

Edit src/engine/board.py to configure:

• Starting position (STANDARD_STARTING_FEN)
• Board matrix mapping (STANDARD_STARTING_POS)
• Promotion piece (default: Queen)

🐛 Troubleshooting

Common Issues

1. Import Errors: Ensure all dependencies are installed with make install
2. Hardware Detection: Check I2C connections and device addresses
3. Move Validation: Verify piece detection matrix configuration
4. LCD Display: Check I2C address and wiring

Debug Mode

Enable debug mode in ChessBoard initialization:

board = ChessBoard(matrix=matrix, debug=True)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting: make pre-commit
5. Commit using conventional commits: uv run cz commit
6. Submit a pull request

Commit Convention

This project uses Conventional Commits for consistent commit messages:

# Use commitizen for guided commits
uv run cz commit

# Or manually follow the format:
# type(scope): description
#
# Examples:
# feat(engine): add castling support
# fix(rpi): resolve GPIO parsing issue
# docs: update README with installation steps
# test: add unit tests for event queue

Pre-commit Hooks

The project includes comprehensive pre-commit hooks that run automatically on every commit:

• Ruff: Fast linting and formatting
• MyPy: Type checking
• Bandit: Security vulnerability scanning
• Pre-commit hooks: File validation and cleanup
• Commitizen: Commit message validation

📚 API Reference

Chess Engine (src.engine)

• ChessBoard: Extended chess board with electronic board support
• RpiChessStack: Event processing stack for piece movements
• Event: Data class representing piece up/down events
• push(): Execute moves from hardware interface
• save_game(): Export game to PGN format

Hardware Interface (src.rpi)

• main(): Main game loop and hardware initialization
• parse_input(): Parse GPIO events to chess moves
• init(): Initialize MCP23017 GPIO expanders
• run(): Main event loop for piece detection

🎯 Future Enhancements

• Computer opponent integration
• Online game support
• Mobile app interface
• Advanced analytics
• Voice commands
• Tournament mode

---

Note: This project requires actual hardware to function. The chess engine can be tested independently, but the full electronic chessboard functionality requires the Raspberry Pi setup with MCP23017 GPIO expanders.