CodeStructure.md

Code Structure

This page provides an overview of the source files in the MicroChess repository, explaining their roles and how they interact to form a compact chess engine for Arduino. The codebase is written in C++ with Arduino-specific components, optimized for less than 2K RAM and 32K program flash.

File Overview

MicroChess is organized into a main Arduino sketch, header/source file pairs for modular components, and supporting files for utilities and testing. Below is a detailed breakdown of each file’s purpose.

File Name	Purpose
MicroChess.ino	Main Arduino sketch, containing setup() and loop() for game flow, move evaluation, and display logic.
MicroChess.h	Header file with enums (e.g., PrintLevel, GameState), structs (e.g., book_t, piece_gen_t), and function prototypes.
board.h/cpp	Define the board_t class for chess board representation, using bit fields for memory efficiency.
move.h/cpp	Implement the move_t class for move representation and functions for move generation/validation.
game.h/cpp	Manage game state via the game_t class, handling turns, check, and endgame conditions.
chessutil.cpp	Utility functions for chess logic, such as piece evaluation and board analysis.
conv.h	Conversion functions for board representations (e.g., algebraic notation to internal format).
led_strip.cpp	Controls the 8x8 LED strip for visual board display using the FastLED library.
options.h/cpp	Define the options_t class for game settings (e.g., search depth, time limits).
pieces.cpp	Implements piece-specific logic, including movement rules and evaluation values.
stats.h/cpp	Track performance metrics (e.g., nodes searched) via the stats_t class.
test/unit_test_001.cpp	Unit tests to verify core functionalities like board and move operations.

Key Components and Interactions

• Main Loop (MicroChess.ino):
  • Initializes the board, game state, and LED strip in setup().
  • Runs the game loop in loop(), handling move input (via Serial Monitor), engine moves, and output updates.
  • Coordinates with game_t, board_t, and move_t for gameplay.
• Board Representation (board.h/cpp):
  • The board_t class uses bit fields to store piece positions and types efficiently.
  • Provides methods like get(), set(), and isOccupied() for board manipulation.
• Move Generation (move.h/cpp):
  • The move_t class stores move details (from/to squares, evaluation score).
  • Functions generate legal moves, including special moves (castling, en passant, promotion).
• Game Logic (game.h/cpp):
  • The game_t class tracks the current turn, move history, and game state (e.g., check, checkmate).
  • Manages move execution and endgame detection.
• Evaluation and Search:
  • pieces.cpp and chessutil.cpp define piece values (e.g., pawn=100, queen=900) and board evaluation logic.
  • MicroChess.ino and supporting files implement minimax with alpha-beta pruning for move selection.
• Display (led_strip.cpp):
  • Maps board positions to an 8x8 LED grid, using FastLED to show pieces as colors.
  • Serial Monitor output (in MicroChess.ino) prints the board and move history.
• Configuration (options.h/cpp):
  • Allows customization of search depth, time limits, and verbosity.
• Metrics and Testing (stats.h/cpp, test/unit_test_001.cpp):
  • stats_t tracks performance (e.g., nodes searched per second).
  • Unit tests ensure reliability of core components.

File Interactions

The files form a modular system:

• MicroChess.ino acts as the central coordinator, calling functions from other modules.
• MicroChess.h provides shared definitions, ensuring consistency across files.
• board_t, move_t, and game_t classes (in their respective .h/.cpp files) handle core chess logic, interacting frequently.
• led_strip.cpp and chessutil.cpp provide supporting functionality for display and logic.
• options_t and stats_t enhance configurability and debugging.
• Unit tests in test/unit_test_001.cpp validate the system’s integrity.

Visual Aids

The repository includes:

• MicroChessSmall.gif: Shows the LED strip displaying the board.
• MicroChessConsole2.gif: Demonstrates Serial Monitor output. These are referenced in the Visuals page.

Next Steps

• Explore Board Representation for details on the board_t class.
• See Move Generation to understand move logic.
• Check Installation to set up the project.

---

Back to Home | Next: Board Representation