Content
# rhc_badge_ai
Turn the RHC robot badge into an **AI-operable device**. The badge runs a
UART command firmware; a host AI (Claude Code / Claude Desktop) drives it
through an MCP server and a Claude skill.
```
┌────────────┐ MCP tools ┌───────────────┐ UART lines ┌──────────────┐
│ Claude │ ─────────────► │ badge_mcp.py │ ─────────────► │ STM32 badge │
│ (+ skill) │ ◄───────────── │ (MCP server) │ ◄───────────── │ firmware │
└────────────┘ tool results └───────────────┘ JSON + events └──────────────┘
```
The host AI operates the badge **entirely over UART** (the CH340 debug link,
115200 baud). No other connection is required.
**Cross-platform:** the MCP server runs on Windows, macOS, and Linux and
**auto-detects** the badge's serial port — plug it in and go.
> ### ⚠️ Put the badge in AI Interactive mode first
> The production badge boots into its **on-device menu**, and the UART line
> protocol is only serviced while the badge is in **AI Interactive mode**.
> Before driving it from the MCP server, the web panel, or `badge.py`, select
> **`AI Interactive`** on the badge (top of the menu, press **B3**). While in
> that mode the badge shows an "AI MODE" screen and answers commands; press
> **B4** to leave. Outside AI mode, commands simply time out.
## Web control panel (no AI host needed)
`badge.py` can also serve a self-contained **web control panel + HTTP API** —
handy for demos and manual testing without an MCP host:
```bash
cd skill/rhc-badge/scripts
python badge.py serve # http://127.0.0.1:13579/
python badge.py serve --host 0.0.0.0 --http-port 13579 # expose on the LAN
```
Open the URL for a dashboard (eyes colour/split/rainbow, buzzer, motor, arm LED,
IR send, display text). Or script it over HTTP:
```bash
curl "http://127.0.0.1:13579/cmd?line=eyes+color+0+128+0"
curl -X POST http://127.0.0.1:13579/cmd --data "buzzer song rowboat"
```
`/cmd` takes one **line-protocol** command (firmware syntax) and returns the
badge's JSON reply. The badge must be in AI Interactive mode (above). Binding to
a non-loopback address lets anyone on the network drive the badge — keep it on
`127.0.0.1` unless you mean to.
**Full endpoint reference** (`/state`, `/connect`, `/disconnect`, `/cmd`,
`/events`, `/image`) + the line-protocol command table: see **[WEBAPI.md](WEBAPI.md)**.
## Layout
| Folder | What it is |
|--------|------------|
| `mcp/` | Python MCP server (`badge_mcp.py`) that bridges MCP tools ↔ the UART protocol. See `mcp/README.md`. |
| `skill/rhc-badge/` | Claude skill (`SKILL.md`) that teaches the model how to drive the badge and gives expression recipes. |
## What the badge can do
RGB **eyes** (solid / split / rainbow / breathe / blink), a **buzzer** (beeps,
tones, melodies), a **motor**, an **arm LED**, **infrared** send + receive
(NEC), a **200×200 e-paper** display (text & images), and **4 buttons** that
stream as events — all controllable from natural language.
## Quick start
1. **Install the MCP server** (`mcp/README.md`):
```bash
cd mcp
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -r requirements.txt
```
2. **Register the MCP server** with your host (Claude Code `.mcp.json` shown).
The port is auto-detected on all three OSes, so `BADGE_PORT` is optional —
add it only to pin a specific port. Use `python3` and a POSIX path on
macOS/Linux:
```json
{
"mcpServers": {
"rhc-badge": {
"command": "python",
"args": ["<abs>/mcp/badge_mcp.py"]
}
}
}
```
> macOS may need the CH340 driver; Linux users need to be in the `dialout`
> group to open the serial port.
3. **Install the skill** so the model knows how to use the tools well. Copy
`skill/rhc-badge/` into your user skills directory:
```bash
# macOS / Linux
cp -r skill/rhc-badge ~/.claude/skills/rhc-badge
```
```powershell
# Windows (PowerShell)
Copy-Item -Recurse skill\rhc-badge $HOME\.claude\skills\rhc-badge
```
4. **Talk to it.** Ask Claude things like *"make the badge look happy"*,
*"blink the eyes red and play the alarm"*, *"show 'HELLO DEFCON' on the
screen"*, or *"watch for button presses and beep when I press one"*.
## How it fits together
- The **MCP server** is a thin, robust bridge: id-matched request/response, a
background reader thread, and an event buffer so button/IR events survive
until the model polls them.
- The **skill** is guidance only — it makes the model use the tools fluently
(colour+sound+motion as "emotions", cleanup habits, event loops) but adds no
new capability.
See each subfolder's README for details.
