Shelly HomeKit固件在Gen3设备上的适配与调试经验

背景介绍

Shelly HomeKit项目为Shelly智能设备提供了原生HomeKit支持，使其能够直接接入苹果智能家居生态系统。近期项目开始支持第三代Shelly设备(Gen3)，但在实际使用中，用户反馈Shelly1 Gen3配合Plus Addon模块控制车库门时出现了状态检测异常的问题。

问题现象

用户报告在升级到2.14.0版本固件后，虽然可以通过HomeKit控制车库门的开关动作，但门状态传感器无法正常工作。具体表现为：

1. 当启用"Swap Inputs"选项时，门关闭状态显示为"Blocked"(阻塞)
2. 关闭该选项后，系统无法识别通过遥控器操作的门状态变化
3. 温度湿度传感器数据可以正常读取

技术分析

Shelly1 Gen3与之前版本在硬件设计上有显著差异，特别是GPIO引脚定义发生了变化。Plus Addon模块需要通过特定的GPIO引脚与主控通信：

1. 输出控制引脚(ADDON_OUT_GPIO) - 用于控制继电器动作
2. 输入检测引脚(ADDON_IN_GPIO) - 用于读取门状态
3. 数字信号引脚(ADDON_DIG_GPIO) - 用于附加功能通信

开发者最初基于硬件文档推测了可能的引脚配置：

ADDON_OUT_GPIO: 9
ADDON_IN_GPIO: 21 
ADDON_DIG_GPIO: 8

调试过程

通过以下步骤最终确定了正确的引脚配置：

1. 初步测试：发布测试固件验证初始假设，确认部分功能(温湿度传感)工作正常，但核心状态检测异常

2. 诊断工具开发：专门构建了支持GPIO读取的调试固件，允许通过RPC接口直接查询各引脚状态：

   curl 设备IP/rpc/GPIO.Read -d '{"pin":引脚号}'
   

3. 引脚扫描：指导用户对候选引脚(1,7,8,19)进行状态扫描，最终发现引脚6在门开关时状态变化明显

4. 配置修正：基于实测结果调整固件中的引脚定义，发布修正版本

解决方案

最终确认的Shelly1 Gen3+Plus Addon正确引脚配置为：

ADDON_OUT_GPIO: 9
ADDON_IN_GPIO: 21
ADDON_DIG_GPIO: 6  // 修正后的关键引脚

这一配置解决了门状态检测异常问题，使整套系统能够正常工作。

经验总结

1. 硬件差异：不同代Shelly设备的GPIO布局可能有显著变化，不能简单沿用旧版配置

2. 诊断方法：直接读取GPIO状态是验证硬件连接的有效手段

3. 测试验证：分阶段测试可以快速定位问题范围（本例中先确认了温湿度传感正常）

4. 用户协作：开发者与用户的紧密配合大大加快了问题解决速度

扩展应用

该调试方法同样适用于其他Gen3设备（如Shelly1 mini Gen3）的适配工作。对于需要定时控制的应用场景（如2分钟后自动关闭灯光），可以通过固件中的"Auto off"功能实现，无需额外开发。

这一案例展示了开源社区协作解决硬件兼容性问题的典型流程，也为后续Gen3设备支持积累了宝贵经验。