企业官网建设流程全解析

小米Home Assistant集成浴霸模式控制丢失：原因、5步修复与验收方法

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

TL;DR：问题、影响与修复成本

• 问题：小米 Home Assistant 集成（ha_xiaomi_home，Xiaomi Home Integration）更新后，奥普（aupu）、易来（yeelink）浴霸在 HA 中的模式控制实体消失，设备下只剩灯光开关，无法再切换换气、暖风、干燥等模式。
• 触发版本：v0.2.2 起。该版本修改了浴霸、空调、新风机的实体转换规则（集成内部术语：把设备属性翻译成 HA 实体的规则）。
• 修复版本：v0.2.3（PR#899），已随版本发布，无需自行改代码。
• 操作成本：更新集成 → 重启 Home Assistant → 配置页勾选两个更新选项 → 移除并重新添加受影响浴霸，全程约 10 分钟，其他设备与自动化不受影响。

现象与影响范围

触发条件：将集成从 v0.2.1 或更早版本升级到 v0.2.2（含）之后出现。v0.2.2 的 更新日志 明确提示：该版本修改了浴霸、空调、新风机的实体转换规则，更新后需要重启 HA 并勾选xiaomi_home > 配置 > 更新实体转换规则 > 下一步重新加载集成。

受影响设备（用户已确认的型号，均以 MIoT 品类bhf_light浴霸灯为主）：

同品类的其他浴霸型号（如 xiaomi.bhf_light.s1、mike.bhf_light.2、yeelink.bhf_light.v10 等）如果也升级到了 v0.2.2+，建议一并自查。

确认是否受影响，按下面 3 步自查：

1. 打开 HA「设置 → 设备与服务 → 设备」，进入浴霸设备页；
2. 查看实体列表：若只有 light（灯光开关）实体，缺少 climate（温湿度/气候）实体，或 climate 实体上没有了模式选项，即中招；
3. 交叉验证：米家 App 仍能正常切换模式、设备本身无故障，说明问题出在集成的属性映射层，而非硬件或云端。

根因复盘：一条属性为什么"映射不到"

排查链条按「现象 → 原始数据 → 转换规则 → 修复点」展开：

1. 现象：实体列表里少了模式控制，其余实体（灯光开关）正常。
2. 原始数据：浴霸在小米 MIoT 规范（设备属性标准描述）中定义了ptc-bath-heater服务，其下的mode属性承载换气、暖风、干燥等模式值，设备一直在正常上报这个属性。
3. 转换规则：v0.2.2 把浴霸的mode属性映射到 climate 实体的 preset mode（HA 的"预设模式"字段，即下拉选择项）。但初始化 climate 实体的开关联动时，没有显式指定服务名和属性名，属性匹配落空，模式实体没有被正确生成。
4. 修复点：v0.2.3 的 PR#899 在初始化时显式指定了服务名与属性名，保证ptc-bath-heater的mode稳定映射到 climate 的 preset mode。同版本还修复了切换预设模式时的 hvac mode 设置错误，以及 yeelink.bhf_light.v10 模式值描述歧义。

集成本身运行正常，状态与控制消息的收发链路没有断，所以设备在线状态、灯光开关都不受影响——坏的只是"属性 → 实体"这一层的映射。集成与网关/云端之间的消息链路可参考下图：

修复与验收：5 步操作与验收标准

前置：将集成更新到 v0.2.3 或更高版本（HACS 用户直接拉取更新；Git 安装方式可切换对应 tag 后重新执行./install.sh，安装方法见 doc/README_zh.md）。

1. 重启 Home Assistant；
2. 进入「设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置」，勾选更新实体转换规则和更新设备列表，重新加载集成；
3. 移除受影响的浴霸设备（奥普/易来等bhf_light型号）；
4. 重新添加该设备；
5. 在设备页验证模式控制。

怎么确认修好了（三条都满足才算修复完成）：

• 设备下重新出现 climate 实体，预设模式下拉包含换气、暖风、干燥等选项；
• 切换预设模式后，设备实际运行状态改变，且状态几秒内同步回 HA；
• 日志中无该设备相关的set_properties报错。

可用米家 App 对照操作一次，确认设备端确实切换了模式，排除"HA 显示已切换但设备未执行"的假修复。

排查速查：给维护者/开发者

• 先锁定设备型号（格式：品牌.品类.型号，如aupu.bhf_light.s10m），再对照 CHANGELOG.md 中涉及 MIoT-Spec 的条目，确认近期是否动过该品类的规则；
• 在 HA「开发者工具 → 状态」中查看设备原始属性，确认目标服务（如ptc-bath-heater）与属性（mode）是否存在、取值是否正常，把问题定位到"数据缺失"还是"映射失败"；
• 检查 miot/specs/specv2entity.py 中该服务的转换映射，以及 spec_modify.yaml、spec_add.json 是否有针对该型号的覆盖规则；
• 核对实体初始化逻辑是否显式指定了服务名与属性名，避免依赖默认匹配——本次事故就是匹配落空；
• 开 debug 日志复现一次开关/切模式操作，搜索对应属性名与set_properties关键字，确认指令是否发出、是否返回错误码。

后续预防

用户侧

• 更新前浏览 CHANGELOG.md 的 Changed 小节，出现"实体转换规则"字样时，升级后重点核对依赖该实体的自动化；
• 升级后对关键设备（浴霸、空调、新风机等品类）做一轮实体清单对比，发现实体变少立即记录型号与日志反馈；
• 更新前备份 HA 配置文件，遇到异常可快速回滚到上一个 tag。

维护者侧

• 调整实体转换规则时，初始化必须显式指定服务名与属性名，不依赖默认匹配逻辑；
• 对 ptc-bath-heater 这类多品牌高频品类建立回归清单，规则变更后用受影响型号批量验证实体生成结果；
• 在 CHANGELOG 中为破坏性变更标注恢复步骤（如本事故的"勾选更新转换规则 + 移除重加设备"），缩短用户自查与修复路径。

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