chch-robot¶

chch-robot — 象棋 XiangQi(Chinese Chess) Robot

项目信息
仓库	https://github.com/Maicarons/chch-robot
主要语言	Python
Stars	4
类型	原创项目
许可证	GPL-3.0
最近更新	2026-08-03
主题	ai · chess · robot

# CH-RO Xiangqi Robot

CH-RO is a Chinese Chess (Xiangqi) human-machine robot system. It combines camera-based board recognition, Pikafish AI search, robot-arm command conversion, STM32 TCP control, and a Flask web interface.

Chinese README: README_zh.md.

Features¶

USB camera and network camera support.
ONNX-based pose and piece classification pipeline.
Board stabilization and dynamic move detection.
Pikafish UCI engine integration for Xiangqi.
Simulation and hardware robot modes.
STM32 five-value motion protocol with homing handshake.
Flask web interface for camera preview, recognition, AI moves, and robot status.

Project Layout¶

ai/                 Pikafish engine wrapper
core/               ONNX inference helpers
vision/             Camera, detector, mapper, stabilizer, recognizer
robot/              Robot protocol, TCP client, controller, firmware assets
web_simulation/     Flask backend and browser UI
model/              ONNX model files
tests/              Python tests and sample images
docs/               VitePress documentation source
firmware/stm32-tcp-server/        STM32 TCP server firmware
camera_servers/orange-pi-camera/   Orange Pi camera server
camera_servers/raspberry-pi-zero2w-usb-camera/  Raspberry Pi camera server

Quick Start¶

Install Python dependencies:

pip install -r requirements.txt

Download Pikafish and place the binary in Pikafish/. Update ENGINE_PATH in config.py if needed.

Run the web interface:

python web_simulation/app.py

Open http://localhost:5000.

Run the CLI:

python main.py
python main.py --demo
python main.py --test-camera
python main.py --test-engine

Tests¶

python -m pytest tests/ -v

Documentation¶

The documentation is managed with VitePress and includes English and Chinese pages.

npm install
npm run docs:dev
npm run docs:build

Docs start at docs/index.md.

Configuration¶

Edit config.py for camera source, model paths, Pikafish path, robot network target, command spacing, and runtime timeouts. Set CHRO_SKIP_STARTUP_PROMPT=1 for non-interactive Flask startup.

Hardware Notes¶

The STM32 controller expects:

startX,startY,endX,endY,signal

Homing uses:

m1_angle,m2_angle,0,0,99

Completion acknowledgement is STATE:5,RESULT:1.