最完整小米智能家居接入方案：hass-xiaomi-miot核心功能全解析

你是否还在为小米智能家居设备接入HomeAssistant（家庭助手，简称HA）时遇到的兼容性问题而烦恼？是否尝试过多种方案却始终无法实现设备的稳定控制？本文将为你详细解析hass-xiaomi-miot插件的核心功能，帮助你轻松搞定小米智能家居设备的接入与管理，让你的智能生活更加便捷高效。读完本文，你将了解到hass-xiaomi-miot的安装方法、配置技巧、设备支持情况以及实用服务等内容，从此告别智能家居设备接入难题。

插件简介

hass-xiaomi-miot是一款能够通过MIoT-Spec（小米IoT设备协议规范）将小米米家智能家居设备自动集成到HomeAssistant的插件，支持Wi-Fi、蓝牙（BLE）、 ZigBee（紫蜂）等多种连接方式的设备。该插件支持HA后台界面集成，无需复杂的yaml配置即可轻松将小米设备接入HA，极大地降低了用户的使用门槛。

项目的核心文件包括README.md和README_zh.md，分别提供了英文和中文的详细说明。插件的主要代码位于custom_components/xiaomi_miot/目录下，其中custom_components/xiaomi_miot/manifest.json文件定义了插件的基本信息、依赖项等，当前版本为1.0.22。

安装指南

HACS安装（推荐）

HACS（Home Assistant Community Store）是HA的社区商店，通过它可以方便地安装和管理各类插件。

1. 首次安装：进入HACS > 集成 > ➕ EXPLORE & DOWNLOAD REPOSITORIES，搜索“Xiaomi Miot Auto”，然后点击“DOWNLOAD THIS REPOSITORY”进行下载安装。
2. 更新组件：进入HACS > 集成，找到“Xiaomi Miot Auto”，点击“UPDATE / Redownload”即可进行更新。

手动安装

如果你的HA没有安装HACS，也可以选择手动安装。

1. 下载hass-xiaomi-miot的源码，将其中的custom_components/xiaomi_miot文件夹复制到你的HomeAssistant配置文件夹下的custom_components文件夹中。

一键安装（通过SSH/Terminal）

你还可以通过SSH或HA的Terminal & SSH插件执行以下命令进行一键安装：

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

或者

wget -O - https://raw.githubusercontent.com/al-one/hass-xiaomi-miot/master/install.sh | ARCHIVE_TAG=latest bash -

Shell Command服务安装

1. 在你的configuration.yaml文件中添加以下代码：

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

2. 重启HA核心。
3. 在HA的开发者工具中调用service: shell_command.update_xiaomi_miot服务。
4. 再次重启HA核心使插件生效。

配置详解

添加集成

安装完成后，进入HA的配置界面，按照以下步骤添加“Xiaomi Miot Auto”集成：

1. 进入【⚙️ 配置】>【设备与服务】>【🧩 集成】>【➕ 添加集成】。
2. 搜索“Xiaomi Miot Auto”并点击进入配置流程。

账号集成

自v0.4.4版本开始，插件支持账号集成时选择连接设备的模式，你可以根据自己的需求选择以下模式：

• 自动模式：插件会定期更新支持本地miot协议的设备列表，并自动将符合条件的设备使用本地连接，这是推荐的模式。
• 本地模式：集成配置所筛选的设备都将使用本地连接，如果勾选了不支持本地miot协议的设备，该设备将不可用。
• 云端模式：集成配置所筛选的设备都将使用云端连接，建议旧版miio、蓝牙、ZigBee设备使用此模式。

本地集成（Host/Token）

对于在局域网环境下支持miot协议的设备，你还可以通过设备的IP地址（host）和token进行集成。这种方式需要你提前获取设备的token，获取方法可以参考本文后面的“获取miio token”部分。

云端模式配置

如果你需要为通过token集成的设备开启云端模式，可以在configuration.yaml文件中添加以下配置：

# configuration.yaml
xiaomi_miot:
  username: xiaomi_username
  password: xiaomi_password
  # server_country: cn # 小米云服务器位置: cn(默认), de, i2, ru, sg, tw, us
  # http_timeout: 15   # 请求小米接口的超时时间(秒)

配置完成后，进入【⚙️ 配置】>【设备与服务】>【🧩 集成】>【Xiaomi Miot Auto】>【选项】，勾选“Enable miot cloud”即可开启云端模式。

实体自定义

hass-xiaomi-miot允许你对设备实体进行自定义配置，以满足个性化的需求。你可以通过修改configuration.yaml和customize.yaml文件来实现，例如：

