hass-xiaomi-miot终极指南：从安装到自动化的小米设备HomeAssistant实战

还在为小米智能家居设备无法完美接入HomeAssistant而烦恼？本篇指南将带你从零基础开始，完成从插件安装到设备自动化的全流程实战，让你的米家设备真正融入智能家居生态。读完本文你将掌握：四种安装方法对比、设备接入的两种核心模式、实体自定义技巧、自动化场景配置，以及常见问题解决方案。

插件安装全解析

hass-xiaomi-miot提供了多种安装方式，适用于不同技术背景的用户。以下是四种主流安装方法的详细对比和操作步骤：

HACS安装（推荐）

作为HomeAssistant最流行的插件管理平台，HACS提供了最简单的安装体验：

1. 在HomeAssistant侧边栏进入HACS > 集成
2. 点击右上角**+ 探索并下载存储库**
3. 搜索Xiaomi Miot Auto并点击下载
4. 重启HomeAssistant使插件生效

这种方式的优势在于自动更新提醒和一键升级，推荐所有用户优先使用。插件元数据信息可查看custom_components/xiaomi_miot/manifest.json，当前最新版本为1.0.22。

手动安装

对于网络环境受限或偏好手动控制的用户：

1. 访问仓库地址克隆或下载项目文件
2. 将custom_components/xiaomi_miot文件夹复制到HomeAssistant配置目录下的custom_components文件夹
3. 重启HomeAssistant

手动安装需要关注README_zh.md中的更新说明，及时获取安全补丁和功能改进。

一键命令安装

通过SSH或Terminal & SSH加载项执行：

wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot bash -

此命令会自动处理依赖关系并安装最新版本，适合熟悉命令行操作的高级用户。

Shell Command服务安装

对于希望将更新集成到自动化流程的用户：

1. 在configuration.yaml中添加：

shell_command:
  update_xiaomi_miot: |-
    wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot bash -

2. 重启HomeAssistant后，在开发者工具中调用shell_command.update_xiaomi_miot服务

设备接入两种模式详解

hass-xiaomi-miot支持两种核心接入模式，适用于不同网络环境和设备类型：

小米账号集成（推荐新手）

从v0.4.4版本开始，插件支持三种账号集成模式：

• 自动模式：系统定期更新支持本地miot-spec的设备列表，自动为支持的设备选择本地连接
• 本地模式：所有设备强制使用局域网连接，不支持本地协议的设备将不可用
• 云端模式：所有设备通过小米云服务连接，适合蓝牙、ZigBee等依赖网关的设备

配置步骤：

1. 进入配置 > 设备与服务 > 集成 > 添加集成
2. 搜索Xiaomi Miot Auto并选择
3. 输入小米账号信息并选择连接模式
4. 在设备列表中勾选要集成的设备

本地Token集成（高级用户）

对于需要更低延迟或局域网隔离环境的用户，可使用设备IP和Token直接连接：

1. 获取设备Token（详见后文"获取miio token"部分）
2. 在集成页面选择"通过IP/Token添加设备"
3. 输入设备IP、Token和设备型号
4. （可选）配置小米云服务以获取高级功能

实体自定义与高级配置

插件提供了丰富的自定义选项，让你可以根据需求调整设备行为。主要配置方式包括：

设备型号级自定义

在configuration.yaml中针对特定设备型号进行配置：

xiaomi_miot:
  device_customizes:
    chuangmi.plug.212a01:  # 设备型号
      miot_local: true     # 强制本地连接
      chunk_properties: 7  # 批量获取属性数量

系统已内置多种设备的优化配置，可参考device_customizes.py文件。

实体级自定义

通过customize.yaml对单个实体进行精细化调整：

# 基础连接设置
switch.your_plug_entity:
  miot_local: true        # 强制本地模式
  miot_cloud: false       # 禁用云端连接
  interval_seconds: 30    # 状态更新间隔（秒）

# 传感器属性配置
sensor.your_air_purifier:
  sensor_properties: temperature,humidity  # 生成子传感器
  exclude_state_attributes: miot_type,raw_data  # 过滤不需要的属性

# 灯光设备特殊配置
light.your_yeelight:
  color_temp_reverse: false  # 色温反转
  yeelight_smooth_on: 2000   # 渐亮时间（毫秒）

翻译词典配置

针对设备状态和属性的中文显示优化：

xiaomi_miot:
  language: zh
  translations:
    # 全局词典
    idle: '空闲'
    busy: '工作中'
    # 设备类型专用词典
    fan.mode:
      straight wind: '直吹模式'
      natural wind: '自然风'

