问题：如何在HomeAssistant中集成小米502设备？

Question

在HomeAssistant中集成小米502设备（如小米空气净化器502）时，常见的技术问题包括设备无法被识别、连接后数据无法更新、或无法实现远程控制。用户常遇到的难点在于如何正确配置MiIO或Miot协议，确保局域网通信正常，并处理设备认证问题。此外，部分用户反馈HomeAssistant重启后设备离线，需检查token是否持久保存。如何获取并配置正确的设备token、选择合适的集成插件（如Xiaomi Miot Auto或MiIO）、以及排查网络与固件兼容性问题，是实现稳定集成的关键步骤。

Answer 1

一、集成概述与常见问题分类

在将小米空气净化器502（以下简称“设备”）集成到 HomeAssistant 时，常见的技术问题包括：

• 设备无法被识别
• 连接后数据无法更新或频繁断开
• 无法实现远程控制
• HomeAssistant 重启后设备离线

这些问题通常与以下因素相关：

1. 设备 token 获取与配置错误
2. 局域网通信异常（如组播、UDP 通信）
3. MiIO 与 Miot 协议选择不当
4. 插件兼容性问题（如 Xiaomi Miot Auto 或 MiIO 插件）
5. 设备固件版本不兼容

二、设备 Token 获取与配置

Token 是设备与 HomeAssistant 通信的关键认证信息。获取方式包括：

1. 使用 Miio 工具扫描局域网设备：

   pip install python-miio
   mirobo --ip <设备IP> info
   

2. 通过 HomeAssistant 集成助手获取：部分插件支持自动发现设备并提示输入 token。

配置 token 时需注意：

问题	解决方法
token 丢失导致重启后离线	确保 token 存储在 configuration.yaml 或插件配置中
token 错误导致连接失败	使用 mirobo 工具验证 token 是否正确

三、协议选择与插件配置

小米设备支持两种主要协议：

• MiIO：适用于旧设备，基于 UDP 协议，支持 token 认证
• MIoT（Miot）：适用于新设备，基于 HTTP/HTTPS，支持更丰富的设备模型

推荐插件如下：

插件名称	适用协议	优势
Xiaomi Miot Auto	MIoT	自动发现设备，支持自动更新 token
MiIO	MiIO	稳定性高，适合老旧设备

配置插件示例（Xiaomi Miot Auto）：

sensor:
  - platform: xiaomi_miot_auto
    name: 小米空气净化器502
    host: 192.168.1.100
    token: YOUR_TOKEN_HERE

四、网络通信与固件兼容性排查

局域网通信问题可能导致设备无法连接或数据无法更新。常见排查步骤如下：

1. 确认设备与 HomeAssistant 处于同一子网
2. 检查路由器是否屏蔽了 UDP 组播通信（MiIO 所需）
3. 关闭防火墙或临时放行相关端口（如 5353、54321）
4. 更新设备固件至最新版本，避免已知协议 bug

设备通信流程图如下： graph TD A[启动 HomeAssistant] --> B[加载插件配置] B --> C{设备是否在局域网?} C -->|是| D[发送发现包] D --> E{设备响应?} E -->|是| F[获取 token] F --> G[建立通信连接] G --> H[获取设备状态] H --> I[展示在 HA 界面] C -->|否| J[设备未发现] E -->|否| K[连接失败]

五、高级调试与日志分析

当设备集成失败时，可启用 HomeAssistant 的日志调试功能：

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

通过日志可发现如下问题：

• token 验证失败
• 设备未响应或超时
• 模型不匹配导致解析失败

也可使用 Wireshark 抓包分析局域网通信，确认设备是否响应 HomeAssistant 的请求。