小米米家设备接入 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.4Operating System ≥ 13.0。当前仓库版本为 v0.5.0见 custom_components/xiaomi_home/manifest.json。安装推荐 git 方式后续可以精确切换 tag 回滚或升级到指定版本cd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /configinstall.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/。登录进入 设置 设备与服务 添加集成搜索Xiaomi Home走 OAuth 2.0 登录授权式登录账号密码不会存到 Home Assistant。生效登录成功后弹出选择家庭与设备对话框选择要导入的米家家庭该家庭下所有设备随之导入为实体。两个后续用得上的入口都在 设置 设备与服务 已配置 Xiaomi Home 配置 里多账号在同一集成页面选添加中枢继续登录其他小米账号不同账号的设备允许放入同一区域Action 调试模式开启后带参数的动作会额外生成一个 Text 实体你可以手填参数向设备发指令用来验证动作可用性。实体映射规则表设备是怎么变成实体的导入后你看到的实体类型取决于 MIoT-Spec-V2小米 IoT 平台的设备描述协议用服务 属性/事件/动作结构描述设备能力的实例翻译结果。不命中特殊规则时属性按下表转换accessformatvalue-listvalue-range生成的实体可写string--Text可写bool--Switch可写非 string、非 bool有-Select可写非 string、非 bool无有Number不可写---Sensor事件统一转成 Event 实体事件参数会传给实体的_trigger_event例如无线双键开关的长按事件携带按键类型参数debug 日志里能看到长按, attributes: {按键类型: 1}。动作分两种无输入参数转成 Button有参数转成 NotifyNotify 实体详情页的 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 # 排除 siid3 的服务 properties: - 4.* # 排除 siid4 服务下的所有属性 events: - 4.1 # 排除 siid4 服务的 eiid1 事件services 里写*则等价于整体忽略该设备。修类型/换算 → spec_modify.yaml。在转换前直接改写规格实例的name、format、access、value-list、unit还能用expr做数值换算。仓库自带文件里就有真实案例比如给某款空调的模式属性补 value-listvalue: 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/目录下任何文件后必须到 配置 更新实体转换规则 才生效只改文件不动这里等于没改。排错清单与安全红线设备没出现或实体类型不对时按这个顺序核对多数问题前三条就能定位设备品类本身不支持。集成目前不处理蓝牙设备、红外设备和虚拟设备这三类不会有任何实体。设备规格缺少特殊转换规则的必选项导致实体未生成。开 debug 日志能看到转换过程在configuration.yaml中加入参见 CLAUDE.md 的 Debugging 一节logger: default: critical logs: custom_components.xiaomi_home: debug实体类型不符预期回上面的映射表核对属性的 access/format 组合必要时用spec_modify.yaml改规格、spec_filter.yaml挡干扰项。安全方面记住两条登录走 OAuth 2.0Home 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
