此项目为 Home Assistant 的巴法云插件。
Fork 自 skddyj/bemfa，在原版基础上修复了多项 Bug 并增加了诸多实用功能。
功能
将 Home Assistant 实体同步至巴法云，并使用小爱同学/天猫精灵/小度音箱控制。
与原版相比的增强功能
🎯 设备类型自定义
- 添加实体时可手动选择巴法云设备类型：不再局限于 HA 实体类型自动映射，例如可以将 HA 中的
switch 实体映射为巴法云的「灯」类型，这样语音说"关闭所有灯"时这些开关也会被关闭
- 编辑时支持修改类型：已同步的实体可以在编辑页面随时更改巴法云设备类型，自动删除旧 Topic 并创建新 Topic，无需删除重建
- 补全所有巴法云设备类型：支持插座(001)、灯(002)、风扇(003)、传感器(004)、空调(005)、开关(006)、窗帘(009) 共 7 种类型
🚀 批量操作
- 多选批量添加实体：支持同时选择多个实体一次性添加，无需逐个操作
- 实体搜索过滤：添加实体时支持关键字实时搜索，快速定位目标实体
- 统一命名/类型配置页：批量添加时，所有实体的名称和类型在同一页面配置，配合参考表格清晰明了
🆕 更多实体类型支持
- input_boolean：修复了原版中 input_boolean 在同步层已支持但 UI 中无法选择的问题
- input_button：新增支持，映射为巴法云开关类型，语音说"打开"时触发 press 服务
🛡️ 稳定性修复
- MQTT 线程安全修复：修复了巴法云→HA 方向控制命令失效的问题。原版在 paho-mqtt 回调线程中使用了非线程安全的
async_create_task()，导致语音控制命令静默丢失，改用线程安全的 hass.services.call() 解决
- API 双重容灾：巴法云新版 API（pro.bemfa.com）不稳定时会自动回退到旧版 API，确保创建/删除/查询/重命名等操作可靠执行
- Topic 命名修复：巴法云 API 不允许 Topic 名称包含下划线等特殊字符（错误码 40009），原版使用 MD5 哈希生成的 Topic 含有字母数字，但新版改为更可读的实体 ID 格式并过滤非法字符
- 色温 MIN/MAX 修正：修复了空调色温最小/最大值互换导致色温控制异常的问题
- MQTT 阻塞修复：修复了 MQTT 连接可能阻塞 HA 事件循环的问题
- API 错误处理：增加了巴法云 API 调用的错误日志记录和异常处理
🔍 孤儿 Topic 检测
- 自动检测巴法云上存在但 HA 中已无对应实体的 Topic（例如实体被删除或重命名后遗留）
- 通过 HA 持久通知提醒用户清理，避免巴法云上残留无用设备
📦 其他改进
- 实体选择器优化：选择列表中同时显示 entity_id 和友好名称，便于精确识别
- HACS 兼容：添加 HACS 验证工作流和品牌图标
- paho-mqtt 升级：升级至 paho-mqtt 2.1.0，兼容最新版 Home Assistant
- LockState 导入修复：修复了 HA 新版本中 LockState 导入路径变更导致的启动错误
- deprecated 属性修复：修复了 HA 新版本中已废弃 API 的调用
使用
- 注册巴法云账号，并获取密钥
- 在 HACS 中搜索 bemfa 安装，或者 clone 此项目，将
custom_components/bemfa 目录拷贝至 Home Assistant 配置目录的 custom_components 目录下
- 重启 Home Assistant 服务
- 在 Home Assistant 的集成页面，搜索 “bemfa” 并添加
- 根据提示输入巴法云密钥后提交
- 安装成功后，点击集成左下角"选项"，同步需要的实体至巴法云
- 在智能音箱 App 中添加巴法云设备：
- 小爱同学：米家 App → 我的 → 其他平台设备 → 点击添加 → 找到"巴法"，输入巴法云账号即可，设备会自动同步到米家
- 天猫精灵：打开天猫精灵 App，搜索"巴法云"，找到巴法云技能，点击绑定账号，登录你的巴法云账号
- 小度音箱：打开小度音箱 App 或小度 App，首页点 + 号 → 添加设备 → 搜索巴法，找到"巴法"，输入巴法云账号即可
支持的实体类型
| HA 域 |
巴法云默认类型 |
说明 |
light |
灯 (002) |
支持亮度、色温/颜色控制 |
switch |
开关 (006) |
开关控制 |
fan |
风扇 (003) |
支持风速、摇头控制 |
cover |
窗帘 (009) |
支持开合度控制 |
climate |
空调 (005) |
支持温度、模式、风速控制 |
sensor |
传感器 (004) |
按区域分组，支持温度/湿度/光照/PM2.5/CO₂ |
binary_sensor |
传感器 (004) |
开关量传感器 |
input_boolean |
开关 (006) |
辅助布尔开关 |
input_button |
开关 (006) |
辅助按钮，语音"打开"时触发 press |
script |
开关 (006) |
脚本执行 |
automation |
开关 (006) |
自动化开关 |
scene |
开关 (006) |
场景触发（始终为 OFF，任意命令触发） |
camera |
开关 (006) |
摄像头状态 |
media_player |
开关 (006) |
播放/暂停 |
lock |
开关 (006) |
锁开关 |
humidifier |
开关 (006) |
加湿器开关 |
vacuum |
开关 (006) |
扫地机启停 |
group |
开关 (006) |
群组开关 |
remote |
开关 (006) |
遥控器 |
siren |
开关 (006) |
警报器 |
💡 所有实体的巴法云类型均可在添加或编辑时手动修改。例如将 switch 类型的实体改为「灯」类型，即可通过"关闭所有灯"语音命令统一控制。
原理
巴法云使用 MQTT 与终端设备通信，每个设备对应一个主题（Topic）。
此插件根据用户选择的需要同步的实体，调用巴法云 API 创建对应主题，将此实体的实时状态发布至此主题，并订阅此主题的信息以控制它。
Q/A
-
Q: 哪些实体支持同步至巴法云？
A: 受巴法云的限制，目前仅支持插座类、灯类、风扇类、窗帘类、空调类和传感器类，并且对每种语音助手的支持各有稍许区别，例如小度音箱不支持风扇的摇头控制，具体参考巴法云文档。此外，此插件将扫地机/脚本/自动化/场景/input_boolean/input_button/分组/摄像机/加湿器/媒体播放器/锁/遥控器/汽笛虚拟成开关类设备，可通过语音开关。
-
Q: 为什么调节灯的颜色时却是调的色温？
A: 巴法云中灯的颜色和色温为同一个字段，此插件中无法精确区分。如果你的灯既可以调节颜色又可以调节色温，可能会出现混乱的情况。
-
Q: Home Assistant 中米家的设备本就支持小爱同学配置，还需同步至巴法云么？
A: 不需要，并且不建议同步，没必要经过巴法云绕一圈。
-
Q: 同时有小爱同学和天猫精灵，如何只同步非米家设备至小爱同学，并同步所有设备至天猫精灵？
A: 目前没有太好的方案，一个可行的方案是注册 2 个巴法云账号，分别配置不同的插件实体进行同步，然后将 2 个账号分别绑定到小爱同学和天猫精灵。
-
Q: 修改了 HA 中的实体名称（entity_id），对已同步的巴法云设备有什么影响？
A: entity_id 变更后，旧的巴法云 Topic 不会自动关联到新实体，会变成"孤儿 Topic"。插件会在启动时检测并通知你清理。你需要在巴法云选项中删除旧的同步，再用新 entity_id 重新添加。
-
Q: 我有一些开关实际控制的是灯，怎么让语音助手把它们当灯来控制？
A: 添加实体时，将类型从默认的"开关"手动选择为"灯"即可。这样语音说"关闭所有灯"时，这些开关也会被关闭。已添加的实体也可以在编辑页面修改类型。
评论