三步把小米设备接入 Home Assistantha_xiaomi_home 完整指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_home 是小米官方支持的 Home Assistant 集成组件manifest 版本 v0.4.7职责很明确把小米设备接入 Home Assistant。它基于小米物联网 MIoT 协议完成设备发现、状态同步与指令下发登录小米账号后灯具、插座、传感器会自动变成 HA 里的标准实体。适合已有 HA 环境、手里有米家设备、不想碰协议细节的用户也是目前上手成本最低的 HA 小米组件之一。三分钟把小米设备装进 HA先确认环境门槛Home Assistant Core ≥ 2024.4.4系统镜像 ≥ 13.0低于此版本缺少组件依赖的接口后续排障会很被动。两种安装方式任选其一Git 克隆拉取仓库后执行自带脚本组件会被复制到 HA 配置目录的custom_components下git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/configHACS在 HACS 商店搜索Xiaomi Home进入详情页下载即可之后的版本更新也在这里完成。授权一步到位进入设置 → 设备与服务 → 添加集成搜索Xiaomi Home按提示登录小米账号并选择账号所属区域中国大陆、欧洲、印度、俄罗斯、新加坡、美国。登录走 OAuth 2.0 流程组件本身不保存你的账号密码。随后在弹出的选择家庭与设备对话框中勾选要导入的家庭组件会自动批量发现账号下的设备无需逐台添加多个区域、多个小米账号的设备也可以汇入同一个 HA 实例统一管理。⚠️install.sh只接受一个参数——HA 的 config 目录路径传多或传少都会直接报错退出无论用哪种方式安装完成后必须重启 Home Assistant集成才会出现在列表中。工作原理MIoT 协议打底云端与本地两条通道ha_xiaomi_home 不逆向米家私有协议而是直接对接小米官方开放的MIoT小米物联网协议。该协议由小米 IoT 平台制定统一了设备的功能描述服务、属性、事件、动作、消息格式与编码接口长期稳定、设备兼容面广——这正是它能一次授权、批量导入而不是逐台手写适配的底气所在。通道层面是两套机制按场景取舍小米云控默认通道组件在小米云的 MQTT Broker 上订阅设备消息属性变更或事件发生会实时推送下来因此无需轮询控制指令则通过云端 HTTP 接口下发。人不在家也能远程操作对网络环境没有特殊要求。小米本地控制小米中枢网关内置标准 MQTT Broker组件直接向网关订阅和发布消息状态与控制指令只在局域网内流转响应接近即时。要求网关固件 ≥ 3.3.0_0023或使用内置中枢网关功能的小米设备软件 ≥ 0.8.9。没有网关时也可开启 LAN 控制作为部分本地方案但 README 对此持保守态度明确建议谨慎使用。对比维度小米云控小米本地控制通信路径设备 → 小米云 → HA设备 → 中枢网关 → HA外网依赖需要依赖小米云服务不需要纯局域网响应延迟受公网波动影响局域网内即时反馈隐私状态数据经云端中转数据不出局域网典型场景远程操控、跨地域访问传感器联动、本地自动化⚠️ 本地控制目前仅支持通过 WiFi 或以太网连接路由器的 IP 设备BLE Mesh、ZigBee 设备不在此列HA 跑在 Docker 中时建议把容器网络模式设为 host否则本地控制可能不生效。实体自动生成设备导完就能用导入完成的那一刻实体就已可用靠的是组件内置的 miot/specs/specv2entity.py 转换引擎。每台小米设备都带一份 MIoT-Spec-V2 规格引擎读取它并自动判断每个属性的读写性与数据类型翻译成对应的 HA 实体全程不需要手写映射。翻译规则在 README.md 中有完整定义核心逻辑四条属性Property可写的布尔属性 → Switch可写字符串 → Text带离散取值列表 → Select带数值范围 → Number只读属性 → Sensor事件Event→ Event 实体事件参数透传给_trigger_event例如无线开关的长按事件会带上按键类型动作Action无参数 → Button带参数 → Notify实体详情页会标注参数格式如[文本(str), 静音执行(bool)]输入形如[你好, true]设备级匹配规格实例名不满足特定转换规则时走通用规则非小米官方命名空间namespace 非 miot-spec-v2的实体名会加*前缀也就是说你面板上的每个 Switch、Sensor、Button 都是同一套规格驱动出来的结果设备规格升级后实体随之调整不需要人工维护对照表。兼容范围六大设备类别 12 种语言组件目录 custom_components/xiaomi_home/ 内组织了 18 个平台文件日常高频的六类设备与 HA 领域对照如下设备类别对应 HA 领域典型设备照明light智能灯泡、灯带开关插座switch智能插座、墙壁开关传感器sensor温湿度计、人体、门窗传感器温控climate空调伴侣、智能温控器风扇fan智能风扇、空气循环扇加湿器humidifier各类智能加湿器cover窗帘、vacuum扫地机、water_heater、media_player、device_tracker、number、select、text、notify、event、button、binary_sensor 等其余平台也已实现。官方 FAQ 说明目前不支持的品类只有三类蓝牙设备、红外设备和虚拟设备。语言方面custom_components/xiaomi_home/translations/ 下提供 13 个翻译文件覆盖 12 种语言中简、中繁、英、日、德、法、西、意、俄、荷、葡含 pt 与 pt-BR 两个地区版本、土。界面与实体文案跟随 HA 的语言设置自动切换无需单独配置。排障手册按顺序过一遍云端连不上 / 登录失败执行ping api.io.mi.com确认网络能访问小米云核对登录区域与账号实际所属区域是否一致可在米家 App → 我的 → 附加设置 → 关于米家中查看确认发起登录的终端与 HA 在同一局域网OAuth 回调地址homeassistant.local:8123可正常访问否则认证可能中途失败。实体状态不同步依次尝试重启 Xiaomi Home 集成 → 清除.storage/xiaomi_home.*缓存文件后再重启 → 检查设备固件是否过旧。本地控制失效确认中枢网关与 HA 在同一局域网 → 核对网关固件 ≥ 3.3.0_0023内置中枢的设备 ≥ 0.8.9→ 确认目标设备走的是 WiFi/以太网连接 → Docker 部署时把网络模式改为 host。部分设备没有出现在导入列表检查米家 App 中当前账号对该设备是否有控制权限家里账号较多时可在集成配置页通过 ADD HUB 继续添加其他小米账号。进阶场景联动为什么能成立两个典型画面。晚上到家门窗传感器触发回家玄关灯light亮起空调伴侣climate切到舒适温度——这条链路依赖的是 MIoT 协议把状态实时同步进 HA云端或本地通道保证传感器值不落地。夜里起身人体传感器sensor/binary_sensor感知到活动路径灯点亮、几分钟后自动关闭——依赖的是转换引擎把传感器能力变成了能直接写进自动化的标准实体。早上出门离家模式关闭全部灯光、空调切到节能。剩下的条件判断、延时、时段编排都是 HA 自动化本分内的事组件只负责把设备能力如实交出来。ha_xiaomi_home 把设备接入收敛成一次授权加自动发现规格翻译与状态同步由它接管。小米设备接入 Home Assistant 之后米家与 HA 之间只剩场景编排这一层而那部分交给 HA 自动化即可。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考