Xiaomi Home Integration for Home Assistant 深度指南从云端/本地控制架构到 MIoT-Spec-V2 实体映射【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeXiaomi Home Integration 是小米官方为 Home Assistant 提供的集成组件让你可以在 Home Assistant 中直接使用小米 IoT 智能设备。本文以仓库根目录 README.md 为核心骨架结合custom_components/xiaomi_home下的真实源码实体转换映射表、Spec 过滤/多语言机制深入展开帮助你完成从安装、登录配置、消息链路理解到 MIoT-Spec-V2 与 Home Assistant 实体映射机制的完整技术闭环。读完本文你将掌握该集成的三种安装方式、OAuth 2.0 登录与多账号管理、云端/本地两种控制架构的原理以及如何通过spec_filter.yaml、multi_lang.json等文件定制实体转换行为。一、集成概览与运行前提Xiaomi Home Integration 是一个由小米官方提供并维护的 Home Assistant 集成组件integration_type: hub其域名domain为xiaomi_home。它通过 MIoT Cloud 云服务或小米中枢网关与小米 IoT 设备通信将设备的功能属性、事件、动作自动转换为 Home Assistant 实体从而让用户用 Home Assistant 的自动化、仪表盘等能力统一控制小米智能设备。根据 manifest.json本集成的关键元信息包括依赖组件http、persistent_notification、ffmpeg、zeroconf运行时 Python 依赖construct2.10.56、paho-mqtt、numpy、cryptography、psutil其中paho-mqtt是 MQTT 客户端zeroconf用于局域网服务发现Zeroconf 服务类型_miot-central._tcp.local.即通过 mDNS 发现小米中枢网关iot_classcloud_polling。环境版本要求官方对运行环境有明确要求Home Assistant Core ≥ 2024.4.4Home Assistant Operating System ≥ 13.0注意版本要求以当前仓库 README 描述为准安装前请先确认你的 Home Assistant 版本满足条件。二、安装三种方式与版本切换方式一Git clone官方推荐cd config git clone https://github.com/XiaoMi/ha_xiaomi_home.git cd ha_xiaomi_home ./install.sh /config官方推荐该方式因为更新到指定版本时可以通过 tag 方便切换。例如升级到 v1.0.0cd config/ha_xiaomi_home git fetch git checkout v1.0.0 ./install.sh /config仓库根目录的 install.sh 脚本实现了一次完整的删除旧版 拷贝新版流程校验传入的config_path参数必须恰好 1 个且目录必须存在将$script_path/custom_components/$component_name即xiaomi_home目录递归复制到$config_path/custom_components/xiaomi_home复制前会先删除旧的组件目录确保不留残留文件完成后提示Xiaomi Home installation is completed. Please restart Home Assistant.即安装后需要重启 Home Assistant 才会生效。方式二HACS 一键安装在 HACS 中搜索Xiaomi Home进入详情页后点击DOWNLOAD即可安装也可通过 HACS 仓库重定向按钮直达。HACS 安装方式适合偏好图形化管理的用户。方式三Samba / FTPS 手动安装将custom_components/xiaomi_home文件夹下载后手动复制到 Home Assistant 的config/custom_components目录下即可。适合没有 git 与 HACS 的环境。三种方式本质一致最终都是在config/custom_components/xiaomi_home下放置完整组件代码随后重启 Home Assistant。三、配置登录、导入设备与多账号3.1 首次登录OAuth 2.0安装并重启后进入Settings Devices services ADD INTEGRATION搜索Xiaomi Home点击NEXT再点击 Click here to login使用小米账号登录。登录成功后会弹出名为Select Home and Devices的对话框。在这里选择需要导入到 Home Assistant 的家庭Home集成会将该家庭下符合条件的设备自动导入。注意不同区域的米家云数据是隔离的因此导入 MIoT 设备时需要选择正确的区域。3.2 添加更多小米账号一个集成实例支持多个小米账号。完成第一个账号登录与用户配置后可以在已配置的 Xiaomi Home 集成页面继续添加Settings Devices services Configured Xiaomi HomeADD HUB NEXT 点击登录 使用另一个小米账号登录。从源码结构看每个登录用户在集成中对应一个miot_client实例见 目录结构说明 中miot/miot_client的描述从而支撑多账号并行运行。3.3 更新配置与调试模式在Settings Devices services Configured Xiaomi HomeCONFIGURE的 Configuration Options 对话框中可以更新用户昵称调整从米家 APP 导入的设备列表更新实体转换规则见下文第五节更新 LAN 控制配置见第四节启用 Action 调试模式Debug mode for action开启后集成为包含参数的 Action 创建一个Text 实体你可以手动向设备发送带参数的 Action 命令消息便于调试设备指令格式其机制详见 第五节-通用转换 中 Action 部分的说明。四、消息传输原理云端控制与本地控制Xiaomi Home Integration 支持两条控制链路云端控制默认、全区域可用与本地控制基于小米中枢网关。4.1 云端控制Control through the Cloud云端控制的核心机制是MQTT 订阅-推送而非轮询状态上报上行Xiaomi Home Integration 在 MIoT Cloud 的 MQTT Broker 上订阅关心的设备消息。当设备属性变化或事件发生时设备向 MIoT Cloud 发送上行消息MQTT Broker 将订阅的设备消息推送给 Xiaomi Home Integration。由于无需轮询获取设备属性值属性变化/事件发生时集成能立即收到通知。初始查询低频得益于消息订阅机制集成只在配置完成时从云端一次性查询所有设备属性对云端访问压力很小。指令下发下行控制设备时Xiaomi Home Integration 通过 MIoT Cloud 的HTTP 接口发送命令消息MIoT Cloud 将下行消息转发给设备设备响应后回执。4.2 本地控制Control locally小米中枢网关Xiaomi Central Hub Gateway固件 3.3.0_0023 及以上内置一个标准的MQTT Broker实现完整的订阅-发布机制状态上报设备属性变化或事件发生时设备向小米中枢网关发送上行消息网关内置的 MQTT Broker 将消息推送给 Xiaomi Home Integration指令下发Xiaomi Home Integration 将设备命令消息发布到 MQTT Broker由网关转发给设备设备响应后回执。从 manifest.json 可以看到集成声明了 zeroconf 服务类型_miot-central._tcp.local.这正是 miot_mdns.py 用于局域网发现中枢网关的机制而本地 MQTT 通信由 miot_mips.py消息总线负责订阅与发布和 miot_lan.pyLAN 控制含设备发现与控制实现。本地模式的适用前提官方 FAQ 要点需要小米中枢网关固件 3.3.0_0023 及以上或支持内置中枢网关功能的小米智能设备软件 0.8.9 及以上小米中枢网关仅在中国大陆地区可用其他区域无法使用若没有中枢网关所有控制命令均通过小米云端发送集成还支持部分本地模式开启 Xiaomi LAN 控制功能后可以控制与 Home Assistant 处于同一局域网内的IP 设备通过 WiFi 或网线连接路由器的设备但不能控制 BLE Mesh、ZigBee 等设备且该功能可能引发异常官方建议不要使用Xiaomi LAN 控制不受区域限制但如果局域网中存在中枢网关即使开启了该功能也不会生效以网关链路优先。五、MIoT-Spec-V2 与 Home Assistant 实体的映射关系MIoT-Spec-V2MIoT Specification Version 2是小米 IoT 平台制定的物联网协议用于对 IoT 设备进行标准化的功能描述包含功能定义其他平台称为数据模型、交互模型、消息格式与编码。在 MIoT-Spec-V2 协议中产品product被定义为一个设备device一个设备包含若干个服务service服务可能包含若干属性property、事件event和动作action。Xiaomi Home Integration 依据 MIoT-Spec-V2 创建 Home Assistant 实体转换规则的核心代码集中在 specv2entity.py运行时解析与过滤逻辑在 miot_spec.py。5.1 转换的整体流程从源码结构可以推断转换分两步执行先判断特定转换MIoT-Spec-V2 使用 URN 定义类型格式为urn:namespace:type:name:value[:vendor-product:version]。集成首先根据实例的name人类可读的名称判断是否命中特定转换规则对应SPEC_DEVICE_TRANS_MAP/SPEC_SERVICE_TRANS_MAP/SPEC_PROP_TRANS_MAP/SPEC_EVENT_TRANS_MAP未命中则回退通用转换依据属性/事件/动作的类型特征access、format、value-list、value-range进行通用映射。此外namespace字段也有语义miot-spec-v2由小米定义的规范bluetooth-spec由蓝牙技术联盟Bluetooth SIG定义的规范其他由第三方厂商定义的规范。此时会在实体名称前加星号标记*。5.2 通用转换规则属性Property→ 实体accessformatvalue-listvalue-rangeHome Assistant 实体writablestring--Textwritablebool--Switchwritable非 string 且非 bool存在-Selectwritable非 string 且非 bool不存在存在Number不可写---Sensor事件Event→ Event 实体MIoT-Spec-V2 事件被转换为 Home Assistant 的 Event 实体事件的参数也会传递到实体的_trigger_event。事件的arguments字段是参数列表列表元素表示同一服务内属性的 piid。README 给出的实例小米无线双键开关Xiaomi Wireless Double-key SwitchMIoT-Spec-V2 类型urn:miot-spec-v2:device:remote-control:0000A021:xiaomi-mcn002:1:0000D057包含 siid2 的 Switch Sensor 服务该服务的 eiid1014Long Press长按事件在按钮被长按时触发。debug 级别日志会打印Press and hold, attributes: {Button Type: 1}——表示按钮类型为 1即右按钮被长按。动作Action→ 实体in入参Home Assistant 实体空Button非空Notify若开启了 Action 调试模式当 action spec 的in字段非空时会额外创建一个Text 实体用于手动输入参数发送 Action。Action 参数格式说明实体详情页的 Attribute 项会显示入参格式——一个有序列表用方括号[]包裹列表中的字符串元素用双引号包裹。例如xiaomi.wifispeaker.s12设备 siid5、aiid5 的 Intelligent Speaker Execute Text Directive智能音箱执行文本指令动作转换出的 Notify 实体其详情页 Attributes 显示[Text Content(str), Silent Execution(bool)]一个正确格式的输入示例为[Hello, true]。5.3 特定转换规则四张映射表特定转换由四个映射常量驱动均在 specv2entity.py 中定义。Device 级转换SPEC_DEVICE_TRANS_MAP{ device instance name: { required: { # 设备必需的服务 service instance name: { required: { # 服务必需的属性/事件/动作 properties: { property instance name: setproperty access: str }, events: setevent instance name: str, actions: setaction instance name: str }, optional: { # 服务可选的属性/事件/动作 properties: setproperty instance name: str, events: setevent instance name: str, actions: setaction instance name: str } } }, optional: { # 设备可选的服务结构同上 service instance name: { ... } }, entity: str # 要创建的 Home Assistant 实体 } }匹配成功条件required.properties中属性实例名的值必须是对应 MIoT-Spec-V2 属性实例 access 模式的子集。如果设备实例不包含全部必需服务、属性、事件或动作则不会创建对应 Home Assistant 实体。源码中的真实例子摘录自SPEC_DEVICE_TRANS_MAPvacuum: { required: { vacuum: { required: { actions: {start-sweep, stop-sweeping}, }, optional: { properties: {status, fan-level}, actions: {pause-sweeping, continue-sweep, stop-and-gocharge} } } }, optional: { identify: {required: {actions: {identify}}}, battery: {required: {actions: {start-charge}}} }, entity: vacuum }即扫地机器人必须提供start-sweep开始清扫与stop-sweeping停止清扫两个动作才会被转换为vacuum实体。类似的设备级映射还包括humidifier、dehumidifier、air-conditioner含air-condition-outlet别名、thermostat、heater、bath-heater、electric-blanket、speaker→wifi-speaker、television、tv-box、watch→device_tracker等。Service 级转换SPEC_SERVICE_TRANS_MAP{ service instance name: { required: { properties: {property instance name: setproperty access: str}, events: setevent instance name: str, actions: setaction instance name: str }, optional: { ... }, entity: str, entity_category?: str # 可选对应 Home Assistant 的 entity category } }服务级映射同样要求必需项全部匹配否则不创建实体。源码中的真实例子light: { required: {properties: {on: {read, write}}}, optional: {properties: {mode, brightness, color, color-temperature}}, entity: light }light服务要求on属性必须可读可写。ambient-light、night-light、white-light服务直接别名到lightfan服务要求on与fan-level均读写fan-control、ceiling-fan、air-fresh、air-purifier别名到fancurtain服务要求motor-control可写→coverwindow-opener、motor-controller、airer均别名到curtainwater-heater服务要求on读写→water_heater。indicator-light指示灯转换为light实体并标记为EntityCategory.CONFIG配置类实体。Property 级转换SPEC_PROP_TRANS_MAP{ entities: { entity name: { format: setstr, # 属性数据格式命中其一即匹配成功 access: setstr # 属性访问模式需全部命中才算匹配成功 } }, properties: { property instance name: { device_class: str, # 实体 _attr_device_class entity: str, state_class?: str, unit_of_measurement?: str } } }entities中format与access的匹配语义不同format命中一个值即成功access需要全部命中。源码中的entities定义entities: { sensor: {format: {int, float}, access: {read}}, binary_sensor: {format: {bool, int}, access: {read}}, switch: {format: {bool}, access: {read, write}} }properties段则指定了各属性实例名对应的device_class、实体类型、state_class与单位。源码中较完整的例子节选property 实例名entitydevice_classHA 常量state_class / 单位temperaturesensorSensorDeviceClass.TEMPERATUREMEASUREMENT/ °Crelative-humiditysensorSensorDeviceClass.HUMIDITYMEASUREMENT/ %air-quality-indexsensorSensorDeviceClass.AQIMEASUREMENTpm2.5-densitysensorSensorDeviceClass.PM25MEASUREMENT/ µg/m³pm10-densitysensorSensorDeviceClass.PM10MEASUREMENT/ µg/m³battery-levelsensorSensorDeviceClass.BATTERYMEASUREMENT/ %electric-powersensorSensorDeviceClass.POWERMEASUREMENT/ Wpower-consumptionsensorSensorDeviceClass.ENERGYTOTAL_INCREASING/ kWhcontact-statebinary_sensorBinarySensorDeviceClass.DOOR-occupancy-statusbinary_sensorBinarySensorDeviceClass.OCCUPANCY-submersion-statebinary_sensorBinarySensorDeviceClass.MOISTURE-此外还有atmospheric-pressurePa、tvoc-density/voc-density、voltageV、electric-currentA、illuminationlx、no-one-determine-time→ DURATION等映射且has-someone-duration、no-one-duration会别名到no-one-determine-time。Event 级转换SPEC_EVENT_TRANS_MAP{ event instance name: str # 值为 _attr_device_class }源码中的定义SPEC_EVENT_TRANS_MAP { click: EventDeviceClass.BUTTON, double-click: EventDeviceClass.BUTTON, long-press: EventDeviceClass.BUTTON, motion-detected: EventDeviceClass.MOTION, no-motion: EventDeviceClass.MOTION, doorbell-ring: EventDeviceClass.DOORBELL }5.4 MIoT-Spec-V2 过滤器spec_filter.yamlspec_filter.yaml仓库位置 custom_components/xiaomi_home/miot/specs/spec_filter.yaml用于过滤掉不会被转换为 Home Assistant 实体的 MIoT-Spec-V2 实例其格式为MIoT-Spec-V2 device instance urn without the version field: services: listservice_iid: str properties: listservice_iid.property_iid: str events: listservice_iid.event_iid: str actions: listservice_iid.action_iid: str规则要点字典的 key 是去掉 version 字段的设备实例 URN。同一产品的不同固件版本可能关联不同版本的 MIoT-Spec-V2 实例而厂商在 MIoT 平台定义产品规范时高版本实例必须包含低版本的全部实例因此 key 无需指定版本号services/properties/events/actions的值是转换过程中将被忽略的实例 idiid支持通配符匹配如*、4.*所有设备的设备信息服务urn:miot-spec-v2:service:device-information:00007801永远不会转换为 Home Assistant 实体。README 给出的示例urn:miot-spec-v2:device:television:0000A010:xiaomi-rmi1: services: - * # 过滤掉所有服务等价于完全忽略该 MIoT-Spec-V2 设备 urn:miot-spec-v2:device:gateway:0000A019:xiaomi-hub1: services: - 3 # 过滤 siid3 的服务 properties: - 4.* # 过滤 siid4 服务下的所有属性 events: - 4.1 # 过滤 siid4 服务下的 eiid1 事件 actions: - 4.1 # 过滤 siid4 服务下的 aiid1 动作仓库真实文件中的部分条目与此格式一致例如urn:miot-spec-v2:device:air-purifier:0000A007:zhimi-ma4: properties: - 9.* - 13.* - 15.* services: - 10 urn:miot-spec-v2:device:vacuum:0000A006:narwa-001: services: - *底层实现过滤器对应 miot_spec.py 中的_SpecFilter类init_async()通过load_yaml_file加载specs/spec_filter.yaml并做结构校验字典嵌套必须是dict - dict - list否则报错并放弃加载set_spec_spec(urn_key)按设备 URN key 缓存当前设备的过滤规则filter_service(siid)、filter_property(siid, piid)、filter_event(siid, eiid)、filter_action(siid, aiid)分别判断服务/属性/事件/动作是否应被过滤返回True表示过滤不转换。其中属性/事件/动作同时支持精确 id 与siid.*通配。从源码可以推断spec_filter.yaml的典型用途是规避某些型号固件上报异常数据如空的 value-list 导致 Select/Number 转换异常通过按设备型号精准裁掉有问题的服务、属性、事件或动作。配套的spec_modify.yaml仓库中还提供 spec_modify.yaml用于在转换前修改MIoT-Spec-V2 实例定义例如重命名属性name: ac-on、修改format、access、unit、补充value-list或将某个版本实例重定向到另一个版本如urn:...:xiaomi-c17:2: urn:...:xiaomi-c17:1。spec_filter.yaml过滤与spec_modify.yaml修改共同构成实体转换规则的预处理层。重要提醒如果在 Home Assistant 中修改了custom_components/xiaomi_home/miot/specs目录下的任何文件spec_filter.yaml、spec_modify.yaml、multi_lang.json等需要在集成 CONFIGURE 页面执行Update entity conversion rules更新实体转换规则才能生效。六、多语言支持6.1 配置流界面语言集成在 config flow 语言选项中提供13 种语言简体中文、繁体中文、英文、西班牙文、俄文、法文、德文、日文、意大利文、荷兰文、葡萄牙文、巴西葡萄牙文、土耳其文。简体中文和英文由开发者人工校对其他语言由机器翻译或社区贡献。如需修改 config flow 页面文案需要修改对应语言的 json 文件custom_components/xiaomi_home/translations/HA 组件级翻译custom_components/xiaomi_home/miot/i18n/6.2 实体名称多语言multi_lang.json展示 Home Assistant 实体名称时集成会从 MIoT Cloud 下载设备厂商配置的多语言文件包含设备 MIoT-Spec-V2 实例的翻译。multi_lang.json是本地维护的多语言字典优先级高于云端多语言文件可用于补充或修正设备的多语言翻译。格式如下{ MIoT-Spec-V2 device instance: { language code: { instance code: translation: str } } }规则要点字典 key 是去掉 version 字段的 MIoT-Spec-V2 设备实例 URN语言代码为zh-Hans、zh-Hant、en、es、ru、fr、de、ja、it、nl、pt、pt-BR、tr对应上述 13 种语言实例代码格式service:siid # 服务 service:siid:property:piid # 属性 service:siid:property:piid:valuelist:index # 属性 value-list 中某个值的索引 service:siid:event:eiid # 事件 service:siid:action:aiid # 动作其中 siid、piid、eiid、aiid 以及 value 均为十进制三位整数。README 示例{ urn:miot-spec-v2:device:health-pot:0000A051:chunmi-a1: { zh-Hant: { service:002: 養生壺, service:002:property:001: 工作狀態, service:002:property:001:valuelist:000: 待機中, service:002:action:002: 停止烹飪, service:005:event:001: 烹飪完成 } } }仓库真实文件 multi_lang.json 中的条目与此一致例如为urn:miot-spec-v2:device:fan:0000A005:zhimi-za1补充土耳其语与简体中文的自然风/直吹风枚举翻译。从 miot_spec.py 的_MIoTSpecMultiLang类可以看到其加载流程优先读取本地specs/multi_lang.json再从云端获取厂商多语言文件本地翻译的优先级更高translate()在服务/属性/事件/动作转换时逐项调用。七、安全性与隐私说明官方安全声明要点集成及其附属云接口由小米官方提供需要使用小米账号登录以获取设备列表集成实现OAuth 2.0登录流程不会在 Home Assistant 应用中保存账号密码但由于 Home Assistant 平台限制登录成功后小米账号的用户信息含设备信息、证书、token 等会以明文保存在 Home Assistant 配置文件中。请确保配置文件存放安全配置文件泄露可能导致他人以你的身份登录若怀疑 OAuth 2.0 token 泄露可通过以下步骤撤销授权米家 APP → 我的 → 点击用户名进入小米账号管理页 → 基本信息应用 → Xiaomi Home (Home Assistant Integration) → 移除。八、官方 FAQ 要点速览支持哪些设备目前支持绝大多数智能设备类别不支持的仅有三类蓝牙设备、红外设备、虚拟设备。支持多个小米账号吗支持。且不同账号下的设备可以添加到同一个区域area中。支持本地模式吗支持分两种通过小米中枢网关或内置中枢网关的设备实现完整本地模式——仅中国大陆可用通过 Xiaomi LAN 控制功能实现部分本地模式——仅能控制与 Home Assistant 同一局域网内的 IP 设备不能控制 BLE Mesh / ZigBee 等设备且可能引发异常官方不建议使用。哪些区域可用中国大陆、欧洲、印度、俄罗斯、新加坡、美国。不同区域米家云数据相互隔离导入 MIoT 设备时需选择区域集成允许将不同区域的设备导入同一 area。九、仓库目录结构导读custom_components/xiaomi_home/ ├── __init__.py # 集成入口 ├── config_flow.py # 配置流 ├── miot/ # 核心代码 │ ├── miot_client.py # 每个登录用户对应一个 miot_client 实例 │ ├── miot_cloud.py # 云服务相关OAuth 登录、HTTP 接口获取用户信息、下发设备控制命令等 │ ├── miot_device.py # 设备实体设备信息、属性/事件/动作处理逻辑 │ ├── miot_mips.py # 消息总线订阅与发布方法 │ ├── miot_spec.py # 解析 MIoT-Spec-V2含过滤、修改、多语言加载 │ ├── miot_lan.py # 设备 LAN 控制设备发现、设备控制等 │ ├── miot_mdns.py # 中枢网关服务的局域网发现 │ ├── miot_network.py # 获取网络状态与网络信息 │ ├── miot_storage.py # 集成的文件存储 │ ├── i18n/ # 集成内部多语言文案 │ └── specs/ # 实体转换规则specv2entity.py、spec_filter.yaml、spec_modify.yaml、multi_lang.json 等 ├── binary_sensor.py ... water_heater.py # 各实体平台实现 └── translations/ # config flow 等 HA 组件级翻译各实体平台文件switch.py、number.py、select.py、text.py、event.py、button.py、notify.py、sensor.py、binary_sensor.py、cover.py、fan.py、humidifier.py、climate.py、light.py、media_player.py、vacuum.py、water_heater.py、device_tracker.py分别对应第五节中转换出的实体类型是理解某个实体在 HA 中如何工作的下一层入口。更多资料可继续阅读仓库内的 CONTRIBUTING.md贡献指南另有简体中文版 doc/CONTRIBUTING_zh.md、CHANGELOG.md版本变更记录与 LICENSE.md许可证。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Xiaomi Home Integration for Home Assistant 深度指南：从云端/本地控制架构到 MIoT-Spec-V2 实体映射
Xiaomi Home Integration for Home Assistant 深度指南从云端/本地控制架构到 MIoT-Spec-V2 实体映射【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeXiaomi Home Integration 是小米官方为 Home Assistant 提供的集成组件让你可以在 Home Assistant 中直接使用小米 IoT 智能设备。本文以仓库根目录 README.md 为核心骨架结合custom_components/xiaomi_home下的真实源码实体转换映射表、Spec 过滤/多语言机制深入展开帮助你完成从安装、登录配置、消息链路理解到 MIoT-Spec-V2 与 Home Assistant 实体映射机制的完整技术闭环。读完本文你将掌握该集成的三种安装方式、OAuth 2.0 登录与多账号管理、云端/本地两种控制架构的原理以及如何通过spec_filter.yaml、multi_lang.json等文件定制实体转换行为。一、集成概览与运行前提Xiaomi Home Integration 是一个由小米官方提供并维护的 Home Assistant 集成组件integration_type: hub其域名domain为xiaomi_home。它通过 MIoT Cloud 云服务或小米中枢网关与小米 IoT 设备通信将设备的功能属性、事件、动作自动转换为 Home Assistant 实体从而让用户用 Home Assistant 的自动化、仪表盘等能力统一控制小米智能设备。根据 manifest.json本集成的关键元信息包括依赖组件http、persistent_notification、ffmpeg、zeroconf运行时 Python 依赖construct2.10.56、paho-mqtt、numpy、cryptography、psutil其中paho-mqtt是 MQTT 客户端zeroconf用于局域网服务发现Zeroconf 服务类型_miot-central._tcp.local.即通过 mDNS 发现小米中枢网关iot_classcloud_polling。环境版本要求官方对运行环境有明确要求Home Assistant Core ≥ 2024.4.4Home Assistant Operating System ≥ 13.0注意版本要求以当前仓库 README 描述为准安装前请先确认你的 Home Assistant 版本满足条件。二、安装三种方式与版本切换方式一Git clone官方推荐cd config git clone https://github.com/XiaoMi/ha_xiaomi_home.git cd ha_xiaomi_home ./install.sh /config官方推荐该方式因为更新到指定版本时可以通过 tag 方便切换。例如升级到 v1.0.0cd config/ha_xiaomi_home git fetch git checkout v1.0.0 ./install.sh /config仓库根目录的 install.sh 脚本实现了一次完整的删除旧版 拷贝新版流程校验传入的config_path参数必须恰好 1 个且目录必须存在将$script_path/custom_components/$component_name即xiaomi_home目录递归复制到$config_path/custom_components/xiaomi_home复制前会先删除旧的组件目录确保不留残留文件完成后提示Xiaomi Home installation is completed. Please restart Home Assistant.即安装后需要重启 Home Assistant 才会生效。方式二HACS 一键安装在 HACS 中搜索Xiaomi Home进入详情页后点击DOWNLOAD即可安装也可通过 HACS 仓库重定向按钮直达。HACS 安装方式适合偏好图形化管理的用户。方式三Samba / FTPS 手动安装将custom_components/xiaomi_home文件夹下载后手动复制到 Home Assistant 的config/custom_components目录下即可。适合没有 git 与 HACS 的环境。三种方式本质一致最终都是在config/custom_components/xiaomi_home下放置完整组件代码随后重启 Home Assistant。三、配置登录、导入设备与多账号3.1 首次登录OAuth 2.0安装并重启后进入Settings Devices services ADD INTEGRATION搜索Xiaomi Home点击NEXT再点击 Click here to login使用小米账号登录。登录成功后会弹出名为Select Home and Devices的对话框。在这里选择需要导入到 Home Assistant 的家庭Home集成会将该家庭下符合条件的设备自动导入。注意不同区域的米家云数据是隔离的因此导入 MIoT 设备时需要选择正确的区域。3.2 添加更多小米账号一个集成实例支持多个小米账号。完成第一个账号登录与用户配置后可以在已配置的 Xiaomi Home 集成页面继续添加Settings Devices services Configured Xiaomi HomeADD HUB NEXT 点击登录 使用另一个小米账号登录。从源码结构看每个登录用户在集成中对应一个miot_client实例见 目录结构说明 中miot/miot_client的描述从而支撑多账号并行运行。3.3 更新配置与调试模式在Settings Devices services Configured Xiaomi HomeCONFIGURE的 Configuration Options 对话框中可以更新用户昵称调整从米家 APP 导入的设备列表更新实体转换规则见下文第五节更新 LAN 控制配置见第四节启用 Action 调试模式Debug mode for action开启后集成为包含参数的 Action 创建一个Text 实体你可以手动向设备发送带参数的 Action 命令消息便于调试设备指令格式其机制详见 第五节-通用转换 中 Action 部分的说明。四、消息传输原理云端控制与本地控制Xiaomi Home Integration 支持两条控制链路云端控制默认、全区域可用与本地控制基于小米中枢网关。4.1 云端控制Control through the Cloud云端控制的核心机制是MQTT 订阅-推送而非轮询状态上报上行Xiaomi Home Integration 在 MIoT Cloud 的 MQTT Broker 上订阅关心的设备消息。当设备属性变化或事件发生时设备向 MIoT Cloud 发送上行消息MQTT Broker 将订阅的设备消息推送给 Xiaomi Home Integration。由于无需轮询获取设备属性值属性变化/事件发生时集成能立即收到通知。初始查询低频得益于消息订阅机制集成只在配置完成时从云端一次性查询所有设备属性对云端访问压力很小。指令下发下行控制设备时Xiaomi Home Integration 通过 MIoT Cloud 的HTTP 接口发送命令消息MIoT Cloud 将下行消息转发给设备设备响应后回执。4.2 本地控制Control locally小米中枢网关Xiaomi Central Hub Gateway固件 3.3.0_0023 及以上内置一个标准的MQTT Broker实现完整的订阅-发布机制状态上报设备属性变化或事件发生时设备向小米中枢网关发送上行消息网关内置的 MQTT Broker 将消息推送给 Xiaomi Home Integration指令下发Xiaomi Home Integration 将设备命令消息发布到 MQTT Broker由网关转发给设备设备响应后回执。从 manifest.json 可以看到集成声明了 zeroconf 服务类型_miot-central._tcp.local.这正是 miot_mdns.py 用于局域网发现中枢网关的机制而本地 MQTT 通信由 miot_mips.py消息总线负责订阅与发布和 miot_lan.pyLAN 控制含设备发现与控制实现。本地模式的适用前提官方 FAQ 要点需要小米中枢网关固件 3.3.0_0023 及以上或支持内置中枢网关功能的小米智能设备软件 0.8.9 及以上小米中枢网关仅在中国大陆地区可用其他区域无法使用若没有中枢网关所有控制命令均通过小米云端发送集成还支持部分本地模式开启 Xiaomi LAN 控制功能后可以控制与 Home Assistant 处于同一局域网内的IP 设备通过 WiFi 或网线连接路由器的设备但不能控制 BLE Mesh、ZigBee 等设备且该功能可能引发异常官方建议不要使用Xiaomi LAN 控制不受区域限制但如果局域网中存在中枢网关即使开启了该功能也不会生效以网关链路优先。五、MIoT-Spec-V2 与 Home Assistant 实体的映射关系MIoT-Spec-V2MIoT Specification Version 2是小米 IoT 平台制定的物联网协议用于对 IoT 设备进行标准化的功能描述包含功能定义其他平台称为数据模型、交互模型、消息格式与编码。在 MIoT-Spec-V2 协议中产品product被定义为一个设备device一个设备包含若干个服务service服务可能包含若干属性property、事件event和动作action。Xiaomi Home Integration 依据 MIoT-Spec-V2 创建 Home Assistant 实体转换规则的核心代码集中在 specv2entity.py运行时解析与过滤逻辑在 miot_spec.py。5.1 转换的整体流程从源码结构可以推断转换分两步执行先判断特定转换MIoT-Spec-V2 使用 URN 定义类型格式为urn:namespace:type:name:value[:vendor-product:version]。集成首先根据实例的name人类可读的名称判断是否命中特定转换规则对应SPEC_DEVICE_TRANS_MAP/SPEC_SERVICE_TRANS_MAP/SPEC_PROP_TRANS_MAP/SPEC_EVENT_TRANS_MAP未命中则回退通用转换依据属性/事件/动作的类型特征access、format、value-list、value-range进行通用映射。此外namespace字段也有语义miot-spec-v2由小米定义的规范bluetooth-spec由蓝牙技术联盟Bluetooth SIG定义的规范其他由第三方厂商定义的规范。此时会在实体名称前加星号标记*。5.2 通用转换规则属性Property→ 实体accessformatvalue-listvalue-rangeHome Assistant 实体writablestring--Textwritablebool--Switchwritable非 string 且非 bool存在-Selectwritable非 string 且非 bool不存在存在Number不可写---Sensor事件Event→ Event 实体MIoT-Spec-V2 事件被转换为 Home Assistant 的 Event 实体事件的参数也会传递到实体的_trigger_event。事件的arguments字段是参数列表列表元素表示同一服务内属性的 piid。README 给出的实例小米无线双键开关Xiaomi Wireless Double-key SwitchMIoT-Spec-V2 类型urn:miot-spec-v2:device:remote-control:0000A021:xiaomi-mcn002:1:0000D057包含 siid2 的 Switch Sensor 服务该服务的 eiid1014Long Press长按事件在按钮被长按时触发。debug 级别日志会打印Press and hold, attributes: {Button Type: 1}——表示按钮类型为 1即右按钮被长按。动作Action→ 实体in入参Home Assistant 实体空Button非空Notify若开启了 Action 调试模式当 action spec 的in字段非空时会额外创建一个Text 实体用于手动输入参数发送 Action。Action 参数格式说明实体详情页的 Attribute 项会显示入参格式——一个有序列表用方括号[]包裹列表中的字符串元素用双引号包裹。例如xiaomi.wifispeaker.s12设备 siid5、aiid5 的 Intelligent Speaker Execute Text Directive智能音箱执行文本指令动作转换出的 Notify 实体其详情页 Attributes 显示[Text Content(str), Silent Execution(bool)]一个正确格式的输入示例为[Hello, true]。5.3 特定转换规则四张映射表特定转换由四个映射常量驱动均在 specv2entity.py 中定义。Device 级转换SPEC_DEVICE_TRANS_MAP{ device instance name: { required: { # 设备必需的服务 service instance name: { required: { # 服务必需的属性/事件/动作 properties: { property instance name: setproperty access: str }, events: setevent instance name: str, actions: setaction instance name: str }, optional: { # 服务可选的属性/事件/动作 properties: setproperty instance name: str, events: setevent instance name: str, actions: setaction instance name: str } } }, optional: { # 设备可选的服务结构同上 service instance name: { ... } }, entity: str # 要创建的 Home Assistant 实体 } }匹配成功条件required.properties中属性实例名的值必须是对应 MIoT-Spec-V2 属性实例 access 模式的子集。如果设备实例不包含全部必需服务、属性、事件或动作则不会创建对应 Home Assistant 实体。源码中的真实例子摘录自SPEC_DEVICE_TRANS_MAPvacuum: { required: { vacuum: { required: { actions: {start-sweep, stop-sweeping}, }, optional: { properties: {status, fan-level}, actions: {pause-sweeping, continue-sweep, stop-and-gocharge} } } }, optional: { identify: {required: {actions: {identify}}}, battery: {required: {actions: {start-charge}}} }, entity: vacuum }即扫地机器人必须提供start-sweep开始清扫与stop-sweeping停止清扫两个动作才会被转换为vacuum实体。类似的设备级映射还包括humidifier、dehumidifier、air-conditioner含air-condition-outlet别名、thermostat、heater、bath-heater、electric-blanket、speaker→wifi-speaker、television、tv-box、watch→device_tracker等。Service 级转换SPEC_SERVICE_TRANS_MAP{ service instance name: { required: { properties: {property instance name: setproperty access: str}, events: setevent instance name: str, actions: setaction instance name: str }, optional: { ... }, entity: str, entity_category?: str # 可选对应 Home Assistant 的 entity category } }服务级映射同样要求必需项全部匹配否则不创建实体。源码中的真实例子light: { required: {properties: {on: {read, write}}}, optional: {properties: {mode, brightness, color, color-temperature}}, entity: light }light服务要求on属性必须可读可写。ambient-light、night-light、white-light服务直接别名到lightfan服务要求on与fan-level均读写fan-control、ceiling-fan、air-fresh、air-purifier别名到fancurtain服务要求motor-control可写→coverwindow-opener、motor-controller、airer均别名到curtainwater-heater服务要求on读写→water_heater。indicator-light指示灯转换为light实体并标记为EntityCategory.CONFIG配置类实体。Property 级转换SPEC_PROP_TRANS_MAP{ entities: { entity name: { format: setstr, # 属性数据格式命中其一即匹配成功 access: setstr # 属性访问模式需全部命中才算匹配成功 } }, properties: { property instance name: { device_class: str, # 实体 _attr_device_class entity: str, state_class?: str, unit_of_measurement?: str } } }entities中format与access的匹配语义不同format命中一个值即成功access需要全部命中。源码中的entities定义entities: { sensor: {format: {int, float}, access: {read}}, binary_sensor: {format: {bool, int}, access: {read}}, switch: {format: {bool}, access: {read, write}} }properties段则指定了各属性实例名对应的device_class、实体类型、state_class与单位。源码中较完整的例子节选property 实例名entitydevice_classHA 常量state_class / 单位temperaturesensorSensorDeviceClass.TEMPERATUREMEASUREMENT/ °Crelative-humiditysensorSensorDeviceClass.HUMIDITYMEASUREMENT/ %air-quality-indexsensorSensorDeviceClass.AQIMEASUREMENTpm2.5-densitysensorSensorDeviceClass.PM25MEASUREMENT/ µg/m³pm10-densitysensorSensorDeviceClass.PM10MEASUREMENT/ µg/m³battery-levelsensorSensorDeviceClass.BATTERYMEASUREMENT/ %electric-powersensorSensorDeviceClass.POWERMEASUREMENT/ Wpower-consumptionsensorSensorDeviceClass.ENERGYTOTAL_INCREASING/ kWhcontact-statebinary_sensorBinarySensorDeviceClass.DOOR-occupancy-statusbinary_sensorBinarySensorDeviceClass.OCCUPANCY-submersion-statebinary_sensorBinarySensorDeviceClass.MOISTURE-此外还有atmospheric-pressurePa、tvoc-density/voc-density、voltageV、electric-currentA、illuminationlx、no-one-determine-time→ DURATION等映射且has-someone-duration、no-one-duration会别名到no-one-determine-time。Event 级转换SPEC_EVENT_TRANS_MAP{ event instance name: str # 值为 _attr_device_class }源码中的定义SPEC_EVENT_TRANS_MAP { click: EventDeviceClass.BUTTON, double-click: EventDeviceClass.BUTTON, long-press: EventDeviceClass.BUTTON, motion-detected: EventDeviceClass.MOTION, no-motion: EventDeviceClass.MOTION, doorbell-ring: EventDeviceClass.DOORBELL }5.4 MIoT-Spec-V2 过滤器spec_filter.yamlspec_filter.yaml仓库位置 custom_components/xiaomi_home/miot/specs/spec_filter.yaml用于过滤掉不会被转换为 Home Assistant 实体的 MIoT-Spec-V2 实例其格式为MIoT-Spec-V2 device instance urn without the version field: services: listservice_iid: str properties: listservice_iid.property_iid: str events: listservice_iid.event_iid: str actions: listservice_iid.action_iid: str规则要点字典的 key 是去掉 version 字段的设备实例 URN。同一产品的不同固件版本可能关联不同版本的 MIoT-Spec-V2 实例而厂商在 MIoT 平台定义产品规范时高版本实例必须包含低版本的全部实例因此 key 无需指定版本号services/properties/events/actions的值是转换过程中将被忽略的实例 idiid支持通配符匹配如*、4.*所有设备的设备信息服务urn:miot-spec-v2:service:device-information:00007801永远不会转换为 Home Assistant 实体。README 给出的示例urn:miot-spec-v2:device:television:0000A010:xiaomi-rmi1: services: - * # 过滤掉所有服务等价于完全忽略该 MIoT-Spec-V2 设备 urn:miot-spec-v2:device:gateway:0000A019:xiaomi-hub1: services: - 3 # 过滤 siid3 的服务 properties: - 4.* # 过滤 siid4 服务下的所有属性 events: - 4.1 # 过滤 siid4 服务下的 eiid1 事件 actions: - 4.1 # 过滤 siid4 服务下的 aiid1 动作仓库真实文件中的部分条目与此格式一致例如urn:miot-spec-v2:device:air-purifier:0000A007:zhimi-ma4: properties: - 9.* - 13.* - 15.* services: - 10 urn:miot-spec-v2:device:vacuum:0000A006:narwa-001: services: - *底层实现过滤器对应 miot_spec.py 中的_SpecFilter类init_async()通过load_yaml_file加载specs/spec_filter.yaml并做结构校验字典嵌套必须是dict - dict - list否则报错并放弃加载set_spec_spec(urn_key)按设备 URN key 缓存当前设备的过滤规则filter_service(siid)、filter_property(siid, piid)、filter_event(siid, eiid)、filter_action(siid, aiid)分别判断服务/属性/事件/动作是否应被过滤返回True表示过滤不转换。其中属性/事件/动作同时支持精确 id 与siid.*通配。从源码可以推断spec_filter.yaml的典型用途是规避某些型号固件上报异常数据如空的 value-list 导致 Select/Number 转换异常通过按设备型号精准裁掉有问题的服务、属性、事件或动作。配套的spec_modify.yaml仓库中还提供 spec_modify.yaml用于在转换前修改MIoT-Spec-V2 实例定义例如重命名属性name: ac-on、修改format、access、unit、补充value-list或将某个版本实例重定向到另一个版本如urn:...:xiaomi-c17:2: urn:...:xiaomi-c17:1。spec_filter.yaml过滤与spec_modify.yaml修改共同构成实体转换规则的预处理层。重要提醒如果在 Home Assistant 中修改了custom_components/xiaomi_home/miot/specs目录下的任何文件spec_filter.yaml、spec_modify.yaml、multi_lang.json等需要在集成 CONFIGURE 页面执行Update entity conversion rules更新实体转换规则才能生效。六、多语言支持6.1 配置流界面语言集成在 config flow 语言选项中提供13 种语言简体中文、繁体中文、英文、西班牙文、俄文、法文、德文、日文、意大利文、荷兰文、葡萄牙文、巴西葡萄牙文、土耳其文。简体中文和英文由开发者人工校对其他语言由机器翻译或社区贡献。如需修改 config flow 页面文案需要修改对应语言的 json 文件custom_components/xiaomi_home/translations/HA 组件级翻译custom_components/xiaomi_home/miot/i18n/6.2 实体名称多语言multi_lang.json展示 Home Assistant 实体名称时集成会从 MIoT Cloud 下载设备厂商配置的多语言文件包含设备 MIoT-Spec-V2 实例的翻译。multi_lang.json是本地维护的多语言字典优先级高于云端多语言文件可用于补充或修正设备的多语言翻译。格式如下{ MIoT-Spec-V2 device instance: { language code: { instance code: translation: str } } }规则要点字典 key 是去掉 version 字段的 MIoT-Spec-V2 设备实例 URN语言代码为zh-Hans、zh-Hant、en、es、ru、fr、de、ja、it、nl、pt、pt-BR、tr对应上述 13 种语言实例代码格式service:siid # 服务 service:siid:property:piid # 属性 service:siid:property:piid:valuelist:index # 属性 value-list 中某个值的索引 service:siid:event:eiid # 事件 service:siid:action:aiid # 动作其中 siid、piid、eiid、aiid 以及 value 均为十进制三位整数。README 示例{ urn:miot-spec-v2:device:health-pot:0000A051:chunmi-a1: { zh-Hant: { service:002: 養生壺, service:002:property:001: 工作狀態, service:002:property:001:valuelist:000: 待機中, service:002:action:002: 停止烹飪, service:005:event:001: 烹飪完成 } } }仓库真实文件 multi_lang.json 中的条目与此一致例如为urn:miot-spec-v2:device:fan:0000A005:zhimi-za1补充土耳其语与简体中文的自然风/直吹风枚举翻译。从 miot_spec.py 的_MIoTSpecMultiLang类可以看到其加载流程优先读取本地specs/multi_lang.json再从云端获取厂商多语言文件本地翻译的优先级更高translate()在服务/属性/事件/动作转换时逐项调用。七、安全性与隐私说明官方安全声明要点集成及其附属云接口由小米官方提供需要使用小米账号登录以获取设备列表集成实现OAuth 2.0登录流程不会在 Home Assistant 应用中保存账号密码但由于 Home Assistant 平台限制登录成功后小米账号的用户信息含设备信息、证书、token 等会以明文保存在 Home Assistant 配置文件中。请确保配置文件存放安全配置文件泄露可能导致他人以你的身份登录若怀疑 OAuth 2.0 token 泄露可通过以下步骤撤销授权米家 APP → 我的 → 点击用户名进入小米账号管理页 → 基本信息应用 → Xiaomi Home (Home Assistant Integration) → 移除。八、官方 FAQ 要点速览支持哪些设备目前支持绝大多数智能设备类别不支持的仅有三类蓝牙设备、红外设备、虚拟设备。支持多个小米账号吗支持。且不同账号下的设备可以添加到同一个区域area中。支持本地模式吗支持分两种通过小米中枢网关或内置中枢网关的设备实现完整本地模式——仅中国大陆可用通过 Xiaomi LAN 控制功能实现部分本地模式——仅能控制与 Home Assistant 同一局域网内的 IP 设备不能控制 BLE Mesh / ZigBee 等设备且可能引发异常官方不建议使用。哪些区域可用中国大陆、欧洲、印度、俄罗斯、新加坡、美国。不同区域米家云数据相互隔离导入 MIoT 设备时需选择区域集成允许将不同区域的设备导入同一 area。九、仓库目录结构导读custom_components/xiaomi_home/ ├── __init__.py # 集成入口 ├── config_flow.py # 配置流 ├── miot/ # 核心代码 │ ├── miot_client.py # 每个登录用户对应一个 miot_client 实例 │ ├── miot_cloud.py # 云服务相关OAuth 登录、HTTP 接口获取用户信息、下发设备控制命令等 │ ├── miot_device.py # 设备实体设备信息、属性/事件/动作处理逻辑 │ ├── miot_mips.py # 消息总线订阅与发布方法 │ ├── miot_spec.py # 解析 MIoT-Spec-V2含过滤、修改、多语言加载 │ ├── miot_lan.py # 设备 LAN 控制设备发现、设备控制等 │ ├── miot_mdns.py # 中枢网关服务的局域网发现 │ ├── miot_network.py # 获取网络状态与网络信息 │ ├── miot_storage.py # 集成的文件存储 │ ├── i18n/ # 集成内部多语言文案 │ └── specs/ # 实体转换规则specv2entity.py、spec_filter.yaml、spec_modify.yaml、multi_lang.json 等 ├── binary_sensor.py ... water_heater.py # 各实体平台实现 └── translations/ # config flow 等 HA 组件级翻译各实体平台文件switch.py、number.py、select.py、text.py、event.py、button.py、notify.py、sensor.py、binary_sensor.py、cover.py、fan.py、humidifier.py、climate.py、light.py、media_player.py、vacuum.py、water_heater.py、device_tracker.py分别对应第五节中转换出的实体类型是理解某个实体在 HA 中如何工作的下一层入口。更多资料可继续阅读仓库内的 CONTRIBUTING.md贡献指南另有简体中文版 doc/CONTRIBUTING_zh.md、CHANGELOG.md版本变更记录与 LICENSE.md许可证。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考