告别设备离线！小米智能家居 Home Assistant 集成更新全攻略

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

您是否遇到过小米智能家居设备在 Home Assistant 中突然离线？自动化规则因更新失效？本文将系统梳理小米智能家居（Xiaomi Home）集成的更新管理规范，帮助您平稳完成设备升级，避免常见问题。

更新前必备检查

在执行任何更新操作前，请完成以下准备工作：

1. 备份关键配置
   导出 Home Assistant 自动化规则和设备实体配置，可通过 Settings > System > Backups 完成完整备份。

2. 查看版本兼容性
   确认当前 Home Assistant 版本是否满足集成要求。v0.3.2 及以上版本已加入 HACS 默认库，可直接通过 HACS。

3. 检查设备型号支持
   部分旧设备可能在新版本中被过滤（如小米路由器 rd03 系列），可查阅 CHANGELOG.md 第 564 行确认设备兼容性。

两种更新方式对比

本地控制更新

适用于已配置局域网控制的用户，更新步骤：

1. 下载最新代码：

   git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
   

2. 运行安装脚本：

   cd ha_xiaomi_home && bash install.sh
   

3. 重启 Home Assistant 服务

云端控制更新

通过小米云服务同步更新，需确保网络通畅：

1. 在 Home Assistant 集成页面进入 Xiaomi Home 配置
2. 勾选 "更新实体转换规则" 选项
3. 点击 "下一步" 完成云端同步

常见问题解决方案

实体 ID 变更导致自动化失效

v0.3.0 版本重构了实体 unique_id 生成规则，可能导致自动化规则失效。临时解决方案：

# 在 configuration.yaml 中添加实体 ID 映射
homeassistant:
  customize_glob:
    "sensor.xiaomi_*":
      new_entity_id: "sensor.mihome_*"

完整迁移补丁参见 PR #972。

设备离线或控制延迟

1. 检查本地网络：确保设备与 Home Assistant 在同一网段，可通过 miot_lan.py 调试网络连接
2. 清除缓存：删除 custom_components/xiaomi_home/.storage 目录下的缓存文件
3. 重新订阅设备：在集成配置中执行 "更新设备列表" 操作

多语言支持问题

若设备名称显示乱码，可更新翻译文件：

# 同步最新翻译
cd custom_components/xiaomi_home/translations
wget https://raw.githubusercontent.com/XiaoMi/ha_xiaomi_home/main/custom_components/xiaomi_home/translations/zh-Hans.json

支持的语言列表可在 translations 目录查看。

版本更新记录速览

版本	关键变更	注意事项
v0.4.3	修复真空吸尘器电池状态显示	移除 VacuumEntityFeature.BATTERY
v0.4.0	新增媒体播放器实体	支持 WiFi 音箱和电视控制
v0.3.0	实体 ID 生成规则变更	可能需要重新配置自动化
v0.2.2	浴霸/空调实体转换规则更新	需重启并勾选 "更新实体转换规则"

完整更新日志请查阅 CHANGELOG.md。

贡献与反馈

若在更新过程中遇到问题，可通过以下方式反馈：

1. GitHub Issues
2. 邮件：ha_xiaomi_home@xiaomi.com
3. 参与代码贡献：提交 PR 前请阅读 贡献指南

定期关注项目更新，及时获取新功能和 bug 修复信息，让智能家居控制更稳定、更高效！

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