告别设备属性混乱！Xiaomi Home Integration规则版本控制全攻略

【免费下载链接】ha_xiaomi_home Xiaomi Home Integration for Home Assistant 项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home

你是否遇到过智能家居设备升级后属性异常、多设备联动失效的问题？作为Home Assistant用户，管理小米智能家居设备时，设备属性联动规则的版本控制往往是最令人头疼的环节。本文将带你掌握 Xiaomi Home Integration for Home Assistant（以下简称"小米集成"）的设备属性联动规则版本控制方法，轻松解决规则冲突、历史回溯和多环境同步难题。

为什么需要规则版本控制？

小米智能家居设备通过MIoT-Spec-V2（MIoT规范版本2）定义设备属性和联动逻辑。随着设备固件更新和集成组件升级，属性定义可能发生变化：

• 格式变更：如温度单位从摄氏度变为华氏度
• 取值范围调整：如风速档位从3档扩展为5档
• 新增属性：如空气净化器新增PM2.5数值校准功能

这些变更若未妥善管理，可能导致自动化脚本失效、数据采集错误等问题。通过版本控制，你可以：

• 追踪规则变更历史
• 快速回滚异常版本
• 在开发/生产环境间安全切换

核心配置文件解析

小米集成通过以下文件实现规则版本控制，所有文件位于custom_components/xiaomi_home/miot/specs/目录：

1. spec_modify.yaml - 属性修改规则

该文件定义设备属性的转换规则，支持单位换算、名称重定义等操作。例如空调功率单位转换：

urn:miot-spec-v2:device:air-conditioner:0000A004:xiaomi-c24:1:
  prop.8.6:
    unit: kWh  # 将原始单位转换为千瓦时

2. spec_filter.yaml - 属性过滤规则

用于排除不需要的设备属性，避免生成冗余实体：

urn:miot-spec-v2:device:air-purifier:0000A007:zhimi-ma4:
  properties:
  - 9.*  # 过滤siid=9服务的所有属性
  - 13.* # 过滤siid=13服务的所有属性

3. multi_lang.json - 多语言支持

维护设备属性的多语言翻译，优先级高于云端数据：

{
  "urn:miot-spec-v2:device:health-pot:0000A051:chunmi-a1": {
    "zh-Hant": {
      "service:002": "養生壺",
      "service:002:property:001": "工作狀態"
    }
  }
}

版本控制实操指南

步骤1：创建规则备份

修改配置前，建议通过以下命令备份当前规则文件：

cd /data/web/disk1/git_repo/GitHub_Trending/ha/ha_xiaomi_home
mkdir -p custom_components/xiaomi_home/miot/specs/backup
cp custom_components/xiaomi_home/miot/specs/*.{yaml,json} custom_components/xiaomi_home/miot/specs/backup/

步骤2：修改规则文件

以调整智能插座功率单位为例，编辑spec_modify.yaml：

urn:miot-spec-v2:device:outlet:0000A002:chuangmi-212a01:3:
  prop.5.1:
    expr: round(src_value*6/1000000, 3)  # 原始值转换为kW
    unit: kW  # 设置新单位

步骤3：应用规则变更

修改完成后，在Home Assistant中更新规则：

1. 进入 设置 > 设备与服务
2. 找到 Xiaomi Home 集成
3. 点击 配置 > 更新实体转换规则

图1：通过云端更新规则的架构示意图

规则冲突解决方案

当多个规则文件对同一属性定义不同转换方式时，遵循以下优先级：

1. spec_modify.yaml > spec_filter.yaml > 默认转换规则
2. multi_lang.json > 云端多语言数据

例如，若某温度属性同时在spec_modify.yaml和默认规则中定义，将优先使用spec_modify.yaml的配置。

版本控制最佳实践

1. 语义化版本命名

为备份文件添加版本号，便于追溯：

# 示例：备份为v1.2版本
cp custom_components/xiaomi_home/miot/specs/spec_modify.yaml custom_components/xiaomi_home/miot/specs/backup/spec_modify_v1.2.yaml

2. 使用Git进行版本管理

将规则文件纳入Git版本控制：

git init
git add custom_components/xiaomi_home/miot/specs/
git commit -m "Initial commit of device property rules"

后续修改可通过git log查看历史记录，通过git checkout <commit-hash>回滚版本。

3. 规则验证流程

修改后建议通过调试模式验证：

1. 启用 动作调试模式（配置 > Xiaomi Home > 调试模式）
2. 监控日志输出：tail -f /config/home-assistant.log | grep xiaomi_home
3. 检查实体属性是否按预期转换

图2：本地控制模式下的规则应用流程

常见问题解决

Q1：修改规则后实体未更新？

A1：尝试以下步骤：

1. 重启Home Assistant
2. 确认规则文件格式正确（可使用test/check_rule_format.py验证）
3. 检查日志是否有语法错误：grep "xiaomi_home" /config/home-assistant.log

Q2：如何批量管理多设备规则？

A2：可使用spec_modify.yaml的继承语法：

# 定义基础规则
base_air_conditioner: &base_ac
  prop.10.6:
    unit: none

# 继承基础规则
urn:miot-spec-v2:device:air-conditioner:0000A004:xiaomi-c17:1:
  <<: *base_ac

urn:miot-spec-v2:device:air-conditioner:0000A004:xiaomi-c20:1:
  <<: *base_ac

总结与展望

通过本文介绍的版本控制方法，你可以：

• 精确管理设备属性转换规则
• 安全回溯历史配置
• 实现多环境规则同步

随着CHANGELOG.md中规划的规则管理UI功能上线，未来将支持可视化规则编辑和版本对比。建议定期关注项目更新，及时获取新功能。

若本文对你有帮助，请点赞收藏！下期将带来《小米多模网关本地控制实战》，敬请期待。

【免费下载链接】ha_xiaomi_home Xiaomi Home Integration for Home Assistant 项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home