📖 Installation Guide — quick start, manual setup, and troubleshooting
git clone https://github.com/sandraschi/yahboom-mcp
cd yahboom-mcp
justThis opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.
If you don't have just installed:
Boomy is a Yahboom Raspbot v2 (Mecanum Version) robot car. Weighing in at approximately 1.0 kg and costing roughly $300 (fully loaded with a Raspberry Pi 5 16GB), it provides a unified platform for testing sensor integration, ROS 2 orchestration, and agentic (AI-driven) robotics. It's also great fun for kids of all ages.
Yahboom is a prominent player in the Chinese robotics and STEM education industry. They offer a diverse range of hardware platforms:
- Market Range: From entry-level $50 DIY kits to advanced $2,000+ STEM robots with precision mechanical arms.
- Industry Position: They specialize in accessible hardware for education and prototyping, positioned below enterprise-grade platforms such as Unitree or Noetix.
- Developer Ecosystem: Yahboom maintains a strong commitment to a FOSS (Free and Open Source Software) stack and provides active GitHub support for developers.
Boomy utilizes a "Double-Stack" controller model to bridge real-time physical reliability with high-level cognitive tasks:
- Rosmaster (ESP32 / Micro-ROS): Small-form-factor hardware controller for low-latency motor control, ultrasonic pinging, and line-sensor processing.
- Raspberry Pi 5 (Optional / Gateway): The main brain for standalone operation.
For scaled deployments, Boomy can operate in a Pi-less Swarm mode:
- Setup: Remove the Raspberry Pi; replace with a WiFi-to-Ethernet/UART bridge ($15).
- Control: Centralized orchestration via a remote Mothership (PC with RTX 4090).
- Scaling: Deploy 3+ units for the price of a single Pi-hosted robot.
This project clearly distinguishes between human-operable controls and machine-optimized interfaces:
- Human Interface: A browser-based Web Dashboard (React/Vite) designed for manual telemetry observation, peripheral control (lights, OLED), and human-robot interaction.
- Machine Interface: A standards-compliant MCP Server (Model Context Protocol) designed for AI agents and MCP clients to programmatic control Boomy as a tool within a larger fleet.
| Pillar | Focus | Key Topics |
|---|---|---|
| Autonomous Missions | v2.4.0 — Ollama → ROS | Natural-language goals → LLM planning → ROS execution; vision detection (SSD MobileNet v2); ultrasonic obstacle avoidance; "find our dog" walkthrough. |
| Startup & bringup | Start here (robot + Goliath) | ROS 2 vs rosbridge_suite (software) vs USB controller tier under the Pi; boot order; Docker/systemd on the Pi; what the webapp can restart; dashboard vs diagnostics. |
| Agent missions & MCP | LLM → Pi missions | yahboom_agent_mission (MCP) and POST /api/v1/agent/mission (HTTP); MissionPlanV1; env vars; boomy_mission_executor; Nav2 and /boomy/detections_json; troubleshooting vs yahboom_agentic_workflow. |
| Rosmaster Architecture | Dual-bus analysis | I2C (0x2b) for motors/sensors, UART for IMU/battery; register map; container layout; micro-ROS analysis. |
| Stack health probe | health.stack |
TTL SSH/TCP probes, YAHBOOM_ROS2_CONTAINER, lifecycle (never started vs exited vs restart loop), optional docker logs preview (redacted). |
| Setup & Installation | Dev install | uv, modes, baseline env vars. |
| Software & Logic | Architecture | System design, ROS 2 node graphs, and state management. |
| Hardware & Pinouts | Physical Layer | Wiring diagrams, I2C addresses, and sensor technical specs. |
| Raspbot v2 hardware stack | Boomy chassis | Chassis, mecanum, motors, lightstrip, PTZ, camera, IMU, ultrasonic, line/cliff, expansion board vs rosbridge software, Pi ports, I2C, battery, switch. |
| ROS 2 Bridge | Connectivity | Bridge architecture, topic map, state cache, env vars, known bugs. |
| Voice & Audio | Sound System | CSK4002 module protocol, espeak-ng TTS, chatrobot architecture. |
| Multi-Robot Integration | Ecosystem | Federated fleet standards and cross-robot communication protocols. |
- Dashboard (
/dashboard) — First page: basic robot link (gateway, target IP, ROS · SSH · video) and operator hints when the Raspbot is off or Goliath has no AP/Ethernet path. - Diagnostic Hub (
/diagnostics) — Detail: ROS topic explorer, node list, resync / hard reset, SSH shell, stack health table (samestackpayload as the dashboard when available). - Server logs (
/logs) — Live yahboom-mcp log stream (SSE) on Goliath.
Historical status logs and legacy research are preserved in the docs/archive/ directory.
This project adheres to SOTA 2026 industrial standards for high-fidelity agentic orchestration:
- Python (Core): Ruff for linting and formatting. Zero-tolerance for
printstatements in core handlers (T201). - Webapp (UI): Biome for sub-millisecond linting.
- MCP: FastMCP 3.2 with Unified Gateway, portmanteau tools, skills, and agentic sampling.
- LLM Providers: Auto-discovery of Ollama (
:11434) and LM Studio (:1234). GPU metrics via nvidia-smi. - Automation: Justfile recipes for all fleet operations (
just lint,just fix,just dev).