小米智能家居全面接入指南：hass-xiaomi-miot终极配置手册

【免费下载链接】hass-xiaomi-miot Automatic integrate all Xiaomi devices to HomeAssistant via miot-spec, support Wi-Fi, BLE, ZigBee devices. 小米米家智能家居设备接入Hass集成 项目地址: https://gitcode.com/gh_mirrors/ha/hass-xiaomi-miot

hass-xiaomi-miot是HomeAssistant生态中最强大的小米设备集成插件，通过MIoT协议规范自动接入Wi-Fi、蓝牙、ZigBee等多种连接方式的小米智能设备。本文将深入解析其核心架构、实战配置和高级应用，帮助技术爱好者和中级用户实现小米智能家居的全面自动化控制。

核心原理：MIoT协议与设备自动发现机制

hass-xiaomi-miot的核心优势在于其基于小米官方MIoT协议规范的智能设备识别系统。MIoT（小米物联网）协议是小米IoT平台为硬件产品设计的标准化功能定义规范，插件通过解析设备规格自动创建对应的HomeAssistant实体。

架构设计解析

项目采用模块化设计，核心文件位于custom_components/xiaomi_miot/core/目录：

• 设备识别层：miot_spec.py负责解析MIoT设备规格，将设备功能映射为HA实体
• 数据转换层：converters.py处理设备原始数据到HA标准格式的转换
• 连接管理层：coordinator.py协调本地与云端连接，支持自动切换
• 实体适配层：各设备类型文件（sensor.py、switch.py等）实现具体功能

架构图说明：hass-xiaomi-miot采用分层架构设计，从设备协议解析到实体创建实现完整自动化流程

支持的设备类型

插件支持22种实体类型，涵盖智能家居全场景：

• 传感器类：温度、湿度、光照、运动等
• 控制类：开关、灯光、风扇、空调
• 安防类：摄像头、门锁、报警器
• 环境类：加湿器、空气净化器、净水器

实战配置：三阶段部署指南

阶段一：快速安装与基础配置

安装方式对比表

安装方式	适用场景	操作复杂度	更新便利性
HACS安装	新手用户	⭐⭐	⭐⭐⭐⭐⭐
手动安装	离线环境	⭐⭐⭐	⭐⭐
一键脚本	快速部署	⭐	⭐⭐⭐⭐

推荐配置方案：通过HACS安装是最佳选择，支持自动更新和版本管理。

# 配置示例：基础小米云服务
xiaomi_miot:
  username: "你的小米账号"
  password: "你的密码"
  server_country: cn  # 服务器地区：cn(中国)、de(欧洲)、us(美国)等

⚠️ 安全建议：建议使用小米账号的App专用密码而非主密码，增强账号安全性。

阶段二：设备连接模式深度配置

hass-xiaomi-miot提供三种连接模式，适应不同设备需求：

1. 自动模式（推荐）

conn_mode: auto

插件自动检测设备支持情况，优先使用本地连接，不支持本地连接的设备自动切换云端。

2. 本地模式

conn_mode: local

强制所有设备使用本地连接，适合局域网环境优化响应速度。

3. 云端模式

conn_mode: cloud

强制使用云端连接，适合蓝牙、ZigBee等无法直接本地连接的设备。

💡 性能优化技巧：混合使用不同模式，Wi-Fi设备用本地模式，蓝牙/ZigBee设备用云端模式。

阶段三：高级实体自定义配置

通过设备自定义文件device_customizes.py实现精细控制：

# 示例：自定义温湿度传感器实体
DEVICE_CUSTOMIZES = {
    "lumi.sensor_ht.v1": {
        "chunk_properties": 5,  # 属性分块数量
        "sensor_properties": "temperature,humidity",  # 显示的温度湿度属性
        "interval_seconds": 30,  # 更新间隔
        "miot_local": True,  # 强制使用本地连接
    }
}

场景应用：智能家居自动化实战

应用场景一：智能温湿度联动控制

场景需求：当室内温度超过28°C且湿度低于40%时，自动开启空调和加湿器。

自动化配置：

automation:
  - alias: "智能温湿度调节"
    trigger:
      - platform: state
        entity_id: sensor.xiaomi_temperature
        to: "28"
      - platform: state
        entity_id: sensor.xiaomi_humidity  
        to: "40"
    condition:
      condition: and
      conditions:
        - condition: numeric_state
          entity_id: sensor.xiaomi_temperature
          above: 28
        - condition: numeric_state
          entity_id: sensor.xiaomi_humidity
          below: 40
    action:
      - service: climate.turn_on
        target:
          entity_id: climate.xiaomi_air_conditioner
      - service: humidifier.turn_on
        target:
          entity_id: humidifier.xiaomi_humidifier

应用场景二：安防联动与通知

