小米智能家居接入Home Assistant升级指南

一、版本适配评估矩阵

在进行升级前，需要对当前系统环境和设备兼容性进行全面评估，确保升级过程顺利进行。

1.1 设备类型与版本匹配

不同类型的小米智能设备对集成版本有不同的要求，以下是常见设备类型与推荐版本的对应关系：

• 空调/新风系统：推荐使用≥v0.4.1版本，该版本修复了湿度范围单位问题，确保设备状态数据准确。
• 扫地机器人：建议升级至≥v0.4.2版本，此版本优化了回充逻辑，解决部分型号吸尘器回充无响应的问题。
• 智能开关：≥v0.3.4版本提升了功率统计精度，能更准确地监测用电情况。
• 加湿器：≥v0.4.1版本修正了水位检测功能，避免误报缺水等问题。

1.2 控制模式选择

小米智能家居集成提供云端和本地两种控制模式，你可以根据网络环境和设备类型选择：

云端控制模式

工作原理：通过MQTT协议订阅小米云服务器消息，设备状态变更实时推送至Home Assistant，控制命令经HTTPS加密传输。

适用场景：无小米多模网关，或需要跨网络远程控制的场景。

特点：平均延迟300-500ms，受网络波动影响较大；配置简单，无需复杂的网络设置。

本地控制模式

工作原理：通过本地局域网内的MQTT Broker直连设备，支持WiFi/以太网设备的实时状态同步和命令下发。

启用条件：

• 小米多模网关固件≥v3.3.0_0023
• 设备支持MIoT-Spec-V2协议
• 与Home Assistant处于同一局域网

特点：延迟稳定在50-150ms，不受公网影响；安全性更高，但对网络环境要求较严格。

1.3 决策检查点

• 你是否已确定所有设备对应的推荐版本？（是/否）
• 你是否根据网络环境和设备类型选择了合适的控制模式？（是/否）
• 你是否了解所选控制模式的特点和要求？（是/否）

二、实施风险控制

升级过程中可能会遇到各种风险，需要提前做好防范措施，以确保系统稳定运行。

2.1 数据备份

在进行升级操作前，务必做好数据备份工作，以防升级失败导致数据丢失。

🔧 操作步骤：

1. 备份custom_components/xiaomi_home目录，可使用以下命令：

cp -r custom_components/xiaomi_home custom_components/xiaomi_home_backup

2. 通过Home Assistant的"Settings > System > Backups"创建系统快照，以便在出现问题时能够快速恢复。

2.2 版本更新方式选择

根据你的实际情况选择合适的更新方式，不同方式的操作复杂度和风险等级不同：

• HACS一键更新：操作复杂度低，风险等级低，适用于稳定版本升级。在HACS中找到Xiaomi Home集成，点击更新即可。
• Git指定版本：操作复杂度中等，风险等级中等，适用于问题版本回滚。使用命令git checkout <版本号>切换到指定版本。
• 手动文件替换：操作复杂度高，风险等级高，适用于定制化修改。需手动下载对应版本的文件并替换到相应目录。

⚠️ 警告：手动文件替换可能会导致文件权限问题或版本不匹配，建议仅在有经验的情况下使用。

2.3 实体ID变更处理

v0.3.0版本重构了实体unique_id（设备身份证号）生成规则，可能导致已配置的自动化规则失效。

问题：自动化规则中引用的实体ID无法找到，日志显示Entity not found: switch.xiaomi_fan。

原因：实体ID生成规则改变，旧的ID格式不再使用。

解决方案：

1. 安装v0.3.0补丁保持旧ID格式。
2. 手动更新自动化规则中的实体引用，示例如下：

问题代码：

alias: "客厅灯自动关闭"
trigger:
  platform: state
  entity_id: light.livingroom_xiaomi_1234

修复代码：

alias: "客厅灯自动关闭"
trigger:
  platform: state
  entity_id: light.xiaomi_light_mb3_1234

验证命令：在Home Assistant开发者工具中检查自动化规则是否能正常触发。

2.4 决策检查点

• 你是否已完成数据备份工作？（是/否）
• 你是否选择了适合自己的版本更新方式？（是/否）
• 你是否处理了实体ID变更可能带来的问题？（是/否）

三、深度优化指南

升级完成后，可以进行一些深度优化操作，提升系统性能和使用体验。

3.1 规格文件定制

高级用户可通过修改规格文件实现设备个性化适配，位于custom_components/xiaomi_home/miot/specs/目录下的三个核心文件：

spec_filter.yaml：过滤不需要的实体

# 示例：隐藏电视的冗余服务
urn:miot-spec-v2:device:television:0000A010:xiaomi-rmi1:
  services:
  - '*'  # 过滤所有服务，完全忽略该设备

spec_modify.yaml：调整属性定义

# 示例：修正空调湿度单位
urn:miot-spec-v2:device:aircondition:0000A004:xiaomi-c17:
  properties:
    1.5:  # siid=1, piid=5
      unit: "%"  # 将单位从"none"改为"%"

multi_lang.json：补充翻译

{
  "urn:miot-spec-v2:device:humidifier:0000A00E:zhimi-ca4": {
    "zh-Hans": {
      "service:002:property:007": "水箱水位"
    }
  }
}

修改后通过配置页面"更新实体转换规则"使生效。

3.2 性能优化

1. 网络优化：为IoT设备创建独立VLAN，减少广播风暴影响，提高网络稳定性。
2. 资源限制：通过configuration.yaml限制并发连接数，避免资源占用过高：

xiaomi_home:
  max_connections: 50  # 默认100

3. 日志管理：在logger.yaml中调整日志级别，减少不必要的日志输出：

logger:
  default: warn
  logs:
    custom_components.xiaomi_home: info  # 仅记录关键操作

3.3 反向兼容性评估

在某些情况下，可能需要降级到旧版本，以下是降级方案的分析：

• 降级原因：新版本存在兼容性问题，导致设备无法正常工作。
• 降级步骤：
  1. 恢复之前备份的custom_components/xiaomi_home目录。
  2. 通过Git切换到需要降级的版本。
  3. 重启Home Assistant服务。
• 注意事项：降级可能会导致部分新功能丢失，且需要重新配置部分设置。

3.4 版本检测与自动化迁移

🔧 版本检测命令：

ha xiaomi version-check

该命令可以帮助你快速了解当前安装的集成版本。

自动化迁移脚本片段：

# 自动化迁移实体ID的简单脚本示例
import os
import re

automation_path = "/config/automations.yaml"
with open(automation_path, "r") as f:
    content = f.read()

# 替换旧实体ID格式为新格式的示例正则表达式
content = re.sub(r"light\.livingroom_xiaomi_(\d+)", r"light.xiaomi_light_mb3_\1", content)

with open(automation_path, "w") as f:
    f.write(content)

3.5 决策检查点

• 你是否根据需求定制了规格文件？（是/否）
• 你是否进行了性能优化操作？（是/否）
• 你是否了解反向兼容性评估和降级方案？（是/否）