技能介绍

解决的问题

当你手里有一台联网智能设备，比如海信除湿机 CF24BD/UW，它能用厂商官方 APP 控制，但 Home Assistant 没有现成的集成，自然也进不了米家生态。这意味着你无法通过小爱音箱喊一句“打开除湿机”来控制它。这个技能要解决的，就是这类“厂商云 API 可控制、但 HA 官方集成不支持”的设备如何接入米家语音控制的问题。

核心思路

厂商设备大多有可逆的云 API（APP 能控制 = 云端有接口）。整个链路由两个桥接拼起来：HA 集成负责设备 ↔ 厂商云，巴法云负责米家/小爱 ↔ HA。凡是厂商云 API 能做的功能（开关/档位/模式/湿度…）都能语音化。

关键步骤

Phase -1: 搭建 Home Assistant

可选 Windows 原生（python -m venv ha_venv + pip install homeassistant）、Docker Desktop、虚拟机 + HassOS 或树莓派/NAS。Windows 原生需注意 DNS/automation/端口保留等兼容问题。

Phase 0: 连接米家扩展包（可选）

安装 xiaomi_home 自定义组件，将已有米家设备（如小爱音箱、米家插座）导入 HA 统一管理。需修复 Windows 下 aiohttp DNS 超时（TCPConnector(resolver=ThreadedResolver())），并确保 OAuth 重定向地址与 internal_url 一致。

Phase 1: 设备接入 HA

优先找现成集成（GitHub/HA 论坛/HACS）。没有则抓包厂商 APP（Charles/mitmproxy/HttpCanary），捕获 access_token、device_id、wifi_id 等参数，搭建 coordinator 轮询 + entity 平台（switch/select/number/sensor）。指令集必须实测：用交互式测试器逐个发送 cmdId，观察设备真实反应，排除“云端接受但设备无反应”的伪有效指令。

Phase 2: 巴法云桥接

安装社区修复版 bemfa 插件，手动装 paho-mqtt==2.1.0。巴法云主题格式为 hass + md5(entity_id) + 后缀（如 006=SWITCH）。通过 API 创建主题，直接改 .storage/core.config_entries 绕过 config flow 401 限制。

Phase 3: 米家绑定

米家 APP → 我的 → 其他平台设备 → 添加 → 巴法 → 登录巴法云账号，设备自动同步。改名不更新时需删绑定重加或手动重命名。

适用边界与注意点

单向限制：xiaomi_home 只能把米家设备导入 HA，不能反向暴露 HA 设备为米家设备。反向暴露必须走巴法云。
指令验证：云端返回 result=True ≠ 设备执行，必须通过 scripts/power_test_server.py 实测每个功能。
DNS 修复：Windows 下所有 aiohttp ClientSession 需加 ThreadedResolver()，否则 ha.api.io.mi.com 解析超时。
automation 失效：Windows 原生 HA 重启前追加到 automations.yaml 的新 automation 可能不生效，可直接在 bemfa 的 _mqtt_on_message 硬编码调 service。
MQTT 验证：巴法云不转发第三方 client 消息，只能通过 MQTT RX 日志和用户实测确认。
版本兼容：HA 2026.x 移除 area_entities，需改用 entity_registry 遍历过滤。