Xiaomi Home for Home Assistant 版本演进全解析从 v0.1.0 到 v0.4.7 的 CHANGELOG 技术解读【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home本篇技术指南以本仓库 CHANGELOG.md 为骨架系统梳理 Xiaomi Home小米官方 Home Assistant 集成组件从首个版本 v0.1.0 到当前 v0.4.7 的完整演进脉络包括新增实体类型媒体播放器、设备跟踪器、新风/浴霸/空调等的扩展路线、多语言支持、MIoT-Spec-V2 规格修正机制以及更新实体转换规则等关键配置选项的来龙去脉。读者读完后将能准确理解该集成的版本化能力边界、每个版本的升级注意事项以及 changelog 中每一条变更背后的源码实现依据。一、版本基线总览一个快速成熟的小米 IoT 集成Xiaomi Home 是小米官方为 Home Assistant 提供的集成组件仓库结构见 custom_components/xiaomi_home/manifest.json当前版本为v0.4.7。从 changelog 看其版本演进遵循v0.1.x → v0.2.x → v0.3.x → v0.4.x的主线每次发布按Added / Changed / Fixed三分类记录变更含义分别为新增能力、行为调整、缺陷修复。两个值得注意的基线事实版本能力由 manifest 固化集成类型为hub依赖http、persistent_notification、ffmpeg、zeroconf运行期依赖construct、paho-mqtt、numpy、cryptography、psutil并通过_miot-central._tcp.local.做 zeroconf 广播发现这对应 changelog 中反复出现的 MQTT 与局域网发现类变更。HACS 里程碑v0.3.2 明确记录——Xiaomi Home 已于2025 年 5 月 8 日加入 Home Assistant Community StoreHACS默认源用户可直接在 HACS 中搜索 Xiaomi Home 一键下载而无需添加自定义仓库。二、实体类型扩展路线Added 维度主线changelog 最显著的主线是实体类型覆盖面的持续扩大从最初的通用转换逐步演进到面向具体设备的专用实体版本新增实体/设备支持对应仓库实体文件v0.1.x基础实体框架、风扇方向控制、小米加热器、水暖/空调/窗帘/热水器缺陷修复fan.py、climate.py、cover.py、water_heater.pyv0.2.x电热毯、带电机控制服务的设备转 cover 实体、surge-power 功率换算规则、浴霸/空调/新风转换规则、恒温器预设模式climate.py、cover.pyv0.3.x共享家庭与共享设备导入、climate 实体的_attr_hvac_action支持climate.pyv0.4.0手表转为 device tracker 实体、WiFi 音箱与电视转为 media player 实体、第三方云设备导入device_tracker.py、media_player.pyv0.4.6电视盒子tv-box转为 media player 实体并为其播放控制服务设置playing-state必需属性media_player.pyv0.4.7新增土耳其语翻译multi_lang.json从实现看实体转换依赖 specv2entity.py 中定义的SPEC_DEVICE_TRANS_MAP等映射字典以设备实例名 → 必需/可选服务 → 必需/可选属性/事件/动作 → entity的嵌套结构描述转换条件只有当 MIoT-Spec-V2 设备实例包含全部必需项时才创建对应实体。changelog 中大量为某服务新增转换规则的条目本质上就是在扩充这些映射字典。三、关键配置选项的演进changelog 展示了集成配置项从粗到细的迭代实体转换规则更新v0.3.0 引入配置流中新增xiaomi_home 配置 更新实体转换规则选项用于在规格字典如 spec_filter.yaml、spec_modify.yaml、multi_lang.json被编辑后重新加载转换规则。源码 config_flow.py 中该选项以update_trans_rules布尔配置项存在并配套async_step_update_trans_rules步骤统计 urn 总数与成功转换数对应trans_rules_count/trans_rules_count_success。Cover 死区宽度v0.4.1 更名原Cover closed position关闭位置选项改为Cover dead zone width死区宽度对应 config_flow.py 中的cover_dead_zone_width配置及MIN_COVER_DEAD_ZONE_WIDTH/MAX_COVER_DEAD_ZONE_WIDTH边界。本地连接状态通知v0.4.0新增通知机制展示与中央网关Central Hub Gateway本地连接的实时状态。局域网控制与网络检测更新局域网控制配置、网络检测配置等选项贯穿多个版本与 miot_lan.py、miot_network.py 的实现对应。四、MIoT-Spec-V2 修正机制Fixed 维度的最大组成部分通读 changelog 会发现每个版本都包含大量针对具体设备型号的 MIoT-Spec-V2 修正这是该集成的常态性维护工作。修正模式可归纳为以下几类且都能在 spec_modify.yaml 中找到对应条目unit单位修正如 v0.4.7 为xiaomi.toothbrush.p001刷头剩余寿命属性补充单位spec_modify.yaml 中prop.4.1041: unit: daysv0.4.1 修复多个空调型号humidity-range的单位v0.3.3 将多款空调湿度范围单位统一为none。format格式与 access访问权限修正如 v0.4.6 修复daikin.aircondition.k2/daikin.airfresh.k33字符串值属性的格式与访问字段spec_modify.yaml 中prop.2.1: format: string且access: [read, notify]v0.4.7 修复多款 WiFi 音箱playing-state属性的访问字段spec_modify.yaml。value-list / value-range枚举与取值范围修正如 v0.4.4 修正qdhkl.airc.a42的 hvac 模式枚举spec_modify.yaml 中 Cool/Dry/Fan/Heat/Auto/Heat_cool 六档、lumi.motion.bmgl01的 value-list。expr换算表达式修正如 v0.4.2 修正表达式计算后的属性值格式spec_modify.yaml 中expr: round(src_value/100, 2)等模式随处可见v0.4.5 明确将取值流程调整为先格式化值类型、再按表达式求值、最后设置精度。与修正机制配套的还有两套定制设施spec_filter.yaml 过滤机制按设备 urn不含版本号→ services/properties/events/actions 的 iid 列表过滤掉不会被转换的实例支持*通配。changelog 中 v0.4.2 忽略 narwa.vacuum.001 与 narwa.vacuum.ax11 的全部不支持实例对应services: [*]、v0.3.4 排除不支持设备型号等均属此类。spec_add.json 自定义实例v0.3.0 引入允许以 JSON 形式补充云上缺失的 MIoT-Spec-V2 实例定义如为090615.aircondition.ktf补充 AC Switch 服务。五、通信与协议层的健壮性演进Changed / Fixedchangelog 中另一大主题是云端 MQTT 与本地控制链路的可靠性v0.3.x ~ v0.4.x 的订阅优化v0.4.3 即使设备离线也订阅代理网关子设备上线消息v0.3.4 即使设备离线也订阅 BLE 设备上行消息v0.4.0 不再订阅 BLE 设备在线/离线状态消息、v0.4.0 每次连接到中央网关时重新订阅本地主题。重连与网络恢复v0.3.4 修复客户端连接 broker 后重连延迟未重置v0.4.6 网络恢复后持续重试拉取设备列表直至成功、修复 paho-mqtt 订阅错误与 http post 错误v0.4.4 主循环关闭时立即停止 MQTT 内部循环v0.3.0 忽略关闭事件循环上的 unsub Event loop is closed 报错。这些与 miot_mips.py消息总线、miot_client.pyMQTT 客户端的实现直接相关。mdns 发现修正v0.4.5 忽略 mdns 的 REMOVED 包v0.4.0 保证 mdns 结果中首个 IP 为最近新增地址。常量与日志治理v0.4.6 用常量替代云端 MQTT broker 主机域名与设备刷新定时延迟v0.4.1 日志打印隐藏敏感信息v0.3.3 为set_properties命令来源增加区分日志、降低 mips unsub internal error 日志级别。六、需要用户介入操作的重点版本以下版本在更新后需要用户在 Home Assistant 侧执行特定操作务必留意v0.2.0传感器默认单位变更部分传感器默认单位被修改更新后 Home Assistant 可能弹出兼容性警告重新添加集成即可解决。v0.2.2climate 转换规则变更影响浴霸ptc-bath-heater、空调、新风设备。更新后需重启 Home Assistant并在xiaomi_home 配置 更新实体转换规则 下一步勾选以重新加载集成。v0.3.0unique_id 生成规则变更重点该版本变更了部分实体的 unique_id 生成规则。若勾选xiaomi_home 配置 更新实体转换规则会导致这些实体上已配置的自动化失效需要重新配置。若想避免大量重配自动化官方提供了补丁见 changelog 对应 PR。unique_id 的实现可在 miot_device.py 看到设备实体的_attr_unique_id直接取自self.entity_id。v0.1.5b1路由器设备不可用该版本过滤了miwifi.*与xiaomi.router.rd03会导致部分不支持的路由器不可用可在配置中更新设备列表或手动删除。七、多语言支持从 5 种到 13 种changelog 完整记录了语言支持的扩展过程v0.1.3语言支持德语dt/dev0.1.2新增葡萄牙语pt、巴西葡萄牙语pt-BRv0.1.5b2新增意大利语v0.4.4新增土耳其语v0.4.7multi_lang.json 中补充土耳其语翻译截至 v0.4.7集成共支持13 种语言简体中文、繁体中文、英语、西班牙语、俄语、法语、德语、日语、意大利语、荷兰语、葡萄牙语、巴西葡萄牙语、土耳其语。翻译文件分别位于 translations配置流界面与 miot/i18n集成内文案目录设备实体名的多语言显示由云端多语言文件与本地 multi_lang.json 字典共同决定后者优先级更高。v0.3.3 还曾修复 multi_lang.json 中中文括号误用、v0.3.4 修复 it.json 缺失变量等翻译质量问题。八、状态同步与实体行为细节修复changelog 中大量 Fixed 条目体现了对设备状态机细节的打磨可分为状态记录策略v0.4.0 记录 motor-controller / window-opener / curtain 服务中频繁出现的 closing/closed 状态v0.3.4 记录晾衣架 opening/closing/closed 状态、cover 实体不记录 stop 状态。实体行为修正v0.4.3 从 vacuum 实体移除VacuumEntityFeature.BATTERYv0.4.2 将电池服务的 start-charge 动作作为 RETURN_HOME 回退v0.3.1 风扇关闭时设置风速档位会先开启风扇v0.2.3 指定 climate 实体开关功能初始化时的服务名与属性名v0.1.5b1 修复风扇速度、支持方向控制v0.4.1 修复真空吸尘器状态不再一直 idle。传感器精度与数值格式v0.4.5 修复xiaomi.derh.lite温度精度v0.4.4 修复浮点值精度v0.4.3 修复整数值 step、contact-state 值格式v0.4.2 修复表达式计算后的属性值格式。BLE mesh 状态v0.4.7 通过中央网关更新 BLE mesh 设备在线状态部分修复。九、从 changelog 到源码的验证路径若想深入验证 changelog 中某条变更的落地情况可按如下路径在仓库中检索规格修正类在 spec_modify.yaml 搜索设备型号关键词如daikin-k2、xiaomi-c24、zhimi-ca4查看 unit/format/access/expr 等字段的实际修改。过滤类在 spec_filter.yaml 搜索被忽略的设备 urn如narwa-001、759413-iezv0.4.3 忽略其不支持属性。自定义规格类在 spec_add.json 查看补充的实例 JSON如xiaomi-l05b的播放动作对应 v0.4.3 为 xiaomi.wifispeaker.l05b 播放动作增加附带按钮实体。配置选项类在 config_flow.py 搜索update_trans_rules、cover_dead_zone_width、action_debug等配置键。实体映射类在 specv2entity.py 查看SPEC_DEVICE_TRANS_MAP等映射字典确认新增实体类型的转换条件。测试佐证v0.1.5b2 起持续补充测试用例云服务、用户证书、mips 重连逻辑等对应 test 目录中的 test_cloud.py、test_lan.py、test_mips.py 等文件。十、升级与排查建议总结基于 changelog 全量内容可总结出该集成的通用升级流程与注意事项版本跨度越大越要逐级阅读变更说明尤其注意 v0.2.0传感器单位、v0.2.2climate 规则、v0.3.0unique_id三个需要手动操作的关键节点。更新后一般需重启 Home Assistant并在配置页勾选更新实体转换规则使规格字典变更生效。若编辑了 specs 目录下的文件spec_filter.yaml、spec_modify.yaml、multi_lang.json 等同样需要通过更新实体转换规则重新加载。多账号与多区域集成支持多个小米账号登录配置页 ADD HUB也支持跨区域导入设备v0.3.0 起支持共享家庭与独立共享设备导入。本地控制前提本地模式依赖中央网关固件 3.3.0_0023 及以上或内置网关功能的设备软件 0.8.9 及以上局域网控制仅支持同网段 IP 设备且区域内存在中央网关时局域网控制不生效详见 README.md 的 FAQ 与消息原理章节。从 v0.1.0 的First version到 v0.4.7 的土耳其语补充这份 changelog 既是一部集成功能的扩展史也是一份设备规格修正的编年档案。理解它的结构Added/Changed/Fixed与关键里程碑可以帮助开发者高效定位版本差异、预判升级风险并借助 specs 目录下的 YAML/JSON 文件快速验证任何一条历史变更的实际实现。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考