133 lines
6.1 KiB
Markdown
133 lines
6.1 KiB
Markdown
# I2C-Lab — I2C 总线监控调试台
|
||
|
||
> 更新：2026-10-02。由 **RP2040 probe 固件**（`firmware/`，pico-sdk C，刷入
|
||
> BPI-Pico-RP2040）+ **PC 端 GUI**（`src/` / 打包版 `release/I2C-Lab.exe`）组成。
|
||
> 在任意 I2C 总线上**纯被动实时监听**：事务流解码 + 逻辑分析仪式波形快照。
|
||
> 前身 I2C-Inject（LT8619C 寄存器择机注入）保留在仓库备查；本工具是其
|
||
> "完整 I2C 调试台"路线的第一阶段（监控），主机读写与从机模拟见 §7 路线。
|
||
|
||
---
|
||
|
||
## 1. 它能做什么
|
||
|
||
| 能力 | 说明 |
|
||
|---|---|
|
||
| **实时事务流** | START→STOP 完整解码: 7bit 地址/RW/每字节 ACK/NAK/数据/收尾方式(含 repeated-START 标记) |
|
||
| **地址过滤** | 只看关心的地址(十六进制空格分隔), 其余只计数不入表 |
|
||
| **波形快照** | 一次抓取最近 256~16384 个 SDA/SCL 边沿, 逻辑分析仪视图: 滚轮缩放(光标锚点)/拖动平移/双击适配/START-STOP 刻线/事务标签 |
|
||
| **CSV 导出** | 全量事务(≤2 万条滚动池)导出, Excel 直接打开 |
|
||
| **固件计数** | 边沿数/事务数/环形覆盖丢包/疑似丢沿, 判断总线活动与负载 |
|
||
| **演示模式** | 无硬件看界面: 模拟 LT8619C demo 板 ~500ms 轮询流量 |
|
||
|
||
**被动性保证**: probe 两脚为纯输入(PIO 只读电平), 不加上拉、不驱动、
|
||
不改总线时序——挂在运行中的 demo 板上零干扰(与 I2C-Inject 同一接线规矩)。
|
||
|
||
## 2. 硬件准备
|
||
|
||
| BPI-Pico-RP2040 | 目标总线 |
|
||
|---|---|
|
||
| GP8（物理脚 11） | SDA |
|
||
| GP9（物理脚 12） | SCL |
|
||
| GND | GND |
|
||
|
||
- **不接 VCC、不外加上下拉**(总线由目标板自带上拉)
|
||
- 独立台架总线(无主)另说: 需 4.7kΩ 上拉×2 到 3.3V 才有静态高电平
|
||
- 固件把系统时钟超到 250MHz(vreg 1.15V), 100/400kHz 总线余量充足;
|
||
官方 USB 枚举不受影响
|
||
|
||
## 3. 刷固件(一次性)
|
||
|
||
1. 按住 BOOTSEL 上电, 出现 `RPI-RP2` U 盘
|
||
2. 把 `release/firmware/i2c_lab.uf2` 拖进去, 板子自动重启
|
||
3. 设备管理器出现 `USB 串行设备`(VID 2E8A)即就绪; LED 上电快闪 3 次后,
|
||
**常亮 = 监控流开启**
|
||
|
||
重新构建固件见 `firmware/` 源码与 §6。
|
||
|
||
## 4. GUI 使用
|
||
|
||
双击 `I2C-Lab.exe`(或 `python src/main.py`; `--demo` 进演示模式):
|
||
|
||
1. **固件串口卡**: 选带 `[RP2040]` 标记的端口 → 连接(日志出现版本横幅)
|
||
2. **监控卡**: 「开始监控」→ 事务表开始滚动; 「暂停滚动」冻结表格方便读
|
||
3. **地址过滤**: 如 `32 50`(十六进制); 空格分隔多个; 留空看全部
|
||
4. **波形卡**: 设边沿数(默认 2048) → 「抓取波形」→ SCL/SDA 双线时序图;
|
||
滚轮缩放, 拖动平移, 双击适配全宽; 绿/红虚线 = START/STOP
|
||
5. **导出CSV**: 保存当前全量事务池(不只表内可见行)
|
||
6. 主题: 跟随系统/浅色/深色(DLPilot/SerialMate 同款三件套)
|
||
|
||
表格列: `# | t0(us) | 时长us | 地址 | RW | ACK | 数据 | 收尾`。
|
||
地址 NAK 红色、截断/半字节断橙色、超 16 字节数据显示省略号(悬停看全量)。
|
||
|
||
## 5. 固件串口命令(可直接用串口终端调)
|
||
|
||
命令行一行一回, `=` 正常 / `!` 告警(全仓约定):
|
||
|
||
```
|
||
? 帮助
|
||
v 版本/时钟/角色
|
||
mon start 开 T 行事务流(监控中)
|
||
mon stop 停流
|
||
stats 计数: edges/trans/trans_drop/susp/ring_ovf/最近边沿距今
|
||
wave [n] 倒出最近 n(默认1024, 上限16384)个边沿: W 行 + 'W.' 收尾
|
||
boot 重进 BOOTSEL(免按按键)
|
||
```
|
||
|
||
T 行语法(与 PC 端 `i2cdec.py` 互为权威, 自测往返覆盖):
|
||
|
||
```
|
||
T <t0_us> <dur_us> <addr7:02X> <R|W> <flags> <acks> <n> <b1..bn>
|
||
flags: '-' stop | 'r' repeated-START 收尾 | 'c' 流截断 | 'p' 半字节断
|
||
可追加 'L' = 长事务截断(>56 字节只保留前段)
|
||
acks : n+1 个 'A'/'N', 首个是地址应答
|
||
W <t_us> <pins> pins bit0=SDA bit1=SCL
|
||
```
|
||
|
||
## 6. 重新构建固件
|
||
|
||
依赖(本机已装齐, 新机器对照):
|
||
|
||
- pico-sdk 2.3.1 + tinyusb 子模块(锁定提交), Arm GNU 13.x, CMake ≥3.16, Ninja
|
||
- pioasm 由 SDK 构建时自动编译; **宿主若无 C++ 编译器**(如本机), 预置
|
||
`firmware/build/pioasm/CMakeCache.txt` 的 `CMAKE_CXX_COMPILER` 为分号列表
|
||
形式的 zig(`pip install ziglang` 后指向 ziglang/zig.exe, 见 AGENTS.md 踩坑表)
|
||
- SDK 2.x 的 UF2 依赖 picotool(要拉 github); 本仓改用 `make_uf2.py`
|
||
(ELF→objcopy→bin→UF2, 与真机 UF2 逐字段核对 + 往返自检)
|
||
|
||
```powershell
|
||
cd firmware
|
||
cmake -B build -G Ninja -DPICO_SDK_PATH=D:/toolchain/pico-sdk `
|
||
-DPICO_TOOLCHAIN_PATH=D:/toolchain/arm-gnu-toolchain-13.3.rel1 `
|
||
-DPICO_BOARD=pico
|
||
cmake --build build
|
||
<arm-none-eabi-objcopy> -O binary build\i2c_lab.elf build\i2c_lab.bin
|
||
python make_uf2.py build\i2c_lab.bin build\i2c_lab.uf2
|
||
copy build\i2c_lab.uf2 ..\release\firmware\
|
||
```
|
||
|
||
## 7. 路线(与 I2C-Inject 的关系)
|
||
|
||
- [x] **v0.1 监控**(本版): 纯被动监听 + 事务流 + 波形快照
|
||
- [ ] **主机模式**: probe 作为 I2C 主机发起读写/总线扫描(复活 I2C-Inject 的
|
||
择机注入语义——避让主控轮询、静置窗口注入、读回校验), GUI 加寄存器读写卡
|
||
- [ ] **从机模拟**: probe 应答主机, 应答内容由 PC 端配置(RP2040 硬件 I2C
|
||
从机 + 应答表), 用于顶替传感器/MCU 验证驱动
|
||
- [ ] 监控增强: 字段级协议插件(如 LT8619C bank/寄存器语义注释)、触发抓取、
|
||
长时记录落盘
|
||
|
||
## 8. 故障排查
|
||
|
||
- 连接后无 T 行: `stats` 看 edges 是否增长; 不增长查接线/共地/上拉
|
||
- 事务乱码: 确认 SDA/SCL 没接反(GP8=SDA!); `wave 512` 看原始边沿
|
||
- `trans_drop`/`susp` 持续增长: 总线负载过高或毛刺多, 减小监控过滤范围
|
||
- 波形抓取期间的事务流有缺口: 正常(`wave` 快照优先, 见固件注释)
|
||
|
||
## 9. 目录内容
|
||
|
||
| 位置 | 用途 |
|
||
|---|---|
|
||
| `src/` | PC 端: main.py(GUI)/i2cdec.py(解码权威)/probelink.py(链路)/waveview.py(波形)/theme.py + 自检/打包/发布脚本 |
|
||
| `firmware/` | probe 固件: main.c + bus_watch.pio + CMakeLists + make_uf2.py + pico_sdk_import.cmake |
|
||
| `assets/` | 图标(沿用 I2C 橙色母题) |
|
||
| `release/` | I2C-Lab.exe + firmware/i2c_lab.uf2/.bin（交付物本地保留，不入库）; zip 不入库 |
|