XiaomiGateway3项目：解决双键开关仅显示单键问题

问题背景

在智能家居系统中，双键墙壁开关是常见的设备类型，它允许用户独立控制两个不同的电路或设备。然而，部分用户在使用XiaomiGateway3集成时遇到了一个特殊问题：原本应该显示两个独立开关的双键设备，在Home Assistant中仅显示一个开关实体。

问题分析

该问题通常发生在特定型号的双键开关设备上，如示例中的"Double Wall Switch"(型号bl02)。正常情况下，这类设备应该被识别为两个独立的开关实体，分别对应两个物理按键。但近期更新后，部分用户发现系统只能识别其中一个开关通道。

解决方案

自定义设备转换器

XiaomiGateway3项目提供了灵活的解决方案——通过自定义设备转换器来正确定义设备功能。对于双键开关设备，需要明确指定每个通道对应的实体类型和属性。

以下是针对"Double Wall Switch"(型号bl02)的转换器配置示例：

from custom_components.xiaomi_gateway3.core.devices import *

DEVICES = [
{
    # 双通道开关，带功率测量功能
    9610: ["bean", "Double Wall Switch", "bl02"],
    "spec": [
        BaseConv("channel_1", "switch", mi="2.p.1"),
        BaseConv("channel_2", "switch", mi="3.p.1"),
        BaseConv("led", "switch", mi="8.p.1"), 
    ],
},] + DEVICES

配置说明

1. 设备标识：9610是设备类型代码，"Double Wall Switch"是设备名称，"bl02"是具体型号
2. 通道定义：
   • channel_1：第一个开关通道
   • channel_2：第二个开关通道
   • led：设备指示灯控制
3. mi参数：指定了设备属性在小米协议中的具体位置

实现原理

XiaomiGateway3通过设备转换器将原始设备数据映射为Home Assistant可识别的实体。当系统遇到未明确定义的设备时，可能会采用默认配置，导致功能显示不全。通过自定义转换器，可以精确控制每个设备功能的映射关系。

注意事项

1. 不同型号的双键开关可能需要不同的配置参数
2. 添加自定义转换器后需要重启Home Assistant使配置生效
3. 建议在修改前备份原有配置
4. 如果设备支持功率测量等额外功能，也应在转换器中明确定义

总结

通过自定义设备转换器，用户可以灵活解决XiaomiGateway3集成中设备功能显示不全的问题。这种方法不仅适用于双键开关，也可用于其他类型的智能设备，为Home Assistant用户提供了高度可定制的设备管理方案。