概念速览
- 米家 (Mi Home)：小米生态的智能家居统一 App，承载 5000+ SKU
- MIoT (Xiaomi MIoT Auto)：小米自 2019 年起对设备开放的本地协议，不依赖云端即可通信
- Miio (旧)：2019 年前的私有协议，HA 通过
xiaomi_miio 集成支持
- 区域账号：国行 / 国际版账号数据隔离，海外服务器可能无法控制国行设备
协议对比
| 维度 | Miio (旧) | MIoT (新) | Mihome Cloud (云) |
|---|
| 通信 | LAN (UDP 54321) | LAN (MQTT 8883) | HTTPS API |
| 是否需 Token | ✓ 需提取 | ✓ OAuth 一次 | ✗ 用账号 |
| 设备支持 | 老款 (Yeelight v1) | 2019+ 大部分 | 全部 |
| 控制延迟 | < 50 ms | < 50 ms | 200-1000 ms |
| 离线可用 | ✓ | ✓ | ❌ |
| 推荐程度 | 仅老设备 | ✅ 首选 | 仅特殊设备 |
集成方式 (HA)
方式 A：OAuth (推荐)
- 设置 → 设备与服务 → 添加集成 → Xiaomi MIoT
- 选
Account 认证
- 用小米账号登录（OAuth 2.0）
- 选地区 (中国 / 国际 / 欧洲)
- HA 自动同步账号下所有设备
方式 B：手动 Token (高级)
适用于 OAuth 失败 / 海外服务器无法同步国行设备的场景：
# Token: 6f8c1a... (32-hex)
把 token 填到 HA 集成的 Configuration 字段。Token 不会因重启丢失，但恢复出厂设置后会变。
网关选型
| 网关 | 协议 | HA 集成 | 价格 | 推荐度 |
|---|
| 小米中枢 (Mi Hub 3) | Zigbee 3.0 + 蓝牙 Mesh | xiaomi_miio 或 xiaomi_ble | ¥350 | ⭐⭐⭐ |
| 小米中枢 4 (Mi Hub 4) | Zigbee 3.0 + Thread | 2025 起 HA 原生 | ¥500 | ⭐⭐⭐⭐ |
| Aqara M2 | Zigbee 3.0 | ZHA / Zigbee2MQTT | ¥400 | ⭐⭐⭐ |
| Aqara M3 | Zigbee + Thread + Matter | ZHA / Matter | ¥700 | ⭐⭐⭐⭐⭐ |
| 不购网关 | 直连 Wi-Fi 设备 | MIoT | ¥0 | 仅插座/灯 |
区域账号问题
- 国行账号：服务器在
cn.openapi.xiaomi.com / api.io.mi.com
- 国际账号：服务器在
open.api.xiaomi.com / api.mi.com
- 问题：2023 年后小米调整 OAuth 流程，部分国行设备无法被国际账号 OAuth
- 解决：用 Token 提取走 MIoT 直连，绕开 OAuth；或注册对应区域的账号
常见设备集成实例
米家智能插座 3 (ZNCZ05CM)
- 协议：MIoT-Wi-Fi
- HA 集成：自动发现 → 实体
switch.living_room_plug
- 进阶：可通过 HA 的
Template Switch 把它变成功率监控实体
米家空气净化器 4 Pro (zhimi.airp.mb4a)
- 协议：MIoT-Wi-Fi
- HA 集成：自动发现 → 实体
fan.air_purifier + sensor.pm2_5
- 自动化示例：PM2.5 > 75 时自动开最大风
米家智能门锁 (loock.lock.xxx)
- 协议：MIoT-Zigbee (需网关)
- HA 集成：门锁事件 + 蓝牙就近解锁
- 注意：远程开锁涉及安全，HA 集成默认禁用远程开锁
Yeelight 灯具 (yeelink.light.xxx)
- 协议：MIoT-Wi-Fi (LAN 控制)
- HA 集成：自动发现；可调色温/亮度/RGB
- 进阶：LAN 控制需灯具固件开启”开发者模式”（米家 App → 灯具 → 设置）
进阶：完全脱离米家 App
- Zigbee 子设备：改用 ZHA / Zigbee2MQTT + 通用 Zigbee 设备，绕开米家网关
- Wi-Fi 子设备：直接 MIoT 集成到 HA，删除米家 App
- 混合方案：保留米家 App 仅做初始配网，配网完成后设备通过 HA 控制
📋 复现条件
| 类别 | 必备 | 可选 / 备注 |
|---|
| 硬件 | 米家智能设备 ≥ 1 个 (插座 / 灯 / 传感器) · Home Assistant 实例 | 树莓派 5 / Linux x86 |
| 操作系统 | HAOS 14+ 或 Debian 12 / Ubuntu 24.04 | macOS 14 (Container) |
| 软件版本 | HA 2024.10+ · python-miio 0.5+ · mijia HACS 集成 | xiaomi-miot-auto (推荐) |
| 网络 | 2.4 GHz Wi-Fi · 米家设备与 HA 同网段 | 公网访问需 Cloudflare Tunnel |
| 账号 | 米家 App (国区 / 台湾 / 新加坡 / 印度 / 俄罗斯任一) | Google / iCloud |
| 时间 | OAuth 接入 5 min · Token 提取 15 min · mDNS 自动发现 10 min | 多设备批量化 30 min |
| 难度 | ⭐⭐⭐ 进阶 | Token 提取有点烦 |
| 前置知识 | HA 基础 · 知道 miio 协议 | Python 基础 (Token 提取脚本) |
⛔ 别这么做 (Anti-patterns)
经验证的坑 —— 跳过 = 至少浪费半天，严重的烧板 / 锁机。
| ❌ 错误做法 | 💥 后果 | ⚠️ 风险 | 范围 |
|---|
| 不要在断电前直接拔 Valetudo 改装中的 USB-TTL | 刷机中途断电 = 变砖。先 dmesg 确认串口没掉再操作。 | 🟡 | 智米扫拖一体 / Roborock S5 Max |
| 不要把米家设备 token 上传到任何第三方云 | token = 设备控制权，泄漏 = 任何人可远程开门。 | 🔴 | 所有米家 / Aqara 设备 |
不要在生产 HA 配置里直接编辑 configuration.yaml 后 check_config 不通过就 reload | 错的 reload 会让 HA 启动失败 → 所有自动化停摆。用 configuration.yaml 备份 + git 版本化。 | 🟢 | Home Assistant |
| 不要给 Frigate 摄像头内网用 admin/admin 默认密码 | RTSP / ONVIF 默认账号 = 局域网裸奔。先改密码。 | 🟡 | 海康 / 大华摄像头 |
| 不要在 ESPHome 设备上直接 OTA 升级到主版本 (major) | 主版本常改 NVS 分区。OTA 升级后启动失败 = 拆壳刷机。先 flash USB 一次。 | 🟡 | ESP32-S3 语音卫星 / 智能开关 |
| 不要在智能家居自动化里写死设备 IP | DHCP 重启后 IP 变 = 自动化失效。用 hostname / mDNS / 静态租约。 | 🟢 | Home Assistant / Hubitat |
| 不要在 Matter 设备首次配对时关掉手机蓝牙 | Matter 配对 = BLE → WiFi handover，全程需要蓝牙。 | 🟢 | Aqara M3 / Apple Home |
🚨 风险总览 (Risk Matrix)
| 风险等级 | 含义 | 例子 |
|---|
| 🟢 低 | 改错可回滚 / 几分钟恢复 | pip 全局装包、DHCP IP 写死 |
| 🟡 中 | 需要重新刷机 / 重装 / 1-2 小时恢复 | 装错 ROS 2 版本、没 OTA 升级看版本 |
| 🔴 高 | 不可逆 / 烧板 / 安全风险 | 电池反接、micro-ROS 没看门狗、刷机中途断电 |
参考资料
