XiaomiGateway3 项目：自定义设备转换器配置指南

背景介绍

XiaomiGateway3 是 Home Assistant 社区中一个广受欢迎的小米网关集成项目，它能够将小米生态链设备接入到 Home Assistant 系统中。在实际使用过程中，用户可能会遇到一些新设备未被官方支持的情况，这时就需要通过自定义转换器(Converter)来扩展设备支持。

问题现象

用户在使用 XiaomiGateway3 集成时，发现一款新型的三键墙壁开关(giot.switch.v83ksm)无法被正确识别。设备仅显示为一个"Mesh"实体，而无法分解为具体的开关和控制选项。

解决方案

1. 确认集成版本

首先需要确认使用的是最新版本的 XiaomiGateway3 集成。旧版本(如3.3.3)和新版本的转换器配置方式有所不同，使用错误的配置方式会导致转换器无法生效。

2. 创建自定义转换器

在新版本的 XiaomiGateway3 中，可以通过在 Home Assistant 配置目录下创建 xiaomi_gateway3.py 文件来添加自定义设备支持。文件内容应包含以下要素：

• 设备型号标识
• 设备名称和描述
• 各功能点的映射关系

3. 转换器配置详解

以三键墙壁开关为例，完整的转换器配置应包含：

基础开关控制：

BaseConv("Left Switch", "switch", mi="2.p.1"),
BaseConv("Middle Switch", "switch", mi="3.p.1"),
BaseConv("Right Switch", "switch", mi="4.p.1")

开关模式设置：

MapConv("Left Switch Mode", "select", mi="2.p.2", map={
    0: "Normal Switch", 
    1: "Wireless Switch",
    2: "Flex Switch",
    3: "Inching Switch",
    4: "Normal + Wireless Switch"
})

背光控制：

MapConv("Normal Mode LED", "select", mi="16.p.1", map={
    0: "Follow Switch Status",
    1: "Opposite To The Switch State",
    2: "Often Out State",
    3: "Normally On State"
})

无线开关动作：

BaseConv("action", "sensor"),
ConstConv("action", mi="12.e.1", value=BUTTON_SINGLE),
ConstConv("action", mi="12.e.2", value=BUTTON_DOUBLE)

4. 配置生效

完成配置后，需要执行以下步骤使配置生效：

1. 保存 xiaomi_gateway3.py 文件
2. 重启 Home Assistant 服务
3. 检查日志中是否有错误信息
4. 在集成界面查看设备是否已正确识别

扩展支持

除了三键开关外，同一系列的单键和双键开关也可以采用类似的配置方式。主要区别在于功能点的数量和对应的mi属性值。

注意事项

1. 确保使用正确的属性路径(mi值)，错误的路径会导致功能无法正常工作
2. 对于不同类型的设备，需要参考官方文档确定正确的属性映射关系
3. 配置完成后建议先检查日志，确认没有错误信息
4. 如果配置不生效，可以尝试直接修改集成核心文件(不推荐长期使用)

总结

通过自定义转换器配置，用户可以灵活扩展 XiaomiGateway3 集成对新设备的支持。关键在于正确理解设备的功能点和属性映射关系，并按照规范的格式编写转换器配置。这种方法不仅适用于墙壁开关，也适用于其他小米生态链设备。