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 集成组件作用是把你手里的米家设备接入 Home Assistant下文简称 HA一次账号授权自动发现并批量导入设备再把设备能力自动转成 HA 实体同时提供云端与本地两条控制通道。按本指南操作从零到跑通第一条自动化全程不需要写一行映射代码。为什么米家设备接 HA 总是出问题而它不用在装任何东西之前先弄清一个前提米家是一个相对封闭的生态设备数据默认只在米家 App 与小米云之间流动。而 HA 的优势恰恰在开放——它期望各家设备通过标准协议上报状态、接收指令。过去想跨过这道墙常见手段是抓包、逆向协议。这类方案的共同问题是脆米家 App 或云端接口一更新插件就可能全线失效且每接一个新设备都得多写一套对接逻辑。ha_xiaomi_home 走的是另一条路直接对接小米官方开放的 MIoT小米物联网协议。简单说MIoT 是小米给每款 IoT 设备写的能力说明书用服务、属性、事件、动作四个部分描述设备会什么、能改什么、发生了什么。对着官方说明书接入有三个直接好处接口由小米官方维护不再随逆向工程失效设备兼容面广覆盖照明、插座、传感器、温控、风扇、加湿器等常见品类接入动作收敛为一次授权、自动发现不为每台设备手写对接代码。✅ 登录走 OAuth 2.0HA 不保存你的小米账号密码但登录后的设备信息、token 会以明文存放在 HA 配置目录里请妥善保管该目录。怀疑 token 泄露时可到米家 App 的账号管理页撤销应用授权。三步装好 Xiaomi Home 集成安装前自检与三种安装方式动手前先过一遍检查点HA Core 版本 ≥ 2024.4.4过低版本缺少组件依赖的接口网络能正常访问小米云服务设备是 WiFi/以太网接入或家中已配备支持本地模式的中枢网关。安装方式三选一任选其一即可方式一Git 克隆 安装脚本官方推荐便于按 tag 切换版本git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/configinstall.sh只接受一个参数——HA 的config目录路径它负责把组件复制到config/custom_components/xiaomi_home。想更新到某个版本时git checkout对应 tag 后重跑脚本即可。方式二HACS在 HACS 商店搜索 Xiaomi Home进入详情页点击下载。方式三手动复制把custom_components/xiaomi_home整个文件夹拷进 HA 的custom_components目录。账号授权与设备导入装完先别急着找设备必须重启 Home Assistant组件才会出现在集成列表里。然后按这个顺序走打开设置 → 设备与服务 → 添加集成搜索 Xiaomi Home按页面提示用小米账号登录选择账号所属区域中国大陆、欧洲、印度、俄罗斯、新加坡、美国登录成功后弹出选择家庭与设备对话框勾选要导入的家庭设备随即批量导入已有其他小米账号在集成设置页继续添加中枢即可追加账号多账号、多区域的设备可以合并进同一个 HA 实例集中调度。导入完成后到设备与服务里确认设备列表再给每台设备点一下实体状态对得上这一步就算跑通了。云端与本地两条通道一张表看懂怎么选组件不是二选一的开关而是两套可随时切换的通信通道差别在于指令和状态数据走哪条路。云端通道状态变化属性变更、上线、离线由小米云的 MQTT Broker 实时推给集成你的控制指令经 HTTP API 发到云端再转发给设备。不挑网络环境人在外地也能操作家里设备。本地通道把通信终点从云端换成小米中枢网关——网关内置的 MQTT Broker 承担状态同步与指令收发数据只在局域网里转一圈不经过任何外部服务器。维度云端通道本地通道数据路径设备 → 小米云 → HA设备 → 中枢网关 → HA出门在外能否用可以只要 HA 能上网不行仅限局域网内指令延迟受网络状况影响毫秒级几乎无感数据去向经云端中转不出局域网前置条件小米云服务可达中枢网关且与 HA 同网段选通道时按场景定别纠结哪个更好你家里有中枢网关 → 优先本地传感器联动这类高频动作走局域网最稳你只有纯云设备 → 走云端本地模式帮不上忙你常出门 → 云端兜底保证远程可用。两个版本门槛要注意独立中枢网关需固件 ≥ 3.3.0_0023带内置中枢功能的设备需软件版本 ≥ 0.8.9。另外组件还提供LAN 控制选项直接走局域网控制同网段的 IP 设备——官方对它的评价是谨慎使用且家中已有中枢网关时开启它也不生效能走网关就别用它。导入的设备为什么自动就有了实体设备一导入灯、插座、传感器就已经在 HA 面板里能用了——这一步背后是 custom_components/xiaomi_home/miot/specs/specv2entity.py 里的转换引擎在干活。MIoT-Spec-V2即上文的 MIoT 协议规格里每个属性都标着访问方式只读、读写和值类型。如果你自己动手翻译要逐属性判断这该变成开关还是传感器引擎把这活自动化了核心规则大致如下MIoT 属性特征生成的 HA 实体可写的布尔属性switch可开关只读的数值属性sensor传感器读数可调档位/数值属性number 或 select动作如开始工作button 或对应领域实体事件如有人移动event 实体设备整体则按类型落到具体领域智能灯 → light、空调伴侣 → climate、智能风扇 → fan、加湿器 → humidifier 等。也就是说你导入完成的那一刻实体已经就位可以直接拖进自动化。当前覆盖六类高频设备照明light、开关插座switch、传感器sensor、温控climate、风扇fan、加湿器humidifier。明确不支持的是蓝牙设备、红外设备与虚拟设备买设备前可以先对一下。第一个联动怎么配四个卡点怎么快速排查跑通第一条自动化别一上来就搭全屋场景先拿一条最短的链验证闭环。例如人体传感器触发 → 玄关灯亮 5 分钟后关闭打开 HA 的自动化与脚本 → 创建自动化触发条件选已导入的人体传感器实体事件类型选发生执行动作选玄关灯的 light 实体打开再追加延时 5 分钟 → 关闭保存后手动在传感器上触发一次或走到传感器跟前确认灯真的动了。这条链同时验证了设备导入、实体转换、指令下发三件事。跑通之后回家、看电影、夜间起床这类场景都只是把同样的积木换一种拼法。卡住时按顺序查这四类问题设备根本连不上先ping api.io.mi.com确认 HA 所在网络能通小米云再到米家 App 里确认该账号对设备有控制权限排除设备本身离线。实体状态和实际不一致按顺序试——重启 Xiaomi Home 集成 → 清理.storage/xiaomi_home.*缓存文件 → 检查设备固件是否过旧。本地控制不生效确认中枢网关与 HA 在同一局域网核对网关 IP 与配置一致确认设备属于本地控制支持范围WiFi/以太网接入BLE Mesh、ZigBee 设备不行。实体类型不符合预期这是转换引擎按 MIoT 规格映射的结果属正常现象可先接受它或在集成设置里调整导入的设备清单。下一步做什么装完之后建议按这个顺序推进今晚就把上面那条人体传感器 → 玄关灯的自动化跑起来先让闭环转一圈把家里最高频的三五个联动回家、离家、夜间、观影排出来逐个用实体拼好有中枢网关的话观察本地通道一两天对比响应速度和稳定性再决定是否把常开设备全切到本地。细节随时可查仓库里的 README.md 与中文文档 doc/README_zh.md本指南只讲主干坑都标在路上了。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
