48 lines
2.1 KiB
Markdown
48 lines
2.1 KiB
Markdown
# tools/serial_tool/ — Python 串口助手
|
|
|
|
> **常驻 daemon + CLI** 架构的串口工具：后台持续收串口日志，CLI 按需查询/发送，
|
|
> 避免反复开关串口导致日志丢失（台架与测试的主力观测工具）。
|
|
|
|
## 文件一览
|
|
|
|
| 文件/目录 | 作用 |
|
|
|---|---|
|
|
| `serial_tool.py` | 串口助手主程序（daemon 与 CLI 合一） |
|
|
| `state/` | **运行时状态目录** |
|
|
| `state/serial.log` | 串口原始日志（`stack_report.py -s` 的输入之一） |
|
|
| `state/daemon.log` | daemon 自身运行日志 |
|
|
| `state/meta.json` | daemon 元数据（端口、状态等） |
|
|
|
|
## 使用方式
|
|
|
|
```bash
|
|
# 打开串口（daemon 自动拉起；端口缺省取 .opencode/serial_config.json，不必带参数）
|
|
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py open
|
|
|
|
# 看有哪些口 / 配置口是否还在位（单一候选时回 hint）
|
|
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py ports
|
|
|
|
# 读日志（先过滤后截尾）/ 发送 / 等静默
|
|
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py log --tail 50 --grep "App init OK"
|
|
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py send "<命令>"
|
|
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py wait-idle --settle-ms 8000 --max-ms 30000
|
|
|
|
# 状态 / 关闭
|
|
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py status
|
|
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py close
|
|
```
|
|
|
|
> 全部命令输出 JSON、退出码 0/1/2/3；具体子命令以 `--help` 为准。
|
|
> 抓开机日志的顺序是 `open` → `clear` → 烧录/复位 → `wait-idle` → 读日志（采集必须先于烧录）。
|
|
|
|
## ⚠️ 注意
|
|
|
|
- **单写者**：串口同一时刻只能被一个进程占用——别同时用本工具和其它串口程序
|
|
- `state/serial.log` 是 `[STACK]` 运行时水位的来源，`scripts/stack_report.py -s` 直接读它
|
|
- `state/` 是运行时数据，**不入库**
|
|
|
|
## 相关文档
|
|
|
|
- `docs/测试说明/串口助手使用指南.md` — 命令用法 / 工作流 / 排障
|
|
- `docs/测试说明/串口助手设计说明.md` — 契约 / daemon 行为 / 陷阱
|