ha_xiaomi_home 实战解析：小米设备接入 Home Assistant 的完整路径

ha_xiaomi_home 实战解析小米设备接入 Home Assistant 的完整路径【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_home 是小米官方出品的 Home Assistant 集成你用小米账号完成 OAuth 2.0 登录后它把账号下的设备自动映射成 HA 实体并支持 MiOT 云推送和本地中枢网关两条控制链路。对家里小米设备占比很高的 HA 用户来说这是目前唯一不需要自己啃 MiIO 协议的官方方案。云控和本地控制各走什么链路 这一节解决你的指令到底怎么到达设备的问题。云控模式下集成先向 MiOT Cloud 的 MQTT Brokerha.mqtt.io.mi.com8883 端口订阅你关心设备的消息。设备属性变化或事件发生时云 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.pyMIoT 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），仅供参考