内容
# rhc_badge_ai
将RHC机器人徽章变成一个**可由AI操作的设备**。该徽章运行一个UART命令固件；一个主机AI（Claude Code / Claude Desktop）通过MCP服务器和Claude技能驱动它。
```
┌────────────┐ MCP工具 ┌───────────────┐ UART线路 ┌──────────────┐
│ Claude │ ─────────────► │ badge_mcp.py │ ─────────────► │ STM32徽章 │
│ (+技能) │ ◄───────────── │ (MCP服务器) │ ◄───────────── │ 固件 │
└────────────┘ 工具结果 └───────────────┘ JSON + 事件 └──────────────┘
```
主机AI**完全通过UART**操作徽章（CH340调试链接，115200波特率）。无需其他连接。
**跨平台：** MCP服务器在Windows、macOS和Linux上运行，并**自动检测**徽章的串行端口 — 直接插入即可使用。
> ### ⚠️ 首先将徽章设置为AI交互模式
> 生产徽章启动到其**设备菜单**，而UART线路协议仅在徽章处于**AI交互模式**时才被服务。在由MCP服务器、网页面板或`badge.py`驱动之前，在徽章上选择**`AI交互`**（菜单顶部，按**B3**）。在该模式下，徽章显示一个“AI模式”屏幕并响应命令；按**B4**退出。在AI模式之外，命令直接超时。
## 网页控制面板（无需AI主机）
`badge.py`还可以提供一个独立的**网页控制面板 + HTTP API** — 方便演示和手动测试，无需MCP主机：
```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 # 在LAN上公开
```
打开URL即可访问仪表盘（眼睛颜色/分割/彩虹，蜂鸣器，马达，手臂LED，红外发送，显示文本）。或通过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`接受一个**行协议**命令（固件语法）并返回徽章的JSON回复。徽章必须处于AI交互模式（上文）。绑定到非环回地址允许网络上的任何人驱动徽章 — 除非你打算，否则请保持在`127.0.0.1`。
**完整端点参考**（`/state`，`/connect`，`/disconnect`，`/cmd`，`/events`，`/image`）+ 行协议命令表：请参见 **[WEBAPI.md](WEBAPI.md)**。
## 布局
| 文件夹 | 内容 |
|--------|------------|
| `mcp/` | Python MCP服务器（`badge_mcp.py`），桥接MCP工具 ↔ UART协议。参见 `mcp/README.md`。 |
| `skill/rhc-badge/` | Claude技能（`SKILL.md`），教导模型如何驱动徽章并提供表达方式配方。 |
## 徽章功能
RGB **眼睛** （纯色 / 分割 / 彩虹 / 呼吸 / 闪烁），**蜂鸣器** （蜂鸣，音调，旋律），**马达** ，**手臂LED** ，**红外** 发送 + 接收（NEC），**200×200电子纸** 显示屏（文本和图像），以及**4个按钮** ，以事件形式流出 — 所有这些都可以通过自然语言控制。
## 快速入门
1. **安装MCP服务器** （`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. **注册MCP服务器** 与您的主机（Claude Code `.mcp.json` 示例如下）。在所有三个操作系统上，端口都是自动检测的，因此 `BADGE_PORT` 是可选的 — 仅当您指定特定端口时添加。使用 `python3` 和 macOS/Linux上的POSIX路径：
```json
{
"mcpServers": {
"rhc-badge": {
"command": "python",
"args": ["<abs>/mcp/badge_mcp.py"]
}
}
}
```
> macOS可能需要CH340驱动程序；Linux用户需要属于 `dialout` 组才能打开串行端口。
3. **安装技能** ，以便模型知道如何熟练使用工具。将 `skill/rhc-badge/` 复制到用户技能目录中：
```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. **与它对话。** 向Claude提问，例如 *"让徽章看起来很开心"*， *"让眼睛闪烁红色并播放警报"*， *"在屏幕上显示'HELLO DEFCON'"*，或 *"监听按钮按下并在按下时蜂鸣"*。
## 工作原理
- **MCP服务器** 是一个薄、健壮的桥梁：ID匹配的请求/响应、后台读取线程和事件缓冲区，以便按钮/IR事件在模型轮询之前存活。
- **技能** 仅提供指导 — 它使模型流畅地使用工具（颜色+声音+运动作为“情感”，清理习惯，事件循环），但不添加新的功能。
请参阅每个子文件夹的README以获取详细信息。
