告别智能孤岛：小米IoT设备与Home Assistant属性联动实战指南

乔如黎

1130人浏览 · 2025-09-09 02:57:58

乔如黎 · 2025-09-09 02:57:58 发布

告别智能孤岛：小米IoT设备与Home Assistant属性联动实战指南

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

你是否还在为智能家居设备各自为战而烦恼？空调、净化器、灯光只能单独控制？本文将通过3个真实场景案例，教你如何利用Xiaomi Home Integration for Home Assistant实现设备属性联动，让你的智能家居系统真正"聪明"起来。读完本文你将掌握：多设备状态联动逻辑设计、属性触发条件配置、复杂场景自动化编写，以及常见故障排查方法。

核心概念解析：从设备属性到联动逻辑

Xiaomi Home Integration基于小米官方MIoT-Spec-V2协议，将设备功能转换为Home Assistant实体。设备包含多个服务，每个服务又包含属性、事件和动作三种基本元素。正是这些元素的组合，构成了智能家居联动的基础。

MIoT与Home Assistant实体映射关系

根据MIoT-Spec-V2规范，设备属性会根据访问权限和数据类型转换为不同的Home Assistant实体：

访问权限	数据格式	Home Assistant实体类型
可写	布尔值	Switch（开关）
可写	字符串	Text（文本）
可写	枚举值	Select（选择器）
可写	数值范围	Number（数值）
只读	任意	Sensor（传感器）

例如，小米空气净化器的"电源状态"属性（布尔值、可写）会转换为Switch实体，而"PM2.5浓度"属性（数值、只读）会转换为Sensor实体。这些实体正是实现设备联动的"积木"。

两种控制模式的架构差异

Xiaomi Home Integration支持云端控制和本地控制两种模式，理解它们的工作原理对设计稳定的联动场景至关重要。

云端控制通过MIoT Cloud的MQTT Broker实现消息订阅，当设备状态变化时，云端会主动推送更新，控制命令也通过云端转发。这种模式依赖互联网连接，但兼容性最好，支持所有小米IoT设备。

本地控制则需要小米多模网关（固件≥3.3.0_0023）或内置网关功能的设备，直接通过局域网内的MQTT Broker通信。本地控制响应速度更快，隐私性更好，但仅支持IP设备，且在部分地区可能无法使用。

场景实战：从简单到复杂的联动案例

案例1：基于PM2.5浓度的空气净化联动

场景描述：当卧室PM2.5浓度超过75μg/m³时，自动开启空气净化器并关闭窗户；当浓度低于35μg/m³时，关闭净化器并打开窗户通风。

涉及设备：

小米空气净化器4 Pro sensor.py
Aqara智能窗帘电机 cover.py

实现步骤：

确认实体ID：在Home Assistant的"开发者工具>状态"中找到对应实体：
- PM2.5传感器：sensor.xiaomi_air_purifier_4_pro_pm25
- 空气净化器开关：switch.xiaomi_air_purifier_4_pro_power
- 窗帘控制：cover.aqara_curtain_motor

创建自动化规则：

alias: PM2.5浓度联动控制
trigger:
  - platform: numeric_state
    entity_id: sensor.xiaomi_air_purifier_4_pro_pm25
    above: 75
    for:
      minutes: 2
  - platform: numeric_state
    entity_id: sensor.xiaomi_air_purifier_4_pro_pm25
    below: 35
    for:
      minutes: 5
condition: []
action:
  - choose:
      - conditions:
          - condition: numeric_state
            entity_id: sensor.xiaomi_air_purifier_4_pro_pm25
            above: 75
        sequence:
          - service: switch.turn_on
            target:
              entity_id: switch.xiaomi_air_purifier_4_pro_power
          - service: cover.close_cover
            target:
              entity_id: cover.aqara_curtain_motor
      - conditions:
          - condition: numeric_state
            entity_id: sensor.xiaomi_air_purifier_4_pro_pm25
            below: 35
        sequence:
          - service: switch.turn_off
            target:
              entity_id: switch.xiaomi_air_purifier_4_pro_power
          - service: cover.open_cover
            target:
              entity_id: cover.aqara_curtain_motor
mode: single

关键点：添加for参数避免传感器数值波动导致的频繁切换，设置合理的延迟时间可提高系统稳定性。

案例2：智能照明与人体传感器的存在感应联动

场景描述：当检测到房间有人移动，且环境光照度低于300lux时，自动打开灯光并调整亮度为70%；当10分钟无人移动时，自动关闭灯光。

涉及设备：

Aqara人体传感器 binary_sensor.py
Yeelight智能吸顶灯 light.py

实现要点：

处理传感器延迟：人体传感器可能存在1-2秒响应延迟，可通过device_class: motion确保状态准确。

亮度平滑调节：Yeelight支持亮度渐变，通过transition参数实现无感知调节：

service: light.turn_on
target:
  entity_id: light.yeelight_ceiling_light
data:
  brightness_pct: 70
  transition: 2

防误触逻辑：结合光照传感器避免白天开灯，通过for参数过滤短暂离开：
```
condition:
  - condition: numeric_state
    entity_id: sensor.illuminance
    below: 300
```

案例3：多设备协同的回家模式场景

场景描述：当指纹锁检测到主人回家（特定指纹），自动执行：①打开客厅主灯；②将空调温度调至26℃；③开启空气净化器自动模式；④拉开客厅窗帘；⑤播放欢迎音乐。

涉及设备：

小米智能门锁E10 binary_sensor.py
米家空调伴侣2 climate.py
小米AI音箱 media_player.py

实现难点：

多设备状态同步：使用parallel模式确保所有设备同时响应，避免等待：
```
mode: parallel
max: 10
```

空调温度精准控制：通过Climate实体设置目标温度：

service: climate.set_temperature
target:
  entity_id: climate.mi_ac_partner
data:
  temperature: 26
  hvac_mode: heat

音箱文本指令：利用Notify实体发送TTS指令：

service: notify.xiaomi_speaker
data:
  message: '欢迎回家！已为您调整好室内环境。'

高级技巧：优化联动体验的实用方法

实体过滤与自定义转换规则

并非所有MIoT属性都需要转换为Home Assistant实体。通过修改spec_filter.yaml文件，可过滤不必要的实体，减少系统负担。例如，过滤掉空气净化器的"电机转速"属性：

urn:miot-spec-v2:device:air-purifier:0000A007:zhimi-ma4:
  properties:
  - 9.*  # 过滤掉siid=9的所有属性

修改后需在集成配置页面更新实体转换规则：设置 > 设备与服务 > Xiaomi Home > 配置 > 更新实体转换规则。

调试模式与事件监控

当联动不按预期工作时，可启用动作调试模式：

进入集成配置页面：设置 > 设备与服务 > Xiaomi Home > 配置
勾选"Debug mode for action"
系统会为设备创建Text实体，可直接发送原始命令进行测试

例如，向空气净化器发送原始MIoT命令：

{"method":"set_properties","params":[{"did":"device_id","siid":2,"piid":1,"value":true}]}

多语言支持与本地化

项目提供8种语言支持，包括简体中文、英文、西班牙文等。语言文件位于translations目录，可根据需要修改实体名称和描述。例如，修改中文环境下的"工作状态"为"运行模式"：

// custom_components/xiaomi_home/translations/zh-Hans.json
{
  "entity": {
    "sensor": {
      "work_state": {
        "name": "运行模式"
      }
    }
  }
}