# Nucleo-F401RE 上的 ZeroClaw — 分步指南

在 Mac 或 Linux 主机上运行 ZeroClaw。通过 USB 连接 Nucleo-F401RE。通过 Telegram 或 CLI 控制 GPIO（LED、引脚）。

---

## 通过 Telegram 获取开发板信息（无需固件）

ZeroClaw 可以通过 USB 从 Nucleo 读取芯片信息，**无需烧录任何固件**。向你的 Telegram 机器人发送消息：

- *"我有什么开发板信息？"*
- *"开发板信息"*
- *"连接了什么硬件？"*
- *"芯片信息"*

代理使用 `hardware_board_info` 工具返回芯片名称、架构和内存映射。启用 `probe` 特性时，它会通过 USB/SWD 读取实时数据；否则返回静态数据手册信息。

**配置：** 首先将 Nucleo 添加到 `config.toml`（以便代理知道查询哪个开发板）：

```toml
[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200
```

**CLI 替代方案：**

```bash
cargo build --features hardware,probe
zeroclaw hardware info
zeroclaw hardware discover
```

---

## 已包含的内容（无需修改代码）

ZeroClaw 包含 Nucleo-F401RE 所需的一切：

| 组件 | 位置 | 目的 |
|-----------|----------|---------|
| 固件 | `firmware/nucleo/` | Embassy Rust — USART2（115200）、gpio_read、gpio_write |
| 串门外设 | `src/peripherals/serial.rs` | 基于串口的 JSON 协议（与 Arduino/ESP32 相同） |
| 烧录命令 | `zeroclaw peripheral flash-nucleo` | 构建固件，通过 probe-rs 烧录 |

协议：换行符分隔的 JSON。请求：`{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}`。响应：`{"id":"1","ok":true,"result":"done"}`。

---

## 前置条件

- Nucleo-F401RE 开发板
- USB 线（USB-A 转 Mini-USB；Nucleo 内置 ST-Link）
- 烧录所需：`cargo install probe-rs-tools --locked`（或使用[安装脚本](https://probe.rs/docs/getting-started/installation/)）

---

## 阶段 1：烧录固件

### 1.1 连接 Nucleo

1. 通过 USB 将 Nucleo 连接到 Mac/Linux。
2. 开发板会显示为 USB 设备（ST-Link）。现代系统不需要单独的驱动。

### 1.2 通过 ZeroClaw 烧录

在 zeroclaw 仓库根目录执行：

```bash
zeroclaw peripheral flash-nucleo
```

这会构建 `firmware/nucleo` 并运行 `probe-rs run --chip STM32F401RETx`。固件烧录后立即运行。

### 1.3 手动烧录（替代方案）

```bash
cd firmware/nucleo
cargo build --release --target thumbv7em-none-eabihf
probe-rs run --chip STM32F401RETx target/thumbv7em-none-eabihf/release/nucleo
```

---

## 阶段 2：查找串口

- **macOS：** `/dev/cu.usbmodem*` 或 `/dev/tty.usbmodem*`（例如 `/dev/cu.usbmodem101`）
- **Linux：** `/dev/ttyACM0`（或插入后查看 `dmesg`）

USART2（PA2/PA3）桥接到 ST-Link 的虚拟 COM 端口，因此主机看到一个串口设备。

---

## 阶段 3：配置 ZeroClaw

添加到 `~/.zeroclaw/config.toml`：

```toml
[peripherals]
enabled = true

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/cu.usbmodem101"   # 调整为你的端口
baud = 115200
```

---

## 阶段 4：运行和测试

```bash
zeroclaw daemon --host 127.0.0.1 --port 42617
```

或直接使用代理：

```bash
zeroclaw agent --message "Turn on the LED on pin 13"
```

引脚 13 = PA5 = Nucleo-F401RE 上的用户 LED（LD2）。

---

## 命令摘要

| 步骤 | 命令 |
|------|---------|
| 1 | 通过 USB 连接 Nucleo |
| 2 | `cargo install probe-rs-tools --locked` |
| 3 | `zeroclaw peripheral flash-nucleo` |
| 4 | 将 Nucleo 添加到 config.toml（path = 你的串口） |
| 5 | `zeroclaw daemon` 或 `zeroclaw agent -m "Turn on LED"` |

---

## 故障排除

- **flash-nucleo 无法识别** — 从仓库构建：`cargo run --features hardware -- peripheral flash-nucleo`。该子命令仅在仓库构建中包含，crates.io 安装版本不包含。
- **找不到 probe-rs** — `cargo install probe-rs-tools --locked`（`probe-rs` crate 是库；CLI 在 `probe-rs-tools` 中）
- **未检测到探针** — 确保 Nucleo 已连接。尝试其他 USB 线/端口。
- **找不到串口** — 在 Linux 上，将用户添加到 `dialout` 组：`sudo usermod -a -G dialout $USER`，然后注销/登录。
- **GPIO 命令被忽略** — 检查配置中的 `path` 与你的串口匹配。运行 `zeroclaw peripheral list` 验证。
