小米米家设备接入 Home Assistant 一步到位：米家集成云控与本地控制完整指南

小米米家设备接入 Home Assistant 一步到位：米家集成云控与本地控制完整指南

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home

小米米家集成（Xiaomi Home Integration）是小米官方支持的 Home Assistant 集成组件，负责把 MIoT 智能设备翻译成 Home Assistant 实体。装它之前只有一个关键决策要做：你的控制链路走云端还是走本地。这个决策决定了每条指令的路径，也决定了你的设备清单里会出现什么——搞错它，后面装得多干净都白搭。本文覆盖决策、安装、实体映射、规则定制和排错的全流程。

云端还是本地：三条链路一张表看清

米家集成同时支持三条链路，且存在优先级关系。先把代价讲清楚：中枢网关链路和局域网链路都只在特定条件下生效，选错了要么功能不可用，要么官方明确警告可能引起异常。

链路	适用条件	限制	硬件要求	地区限制
云端控制	无中枢网关时的默认链路，全球可用	依赖外网；不同地区的小米云数据相互隔离，导入设备时要选对账号地区	无额外硬件	中国大陆、欧洲、印度、俄罗斯、新加坡、美国
本地控制（中枢网关）	有中枢网关时优先，断外网可用	状态订阅与指令下发全在局域网内完成，依赖网关在线	小米中枢网关（固件 3.3.0_0023 及以上），或内置中枢网关功能的米家设备（软件 0.8.9 及以上）	仅中国大陆
小米局域网控制	手动开启，与 HA 同网段的 IP 设备	管不到 BLE Mesh、ZigBee 设备；官方在 README 中明确建议不要开启，可能引起异常；局域网内只要存在中枢网关，即使手动开启也不生效，中枢网关链路优先	设备需 WiFi 或网线连接	无地区限制

一句话结论：有中枢网关（大陆地区）走本地，其余情况走云端，小米局域网控制保持关闭。

最短可用路径：安装、登录、生效三步

版本门槛：Home Assistant Core ≥ 2024.4.4，Operating System ≥ 13.0。当前仓库版本为 v0.5.0（见 custom_components/xiaomi_home/manifest.json）。

1. 安装：推荐 git 方式，后续可以精确切换 tag 回滚或升级到指定版本：

cd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config

install.sh 会把custom_components/xiaomi_home/复制到/config/custom_components/下并覆盖旧版本，运行后重启 Home Assistant。升级或回滚到某个版本：

cd /config/ha_xiaomi_home git fetch git checkout v0.4.7 ./install.sh /config

另外两条路：HACS 中搜索 "Xiaomi Home" 后 DOWNLOAD；或手动把custom_components/xiaomi_home/文件夹拷入config/custom_components/。

2. 登录：进入 设置 > 设备与服务 > 添加集成，搜索Xiaomi Home，走 OAuth 2.0 登录（授权式登录，账号密码不会存到 Home Assistant）。

3. 生效：登录成功后弹出"选择家庭与设备"对话框，选择要导入的米家家庭，该家庭下所有设备随之导入为实体。

两个后续用得上的入口都在 设置 > 设备与服务 > 已配置 > Xiaomi Home > 配置 里：多账号在同一集成页面选"添加中枢"继续登录其他小米账号，不同账号的设备允许放入同一区域；"Action 调试模式"开启后，带参数的动作会额外生成一个 Text 实体，你可以手填参数向设备发指令，用来验证动作可用性。

实体映射规则表：设备是怎么变成实体的

导入后你看到的实体类型，取决于 MIoT-Spec-V2（小米 IoT 平台的设备描述协议，用"服务 + 属性/事件/动作"结构描述设备能力）的实例翻译结果。

不命中特殊规则时，属性按下表转换：

access	format	value-list	value-range	生成的实体
可写	string	-	-	Text
可写	bool	-	-	Switch
可写	非 string、非 bool	有	-	Select
可写	非 string、非 bool	无	有	Number
不可写	-	-	-	Sensor

事件统一转成 Event 实体，事件参数会传给实体的_trigger_event（例如无线双键开关的长按事件携带"按键类型"参数，debug 日志里能看到长按, attributes: {'按键类型': 1}）。动作分两种：无输入参数转成 Button，有参数转成 Notify；Notify 实体详情页的 Attributes 会显示参数格式，如[Text Content(str), Silent Execution(bool)]，正确输入就是["Hello", true]。

