The system manual

The hand-written half of this site: how the Kirin autonomous chess system is built, how it is operated, and why it is the way it is. The generated API reference answers the other question — what a given symbol is — and the two share one search box, which is the whole reason this site exists.

Nine parts, following the system from the engine outward to the fleet. Two entry points are worth knowing:

• New to the codebase? Start with The Kirin System, then the part covering whatever you are touching.

• Wondering why something is the way it is? The Decision Register lists every architectural decision the project has made, with a link to the full entry — context, alternatives rejected, and consequences. It is generated from the decision records in the body, so it cannot drift from them.

Note

This manual is the canonical one. It was migrated from LaTeX in docs/docsite-docs/PLAN.md U2/U5 and the .tex sources were retired at U3 — this is now the only copy. ./docs/site/build.sh --pdf builds the printed edition from these same sources.

System Overview

• The Kirin System
  • Decision record: the plan archive
• Introduction
  • Overview
  • Features
  • System Requirements

Building and Testing

• Building and Testing
• Building Kirin
  • Two build roots
  • GPIO support
  • Running the engine
  • Using Kirin as a UCI engine
• Testing
  • Perft Testing
  • Test Positions
  • The automated suite
  • Strength is a separate question
• Testing
  • Test Coverage
  • Running Tests
• Contributing
  • Development Setup
  • Code Style
  • Pull Request Process

Chess Engine

• Architecture
  • Overview
  • Board Representation
  • Move Generation
• Search Algorithm
  • Overview
  • Alpha-Beta Search
  • Iterative Deepening
  • Search Enhancements
  • The pruning and reduction surface
• Evaluation
  • Overview
  • Material
  • Positional Factors
  • Pawn Structure
• NNUE Evaluation
  • Why a second evaluation at all
  • The .knnue format
  • Blend and residual: how the two evaluations combine
  • Training pipeline
• UCI Protocol
  • Overview
  • Supported Commands
  • The option surface
  • Skill Level
• Time Management
  • The three ways to bound a search
  • The budget calculation
  • The cap that cost 17 Elo
  • Checking the clock during search
• Measuring Strength
  • Why eyeballing does not work
  • The gauntlet harness
  • A worked example: the SEE investigation
  • What is still switched off
• API Reference
  • Core Functions
• Performance
  • Optimization Techniques
  • Memory Usage

Physical Board

• Introduction
  • Overview
  • Responsibilities
  • Position in the System Architecture
  • Coordinate System
• Data Structures
  • BoardCoord
  • Path
  • PieceType
  • PhysicalMove
  • RelocationPlan
  • MovePlan
  • PhysicalBoard
• Path Generation
  • Overview
  • Dispatch
  • Piece-Specific Generators
  • Primitive Path Helpers
  • Path Selection
• Blocker Detection and Relocation
  • Blocker Detection
  • Parking Spot Selection
  • Recursive Blocker Relocation
• A* Pathfinding
  • Overview
  • Algorithm Details
  • Distance Metrics
• Move Planning
  • planMove
  • Planning Algorithm
  • Error Handling
• Utility Functions and Bitboard Helpers
  • Neighbour Enumeration
  • Inline Helper
  • Bitboard Utilities
  • Position Parsing
• Debug Functions
  • printPath
  • printMovePlan
• Piece Identity and Physical Setup
  • Why types are not enough
  • Promotion: the board and the FEN diverge on purpose
  • The setup planner
  • Arbitrary FENs: the puzzle case
• Desync Detection and Recovery
  • What the sensors can and cannot tell you
  • The decision function
  • Acting on the plan
• The LED Highlight Subsystem
  • Driving the chain
  • The snake mapping
  • The power invariant
  • Reacting to a lift
• Integration Guide
  • Typical Usage Pattern
  • Capture Moves
  • Special Chess Moves

Hardware Integration

• Overview
  • What This Document Covers
  • System Architecture
  • Runtime Move Pipeline
  • Prerequisites
• Building the Software
  • Clone and Build
  • Install Dependencies
  • Run the Tests
• Wiring the Hall Effect Sensors
  • Sensor Overview
  • Multiplexer Wiring
  • Sensor-to-Channel Mapping
  • A3144 Sensor Circuit
• Connecting the Gantry
  • The motion controller
  • Serial connection
  • GRBL Settings
  • Electromagnet Control
  • GRBL Motion Mode Setup
  • Physical Coordinate System
• Headless Operator UI: OLED and Buttons
  • Where this fits now
  • OLED Display
  • Operator Buttons
• First Power-On Procedure
  • Step 1: Verify GPIO Chip
  • Step 2: Start Kirin in Physical Mode
  • Step 3: Run Sensor Diagnostics
  • Step 4: Quick Scan
  • Step 5: Test the Gantry
  • Step 6: Gantry Coordinate Calibration
• Running Your First Game
  • Stage 1: Manual Move Entry (No Sensors)
  • Stage 2: Sensor-Based Play
  • Stage 3: Full Game
• Troubleshooting
  • Sensor Issues
  • Gantry Issues
  • Move Detection Issues
• Tunable Parameters

Application and User Interface

• The Application Layer
  • One process
  • GameSession: the loop, without a frontend
  • The two interfaces underneath
  • The Qt layer: bridges
• Playing a Game
  • Personalities: the opponent ladder
  • Odds games
  • The clock
  • Takeback
  • Restart, and who sets the board up
  • The Kirin rating
• Match Review
  • What is recorded
  • Analysis
  • Physical review
  • The review screen
• Puzzles
  • Two sources, and the optional one is Lichess
  • Setting the position up
  • Fair play is structural
  • After the attempt
• The Touch Interface
  • The shell
  • Board lighting settings
  • Display sleep
  • Power, and never pulling the plug

Connected Services

• Networked Play
  • The seam: an opponent is an interface
  • The server
  • Seating, and what a rated game means
  • Physical desync and recovery
• Accounts, Devices and Ratings
  • Two identity layers
  • Provisioning and linking a board
  • The data model
  • Ratings and leaderboards
  • Presence
• The Live Board Feed and Telemetry
  • Per device, not per game
  • On the board: FeedPublisher
  • Telemetry
• Broadcast Mirroring
  • Three assumptions that did not survive
  • The stream is whole games, and that is the good news
  • Choosing a board
• The Lichess Integration
  • The terms
  • Auth: the phone does the OAuth
  • Fair play — the constraint that must not be violated
  • Two ratings, kept apart
  • What is not built

Fleet and Operations

• The Golden Image
  • What the card locks in forever
  • Unit serials
  • The dev bench is not a fleet board
• Over-the-Air Updates
  • What ships, and what swaps
  • Signing
  • The swap, and the safety net
  • Channels, rollouts and the fleet view
• The First-Run Wizard
  • The gate
  • The steps
  • No stored cursor
• Security Posture
  • What is protected, and where
  • Accepted risks
  • Rules that are structural, not configured

Appendices

• Decision Register
• GPIO Pin Reference
• UCI Option Reference
  • Search features
  • Evaluation
  • Time management
  • General
• Software Command Reference
  • Command-Line Validation Modes
  • Physical Mode Commands
• Original 12-Week Development Timeline
  • Project Overview
  • Phase Overview
  • Detailed Weekly Schedule
  • Minimum Viable Prototype (MVP) Criteria
  • Task Division
• Glossary
• Glossary
• References
• References