Introduction

Overview

This document provides comprehensive documentation for the Board Interpreter module of the Kirin autonomous chess system. The board interpreter is the translation layer between the abstract chess world of the Kirin engine and the physical reality of the robotic gantry that moves pieces on the board.

When the Kirin engine decides on a move, it communicates that decision as a UCI move string (e.g., e2e4). The board interpreter’s job is to answer the question: how does the robot actually execute that move on a physical board with pieces that may be in the way? This involves computing geometrically valid physical paths for the magnetic gantry head, detecting pieces that block those paths, temporarily relocating blockers to safe parking squares, and finally generating a complete ordered action plan for the gantry controller to execute step by step.

Responsibilities

The board interpreter module is responsible for:

  • Coordinate translation: Converting between FEN algebraic notation and physical (row, col) grid coordinates.

  • Physical board state tracking: Maintaining a temporary occupancy model of the board during move planning so that blocker relocations can be simulated before being sent to the gantry.

  • Piece-type-aware path generation: Computing one or more geometrically valid sweep paths for each piece type (pawns, knights, bishops, rooks, queens, and kings), reflecting how the gantry head must physically travel.

  • Blocker detection and relocation planning: Identifying pieces that obstruct the chosen path and computing sub-plans to park them temporarily on safe empty squares.

  • A* pathfinding for blocker routing: Finding collision-free routes for blocker pieces being moved to and from parking spots, using A* search with Chebyshev distance as the heuristic.

  • Move plan assembly: Packaging the complete sequence of relocations, the primary piece move, and post-move restorations of parked pieces into a MovePlan structure that the gantry controller can execute directly.

Position in the System Architecture

The board interpreter sits between the chess engine and the gantry controller in the Kirin software stack:

interp-01-introduction-1

The engine provides two pieces of information: the move in UCI notation and a bitboard encoding which squares are currently occupied. The board interpreter uses these to produce a fully sequenced MovePlan. The gantry controller then executes each step of that plan in order without needing to reason about board geometry.

Coordinate System

The board interpreter uses a (row, col) coordinate system that maps directly to the physical grid layout of the board:

Axis

Range

Convention

Row

0–7

Row 0 = rank 8 (far side from white), Row 7 = rank 1

Col

0–7

Col 0 = file a (left side), Col 7 = file h (right side)

Physical board coordinate conventions

Square indices used in the underlying bitboard follow the engine convention: bit 0 corresponds to a8 (row 0, col 0) and bit 63 corresponds to h1 (row 7, col 7). The formula is square = row * 8 + col.