feat: refactor sgclaw around zeroclaw compat runtime
This commit is contained in:
zyl
217
third_party/zeroclaw/docs/i18n/zh-CN/hardware/arduino-uno-q-setup.zh-CN.md
vendored
Normal file
217
third_party/zeroclaw/docs/i18n/zh-CN/hardware/arduino-uno-q-setup.zh-CN.md
vendored
Normal file
@@ -0,0 +1,217 @@
|
||||
# Arduino Uno Q 上的 ZeroClaw — 分步指南
|
||||
|
||||
在 Arduino Uno Q 的 Linux 端运行 ZeroClaw。Telegram 通过 Wi-Fi 工作；GPIO 控制使用桥接（需要最小化的 App Lab 应用）。
|
||||
|
||||
---
|
||||
|
||||
## 已包含的内容（无需修改代码）
|
||||
|
||||
ZeroClaw 包含 Arduino Uno Q 所需的一切。**克隆仓库并按照本指南操作 —— 无需补丁或自定义代码。**
|
||||
|
||||
| 组件 | 位置 | 目的 |
|
||||
|-----------|----------|---------|
|
||||
| 桥接应用 | `firmware/uno-q-bridge/` | MCU 草图 + Python Socket 服务器（端口 9999）用于 GPIO |
|
||||
| 桥接工具 | `src/peripherals/uno_q_bridge.rs` | 通过 TCP 与桥接通信的 `gpio_read` / `gpio_write` 工具 |
|
||||
| 设置命令 | `src/peripherals/uno_q_setup.rs` | `zeroclaw peripheral setup-uno-q` 通过 scp + arduino-app-cli 部署桥接 |
|
||||
| 配置 schema | `board = "arduino-uno-q"`, `transport = "bridge"` | 在 `config.toml` 中支持 |
|
||||
|
||||
使用 `--features hardware` 构建以包含 Uno Q 支持。
|
||||
|
||||
---
|
||||
|
||||
## 前置条件
|
||||
|
||||
- 已配置 Wi-Fi 的 Arduino Uno Q
|
||||
- 安装在 Mac 上的 Arduino App Lab（用于初始设置和部署）
|
||||
- LLM 的 API 密钥（OpenRouter 等）
|
||||
|
||||
---
|
||||
|
||||
## 阶段 1：Uno Q 初始设置（一次性）
|
||||
|
||||
### 1.1 通过 App Lab 配置 Uno Q
|
||||
|
||||
1. 下载 [Arduino App Lab](https://docs.arduino.cc/software/app-lab/)（Linux 上是 AppImage）。
|
||||
2. 通过 USB 连接 Uno Q，开机。
|
||||
3. 打开 App Lab，连接到开发板。
|
||||
4. 按照设置向导操作：
|
||||
- 设置用户名和密码（用于 SSH）
|
||||
- 配置 Wi-Fi（SSID、密码）
|
||||
- 应用所有固件更新
|
||||
5. 记录显示的 IP 地址（例如 `arduino@192.168.1.42`），或稍后在 App Lab 的终端中通过 `ip addr show` 查找。
|
||||
|
||||
### 1.2 验证 SSH 访问
|
||||
|
||||
```bash
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
# 输入你设置的密码
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 阶段 2：在 Uno Q 上安装 ZeroClaw
|
||||
|
||||
### 选项 A：在设备上构建（更简单，约 20–40 分钟）
|
||||
|
||||
```bash
|
||||
# SSH 进入 Uno Q
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
|
||||
# 安装 Rust
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
|
||||
source ~/.cargo/env
|
||||
|
||||
# 安装构建依赖（Debian）
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y pkg-config libssl-dev
|
||||
|
||||
# 克隆 zeroclaw（或 scp 你的项目）
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
# 构建（在 Uno Q 上约 15–30 分钟）
|
||||
cargo build --release --features hardware
|
||||
|
||||
# 安装
|
||||
sudo cp target/release/zeroclaw /usr/local/bin/
|
||||
```
|
||||
|
||||
### 选项 B：在 Mac 上交叉编译（更快）
|
||||
|
||||
```bash
|
||||
# 在 Mac 上 — 添加 aarch64 目标
|
||||
rustup target add aarch64-unknown-linux-gnu
|
||||
|
||||
# 安装交叉编译器（macOS；链接所需）
|
||||
brew tap messense/macos-cross-toolchains
|
||||
brew install aarch64-unknown-linux-gnu
|
||||
|
||||
# 构建
|
||||
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc cargo build --release --target aarch64-unknown-linux-gnu --features hardware
|
||||
|
||||
# 复制到 Uno Q
|
||||
scp target/aarch64-unknown-linux-gnu/release/zeroclaw arduino@<UNO_Q_IP>:~/
|
||||
ssh arduino@<UNO_Q_IP> "sudo mv ~/zeroclaw /usr/local/bin/"
|
||||
```
|
||||
|
||||
如果交叉编译失败，使用选项 A 在设备上构建。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 3：配置 ZeroClaw
|
||||
|
||||
### 3.1 运行引导配置（或手动创建配置）
|
||||
|
||||
```bash
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
|
||||
# 快速配置
|
||||
zeroclaw onboard --api-key YOUR_OPENROUTER_KEY --provider openrouter
|
||||
|
||||
# 或手动创建配置
|
||||
mkdir -p ~/.zeroclaw/workspace
|
||||
nano ~/.zeroclaw/config.toml
|
||||
```
|
||||
|
||||
### 3.2 最小化 config.toml
|
||||
|
||||
```toml
|
||||
api_key = "YOUR_OPENROUTER_API_KEY"
|
||||
default_provider = "openrouter"
|
||||
default_model = "anthropic/claude-sonnet-4-6"
|
||||
|
||||
[peripherals]
|
||||
enabled = false
|
||||
# 通过桥接使用 GPIO 需要完成阶段 4
|
||||
|
||||
[channels_config.telegram]
|
||||
bot_token = "YOUR_TELEGRAM_BOT_TOKEN"
|
||||
allowed_users = ["*"]
|
||||
|
||||
[gateway]
|
||||
host = "127.0.0.1"
|
||||
port = 42617
|
||||
allow_public_bind = false
|
||||
|
||||
[agent]
|
||||
compact_context = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 阶段 4：运行 ZeroClaw 守护进程
|
||||
|
||||
```bash
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
|
||||
# 运行守护进程（Telegram 轮询通过 Wi-Fi 工作）
|
||||
zeroclaw daemon --host 127.0.0.1 --port 42617
|
||||
```
|
||||
|
||||
**此时：** Telegram 聊天正常工作。向你的机器人发送消息 —— ZeroClaw 会响应。还没有 GPIO 功能。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 5：通过桥接实现 GPIO（ZeroClaw 自动处理）
|
||||
|
||||
ZeroClaw 包含桥接应用和设置命令。
|
||||
|
||||
### 5.1 部署桥接应用
|
||||
|
||||
**从你的 Mac**（在 zeroclaw 仓库中）：
|
||||
```bash
|
||||
zeroclaw peripheral setup-uno-q --host 192.168.0.48
|
||||
```
|
||||
|
||||
**从 Uno Q**（已 SSH 连接）：
|
||||
```bash
|
||||
zeroclaw peripheral setup-uno-q
|
||||
```
|
||||
|
||||
这会将桥接应用复制到 `~/ArduinoApps/uno-q-bridge` 并启动。
|
||||
|
||||
### 5.2 添加到 config.toml
|
||||
|
||||
```toml
|
||||
[peripherals]
|
||||
enabled = true
|
||||
|
||||
[[peripherals.boards]]
|
||||
board = "arduino-uno-q"
|
||||
transport = "bridge"
|
||||
```
|
||||
|
||||
### 5.3 运行 ZeroClaw
|
||||
|
||||
```bash
|
||||
zeroclaw daemon --host 127.0.0.1 --port 42617
|
||||
```
|
||||
|
||||
现在当你向 Telegram 机器人发送 *"Turn on the LED"* 或 *"Set pin 13 high"* 时，ZeroClaw 会通过桥接使用 `gpio_write`。
|
||||
|
||||
---
|
||||
|
||||
## 命令摘要（从头到尾）
|
||||
|
||||
| 步骤 | 命令 |
|
||||
|------|---------|
|
||||
| 1 | 在 App Lab 中配置 Uno Q（Wi-Fi、SSH） |
|
||||
| 2 | `ssh arduino@<IP>` |
|
||||
| 3 | `curl -sSf https://sh.rustup.rs \| sh -s -- -y && source ~/.cargo/env` |
|
||||
| 4 | `sudo apt-get install -y pkg-config libssl-dev` |
|
||||
| 5 | `git clone https://github.com/zeroclaw-labs/zeroclaw.git && cd zeroclaw` |
|
||||
| 6 | `cargo build --release --features hardware` |
|
||||
| 7 | `zeroclaw onboard --api-key KEY --provider openrouter` |
|
||||
| 8 | 编辑 `~/.zeroclaw/config.toml`（添加 Telegram bot_token） |
|
||||
| 9 | `zeroclaw daemon --host 127.0.0.1 --port 42617` |
|
||||
| 10 | 向 Telegram 机器人发送消息 —— 它会响应 |
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
- **"command not found: zeroclaw"** — 使用完整路径：`/usr/local/bin/zeroclaw` 或确保 `~/.cargo/bin` 在 PATH 中。
|
||||
- **Telegram 不响应** — 检查 bot_token、allowed_users，以及 Uno Q 有互联网连接（Wi-Fi）。
|
||||
- **内存不足** — 保持特性最小化（Uno Q 使用 `--features hardware`）；考虑设置 `compact_context = true`。
|
||||
- **GPIO 命令被忽略** — 确保桥接应用正在运行（`zeroclaw peripheral setup-uno-q` 会部署并启动它）。配置必须包含 `board = "arduino-uno-q"` 和 `transport = "bridge"`。
|
||||
- **LLM 提供商（GLM/智谱）** — 使用 `default_provider = "glm"` 或 `"zhipu"`，并在环境或配置中设置 `GLM_API_KEY`。ZeroClaw 使用正确的 v4 端点。
|
||||
Reference in New Issue
Block a user