硬件外设设计：ZeroClaw

ZeroClaw 使微控制器（MCU）和单板计算机（SBC）能够动态解释自然语言命令，生成特定于硬件的代码，并实时执行外围设备交互。

1. 视觉

目标： ZeroClaw 作为一个硬件感知的 AI 代理，能够：

通过频道（如 WhatsApp、Telegram）接收自然语言触发指令（例如“移动 X 轴”、“打开 LED”）
获取准确的硬件文档（数据手册、寄存器映射）
使用大语言模型（如 Gemini、本地开源模型）合成 Rust 代码/逻辑
执行用于操作外设（GPIO、I2C、SPI）的逻辑
持久化优化后的代码，以便将来复用

心智模型： ZeroClaw = 理解硬件的大脑。外设 = 它控制的臂和腿。

2. 两种操作模式

模式 1：边缘原生（独立）

目标： 支持 Wi-Fi 的板子（ESP32、树莓派）。

ZeroClaw 直接在设备上运行。该板卡会启动一个 gRPC/nanoRPC 服务器，并与外围设备在本地进行通信。

ZeroClaw on ESP32 / Raspberry Pi (Edge-Native)

  Channels (WhatsApp, Telegram)
        │
        ▼
  Agent Loop (LLM calls) ──► RAG: datasheets, register maps ──► LLM context
        │
        ▼
  Code synthesis ──► Wasm / dynamic exec ──► GPIO / I2C / SPI ──► persist
        │
        ▼
  gRPC/nanoRPC server ◄──► Peripherals (GPIO, I2C, SPI, sensors, actuators)

工作流程：

用户通过 WhatsApp 发送：“打开引脚 13 上的 LED”
ZeroClaw 会获取特定板子的文档（例如 ESP32 GPIO 映射）
LLM 生成 Rust 代码
代码在沙箱中运行（Wasm 或动态链接）
GPIO 被切换；结果返回给用户
优化后的代码会被持久化，以便用于未来的“打开 LED”请求

所有操作均在设备本地完成。 无需主机。

模式 2：主机中介（开发/调试）

**目标：**通过 USB / J-Link 连接到主机的硬件。

ZeroClaw 在主机上运行，并与目标设备保持硬件感知的连接。用于开发、内省和烧录。

  ZeroClaw on Mac (host)              STM32 Nucleo-F401RE (or other MCU)
  ─────────────────────              ──────────────────────────────────
  - Channels                         - Memory map
  - LLM                              - Peripherals (GPIO, ADC, I2C)
  - Hardware probe        ◄────────► - Flash / RAM
  - Flash / debug
                       USB / J-Link
                       VID/PID discovery

工作流程：

用户通过 Telegram 发送：“这个 USB 设备上有哪些可读的内存地址？”
ZeroClaw 识别连接的硬件（VID/PID、架构）
执行内存映射；建议可用的地址空间
将结果返回给用户

或者：

将此固件刷写到 Nucleo
ZeroClaw 通过 OpenOCD 或 probe-rs 写入/烧录
确认成功

或者：

ZeroClaw 自动发现：“STM32 Nucleo 位于 /dev/ttyACM0，ARM Cortex-M4”
建议：“我可以读写 GPIO、ADC 和闪存。你想做什么？”

模式比较

方面	边缘原生	主机介导
ZeroClaw 运行在	设备（ESP32、RPi）	主机（Mac、Linux）
硬件链接	本地（GPIO、I2C、SPI）	USB, J-Link
LLM	在设备上或云端（Gemini）	主机（云端或本地）
用例	生产环境，独立部署	开发、调试、内省
频道	WhatsApp 等（通过 WiFi）	Telegram、命令行界面（CLI）等。

3. 传统/更简单的模式（LLM 边缘部署之前）

对于没有 WiFi 的板子，或者在 Edge-Native 完全就绪之前：

模式 A：主机 + 远程外设（通过串口连接 STM32）

主机运行 ZeroClaw；外设运行精简固件。通过串口传输简单的 JSON 数据。

模式 B：RPi 作为主机（原生 GPIO）

ZeroClaw 在树莓派上运行；通过 rppal 或 sysfs 访问 GPIO。无需单独的固件。

4. 技术要求

