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_home米家设备困在小米 App 里Home Assistant 的自动化点不了灯、读不到传感器ha_xiaomi_home 是小米官方支持的集成组件登录一次小米账号设备就进 Home Assistant本地中枢与云端双通路控制。先跑起来三步装好米家集成前置条件Home Assistant Core 2024.4.4 及以上Operating System 13.0 及以上设备已在米家 App 中绑定到你的小米账号能访问 HA 的配置目录SSH、Samba 或 FTP 均可安装与授权克隆仓库并执行安装脚本/config是 Docker 部署下的配置目录路径按你的实际路径调整cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config重启 Home Assistant。打开 设置 设备与服务 添加集成搜索Xiaomi Home按提示用小米账号登录走 OAuth 2.0 授权密码不会保存在本地。在弹窗中先后选择设备所在区域中国大陆、欧洲、印度、俄罗斯、新加坡、美国和家庭完成设备导入。✅确认装好了重启后「添加集成」里能搜到 Xiaomi Home且仪表盘出现灯光、传感器等米家实体即表示成功。[!TIP] 以后升级只需切到对应版本 Tag 再跑一次 install.sh版本历史见 CHANGELOG.md。它到底怎么工作本地控制与云端控制打个比方你对空调说打开本地模式像打分机电话——电话直接走家里的总机小米中枢网关不出家门网络云端模式像走运营商中继——先出公网、由小米云平台转发再回到家里。两条通路都走订阅-推送集成向 MQTT Broker一种消息中间件订阅设备消息状态一变就立刻推过来而不是反复轮询问你好了没所以云端压力也很小。云端控制没有网关时状态经小米云 MQTT Broker 推送控制指令经 HTTP 接口发到云端再转发给设备。本地控制家里有小米中枢网关固件 3.3.0_0023 及以上或内置中枢网关的设备软件 0.8.9 及以上时集成通过 mDNS 自动发现它服务名就写在 manifest.json 里zeroconf: [_miot-central._tcp.local.]网关内嵌标准 MQTT Broker订阅和下发都在局域网内完成指令不出家门延迟更低。注意独立中枢网关目前仅在中国大陆可买。默认控制模式是auto会自动判断该走哪条通路也可以手动指定见下节。调一调更好用手动指定本地控制改哪里已配置 Xiaomi Home CONFIGURE控制模式项源码中键名为ctrl_mode见 miot/const.py。改成什么默认auto有中枢网关时可固定为本地。为什么分机线路优先于运营商中继局域网直达更快更稳。过滤不想要的实体改哪里组件目录下的 miot/specs/spec_filter.yaml。改成什么按设备 URN 追加规则可过滤整台设备或指定服务/属性支持通配符urn:miot-spec-v2:device:television:0000A010:xiaomi-rmi1: services: - *为什么一台设备可能转出几十个实体过滤后面板和自动化更干净。改完在 CONFIGURE 页点更新实体转换规则生效。开启 Action 调试模式改哪里同一 CONFIGURE 页 Action 调试模式。改成什么打开。为什么面板会出现文本实体可以手写参数直接下发 action 指令验证设备能力时最省事。卡住了先看这里导入后个别设备不显示现象某台米家设备没出现在实体列表。最可能原因蓝牙、红外和虚拟设备这几类品类不支持个别型号也被明确排除。解决动作确认设备接入方式WiFi 或网线IP 连接的设备才能正常集成支持范围详见 README.md 的 FAQ。控制响应慢、偶尔失败现象面板点开关设备要等一两秒才动。最可能原因家里没有中枢网关指令全部绕云端受外网质量影响。解决动作加装中枢网关固件 3.3.0_0023 及以上或使用内置中枢设备并把控制模式改为本地。⚠️ 不建议强开局域网控制功能它只覆盖 IP 接入设备且官方文档明确不推荐。选不到别的账号或海外区的设备现象只能看到一个账号、一个区域的设备。最可能原因小米云数据按区域隔离每个账号只导入自己所选区域的数据。解决动作在集成页点添加中枢登录第二个账号导入时选好对应区域不同账号的设备可以放进同一个 Home Assistant 区域。到这里装好、导入、调通米家设备就能进 Home Assistant 的自动化和仪表盘了。想继续深入 MIoT-Spec-V2 到 HA 实体的映射规则可以翻 中文文档或到 test/ 目录里跑测试脚本验证你的自定义配置。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考