XiaomiGateway3项目中的PTX BLE无线三键开关集成方案

设备背景与问题描述

PTX BLE无线三键开关（型号14610）是一款采用蓝牙低能耗(BLE)技术的三按钮控制设备，型号为PTX-AK3-QMIMC。该设备在与XiaomiGateway3集成时出现了识别但功能异常的情况——虽然能被系统识别，但按钮操作无法在Home Assistant中正确记录和响应。

技术分析

通过分析设备通信协议，发现该开关通过不同的BLE事件代码来区分各个按钮的不同操作模式：

• 单次点击操作对应的事件代码为1012
• 长按操作对应的事件代码为1014
• 三个物理按钮分别通过前缀数字2、4、5来区分

解决方案实现

通过在XiaomiGateway3项目的核心代码文件xiaomi_gateway3.py中添加设备定义，成功实现了对该开关的完整支持。具体实现方式是为设备添加了规范(spec)定义，将原始BLE事件映射为Home Assistant可识别的标准按钮动作事件。

代码实现的关键部分包括：

1. 设备ID与型号定义
2. 动作类型转换器(BaseConv)配置
3. 具体事件到标准动作的映射(ConstConv)

技术细节

完整的设备定义代码如下：

DEVICES = [{
    14610: ["PTX", "Triple Wireless Switch", "PTX-AK3-QMIMC"],
    "spec": [
        BaseConv("action", "sensor"),
        ConstConv("action", mi="2.e.1012", value=BUTTON_1_SINGLE),
        ConstConv("action", mi="4.e.1012", value=BUTTON_2_SINGLE),
        ConstConv("action", mi="5.e.1012", value=BUTTON_3_SINGLE),
        ConstConv("action", mi="2.e.1014", value=BUTTON_1_HOLD),
        ConstConv("action", mi="4.e.1014", value=BUTTON_2_HOLD),
        ConstConv("action", mi="5.e.1014", value=BUTTON_3_HOLD),
    ],
}] + DEVICES

这段代码实现了：

• 三个按钮的独立识别（按钮1、按钮2、按钮3）
• 两种操作类型的区分（单次点击和长按）
• 动作事件到标准值的转换

应用价值

该解决方案的成功实施不仅解决了特定型号开关的兼容性问题，也为类似BLE设备的集成提供了参考范例。这种基于事件代码映射的方法可以推广到其他多按钮BLE设备的集成场景中。

后续建议

对于开发者而言，可以考虑：

1. 将该设备定义合并到项目主分支
2. 建立更完善的BLE设备事件代码数据库
3. 开发自动化设备识别和配置机制

对于终端用户，建议在遇到类似设备兼容性问题时：

1. 检查设备原始事件代码
2. 参考现有设备定义格式
3. 通过社区分享解决方案