mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
SiYue-ZO
92 lines
3.4 KiB
Markdown
92 lines
3.4 KiB
Markdown
# 当前硬件支持现状与串口 Tool 方案
|
||
|
||
## 现状结论
|
||
|
||
当前项目已有的硬件相关能力主要分为两条线：
|
||
|
||
1. 设备事件监控
|
||
- `pkg/devices` 已实现设备事件服务。
|
||
- 当前只有 Linux USB 热插拔事件源 `pkg/devices/sources/usb_linux.go`。
|
||
- 能力定位是“发现和通知”，不是“总线读写控制”。
|
||
|
||
2. 硬件控制 Tool
|
||
- `pkg/tools/hardware/i2c*.go`：I2C Tool，支持 `detect`、`scan`、`read`、`write`。
|
||
- `pkg/tools/hardware/spi*.go`：SPI Tool，支持 `list`、`transfer`、`read`。
|
||
- 这两类 Tool 当前都只在 Linux 主机上启用，直接依赖 `/dev/i2c-*` 与 `/dev/spidev*`。
|
||
|
||
因此，项目在“硬件支持能力”上已经具备：
|
||
|
||
- Linux USB 设备插拔感知
|
||
- Linux I2C 总线控制
|
||
- Linux SPI 总线控制
|
||
|
||
但还缺少：
|
||
|
||
- 串口/UART 控制
|
||
- macOS / Windows 下可直接使用的硬件控制 Tool
|
||
- 面向统一硬件抽象的跨总线能力模型
|
||
|
||
## 本次新增
|
||
|
||
本次新增内建 `serial` Tool，并接入现有 Tool 体系：
|
||
|
||
- 配置项：`tools.serial.enabled`
|
||
- Tool 注册：`pkg/agent/agent_init.go`
|
||
- Web 工具页：`/api/tools` 能展示与切换 `serial`
|
||
- 前端状态文案：新增 `requires_serial_platform`
|
||
|
||
## Serial Tool 设计
|
||
|
||
`serial` 采用无状态调用模型，每次请求都自行打开和关闭端口，避免在 agent 回合之间维护串口会话状态。
|
||
|
||
支持动作：
|
||
|
||
- `list`：枚举主机串口
|
||
- `read`：从串口读取指定长度字节
|
||
- `write`：向串口写入字节或文本
|
||
|
||
公共参数：
|
||
|
||
- `port`
|
||
- `baud`
|
||
- `data_bits`
|
||
- `parity`
|
||
- `stop_bits`
|
||
- `timeout_ms`
|
||
|
||
当前波特率实现边界：
|
||
|
||
- Windows 允许配置工具层接受的范围 `50-4000000`
|
||
- Linux / macOS 当前仅支持标准 termios 波特率，实际支持到 `230400`
|
||
- 因此 `baud` 的跨平台可移植取值应优先使用 `230400` 及以下的常见标准速率
|
||
|
||
安全约束：
|
||
|
||
- `write` 必须显式传 `confirm: true`
|
||
- 单次读写负载限制为 `4096` 字节
|
||
- `port` 只接受白名单串口名：
|
||
- Linux / macOS 仅允许 `/dev/tty*`、`/dev/cu.*` 及对应简写设备名
|
||
- Windows 仅允许 `COM\d+` 或 `\\.\COM\d+`
|
||
- 明确拒绝 `..`、普通文件绝对路径、盘符路径等非串口设备路径，避免路径穿越或误打开任意文件
|
||
|
||
## 跨平台实现边界
|
||
|
||
- Linux / macOS：
|
||
- 基于 `golang.org/x/sys/unix` 和 termios 配置串口参数。
|
||
- 当前仅接入标准 termios 波特率映射，最高到 `230400`，尚未扩展 `460800`、`921600`、`1000000`、`2000000` 等更高速率。
|
||
- 通过 `/dev/...` 枚举和访问设备。
|
||
|
||
- Windows：
|
||
- 基于 `kernel32` 串口 API 配置 `DCB` 和 `COMMTIMEOUTS`。
|
||
- 当前读写仍使用同步 `ReadFile` / `WriteFile`；一旦 syscall 已进入执行，turn context cancellation 不能立即打断，只能等待 `COMMTIMEOUTS` 触发后返回。
|
||
- 通过注册表 `HARDWARE\\DEVICEMAP\\SERIALCOMM` 枚举端口。
|
||
|
||
- 其他平台：
|
||
- `serial` Tool 显式返回 unsupported，不做静默降级。
|
||
|
||
## 后续建议
|
||
|
||
1. 如果需要持续交互式串口会话，建议再增加 session 型 Tool，而不是让 LLM 反复做短连接轮询。
|
||
2. 如果后续要支持 CAN、GPIO、PWM，建议抽出统一的硬件 capability 描述层，而不是继续只靠 Tool 名称区分。
|
||
3. 若需要生产级稳定性，建议补真实串口回环测试，至少覆盖 Linux PTY 和 Windows COM 模拟场景。
|