系统默认翻译可参考translation_languages.py文件。

自动化场景实战

hass-xiaomi-miot提供了多种工具帮助用户构建智能自动化场景，包括预定义的自动化蓝图和灵活的服务调用。

自动化蓝图

项目内置了两个实用的摄像头录制通知蓝图：

• camera-recording-notify-phone.yaml：检测到移动时向手机发送通知
• camera-recording-notify.yaml：基础录制通知功能

使用方法：

1. 进入设置 > 自动化 > 蓝图 > 导入蓝图
2. 粘贴上述文件路径或内容
3. 根据向导配置设备和通知方式

服务调用示例

插件提供了丰富的服务接口，可在自动化中灵活调用：

设置设备属性

service: xiaomi_miot.set_property
data:
  entity_id: fan.xiaomi_fan_entity
  field: fan.mode
  value: natural wind

调用设备动作

service: xiaomi_miot.call_action
data:
  entity_id: vacuum.xiaomi_vacuum_entity
  siid: 4  # vacuum-extend服务
  aiid: 1  # start-clean动作
  params:
    - 18  # 工作模式
    - '{"selects":[[7,1,0,2,1]]}'  # 清洁区域参数

获取设备Token

对于需要本地连接的设备，可通过服务获取Token：

service: xiaomi_miot.get_token
data:
  name: 客厅灯  # 米家中的设备名称关键词

Token将通过HomeAssistant通知发送给用户。

支持设备与功能扩展

插件通过MIoT协议规范支持绝大多数小米IoT设备，涵盖家居生活的方方面面：

主要支持设备类型

• 照明设备：智能灯泡、吸顶灯、灯带等，支持亮度、色温、RGB调节
• 环境控制：空调、风扇、空气净化器、加湿器，支持模式切换和参数调节
• 安防监控：摄像头、门铃、门锁，支持实时查看和事件通知
• 厨房电器：冰箱、洗衣机、微波炉，支持程序控制和状态监控
• 生活电器：扫地机器人、窗帘电机、晾衣架，支持自动化控制

完整支持列表可参考README_zh.md中的"支持的设备"章节，包含20多个类别上百种设备。

功能扩展架构

插件采用模块化设计，核心功能由以下模块构成：

• 设备管理：device.py负责设备生命周期管理
• 协议处理：miot_spec.py解析MIoT设备描述规范
• 数据转换：converters.py处理设备数据与HA实体间的转换
• 状态同步：coordinator.py管理设备状态更新

调试与问题解决

即使是最稳定的系统也可能遇到问题，以下是常见问题的诊断和解决方法：

开启调试日志

在configuration.yaml中添加：

logger:
  default: warning
  logs:
    custom_components.xiaomi_miot: debug

日志可在配置 > 系统 > 日志中查看，帮助定位连接、通信等问题。

常见问题排查

1. 设备无法添加：检查网络连接，确认设备已在米家APP中正常工作
2. 状态更新延迟：调整interval_seconds参数，或启用miot_local: true尝试本地连接
3. 实体缺失：检查设备是否在不支持的设备列表中，部分无线开关和传感器需要额外配置
4. 控制无响应：尝试切换连接模式（本地/云端），检查网络防火墙设置

获取技术支持

如果遇到无法解决的问题，可通过以下途径获取帮助：

1. 查阅常见问题章节，包含大量用户经验总结
2. 检查GitHub Issues寻找类似问题和解决方案
3. 加入项目交流群组获取社区支持

总结与展望

hass-xiaomi-miot作为小米设备接入HomeAssistant的桥梁，通过MIoT协议规范实现了高度自动化的设备集成方案。从简单的开关控制到复杂的场景自动化，从单一设备到全屋智能，插件提供了灵活而强大的工具集。

随着小米IoT生态的不断扩展和HomeAssistant平台的持续进化，插件也在不断更新迭代。未来版本将重点改进：

1. 设备发现机制优化，提高新设备支持速度
2. 本地协议支持增强，减少对云端的依赖
3. 自动化模板扩展，提供更多场景化解决方案
4. 用户界面改进，降低配置复杂度

希望本指南能帮助你充分利用hass-xiaomi-miot插件，构建属于自己的智能生活体验。如有任何问题或建议，欢迎通过项目仓库提交反馈。

如果你觉得本指南对你有帮助，请点赞、收藏并关注项目更新，不错过未来的功能增强和优化改进！