ZeroClaw 让微控制器（MCU，Microcontroller Unit）和单板计算机（SBC，Single Board Computer）能够动态解释自然语言命令，生成硬件特定代码，并实时执行外设交互。
目标： ZeroClaw 作为具备硬件感知能力的 AI 代理，能够：
- 通过渠道（WhatsApp、Telegram）接收自然语言触发（例如"移动 X 机械臂"、"打开 LED"）
- 获取准确的硬件文档（数据手册、寄存器映射）
- 使用 LLM（大语言模型，如 Gemini、本地开源模型）合成 Rust 代码/逻辑
- 执行逻辑操作外设（GPIO、I2C、SPI）
- 持久化优化后的代码供未来复用
思维模型： ZeroClaw = 理解硬件的大脑。外设 = 它控制的手臂和腿。
目标： 支持 Wi-Fi 的开发板（ESP32、树莓派）。
ZeroClaw 直接运行在设备上。开发板启动 gRPC/nanoRPC 服务器，与本地外设通信。
┌─────────────────────────────────────────────────────────────────────────────┐
│ ZeroClaw on ESP32 / Raspberry Pi (Edge-Native) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────────────┐ │
│ │ Channels │───►│ Agent Loop │───►│ RAG: datasheets, register maps │ │
│ │ WhatsApp │ │ (LLM calls) │ │ → LLM context │ │
│ │ Telegram │ └──────┬───────┘ └─────────────────────────────────┘ │
│ └─────────────┘ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ 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"请求使用
所有操作都在设备上完成。 不需要主机。
目标： 通过 USB / J-Link / Aardvark 连接到主机（macOS、Linux）的硬件。
ZeroClaw 运行在主机上，并维护到目标的硬件感知链接。用于开发、内省和烧录。
┌─────────────────────┐ ┌──────────────────────────────────┐
│ ZeroClaw on Mac │ USB / J-Link / │ STM32 Nucleo-F401RE │
│ │ Aardvark │ (or other MCU) │
│ - Channels │ ◄────────────────► │ - Memory map │
│ - LLM │ │ - Peripherals (GPIO, ADC, I2C) │
│ - Hardware probe │ VID/PID │ - Flash / RAM │
│ - Flash / debug │ discovery │ │
└─────────────────────┘ └──────────────────────────────────┘
工作流：
- 用户发送 Telegram 消息："这个 USB 设备上的可读内存地址是什么？"
- ZeroClaw 识别连接的硬件（VID/PID、架构）
- 执行内存映射；建议可用的地址空间
- 将结果返回给用户
或：
- 用户："将这个固件烧录到 Nucleo"
- ZeroClaw 通过 OpenOCD 或 probe-rs 写入/烧录
- 确认成功
或：
- ZeroClaw 自动发现："STM32 Nucleo 位于 /dev/ttyACM0，ARM Cortex-M4"
- 建议："我可以读取/写入 GPIO、ADC、闪存。你想做什么？"
| 方面 | 边缘原生 | 主机介导 |
|---|---|---|
| ZeroClaw 运行位置 | 设备（ESP32、树莓派） | 主机（Mac、Linux） |
| 硬件链接 | 本地（GPIO、I2C、SPI） | USB、J-Link、Aardvark |
| LLM | 设备端或云端（Gemini） | 主机（云端或本地） |
| 使用场景 | 生产环境、独立运行 | 开发、调试、内省 |
| 渠道 | WhatsApp 等（通过 Wi-Fi） | Telegram、CLI 等 |
对于没有 Wi-Fi 的开发板，或在边缘原生模式完全就绪之前：
主机运行 ZeroClaw；外设运行最小化固件。通过串口传输简单 JSON。
ZeroClaw 运行在树莓派上；通过 rppal 或 sysfs 访问 GPIO。不需要单独的固件。
| 要求 | 描述 |
|---|---|
| 语言 | 纯 Rust。嵌入式目标（STM32、ESP32）适用时使用 no_std。 |
| 通信 | 轻量级 gRPC 或 nanoRPC 栈，用于低延迟命令处理。 |
| 动态执行 | 安全地即时运行 LLM 生成的逻辑：用于隔离的 Wasm 运行时，或支持时使用动态链接。 |
| 文档检索 | RAG（检索增强生成）流水线，将数据手册片段、寄存器映射和引脚定义输入到 LLM 上下文。 |
| 硬件发现 | USB 设备基于 VID/PID 的识别；架构检测（ARM Cortex-M、RISC-V 等）。 |
- 索引： 数据手册、参考手册、寄存器映射（PDF → 分块、嵌入向量）。
- 检索： 用户查询（"打开 LED"）时，获取相关片段（例如目标开发板的 GPIO 部分）。
- 注入： 添加到 LLM 系统提示或上下文。
- 结果： LLM 生成准确的、开发板特定的代码。
| 选项 | 优点 | 缺点 |
|---|---|---|
| Wasm | 沙箱化、可移植、无 FFI | 开销大；Wasm 对硬件访问有限 |
| 动态链接 | 原生速度、完全硬件访问 | 平台特定；安全隐患 |
| 解释型 DSL | 安全、可审计 | 速度慢；表达能力有限 |
| 预编译模板 | 快速、安全 | 灵活性较低；需要模板库 |
建议： 从预编译模板 + 参数化开始；稳定后演进到 Wasm 支持用户自定义逻辑。
# 边缘原生：在设备上运行（ESP32、树莓派）
zeroclaw agent --mode edge
# 主机介导：连接到 USB/J-Link 目标
zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0
zeroclaw agent --probe jlink
# 硬件内省
zeroclaw hardware discover
zeroclaw hardware introspect /dev/ttyACM0[peripherals]
enabled = true
mode = "host" # "edge" | "host"
datasheet_dir = "docs/datasheets" # RAG: 供 LLM 上下文使用的开发板特定文档
[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200
[[peripherals.boards]]
board = "rpi-gpio"
transport = "native"
[[peripherals.boards]]
board = "esp32"
transport = "wifi"
# 边缘原生：ZeroClaw 运行在 ESP32 上/// A hardware peripheral that exposes capabilities as tools.
#[async_trait]
pub trait Peripheral: Send + Sync {
fn name(&self) -> &str;
fn board_type(&self) -> &str; // e.g. "nucleo-f401re", "rpi-gpio"
async fn connect(&mut self) -> anyhow::Result<()>;
async fn disconnect(&mut self) -> anyhow::Result<()>;
async fn health_check(&self) -> bool;
/// Tools this peripheral provides (gpio_read, gpio_write, sensor_read, etc.)
fn tools(&self) -> Vec<Box<dyn Tool>>;
}- 启动： ZeroClaw 加载配置，读取
peripherals.boards。 - 连接： 为每个开发板创建
Peripheral实现，调用connect()。 - 工具： 收集所有连接外设的工具；与默认工具合并。
- 代理循环： 代理可以调用
gpio_write、sensor_read等 —— 这些调用委托给外设。 - 关闭： 对每个外设调用
disconnect()。
| 开发板 | 传输方式 | 固件 / 驱动 | 工具 |
|---|---|---|---|
| nucleo-f401re | 串口 | Zephyr / Embassy | gpio_read, gpio_write, adc_read |
| rpi-gpio | 原生 | rppal or sysfs | gpio_read, gpio_write |
| esp32 | 串口/websocket | ESP-IDF / Embassy | gpio, wifi, mqtt |
用于 ZeroClaw 和外设之间的低延迟、类型化 RPC：
- nanoRPC 或 tonic（gRPC）：Protobuf 定义的服务。
- 方法：
GpioWrite、GpioRead、I2cTransfer、SpiTransfer、MemoryRead、FlashWrite等。 - 支持流、双向调用和从
.proto文件生成代码。
对于不支持 gRPC 的开发板，通过串口传输简单 JSON：
请求（主机 → 外设）：
{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}响应（外设 → 主机）：
{"id":"1","ok":true,"result":"done"}- zeroclaw-firmware 或 zeroclaw-peripheral —— 独立的 crate/工作区。
- 目标：
thumbv7em-none-eabihf（STM32）、armv7-unknown-linux-gnueabihf（树莓派）等。 - STM32 使用
embassy或 Zephyr。 - 实现上述协议。
- 用户将其烧录到开发板；ZeroClaw 连接并发现能力。
- 添加
Peripheral特征、配置 schema、CLI（zeroclaw peripheral list/add） - 为代理添加
--peripheral标志 - 在 AGENTS.md 中记录
-
zeroclaw hardware discover：枚举 USB 设备（VID/PID） - 开发板注册表：映射 VID/PID → 架构、名称（例如 Nucleo-F401RE）
-
zeroclaw hardware introspect <path>：内存映射、外设列表
- 支持通过 USB CDC 连接 STM32 的
SerialPeripheral - 集成 probe-rs 或 OpenOCD 用于烧录/调试
- 工具：
gpio_read、gpio_write（未来支持 memory_read、flash_write）
- 数据手册索引（markdown/text → 分块）
- 硬件相关查询时检索并注入到 LLM 上下文
- 开发板特定提示增强
用法： 在 config.toml 的 [peripherals] 部分添加 datasheet_dir = "docs/datasheets"。按开发板命名放置 .md 或 .txt 文件（例如 nucleo-f401re.md、rpi-gpio.md）。_generic/ 目录下或名为 generic.md 的文件适用于所有开发板。通过关键词匹配检索分块并注入到用户消息上下文。
- 树莓派上的 ZeroClaw（通过 rppal 实现原生 GPIO）
- 用于本地外设访问的 gRPC/nanoRPC 服务器
- 代码持久化（存储合成的片段）
- 主机介导的 ESP32（串口传输）—— 与 STM32 相同的 JSON 协议
-
esp32固件 crate（firmware/esp32）—— 通过 UART 实现 GPIO - 硬件注册表中的 ESP32（CH340 VID/PID）
- ESP32 上运行 ZeroClaw（Wi-Fi + LLM，边缘原生）—— 未来
- 基于 Wasm 或模板的 LLM 生成逻辑执行
用法： 将 firmware/esp32 烧录到 ESP32，在配置中添加 board = "esp32"、transport = "serial"、path = "/dev/ttyUSB0"。
- 模板库：参数化的 GPIO/I2C/SPI 片段
- 可选：用于用户自定义逻辑的 Wasm 运行时（沙箱化）
- 持久化和复用优化的代码路径
- 串口路径： 验证
path在白名单中（例如/dev/ttyACM*、/dev/ttyUSB*）；永远不允许任意路径。 - GPIO： 限制暴露的引脚；避免电源/复位引脚。
- 外设上无密钥： 固件不应存储 API 密钥；主机处理认证。
- 在裸 STM32 上运行完整 ZeroClaw（无 Wi-Fi、RAM 有限）—— 改用主机介导模式
- 实时保证 —— 外设是尽力而为的
- LLM 生成的任意原生代码执行 —— 优先使用 Wasm 或模板
- adding-boards-and-tools.md — 如何添加开发板和数据手册
- network-deployment.md — 树莓派和网络部署
- Zephyr RTOS Rust support
- Embassy — 异步嵌入式框架
- rppal — Rust 实现的树莓派 GPIO
- STM32 Nucleo-F401RE
- tonic — Rust 实现的 gRPC
- probe-rs — ARM 调试探针、烧录、内存访问
- nusb — USB 设备枚举（VID/PID）
"像 ESP、树莓派或带 Wi-Fi 的开发板可以连接到 LLM（Gemini 或开源模型）。ZeroClaw 运行在设备上，创建自己的 gRPC 服务，启动服务并与外设通信。用户通过 WhatsApp 询问：'移动 X 机械臂'或'打开 LED'。ZeroClaw 获取准确的文档，编写代码，执行它，优化存储，运行并打开 LED —— 所有操作都在开发板上完成。
对于通过 USB/J-Link/Aardvark 连接到我 Mac 的 STM Nucleo：我 Mac 上的 ZeroClaw 访问硬件，在设备上安装或写入想要的内容，并返回结果。示例：'嘿 ZeroClaw，这个 USB 设备上的可用/可读地址是什么？'它能找出连接的内容和位置并给出建议。"