在hass-xiaomi-miot项目中为智能马桶添加冲水功能的技术实现

背景介绍

在智能家居系统中，智能马桶作为新兴的智能设备逐渐普及。hass-xiaomi-miot项目作为Home Assistant中对接小米生态链设备的重要集成，需要不断适配新设备的功能。本文将详细介绍如何为xjx.toilet.relax型号的智能马桶添加冲水功能支持。

技术原理

hass-xiaomi-miot项目通过两种方式与设备通信：

1. 基于MIoT协议的自动发现机制
2. 通过miio2miot模块实现的特殊设备适配

当设备功能不在标准MIoT协议中时，需要通过扩展规范(miot_specs_extend)和特殊映射(miio2miot_specs)来实现功能支持。

实现步骤

1. 扩展规范定义

首先需要在miot_specs_extend中为设备添加冲水动作的定义。这里有几个关键点需要注意：

• 服务iid选择：应选择设备已存在的服务iid（如2），而不是随意创建新iid
• 动作iid范围：自定义动作的iid应从100开始递增，避免与标准iid冲突
• 类型定义：必须指定动作的类型URI

正确的扩展定义如下：

"xjx.toilet.relax": [
    {
      "iid": 2,
      "actions": [
        {
          "iid": 101,
          "type": "urn:miot-spec-v2:action:flush-on",
          "description": "Flush",
          "in": [],
          "out": []
        }
      ]
    }
  ]

2. miio命令映射

在miio2miot_specs中需要建立MIoT动作与底层miio命令的映射关系：

'xjx.toilet.relax': {
    'extend_model': 'xjx.toilet.pro',
    'miio_specs': {
        'prop.2.1': {'prop': 'seating'},
        'prop.2.2': {'prop': 'status_bubbleshield', 'setter': 'set_bubble', 'set_template': '{{ [value|int] }}'},
        'prop.3.1': {'prop': 'status_seatheat', 'setter': 'work_seatheat', 'set_template': '{{ [value|int] }}'},
        'prop.3.2': {'prop': 'seat_temp', 'setter': 'set_seat_temp'},
        'prop.4.1': {'prop': 'status_led', 'setter': 'work_night_led', 'set_template': '{{ [value|int] }}'},
        'action.2.101': {'setter': 'flush_on'},
    },
},

3. 实现要点解析

1. iid选择原则：服务iid必须对应设备已有的服务实例，不能随意创建。通过分析设备属性可以确定可用iid。

2. 动作定义：自定义动作需要完整定义type、description等字段，确保系统能正确识别。

3. 命令映射：miio2miot_specs中的action映射必须与扩展定义中的iid完全一致（这里是2.101）。

4. 模板处理：对于布尔值参数，通常需要使用int转换模板确保数据类型正确。

常见问题排查

如果按照上述步骤配置后仍无法看到冲水实体，可以检查以下方面：

1. 确认设备型号完全匹配（大小写敏感）
2. 检查iid是否与设备实际服务对应
3. 查看Home Assistant日志是否有相关错误信息
4. 确认miio协议中确实存在flush_on命令

总结

通过扩展MIoT规范和建立miio命令映射，我们可以为不完全兼容标准协议的设备添加额外功能支持。这种方法不仅适用于智能马桶，也可以推广到其他类型的智能设备。关键在于理解设备通信协议和项目架构，合理使用扩展机制。