# configuration.yaml
homeassistant:
  customize: !include customize.yaml

# 通过设备型号自定义
xiaomi_miot:
  # [设备自定义配置源码](https://gitcode.com/gh_mirrors/ha/hass-xiaomi-miot/blob/405af4e3e3d34e45195acae2c874552c138fefdb/custom_components/xiaomi_miot/core/device_customizes.py?utm_source=gitcode_repo_files)
  device_customizes:
    chuangmi.plug.212a01:
      miot_local: true
      chunk_properties: 7

# 通过父实体自定义（customize.yaml）
domain.your_entity_id:
  miot_local: true        # 使用本地模式 (通过账号接入的设备)
  miot_cloud: true        # 为该实体开启云端模式 (read, write, action)
  miot_cloud_write: true  # 仅写属性使用云端模式
  miot_cloud_action: true # 仅action使用云端模式
  check_lan: true         # 云端模式下检查设备在局域网是否可用
  miio_properties: power,battery # 获取miio属性到实体的属性中
  miio_cloud_props: prop.power,event.dev_online

通过这些自定义配置，你可以灵活地控制设备的连接模式、属性获取等。

设备支持

hass-xiaomi-miot支持大部分小米米家智能设备，涵盖了生活的方方面面，以下是一些主要的设备类型：

• 插座/开关：如插座、开关等。
• 智能灯：如智能灯。
• 空调及相关设备：如空调、空调伴侣、红外空调等。
• 风扇：如风扇、凉霸。
• 浴霸/取暖器：如浴霸、取暖器。
• 摄像头/可视门铃：如摄像头、猫眼/可视门铃。
• 电视/投影仪/机顶盒：如电视、投影仪、机顶盒。
• 扫地/扫拖机器人：如扫地/扫拖机器人、擦地机。

不过，也有部分设备暂时不支持，例如无线场景开关类、人体传感器类、门窗传感器类等，这些设备由于插件采用轮询方式获取状态，无法实时监听事件，所以暂时无法很好地支持。

实用服务

hass-xiaomi-miot提供了多种实用的服务，方便你对设备进行控制和管理，以下是一些常用的服务：

设置设备属性

通过xiaomi_miot.set_property服务可以设置设备的属性，例如：

service: xiaomi_miot.set_property
data:
  entity_id: camera.isa_hlc7_xxxx
  field: camera_control.on
  value: true

调用设备动作

使用xiaomi_miot.call_action服务可以调用设备的特定动作，例如控制扫地机器人开始清扫：

service: xiaomi_miot.call_action
data:
  entity_id: vacuum.dreame_p2259_entity_id
  siid: 4 # vacuum-extend
  aiid: 1 # start-clean
  params:
    - 18 # piid: 1 - work-mode
    - '{"selects":[[7,1,0,2,1]]}' # piid: 10 - clean-extend-data

获取设备Token

xiaomi_miot.get_token服务可以帮助你获取设备的token，这在进行本地集成时非常有用：

service: xiaomi_miot.get_token
data:
  name: Light # 米家中的设备名称关键词或IP、型号

更多服务可以参考custom_components/xiaomi_miot/services.yaml文件。

调试与问题解决

在使用过程中，如果遇到问题，可以通过以下方式进行调试和解决：

获取实体状态属性

进入HA的【🔨 开发者工具】>【ℹ️ 状态】，筛选相应的实体，查看其实体状态属性，有助于分析问题。

获取调试日志

在configuration.yaml文件中添加以下配置，可以开启调试日志，以便更详细地了解插件的运行情况：

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

然后进入【⚙️ 配置】>【⚙️ 系统】>【✍️ 日志】查看详细日志信息。

常见问题

如果你遇到登录失败、没有实体等常见问题，可以参考登录失败/没有实体等常见问题解决办法。对于其他问题，也可以查阅常见问题部分，其中汇总了许多用户可能遇到的问题及解决方法。

总结与展望

hass-xiaomi-miot作为一款功能强大的小米智能家居设备接入插件，为用户提供了便捷、高效的设备集成方案。通过本文的介绍，相信你已经对其核心功能有了全面的了解。从安装到配置，从设备支持到实用服务，hass-xiaomi-miot都展现出了其优秀的性能和易用性。

未来，随着小米智能家居设备的不断更新和扩展，相信hass-xiaomi-miot也会持续优化和升级，为用户带来更好的使用体验。如果你觉得本文对你有帮助，欢迎点赞、收藏、关注，以便获取更多关于智能家居的实用内容。下期我们将为大家带来hass-xiaomi-miot的高级应用技巧，敬请期待！