Universal Embedded AI Infrastructure & Serial over TCP Gateway for Antigravity & AI Agents
在嵌入式与机器人开发中，传统物理串口（COM / UART）存在以下核心痛点：
- Windows 串口强排他性：一个 COM 口被上位机、VOFA+ 或终端打开后，AI Agent、自动化测试与 CLI 工具均会遭遇拒绝访问（
WinError 5）。 - 多端并发写入冲突：多个 AI Agent 或测试脚本并发操作同一串口时，总线字节交错撕裂，回显混淆。
- 跨 Chunk 解码乱码：单片机输出中文或多字节 UTF-8 日志时，若按数据包切割解码，汉字极易损坏变成
\ufffd。 - 高频遥测淹没交互：单片机持续以 50Hz/10Hz 吐出红外或电机遥测流时，命令回执会被瞬间淹没。
Embedded MCP 通过 Serial over TCP Gateway 架构，将物理串口抽象为双端口微服务网络：
- 5001 纯数据透传端口 (Raw Sniffer)：PuTTY / VOFA+ 零配置直连监听波形与日志，无锁多读。
- 5101 JSON-RPC 控制端口 (Control & Multiplexing)：为 Antigravity AI Agent、自动化脚本与 CLI 提供结构化管控。
- 方案二：微秒级原子事务排队池 (Transaction Multiplexing)：并发下发命令无需手动申请锁，自动在异步 FIFO 队列中借还租约并剥离回显。
- 单调偏移防乱码环形缓冲区 (ChunkedRingBuffer)：在 Raw Bytes 空间反向定位边界，多字节 100% 完整，高频遥测下精准捕获命令回执。
┌──────────────────────────────────────────────────────────┐
│ Antigravity Agent / Claude Client │
└────────────────────────────┬─────────────────────────────┘
│ stdio (JSON-RPC 2.0)
▼
┌──────────────────────────────────────────────────────────┐
│ embedded-mcp Server │
│ (board_list, board_status, serial_tail, serial_exchange)│
└────────────────────────────┬─────────────────────────────┘
│
┌──────────┴──────────┐
▼ ▼
JSON-RPC 2.0 (Port 5101) Raw Stream (Port 5001)
[Control & Leased Writes] [PuTTY / VOFA+ Sniffer]
│ ▲
└──────────┬──────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ SerialGateway Engine │
│ ├── LeaseArbiter (FIFO Transaction Multiplexing Queue) │
│ ├── ChunkedRingBuffer (Monotonic Byte Sliced Safe Buffer)│
│ └── SerialWorker (Dedicated Thread, Win32 Auto-Heal) │
└────────────────────────────┬─────────────────────────────┘
│ pyserial (dtr=None, rts=None)
▼
COM4 (ATK-HSWL-CMSIS-DAP 04D8:00DF)
本项目遵循 uv 环境规范，禁止使用传统 pip。
在项目根目录（e:\WorkSpace\embedded-mcp）执行：
uv sync --extra dev- 推荐方法：通过 uv tool 全局链接
uv tool install --editable . --force - 全局 PATH 支持：
若当前终端未包含
~/.local/bin，系统已在全局 PATH（C:\Users\Administrator\.gemini\antigravity\bin\）配置了二进制包装器，可直接在任意目录（如E:\Chassis control）执行embedded-mcp。
所有板卡定义存放于 config/boards/*.json 中，系统在任何目录下运行都会自动定位到本目录，支持自动热重载。
{
"id": "board_a",
"name": "ATK-HSWL-CMSIS-DAP Board",
"adapter": "generic",
"match": {
"vid": 1240,
"pid": 223,
"serial_number": "ATK_20190528",
"port": "COM4"
},
"serial": {
"baudrate": 115200,
"bytesize": 8,
"parity": "N",
"stopbits": 1,
"dtr": null,
"rts": null,
"timeout": 0.05,
"gateway": {
"bind": "127.0.0.1",
"data_port": 5001,
"control_port": 5101
}
},
"metadata": {
"description": "Robot chassis main control board",
"controller": "STM32",
"shell_prompt": "dock:/$ "
}
}match：支持基于vid/pid、serial_number或显式port自动过滤并热插拔寻址，自动过滤 Windows 虚假 ACPI 端口。dtr: null, rts: null：严格杜绝 Windows 串口打开时拉低引脚意外复位单片机。
你可以在系统中的任何目录（例如 E:\Chassis control 或任意项目文件夹）打开终端直接使用：
# 列出系统中所有已注册板卡与当前匹配的物理端口
embedded-mcp board list
# 扫描宿主机当前可用的物理串口（已过滤虚假 ACPI 端口）
embedded-mcp board ports# 前台启动指定板卡的网关服务（若已有服务在运行，会自动友好提示）
embedded-mcp gateway run board_a
# 查询指定板卡的网关运行状态、波特率、收发字节数与控制器租约
embedded-mcp gateway status board_a# 查看最近 20 行历史日志（不抢占端口）
embedded-mcp serial tail board_a --lines 20
# 持续跟随实时输出（类似 Linux 的 tail -f，按 Ctrl+C 退出）
embedded-mcp serial tail board_a -f利用方案二事务池，命令在微秒级短借租约中排队下发，自动剥离回显并返回纯净内容：
# 查询当前电池电压
embedded-mcp serial exchange board_a "bat"
# 查询充电状态
embedded-mcp serial exchange board_a "charge_status"
# 查询底盘 Shell 支持的所有命令列表
embedded-mcp serial exchange board_a "help"
# 带自定义 Prompt 与超时时间的命令交互
embedded-mcp serial exchange board_a "status" --timeout 2000 --prompt "dock:/$ "除了原子单次命令外，支持像物理串口助手/串口终端一样直接交互敲命令：
-
方法 A：内置交互控制台（纯终端无依赖） 在任何终端中输入以下指令，直接进入板卡全双工 Shell 会话（按回车发送指令，输入
exit或Ctrl+C退出）：embedded-mcp console board_a # 或 embedded-mcp serial console board_a
-
方法 B：Netcat 终端直连 宿主机已内置
nc，直接连接 5001 端口：nc 127.0.0.1 5001
直接键盘敲入
bat、help等指令，单片机实时回显并输出。 -
方法 C：PuTTY / MobaXterm / SecureCRT 直连
- 协议选择：
Raw或Telnet - 主机 IP：
127.0.0.1，端口：5001 - 打开即是标准串口终端，支持快捷键输入与实时波形/日志回显。
- 协议选择：
本项目完整支持官方 MCP (Model Context Protocol) 2.x 协议标准，通过 stdio 与 Google Antigravity / Claude 互通。
位于 C:\Users\Administrator\.gemini\config\mcp_config.json：
{
"mcpServers": {
"embedded-mcp": {
"command": "C:\\Users\\Administrator\\.gemini\\antigravity\\bin\\embedded-mcp.exe",
"args": ["mcp"],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}位于 C:\Users\Administrator\.gemini\config\skills\embedded-mcp\SKILL.md，AI Agent 自动加载并具备底层硬件诊断与无锁协同操作能力。
| Tool 名称 | 核心用途 |
|---|---|
board_list |
获取注册的所有板卡及配置元数据 |
board_status |
查询目标板卡串口连通性、收发计数、活跃租约与缓冲区指标 |
serial_connect |
幂等确保板卡网关已启动连接物理串口 |
serial_tail |
安全跨多字节边界读取最近历史日志（N 读无需持锁） |
serial_exchange |
核心交互工具：原子微事务下发指令、匹配 Prompt、剥离回显 |
serial_write |
长命令或二进制数据受控写入（需配合 Lease） |
lease_acquire |
为独占性长任务（如固件刷写、连续测试）申请长租约 |
lease_release |
释放租约，恢复观察者模式 |
lease_renew |
租约续期心跳 |
你可以在 AI 持续监视、CLI 下发测试的同时，使用图形化上位机直连观察波形：
- 打开 PuTTY 或 VOFA+。
- 连接类型选择 TCP（或 Raw）。
- 主机 IP 填
127.0.0.1，端口填5001。 - 点击连接，即可实时接收底层完全相同、无任何延迟的原始数据流，彻底终结“调串口必须先关上位机”的历史。
后续对本库进行迭代、扩展适配新板卡或重构时，必须执行以下维护流程：
uv run pytest -v- 包含 20 项测试：单元测试、JSON-RPC 协议解析、跨 Chunk 汉字切片无损性、多客户端高并发多写排队事务、以及对物理硬件（COM4）的生命周期全流程测试。
uv run ruff check .- 要求 0 warning / 0 error，保持 100% 格式洁净。
- 在
config/boards/下新建<board_id>.json。 - 配置 VID/PID 或串口号与波特率。
- 运行
embedded-mcp board list验证识别。 - 运行
embedded-mcp serial tail <board_id>验证通信。