米家设备接入 Home Assistant 完整指南：ha_xiaomi_home 快速安装与双模式控制
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
出门前想确认家里所有设备状态，你不想再开米家 APP 刷一遍。ha_xiaomi_home 是小米官方支持的 Home Assistant 集成组件，登录后自动导入你米家账号下的 MIoT 设备，并把它们转换成 Home Assistant 原生实体，灯光、空调、传感器从此可以在同一个平台里做联动。
一键安装步骤与账号授权
先确认版本要求：Home Assistant Core ≥ 2024.4.4，Operating System ≥ 13.0。当前仓库 manifest 中的组件版本为 v0.4.7。
方式一：git clone（官方推荐），好处是回退到指定版本只需切换 tag。
git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home && ./install.sh /config方式二：HACS，在 HACS 搜索框输入 Xiaomi Home，进入详情页点 DOWNLOAD 即可。
安装后重启 Home Assistant，进入"设置 > 设备与服务 > 添加集成"，搜索 Xiaomi Home。登录走 OAuth 2.0 流程，组件不会保存你的账号密码；成功后弹出"选择家庭与设备"，选中米家家庭，该家庭下所有设备一次性导入。几个细节值得知道：
- 支持多账号，可继续"添加中枢"导入第二、第三个小米账号，不同账号设备能放进同一区域
- 云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个地区，导入前需选区；不同地区的设备也能合并到同一区域
- 我装好后第一个发现的是：温湿度传感器变成带 device_class 的标准 Sensor，不用再写模板实体
它怎么连上设备：云控与本地控制
组件支持两条链路，像打电话和当面对话的区别：云控指令要经过小米云"运营商"转发，本地控制则是在局域网里直接对话。
云端控制：组件订阅小米云 MQTT Broker 中你关注的设备消息。设备属性变化、事件触发、在线/离线，都会以 properties_changed、event 消息实时推下来，不用轮询。控制方向则走云端 HTTP API 的 set_properties 和 action 接口。官方说明，正因为是订阅制，组件只在配置完成时向云端查询一次全部设备属性，后续靠推送，对云端压力很小。
本地控制：小米中枢网关内置标准 MQTT Broker，完整的订阅-发布机制落在局域网里。组件通过 zeroconf 发现服务_miot-central._tcp.local.来找到网关。注意两条硬限制：中枢网关目前仅在中国大陆销售；要求网关固件 ≥ 3.3.0_0023，或带内置中枢网关的设备软件 ≥ 0.8.9。没有中枢时，所有指令自动回落云端。
三组场景玩法
夜间走廊感应灯
人体传感器（如 lumi.sensor_motion）在 MIoT-Spec-V2 里定义的是"事件"，会被转成 Event 实体并带出触发参数。用它做条件，夜间时间段触发走廊灯开关，比定时更贴合实际活动。
空调伴侣自动调温
空调伴侣会转成 climate 实体。写一条自动化：室内温度实体高于 28℃ 且人不在家，就通过 HTTP API 下发 set_properties 把空调调到节能温度，全程不需要你碰手机。
音箱播报联动
带参数的 Action 会转成 Notify 实体。官方 README 里给了小米智能音箱 xiaomi.wifispeaker.s12 的例子，正确入参格式是["Hello", true]。你可以在"离家模式"里加一步语音播报"已为您关闭全部灯光"，出门不慌。
能力与代码速览
组件按平台文件组织，共 17 类实体入口：light、switch、sensor、binary_sensor、button、climate、cover、fan、humidifier、vacuum、media_player、water_heater、device_tracker、event、number、select、text。绝大多数 MIoT 品类能覆盖；明确不支持的是蓝牙、红外和虚拟设备三类。
- 实体转换核心：miot/specs/specv2entity.py。规则很简单，可写 bool 属性变 Switch，只读属性变 Sensor，带 value-list 变 Select，带 value-range 变 Number
- 过滤与定制规则：miot/specs/ 下的 spec_filter.yaml（过滤不转的实例）、spec_modify.yaml、multi_lang.json（本地多语言字典，优先级高于云端翻译）
- 局域网控制设备清单：miot/lan/profile_models.yaml，记录了各型号支持的 LAN 控制时间戳
- 配置流程界面语言：translations/，共 13 种语言
避坑清单
- 改过 specs 目录文件不生效：编辑 spec_filter.yaml、multi_lang.json 等后，必须在集成的 CONFIGURE 页面点"更新实体转换规则"才会生效
- 局域网控制功能谨慎开：它只能控 WiFi/网线接入的 IP 设备，碰不了 BLE Mesh、ZigBee 设备，且局域网里若有中枢网关则该功能自动失效；官方建议不要使用
- 配置文件是明文：登录后的证书、token 明文存在配置目录，怀疑泄露时去米家 APP > 小米账号管理 > 应用授权里取消 Xiaomi Home 的授权
- 多地区设备别漏选区：不同地区云端数据隔离，配置流程里选错区会看不到对应设备
- 蓝牙设备找不到：这是预期行为，蓝牙品类不在支持范围，换 WiFi 网关或中枢接入的设备即可
ha_xiaomi_home 的价值在于两点：订阅制消息让设备状态免轮询地实时同步，MIoT-Spec-V2 到 HA 实体的自动转换让你几乎不用手写映射。去仓库看看最新版，装好之后你会发现，联动自动化里少掉的"手动刷米家"那一步，终于可以删掉了。
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