场景需求：门锁异常开启或摄像头检测到运动时，发送手机通知并录像。

服务调用示例：

service: xiaomi_miot.set_property
data:
  entity_id: alarm_control_panel.xiaomi_door_lock
  field: alarm_state
  value: "armed_away"

高级技巧：性能优化与故障排除

优化策略一：连接稳定性提升

问题现象：设备频繁离线或响应延迟 解决方案：

1. 检查网络环境，确保设备与HA服务器在同一局域网
2. 调整轮询间隔，避免过于频繁的设备查询
3. 启用设备心跳检测，及时识别离线状态

# 配置优化示例
xiaomi_miot:
  scan_interval: 60  # 扫描间隔调整为60秒
  heartbeat_interval: 300  # 心跳检测间隔300秒

优化策略二：实体管理优化

常见问题：实体数量过多导致界面混乱 解决方案：

1. 使用设备自定义隐藏不必要的实体
2. 通过区域和分组整理设备
3. 利用HA的实体注册表进行批量管理

# 隐藏非必要传感器实体
DEVICE_CUSTOMIZES = {
    "zhimi.airpurifier.mb3": {
        "exclude_miot_services": "filter,maintenance",  # 排除滤芯和维护相关实体
    }
}

故障排除指南

故障现象	可能原因	解决方案
设备无法添加	账号密码错误	检查小米账号密码，确保地区设置正确
实体状态延迟	云端模式响应慢	切换到本地模式或调整扫描间隔
部分功能缺失	设备规格解析错误	更新插件版本或手动配置设备自定义
频繁离线	网络不稳定	检查路由器设置，优化Wi-Fi信号

安全建议与最佳实践

安全配置要点

1. 账号安全：使用小米App专用密码而非主密码
2. 网络隔离：智能设备建议部署在独立的IoT VLAN
3. 权限控制：限制HA外部访问，启用HTTPS加密
4. 定期更新：保持插件和设备固件最新版本

最佳实践总结

🎯 配置最佳实践：

• 新设备优先使用自动连接模式测试
• 重要设备配置本地连接确保稳定性
• 定期备份设备自定义配置文件

🎯 维护最佳实践：

• 每月检查一次设备连接状态
• 季度性更新插件版本
• 建立设备变更日志记录

🎯 扩展最佳实践：

• 利用模板创建虚拟传感器聚合数据
• 结合Node-RED实现复杂场景自动化
• 使用HA历史数据进行分析优化

技术深度：MIoT协议解析与扩展

协议工作机制

hass-xiaomi-miot通过解析MIoT设备规格文件实现设备功能自动映射。每个小米设备都有对应的规格定义，包含服务(SIID)、属性(PIID)和动作(AIID)的三元组标识。

规格文件示例结构：

{
  "type": "urn:miot-spec-v2:device:air-conditioner:0000A004",
  "services": [
    {
      "iid": 2,
      "type": "urn:miot-spec-v2:service:air-conditioner:00007801",
      "properties": [
        {
          "iid": 1,
          "type": "urn:miot-spec-v2:property:on:00000006",
          "description": "Switch Status",
          "format": "bool",
          "access": ["read", "write", "notify"]
        }
      ]
    }
  ]
}

自定义扩展机制

高级用户可以通过修改miot_specs_extend.json文件扩展设备支持：

{
  "custom_specs": {
    "my_custom_device": {
      "type": "urn:miot-spec-v2:device:custom:0000A001",
      "services": [
        {
          "iid": 1,
          "type": "urn:miot-spec-v2:service:custom-service:00007801",
          "description": "Custom Service",
          "properties": [
            {
              "iid": 1,
              "type": "urn:miot-spec-v2:property:custom-property:00000001",
              "description": "Custom Property",
              "format": "uint8",
              "access": ["read", "write"],
              "value-range": [0, 100, 1]
            }
          ]
        }
      ]
    }
  }
}

未来展望与社区贡献

hass-xiaomi-miot项目持续演进，支持设备数量不断增加。社区用户可以通过以下方式参与贡献：

1. 设备测试：测试新设备并提交兼容性报告
2. 规格提交：为新设备创建MIoT规格定义
3. 翻译完善：帮助完善多语言翻译文件
4. 文档贡献：编写使用教程和最佳实践指南

通过本文的全面指南，您应该能够充分利用hass-xiaomi-miot的强大功能，构建稳定、高效、安全的小米智能家居系统。无论是基础部署还是高级定制，这个插件都为HomeAssistant用户提供了最完整的小米设备集成解决方案。

【免费下载链接】hass-xiaomi-miot Automatic integrate all Xiaomi devices to HomeAssistant via miot-spec, support Wi-Fi, BLE, ZigBee devices. 小米米家智能家居设备接入Hass集成 项目地址: https://gitcode.com/gh_mirrors/ha/hass-xiaomi-miot