需求	描述
语言	纯 Rust 实现。在嵌入式目标平台（如 STM32、ESP32）上适用 `no_std`。
通信	用于低延迟命令处理的轻量级 gRPC 或 nanoRPC 堆栈。
动态执行	安全地运行即时生成的 LLM 逻辑：使用 Wasm 运行时进行隔离，或在支持的情况下使用动态链接。
文档检索	RAG（检索增强生成）管道，用于将数据表片段、寄存器映射和引脚图注入到 LLM 上下文中。
硬件发现	基于 VID/PID 的 USB 设备识别；架构检测（ARM Cortex-M、RISC-V 等）。

RAG 管道（数据表检索）

索引： 数据手册、参考手册、寄存器映射（已预转换的 .md / .txt → 分块、嵌入）。
检索： 在用户查询（如“打开 LED”）时，获取相关片段（例如目标板的 GPIO 部分）。
注入： 添加到 LLM 系统提示或上下文中。
结果： LLM 生成准确、针对特定板子的代码。

动态执行选项

选项	优点	缺点
Wasm	沙盒化、可移植、无 FFI	开销；Wasm 对硬件访问受限
动态链接	原生速度，完全硬件访问	特定于平台的；安全注意事项
解释型 DSL	安全、可审计	较慢；表达能力有限
预编译模板	快速、安全	灵活性较低；需要模板库

建议： 从预编译模板和参数化入手；待稳定后，再演进至使用 Wasm 实现用户自定义逻辑。

5. CLI 和配置

有关 zeroclaw hardware / zeroclaw peripheral 子命令的详细信息，请参阅 CLI 参考；有关 [peripherals] 和 [[peripherals.boards]] 字段的配置说明，请参阅配置参考。

6. 架构：外设作为扩展点

新特性：`Peripheral`

#![allow(unused)]
fn main() {
/// 一个将功能作为工具暴露的硬件外设。
#[async_trait]
pub trait Peripheral: Send + Sync {
    fn name(&self) -> &str;
    fn board_type(&self) -> &str;  // 例如 "nucleo-f401re"、"rpi-gpio"
    async fn connect(&mut self) -> anyhow::Result<()>;
    async fn disconnect(&mut self) -> anyhow::Result<()>;
    async fn health_check(&self) -> bool;
    /// 该外设提供的工具（gpio_read、gpio_write、sensor_read 等）
    fn tools(&self) -> Vec<Box<dyn Tool>>;
}
}

流程

启动： ZeroClaw 加载配置，检测到 peripherals.boards。
连接： 为每个板子创建一个 Peripheral 实现，并调用 connect()。
工具： 从所有连接的外设中收集工具；与默认工具合并。
**Agent 循环：**Agent 可以调用 gpio_write、sensor_read 等函数，这些函数会委托给外设处理。
关闭： 对每个外围设备调用 disconnect()。

板级支持

开发板通过规范注册表中的 USB VID/PID 进行标识：

开发板	架构	USB VID:PID
`nucleo-f401re`	ARM Cortex-M4	`0x0483`:`0x374b`
`nucleo-f411re`	ARM Cortex-M4	`0x0483`:`0x3748`
`arduino-uno`	AVR ATmega328P	`0x2341`:`0x0043`
`arduino-uno`	Arduino Uno Q / ATmega328P	`0x2341`:`0x0078`
`arduino-mega`	AVR ATmega2560	`0x2341`:`0x0042`
`cp2102`	USB-UART 桥接器	`0x10c4`:`0xea60`
`cp2102n`	USB-UART 桥接器	`0x10c4`:`0xea70`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x7523`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x55d4`

每个连接的板卡都通过某个子系统传输通道进行驱动：

传输	描述
`serial`	基于 USB CDC 串口的换行符分隔 JSON
`swd`	SWD 调试探针 (probe-rs)
`uf2`	UF2 大容量存储固件烧录
`native`	直接 Linux GPIO/I2C/SPI（rppal、sysfs）

每个板卡提供的基本工具都列在硬件子系统 → 运行时工具中。

7. 通信协议

gRPC / nanoRPC（边缘原生，主机中介）

用于 ZeroClaw 与外设之间的低延迟、类型化 RPC：

nanoRPC 或 tonic（gRPC）：由 Protobuf 定义的服务。
方法：GpioWrite、GpioRead、I2cTransfer、SpiTransfer、MemoryRead、FlashWrite 等。
启用从 .proto 文件进行流式双向调用和代码生成。

串行传输（主机中介，旧版）

适用于不支持 gRPC 的板子的简单 JSON 串行通信：

请求（主机 → 外设）：

{"id":"1","cmd":`gpio_write`,"参数":{固定:13,“值”:1}}

