ESP Input Bridge
# ESP Input Bridge
**用 ESP32 硬件键鼠替换 Agent 的软件输入后端。** Agent 沿用原有的观察和决策流程,本项目负责动作转换、设备传输与 HID 执行,MCP 路径不调用第二个模型。
An MIT-licensed hardware input adapter: ESP32-C3 BLE HID, ESP32-S3 BLE/USB HID, and a lightweight local MCP plugin for existing agents.
## 两个固件
| 固件 | 蓝牙键鼠 | 有线 USB 键鼠 | 命令接收 |
| --- | --- | --- | --- |
| ESP32-C3 | 支持 | 不支持 | USB 串口 / BLE GATT |
| ESP32-S3 | 支持 | 支持 | USB CDC 串口 / BLE GATT |
共用源码和协议,分别生成芯片对应的二进制。C3 是 RISC-V,S3 是 Xtensa,不能交叉烧录。插件通过 `ping` 握手识别型号和能力。S3 的 `output=auto` 优先使用已就绪的 USB,否则使用 BLE;批次中断线不会切换到另一个输出。
S3 必须连接开发板的**原生 USB OTG 口**。C3 原生 USB 仅作串口/JTAG,不能提供 USB HID:[乐鑫说明](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jtag-console.html)。
**C3 的实板烧录和 OTA 验证记录见 [OTA 文档](docs/OTA.md)。** 编译、模拟、硬件与应用结果分别记录,不保证绕过软件的自动化检测。
## 安装主机端
Python 3.11+:
```bash
git clone https://github.com/jensengao194-spec/esp-input-bridge.git
cd esp-input-bridge
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/esp-use mcp --demo
```
最后一条启动 stdio MCP 服务,应由 MCP 客户端连接。可视演示可直接运行:
```bash
.venv/bin/esp-use demo
.venv/bin/esp-use serve
```
控制台为 `http://127.0.0.1:8765`。演示在模拟表单里输入 `Hello ESP32-C3!` 并提交,不产生系统键鼠输入。
## 安装插件市场
本仓库含 `.agents/plugins/marketplace.json`:
```bash
codex plugin marketplace add jensengao194-spec/esp-input-bridge --ref main
codex plugin add esp-input-bridge@esp-input-bridge
```
也可在桌面插件目录中添加此仓库市场。插件带有服务器 wheel、图标、配置示例与使用技能。首次按照插件 SETUP 运行 `scripts/setup.py`,在独立用户缓存虚拟环境中安装声明的依赖,再重新连接 MCP。启动器本身不自动联网安装。需要本地桌面任务和可用的 `python3`。
GitHub 插件市场与 OpenAI 公共目录是不同渠道。官方公共目录的本地 MCP 提交目前需要合作方白名单、身份验证及审核;本仓库市场可独立分发,不代表已通过公共目录审核。见[官方要求](https://developers.openai.com/plugins/deploy/desktop-only)。
## MCP:三个工具
| 工具 | 行为 |
| --- | --- |
| `observe(image=true)` | 返回新 observation ID、简短状态及可选图片 |
| `act(observation_id, actions, image=false)` | 执行最多 8 个动作,返回下一次观察状态 |
| `stop()` | 停止会话并尝试释放输入,重启服务后才能再次输入 |
动作:`move_to`、`move`、`click`、`scroll`、`key`、`type_text`、`wait`。一次点击示例:
```json
[
{"type":"move_to","x":180,"y":245},
{"type":"click","button":"left","count":1}
]
```
坐标相对于观察图片,区域原点与缩放由本地映射。鼠标位置修正、拆键码、分片和 ACK 全在本地,不让模型逐包调用。`type_text` 支持 US ASCII;中文需显式 IME 按键流程。
`act` 默认只返回状态,需要视觉决策时再请求图像。图片以原生 MCP ImageContent 返回,不把 Base64 塞进普通文本。MCP 不保存日志,除非设置 `bridge.output_dir`。
## 配置硬件
无配置时默认是明确标记的 demo 模式。复制 `bridge.example.toml` 到 `~/.config/esp-input-bridge/config.toml`,或通过 `ESP_INPUT_CONFIG` 指定文件。不需要模型 API Key。
```toml
[bridge]
mode = "hardware" # demo / preview / hardware
[observation]
monitor = 1
max_width = 1280
[transport]
kind = "serial" # serial / ble
port = "/dev/cu.usbmodem_REPLACE" # Windows: COMx; Linux: /dev/ttyACMx
output = "auto" # auto / ble / usb
token_env = "ESP_HID_TOKEN"
```
BLE 控制通道用 `address` 替代 `port`,可用 `.venv/bin/esp-use scan` 发现地址。命令输入和 HID 输出是独立通道:通过 USB 控制 C3,它仍以蓝牙键鼠输出。
公开固件不含共享 token,首次通过物理串口设置:
```bash
export ESP_HID_TOKEN="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
.venv/bin/esp-use provision --port /dev/cu.usbmodem_REPLACE
.venv/bin/esp-use pair --port /dev/cu.usbmodem_REPLACE
.venv/bin/esp-use device --port /dev/cu.usbmodem_REPLACE
```
保存 token,并在 MCP 服务进程环境中提供相同 `ESP_HID_TOKEN`。凭证保存在板上 NVS。修改已有凭证还需设置 `ESP_HID_CURRENT_TOKEN`;不能通过 BLE 配置或重置。凭证不能放进公开仓库或插件包。
`pair` 通过 USB 验证 token 后打开 120 秒窗口,并显示一次性六位配对码;在目标电脑的蓝牙配对界面输入该码。每次窗口只接受一次新连接尝试,成功、失败、断线或超时均关闭。需要另一个 BLE 控制端时,重新从 USB 打开窗口。正常重连使用已绑定密钥,不重复输入配对码。默认不接受新设备,也不自动覆盖旧绑定;丢失绑定时通过 USB 执行 `esp-use forget-bonds --port ...`,再重新配对。详见[安全说明](docs/SECURITY.md)。
观察进程必须运行在接收键鼠输入的电脑上。macOS 需给启动程序屏幕录制权限,BLE 另需蓝牙权限;Linux 目前要求 X11。`.venv/bin/esp-use doctor` 只检查环境,不连接硬件。
## 编译与打包
将 PlatformIO 与 MCP 依赖环境分开:
```bash
python3 -m venv .pio-venv
.pio-venv/bin/python -m pip install -r firmware/requirements.txt
PLATFORMIO_CORE_DIR="$PWD/.platformio" .pio-venv/bin/pio run -d firmware -e esp32c3_usb -e esp32s3_usb
.venv/bin/python scripts/package_firmware.py
.venv/bin/pytest -q
.venv/bin/python scripts/build_plugin.py
```
固定 pioarduino `55.03.37`、Arduino-ESP32 `3.3.7`、NimBLE `2.3.9`、ArduinoJson `7.4.2`。NimBLE 升级修复 C3 在 Arduino 3.3.7 下初始化崩溃的问题。默认 C3 DevKitM-1 与 S3 DevKitC-1 板型;其他板型需核对 Flash 和 USB 接法。可选 `esp32c3_uart` / `esp32s3_uart` 环境供 USB-UART 控制口使用。
C3 使用 4MiB A/B 分区,蓝牙升级自动使用二进制窗口传输,并在重启后确认新镜像。使用方式及回滚行为见 [OTA 文档](docs/OTA.md),控制链路延迟实测见 [LATENCY](docs/LATENCY.md)。历史发布包保留其原版本构建内容。
固件打包脚本生成 `dist/esp-input-bridge-{esp32c3,esp32s3}-0.3.1.zip` 和 `dist/firmware-0.3.1/manifest.json`,保留历史版本路径。插件包为 `dist/esp-input-bridge-plugin-0.3.1.zip`,版本取自主机项目和插件 manifest,并核对两者一致;包内仅包含当前版本 wheel,历史 wheel 保留在原处。`firmware.bin` 是应用镜像,不能单独当作地址 0 的完整 Flash 镜像;首次烧录需按 manifest 使用 bootloader、分区表、boot_app0 与应用镜像。镜像分段烧录不覆盖 NVS,禁止跨芯片烧录。
插件 ZIP 带服务器 wheel。首次 setup 从用户配置的 Python 包索引安装声明的依赖,不修改系统 Python。官方目录的资格与审核独立于本地打包成功。
主机端 0.3.1 复用同一观察的 JPEG、哈希和 Base64,规划结果完成即继续执行;蓝牙只保留当前请求的 ACK,断线及时停止等待。可用以下命令复测主机开销,运行时不连接板子或发送输入:
```bash
.venv/bin/python scripts/benchmark_host.py --iterations 30
```
基准范围与前后结果见 [主机优化记录](docs/HOST_OPTIMIZATIONS.md)。使用新版插件包后需运行该包的 setup 并重新连接 MCP;已安装的 0.2.0 缓存不会随源码修改而自动更新。
停止按钮、Ctrl+C、MCP stop、或日志目录里的 STOP 文件会停止输入并尝试释放。设备使用有界按键/点击脉冲、30 秒租约,未知投递不自动重发。链路失效时无法保证释放报告送达;ACK 不代表软件完成操作,仍应观察结果。
## 文档与开源
- [协议](docs/PROTOCOL.md) · [验证边界](docs/VALIDATION.md)
- [隐私](docs/PRIVACY.md) · [条款](docs/TERMS.md) · [第三方组件](THIRD_PARTY.md)
- [MIT License](LICENSE)
旧的 Responses / Chat Completions / 自定义 HTTP 规划演示仍可用 `run` 命令和 `config.example.toml` 运行,它不是插件的核心执行路径。
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: observe reads state, act performs input actions, and stop ends the session. There is no meaningful overlap in intent or selection risk.
All three names are short lowercase imperative verbs with a consistent style. The convention is predictable across the entire tool set.
Three tools is a tight, well-scoped surface for an input bridge: observe, act, and stop correspond directly to the core interaction loop. Each tool earns its place, with no redundant or filler operations.
The observe-act-stop loop covers basic operation, but stopping is a dead end unless the server is restarted externally. There is no explicit start/reset tool and no way to discover supported action types, which are notable gaps for agent use.