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早上 7 点卧室的灯还亮着窗帘纹丝不动——因为你得先在手机上解锁米家 App找到对应的房间再逐个点开开关。如果家里同时还有 Home Assistant 在跑其他自动化这种两套系统来回切的日子几乎每天都在重复。而今天要介绍的 ha_xiaomi_home正是用来结束这种局面的它是小米官方为 Home Assistant 提供的集成组件专门解决小米智能家居与 Home Assistant 统一管理这件事。先说结论这个组件能帮你省下什么在动手之前先搞清楚它到底做了什么。ha_xiaomi_home 的核心作用只有一句话把你小米账号下的设备映射成 Home Assistant 里可以直接调用的实体entity。装好之后灯、开关、传感器、空调、加湿器这些设备会出现在同一个控制面板里你可以像操作普通 HA 设备一样使用它们也能让它们参与 HA 的自动化与场景联动。几个值得注意的事实它由小米官方维护云端接口走的也是官方通道不是第三方逆向方案。支持中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个区域的账号数据。支持多账号登录不同账号下的设备还能归入同一个 Home Assistant 区域。当前版本已覆盖灯具、开关、传感器、空调、风扇、加湿器、窗帘、扫地机、音箱等大部分常见品类蓝牙、红外和虚拟设备暂不支持。快速上手装好并跑通只要一个下午前置条件先核对检查项要求Home Assistant Core版本不低于 2024.4.4运行系统版本不低于 13.0网络能访问小米云服务可用ping api.io.mi.com验证三条安装路径任选其一路径一命令行克隆推荐方便日后切版本git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config路径二HACS 商店安装在 HACS 的搜索框里输入Xiaomi Home进入详情页点 DOWNLOAD 即可。安装完成后重启 Home Assistant就能在设备与服务里看到它。路径三手动拷贝把custom_components/xiaomi_home整个文件夹复制到 Home Assistant 的config/custom_components目录下同样需要重启生效。登录与设备导入装好之后进入设置 → 设备与服务 → 添加集成搜索 Xiaomi Home按提示登录小米账号。登录成功后会出现选择家庭与设备的对话框勾选你想导入的家庭该家庭下的设备就会批量进入 Home Assistant。这里有两个实用技巧一是登录成功后可以继续添加中枢把第二个小米账号也接进来二是如果设备分布在不同地区配置时记得选对区域——组件允许把不同区域的设备合并到同一个 Home Assistant 区域里管理。两种工作模式云上遥控还是本地直连先理解一个概念设备消息的流转路径决定了你的控制体验。ha_xiaomi_home 提供两种模式适合不同的人。对比维度云端模式本地模式消息中转站小米云MQTT Broker HTTP API小米中枢网关内置的 MQTT Broker适用场景外出远程控制、未购置网关的用户追求低延迟与隐私的局域网场景前置条件小米账号即可需要中枢网关或带内置中枢的米家设备地区限制六个区域均可用中枢网关目前仅中国大陆发售云端模式是默认兜底方案。设备状态变化时设备会向小米云发送上行消息云端的 MQTT Broker 会实时推送给集成你要控制设备时集成则通过 HTTP 接口下发指令。得益于订阅推送而不是轮询查询组件只在配置完成时向云端同步一次全量属性之后全靠事件驱动对云端的访问压力很小消息延迟也低。本地模式把中转站搬到了家里。小米中枢网关固件 3.3.0_0023 及以上或内置中枢网关的米家设备软件 0.8.9 及以上自带一个完整的 MQTT Broker设备上报与指令下发全程在局域网内完成不经过云端。对响应速度敏感的场景——比如人体传感器触发灯光、温湿度变化联动加湿器——这种模式会更从容。需要提醒的是如果你没有中枢网关所有指令都会走小米云而所谓小米局域网控制功能只能控制与 HA 同一局域网内的 IP 设备WiFi 或网线接入对蓝牙 Mesh、ZigBee 设备无能为力官方还提示该功能可能引发异常不建议普通用户开启。设备是怎么翻译成 HA 实体的小米设备遵循 MIoT-Spec-V2 协议——你可以把它理解成一套设备能力说明书每台设备会声明自己有哪些服务service、属性property、事件event和动作action。ha_xiaomi_home 的转换引擎核心逻辑位于custom_components/xiaomi_home/miot/specs/specv2entity.py会读取这份说明书自动把能力映射成对应的 HA 实体。映射规则其实很直观属性的读写性与格式生成的实体可写、布尔型Switch开关可写、枚举列表Select下拉选择可写、数值区间Number数字调节可写、字符串Text文本输入只读Sensor传感器事件Event事件实体无参数的动作Button按钮带参数的动作Notify通知这套智能转换意味着你不需要为每个设备手写映射关系设备接入后实体类型基本是自动生成的。组件还提供了spec_filter.yaml过滤规则可以把不需要的实例从转换中剔除保持实体列表干净整洁。真实场景一个家庭自动化的小样本原理讲完落到日常。假设家里有 5 盏智能灯、一台空调伴侣、一个温湿度传感器和一个门磁传感器接入 ha_xiaomi_home 之后可以组合出这样的自动化晚归模式门磁检测到开门客厅灯在 5 秒内渐亮至 40%空调根据室外温度自动设定。湿度联动书房湿度低于 45% 时加湿器自动开启达到 55% 后停止。离家兜底所有灯具在检测到离家后统一关闭空调切到节能档。夜间过道人体传感器在 23 点后触发仅点亮 10% 亮度的路径灯2 分钟后自动熄灭。这些场景里设备本身并没有变变的是它们从米家 App 里的图标变成了Home Assistant 里的实体——自动化的编写方式与任何其他 HA 设备完全一致。兼容性一览语言、地区与设备组件支持 13 种语言简体中文、繁体中文、英文、西班牙语、俄语、法语、德语、日语、意大利语、荷兰语、葡萄牙语、巴西葡萄牙语、土耳其语配置文件在custom_components/xiaomi_home/translations/目录下想微调界面文案可以改对应语言的 JSON 文件。设备实体的名称显示还会从云端拉取厂商的多语言文件本地字典multi_lang.json优先级更高可以用来修正个别翻译。避坑清单别人踩过的坑你提前绕开设备连不上云先确认网络能访问小米云再检查账号在米家 App 里对设备是否有控制权限。实体状态不同步依次尝试重启集成、在配置里选择更新实体转换规则、确认设备固件是否为最新版本。本地模式不生效确认网关与 Home Assistant 在同一局域网且网关固件版本达标如果家里同时存在中枢网关局域网控制功能会自动让位给中枢网关。关于账号安全集成采用 OAuth 2.0 登录不保存你的账号密码但设备信息、token 等用户数据会以明文存在 Home Assistant 配置文件中请务必保管好这份配置文件。若怀疑 token 泄露可在米家 App → 我的 → 账号与安全 → 应用授权中撤销授权。写在最后ha_xiaomi_home 的价值不在于它多了一个集成而在于它让小米设备真正成为了开放生态的一部分——你不需要为了一个品牌去维护一套孤立的系统。装好它登录账号选好家庭剩下的就交给自动化去运转。如果你正打算入手建议按这样的顺序推进先按文中的快速上手流程跑通云端模式确认日常使用稳定后再考虑是否添置中枢网关升级到本地模式。设备接入只是第一步真正有意思的部分从你写第一条自动化规则才开始。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考