Hardware layer (kirin_hardware)

Everything touching the physical board — motion, sensing, and the operator surface. More...

Files
file	board_interpreter.cpp
	Physical board path planning and state management.
file	board_interpreter.h
	Physical board path planning and state management.
file	board_scanner.cpp
	Hall effect sensor board scanning implementation.
file	board_scanner.h
	Hall effect sensor board scanning via multiplexed GPIO.
file	board_setup_planner.cpp
	see board_setup_planner.h.
file	board_setup_planner.h
	Physical setup ordering for match review (review-docs PLAN §6.3).
file	button_controller.cpp
	GPIO button input controller.
file	button_controller.h
	GPIO button input controller.
file	display_controller.cpp
	I2C OLED status display controller.
file	display_controller.h
	I2C OLED status display controller.
file	game_controller.cpp
	Integration layer implementation.
file	game_controller.h
	Integration layer between engine and physical board.
file	gantry_controller.cpp
	Physical coordinate translation and G-code generation.
file	gantry_controller.h
	Physical coordinate translation and G-code generation.
file	gantry_tuning.cpp
	Gantry capability probe + persistent motion profile.
file	gantry_tuning.h
	Gantry capability probe + persistent motion profile.
file	led_controller.cpp
	see led_controller.h
file	led_controller.h
	Addressable-RGB square-highlight framebuffer + driver seam.
file	piece_tracker.h
	Piece identity tracking for storage-based capture disambiguation.

Detailed Description

Everything touching the physical board — motion, sensing, and the operator surface.

Everything that touches the physical board. Depends on Chess engine (kirin_engine); nothing in Chess engine (kirin_engine) may depend on this.

• GameController — orchestrates engine ↔ board for a live game.
• BoardInterpreter — turns an engine move into physical motion: piece-specific paths, blocker parking, A* routing, capture→storage disambiguation.
• GrblController / gantry — emits G-code over serial; electromagnet via M8/M9.
• BoardScanner — polls the 96 hall-effect sensors to read the human's move.
• DisplayController / ButtonController / LedController — the operator surface.

Identities, not types

This layer works in piece identity, because a captured piece must be routed to its own labelled storage slot. PieceTracker is the bridge: it maps each square to the identity currently sitting on it, so a captured type coming out of the engine can be matched to the correct physical slot. When you touch capture handling, storage routing, or path planning, that is the seam you are working on.

Design reference: docs/board-interpreter-docs/, docs/hardware-integration-docs/.