命中特殊规则时，匹配优先级链是：设备级规则 > 服务级规则 > 属性级规则 > 一般规则。规则字典定义在 custom_components/xiaomi_home/miot/specs/specv2entity.py。

两个直接影响你"看到什么"的细节：

• 实例缺少规则要求的必选服务、属性或动作时，对应实体不生成——这是"某个功能没变成实体"最常见的原因。
• 实例的 namespace 不是miot-spec-v2（非小米官方定义）时，实体名称前带星号*，提示这不是标准小米物模型。

另外，所有设备的"设备信息服务"（device-information service）永远不转成实体，这不是 bug。

三个规则文件：修类型、删冗余、改名字

实体类型不对、数值没换算、名字是厂商的奇怪翻译——不用改代码，改custom_components/xiaomi_home/miot/specs/下对应文件即可。

删冗余实体 → spec_filter.yaml。键是设备实例 URN（不含版本号），值列出要过滤的 iid，支持通配符：

urn:miot-spec-v2:device:gateway:0000A019:xiaomi-hub1: services: - '3' # 排除 siid=3 的服务 properties: - '4.*' # 排除 siid=4 服务下的所有属性 events: - '4.1' # 排除 siid=4 服务的 eiid=1 事件

services 里写'*'则等价于整体忽略该设备。

修类型/换算 → spec_modify.yaml。在转换前直接改写规格实例的name、format、access、value-list、unit，还能用expr做数值换算。仓库自带文件里就有真实案例，比如给某款空调的模式属性补 value-list（value: 1对应 Cool、value: 2对应 Dry），或给功率属性写unit: kWh。你遇到的"数值是原始整数没换算"基本都能用同样方式处理。

改名字 → multi_lang.json。实体显示名优先取自这份本地字典，它覆盖从云端下载的厂商多语言文件。层级是设备 URN > 语言代码 > 实例代码：

{ "urn:miot-spec-v2:device:health-pot:0000A051:chunmi-a1": { "zh-Hant": { "service:002:property:001": "工作狀態", "service:005:event:001": "烹飪完成" } } }

实例代码写法为service:<siid>、service:<siid>:property:<piid>、service:<siid>:property:<piid>:valuelist:<index>、service:<siid>:event:<eiid>、service:<siid>:action:<aiid>，各项均为三位十进制数；语言代码支持 13 种（zh-Hans、zh-Hant、en 等）。注意区分：要改的是配置页面本身的文案，改的是custom_components/xiaomi_home/translations/和custom_components/xiaomi_home/miot/i18n/下的 json 文件，不是这个。

最关键的一步：编辑miot/specs/目录下任何文件后，必须到 配置 > 更新实体转换规则 才生效，只改文件不动这里等于没改。

排错清单与安全红线

设备没出现或实体类型不对时，按这个顺序核对，多数问题前三条就能定位：

1. 设备品类本身不支持。集成目前不处理蓝牙设备、红外设备和虚拟设备，这三类不会有任何实体。
2. 设备规格缺少特殊转换规则的必选项，导致实体未生成。开 debug 日志能看到转换过程：在configuration.yaml中加入（参见 CLAUDE.md 的 Debugging 一节）：

logger: default: critical logs: custom_components.xiaomi_home: debug

3. 实体类型不符预期，回上面的映射表核对属性的 access/format 组合，必要时用spec_modify.yaml改规格、spec_filter.yaml挡干扰项。

安全方面记住两条：

• 登录走 OAuth 2.0，Home Assistant 不保存你的小米密码。但受平台限制，登录后的用户信息（设备信息、证书、token 等）会明文保存在 Home Assistant 配置文件中，配置文件泄露等于账号授权泄露，注意config目录的访问权限。
• 怀疑 token 泄露时，到 米家 APP > 我的 > 用户名进入账号页 > 应用授权 > "Xiaomi Home (Home Assistant Integration)" 中取消授权即可。

进阶阅读入口

• 实体转换的三张规则字典：custom_components/xiaomi_home/miot/specs/specv2entity.py
• 集成核心代码（云接口、消息总线、设备实体）：custom_components/xiaomi_home/miot/
• 验证你的映射判断：test/
• 版本行为差异对照：CHANGELOG.md

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home