ha_xiaomi_home 实战解析：小米设备接入 Home Assistant 的完整路径
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
ha_xiaomi_home 是小米官方出品的 Home Assistant 集成：你用小米账号完成 OAuth 2.0 登录后，它把账号下的设备自动映射成 HA 实体，并支持 MiOT 云推送和本地中枢网关两条控制链路。对家里小米设备占比很高的 HA 用户来说，这是目前唯一不需要自己啃 MiIO 协议的官方方案。
云控和本地控制，各走什么链路 📡
这一节解决"你的指令到底怎么到达设备"的问题。
云控模式下，集成先向 MiOT Cloud 的 MQTT Broker（ha.mqtt.io.mi.com，8883 端口）订阅你关心设备的消息。设备属性变化或事件发生时，云 Broker 直接推给你，不需要轮询；控制指令则通过云的 HTTP 接口下发。这也是它默认cloud_polling却几乎不产生查询压力的原因——配置完成后只查一次全量属性，之后全凭推送。
本地控制模式依赖小米中枢网关（固件 3.3.0_0023 及以上），或内置中枢功能的设备（软件版本 0.8.9 及以上）。网关内置标准 MQTT Broker，集成通过 mDNS 服务_miot-central._tcp.local.自动发现它，订阅和发布都走局域网，指令不出内网。要注意：中枢网关目前仅在中国大陆地区销售，海外账号基本只能走云控。
三步跑通最小部署
这一节给你从克隆到看到实体的最短路径。
在 HA 的配置目录里执行克隆和安装脚本（./install.sh只做了两件事：把custom_components/xiaomi_home拷进配置目录，然后提示你重启）：
cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config然后：
- 重启 Home Assistant（要求 Core ≥ 2024.4.4）
- 设置 → 设备与服务 → 添加集成，搜索Xiaomi Home
- 页面里点击登录，用小米账号完成 OAuth 授权
- 在弹出的"选择家庭和设备"对话框里勾选要导入的家庭
支持多账号、多地区：同一个集成实例里可以再加 HUB 登录第二个小米账号，不同地区的设备可以放进同一个区域。
核心机制：一份 Spec，三种实体 🧩
这一节讲设备是怎么"翻译"成 HA 实体的，值得看代码。
miot/miot_client.py：统一门面。它把云、网关、LAN 三条链路的差异全部收拢在内部，上层实体只调用sub_prop/set_prop_async/action_async，不关心消息从哪条链路来。miot/miot_mips.py：MIoT Pub/Sub 消息层。基于 paho-mqtt 实现，云和本地网关各有一个客户端实现，但对外接口一致，切换控制模式时实体代码零改动。miot/specs/specv2entity.py：转换引擎。小米的MIoT-Spec-V2规定了每个设备的 services / properties / events / actions，集成按规则建实体：可写的 bool 属性变 Switch，带 value-list 的变 Select，带 value-range 的变 Number，只读属性变 Sensor，无参 Action 变 Button，有参 Action 变 Notify。一共支持 light、switch、climate、sensor、fan、vacuum、media_player 等 18 类平台。
所以"设备能不能进 HA、进来长什么样"完全由 Spec 决定，这是它和第三方小米集成最大的差别——规格描述是厂商自己维护的，准确性有保证。
进阶玩法：改规则文件，定制你的实体
跑通之后，custom_components/xiaomi_home/miot/specs/目录是你最常碰的地方：
spec_filter.yaml：按设备 URN 过滤掉不想创建的实体，支持通配符（比如过滤某服务下的全部属性）spec_modify.yaml：修改属性的 access、format、unit、value-range 等字段multi_lang.json：本地维护的多语言字典，优先级高于云端翻译，可修正设备名称和单位
改完这些文件后，必须在集成 CONFIGURE 页面点Update entity conversion rules才会生效。另外可以打开Debug mode for action：每个带参 Action 会多生成一个 Text 实体，直接手输参数数组（例如["Hello", true]）就能向设备发指令，调试时省掉了写自动化。
排错速查表 🔧
- 登录后设备列表为空→ 确认所选地区正确（不同地区云数据隔离），回到 CONFIGURE 重新选择家庭；若怀疑 token 泄露，到米家 App → 我的 → 小米账号 → 授权管理中移除"Xiaomi Home"重新授权
- 本地模式不生效→ 确认网关固件 ≥ 3.3.0_0023 且与 HA 同网段；如果你只开了 LAN 控制功能但局域网里存在中枢网关，LAN 控制会被自动忽略，以网关为准
- 实体状态不同步→ 集成页重启一次；仍异常可清理
.storage里xiaomi_home相关缓存文件后重新导入 - 某类设备完全进不来→ 蓝牙、红外、虚拟设备不在支持范围内；个别型号在
const.py的UNSUPPORTED_MODELS黑名单里，属于官方明确不兼容 - 官方不推荐 LAN 控制功能→ 它只能控同网段 IP 设备，且文档明说可能引起异常，没有中枢网关时再考虑，开启入口在 CONFIGURE → Update LAN control configuration
下一步建议：翻一遍 CHANGELOG.md 看看最近修了哪些你设备的型号问题，想提修改需求可以直接参考 CONTRIBUTING.md 给 specs 目录提 PR——改设备规格不需要碰代码，是参与这个项目成本最低的方式。
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
