i2c-bringup-diagnostician

I2C Bringup Diagnostician

用途

此技能适用于传感器或设备本应在总线上，但 I2C 链路仍不可信的情况。当用户遇到以下请求时使用：

• “找不到 I2C 设备”
• 扫描器发现地址，但库无法初始化设备
• 两个 I2C 设备冲突或其中一个消失
• ESP32 引脚、总线或第二通道混淆
• 上拉、线长或电压电平问题
• 基础检测成功后传感器读数明显错误

主要能力

技能附带以下参考资料：

• references/bringup-flow.md：有序的 I2C 故障隔离工作流
• references/scanner-vs-library.md：扫描器找到设备但库仍失败时的处理
• references/esp32-and-board-quirks.md：ESP32 系列及板卡特有的注意事项
• ../../docs/board-support/uno-r4-family.md：相关的 Uno R4 系列板卡说明

使用方式（工作流）

1. 确定基本故障形态：
   • 扫描器检测不到 → 打开 references/bringup-flow.md
   • 扫描器检测到但库失败 → 打开 references/scanner-vs-library.md
   • ESP32 系列多总线或引脚问题 → 打开 references/esp32-and-board-quirks.md
2. 在更换库之前确认电气基础：
   • 电源
   • 共地
   • SDA 与 SCL 映射
   • 上拉电阻
   • 逻辑电平兼容性
3. 只有在总线电气上合理之后，才检查地址、设备模式和库预期。
4. 如果板卡属于 Uno R4 系列且故障涉及板卡特有的 I2C 或支持问题，还要打开 ../../docs/board-support/uno-r4-family.md。

核心规则

• 扫描器成功并不证明库正在正确使用该设备。
• 库失败并不证明传感器已损坏。
• 在盲目修改代码之前，必须明确总线电压、上拉和引脚映射。
• 对于 ESP32 系列板卡，引脚选择和多总线假设并不总是跨变体可移植。

验证

• 确认扫描器是否看到预期地址。
• 确认最小的寄存器读取或标识读取是否工作。
• 确认失败行为是否随板卡系列、总线实例或库而变化，而非仅与传感器相关。
• 确认最终修复能否在重复扫描和实际传感器读取中持续有效。

集成

• 与 circuit-debugger 配合，进行更深入的硬件隔离。
• 当正确的地址、电源或时序细节未知时，与 datasheet-interpreter 配合。
• 当用户需要最小测试草图或清理过的总线探测时，与 arduino-code-generator 配合。

共享输出契约

使用 the shared Arduino skill contract：说明假设、所需工具与版本、实现步骤、按证明阶段划分的测试/证据、已知限制以及恢复/安全说明。