i2c-bringup-diagnostician

I2C 启动诊断

当传感器或设备应当连接到总线上，但 I2C 通路仍不可靠时，使用此技能。

资源

• 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 系列开发板说明

适用情形

当请求包含以下情况时，使用此技能：

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

工作流

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 使用。

共享输出规范

请遵循共享 Arduino 技能规范： 说明假设、所需工具及版本、实施步骤、各验证阶段的测试／证据、已知限制以及恢复／安全注意事项。