响应（外设 → 主机）：

{"id":"1",“好的”:true,"结果":完成}

8. 固件（独立仓库或 Crate）

zeroclaw-firmware 或 zeroclaw-peripheral：一个独立的 crate/workspace。
目标平台：thumbv7em-none-eabihf（STM32）、armv7-unknown-linux-gnueabihf（树莓派）等。
在 STM32 上使用 embassy 或 Zephyr。
实现上述协议。
用户将此固件刷写到开发板上；ZeroClaw 连接并发现其功能。

9. 能力层

该子系统采用分层构建，每一层均可独立使用。与其在此跟踪各阶段状态（随着工作的推进会逐渐失真），不如列出各层：

框架。 Peripheral trait、配置模式以及 zeroclaw peripheral CLI。--peripheral 标志将开发板接入到 agent 中。
主机协调发现。 zeroclaw hardware discover 通过 VID/PID 枚举 USB 设备；板卡注册表将其映射到架构和名称；zeroclaw hardware introspect <path> 报告内存映射和外设列表。
串行 / 探针传输。 SerialPeripheral 通过 USB CDC 承载 JSON 协议；probe 功能添加了用于刷写、内存映射和内存读取的 probe-rs SWD（参见 hardware_* 工具）。
RAG 流水线。 数据手册经过索引，并在硬件查询时注入到 LLM 上下文中。

用法： zeroclaw config set peripherals.datasheet-dir docs/datasheets。放置以板子命名的 .md 或 .txt 文件（例如 nucleo-f401re.md、rpi-gpio.md）。位于 _generic/ 目录中或名为 generic.md 的文件适用于所有板子。通过关键词匹配检索内容块，并将其注入到用户消息上下文中。
边缘原生（Raspberry Pi）。 ZeroClaw 通过 rppal 在 Pi 上运行，原生支持 GPIO（peripheral-rpi 特性）。
ESP32。 通过串行传输由主机中介，使用与 STM32 相同的 JSON 协议。ESP32 开发板通过其 CH340 USB VID/PID 注册在登记表中。

用法： 将 firmware/esp32 烧录到 ESP32，并在配置中添加 board = "esp32"、transport = "serial"、path = "/dev/ttyUSB0"。
动态执行。 LLM 生成的逻辑通过参数化模板运行，而沙盒化的 Wasm 运行时则是用户自定义逻辑的长期发展方向。

10. 安全注意事项

串行路径： 验证 path 是否在允许列表中（例如 /dev/ttyACM*、/dev/ttyUSB*）；绝不允许任意路径。
GPIO： 限制暴露的引脚；避免使用电源/复位引脚。
外设上不存储密钥： 固件不应存储 API 密钥；主机负责处理身份验证。

11. 非目标（暂时）

在裸机 STM32 上_直接_运行完整的 ZeroClaw（无 WiFi、RAM 有限），请改用 Host-Mediated 方式
实时性保证：外设采用尽力而为方式处理
来自 LLM 的任意本机代码执行：建议使用 Wasm 或模板

12. 相关文档

adding-boards-and-tools.md：如何添加开发板和数据手册
network-deployment.md：RPi 与网络部署

13. 参考文献

Zephyr RTOS Rust 支持
Embassy：异步嵌入式框架
rppal：Rust 编写的 Raspberry Pi GPIO 库
STM32 Nucleo-F401RE
tonic：Rust 的 gRPC 实现
probe-rs：ARM 调试探针、烧录、内存访问
nusb：USB 设备枚举（VID/PID）

14. 原始提示摘要

像 ESP、Raspberry Pi 或带 WiFi 的开发板可以连接到 LLM（Gemini 或开源模型）。ZeroClaw 在设备上运行，创建自己的 gRPC，启动它，并与外设进行通信。用户通过 WhatsApp 提问：“移动 X 机械臂”或“打开 LED”。ZeroClaw 获取准确的文档，编写代码，执行代码，以最优方式存储，运行它，并点亮 LED，这一切都在开发板上完成。

对于通过 USB/J-Link 连接到我的 Mac 的 STM Nucleo：ZeroClaw 可以从我的 Mac 访问硬件，在设备上安装或写入所需内容，然后返回结果。例如：“嘿 ZeroClaw，这个 USB 设备上有哪些可用/可读地址？”它可以判断连接了哪些设备以及连接位置，并给出建议。

Keyboard shortcuts

ZeroClaw Docs