Posts

折腾 Home Assistant + 米家设备时，最让人头疼的就是"数据延迟"。官方集成走米家云，温湿度 2-3 分钟才更新一次，偶尔云端数据还会"抽风"报错。本文记录我用 python-miio 绕过米家云、局域网直连除湿机，把数据采集频率做到秒级、并接入 HA 的完整实战。 一、痛点：为什么需要本地直连 先看一张真实对比（同一台除湿机，同一时刻）： 数据来源 当前值 状态 米家云（官方集成） 30 °F ❌ 云端数据坏了，实际应是 84 °F 本地直连（python-miio） 29.5 °C ✅ 准确 官方 HA 米家集成的工作方式是 MQTT 订阅推送： 设备属性变化 → 设备上报米家云 → 米家云 MQTT 推送 → HA ```plain 理论上 HA 能"第一时间"收到，但实际依赖两点： 1. **设备主动上报**（米家 WiFi 设备为省电，通常 2-3 分钟才上报一次传感器数据） 2. **推送可靠性**（官方仓库 Issue 里提到 WiFi 设备推送丢失率接近 30%） 结果就是：**延迟大、还不一定准**。 而**本地直连**的路径是： ```plain 你的脚本 → 局域网直连设备（miio 协议）→ 秒级返回 ```plain 不经过米家云，不依赖设备上报节奏，你想读就读，又快又准。 --- ## 二、原理：米家设备的本地通信 小米的 WiFi 设备（除湿机、空气净化器、扫地机等）在局域网内会开放一个 **miio 协议**（UDP 54321 端口）。只要你有设备的 **token**（一个 32 位十六进制密钥），就能在局域网内直接和设备通信。 ```plain ┌──────────┐ 局域网 (UDP 54321) ┌──────────┐ │ 你的脚本 │ ──── miio 协议 ──────▶│ 小米设备 │ │(python-miio)│ ◀── 加密响应 ────── │ │ └──────────┘ └──────────┘ ```plain 关键点： - **token** 是设备配对时生成的密钥，控制设备的"钥匙" - miio 协议是加密的，token 用于加解密 - [python-miio](https://github.com/rytilahti/python-miio) 是开源的 Python 库，封装了这套协议 - MIoT（小米新一代物模型）设备用 `siid/piid`（服务ID/属性ID）寻址属性 --- ## 三、实战：除湿机本地直连全流程 ### 第 1 步：获取设备 token token 是本地直连的必需品。获取方式有几种： **方法 A：从 Home Assistant 官方集成配置里提取（最省事）** 如果你已经在 HA 装了官方米家集成，token 已经明文存在配置里： ```plain /config/.storage/xiaomi_home/miot_devices/<你的uid>_cn.dict ```plain 这个文件是 JSON，里面每个设备都带 `token` 字段。 **方法 B：用旧版米家 APP 提取数据库** 安卓米家 APP（旧版 5.4.54）的数据库里有 token，用 [mihome-binary-extractor](https://github.com/Maxmudjon/Get_MiHome_devices_token) 提取。 **方法 C：在线工具**（不推荐，有账号泄露风险） > ⚠️ **token 等于设备控制权**，千万不要提交到公开仓库或发到群里。 ### 第 2 步：找到设备局域网 IP 本地直连需要设备的局域网 IP。几种方式： - 路由器后台看 DHCP 客户端列表 - `ip neigh` / `arp -a` 看 ARP 表 - python-miio 的发现功能 但设备 MAC 可能随机化，最稳的办法是**用 token 遍历候选 IP 试连**： ```python from miio import MiotDevice token = "你的token" for ip in ["192.168.1.98", "192.168.1.107", "192.168.1.89"]: try: dev = MiotDevice(ip=ip, token=token, mapping={}) info = dev.info() print(f"✅ {ip}: {info.model}") except Exception: print(f"❌ {ip}") ```plain 哪个 IP 返回了 `model`，就是它（我的除湿机是 `192.168.1.89`，model `xiaomi.derh.13l`）。 ### 第 3 步：读数据 —— 理解 MIoT 的 siid/piid MIoT 设备用**服务(siid) + 属性(piid)** 来组织功能。比如除湿机： - `siid=3, piid=2` → 温度 - `siid=3, piid=1` → 湿度 - `siid=2, piid=5` → 目标湿度 读取用 `get_property_by(siid, piid)`： ```python from miio import MiotDevice dev = MiotDevice(ip="192.168.1.89", token="你的token", mapping={}) temp = dev.get_property_by(3, 2)[0]["value"] # 温度 humidity = dev.get_property_by(3, 1)[0]["value"] # 湿度 print(f"温度 {temp}°C, 湿度 {humidity}%") # 输出: 温度 29.5°C, 湿度 58% ```plain **怎么知道哪个 siid/piid 是温度？** —— 扫描： ```python for siid in range(1, 9): for piid in range(1, 8): try: r = dev.get_property_by(siid, piid)[0] if r.get("code") == 0 and r.get("value") is not None: print(f"siid={siid} piid={piid}: {r['value']}") except Exception: pass ```plain 看输出里哪个值像温度（20-30）、哪个像湿度（40-70），就能对上号。也可以查设备的 [MIoT Spec](https://home.miot-spec.com/)。 ### 第 4 步：MQTT 推送到 HA，秒级显示 光自己读到数据还不够，要让它进 HA、能在仪表盘显示，最优雅的方式是 **MQTT Discovery**：你的脚本发布一个 discovery 消息，HA 自动创建对应传感器。 架构： ```plain 除湿机 ──python-miio──▶ 采集脚本 ──paho-mqtt──▶ mosquitto ──discovery──▶ HA ```plain 完整采集脚本： ```python import time, json import paho.mqtt.client as mqtt from miio import MiotDevice MQTT_HOST = "127.0.0.1" DEV_IP = "192.168.1.89" DEV_TOKEN = "你的token" INTERVAL = 10 # 每10秒采集一次 # 连 MQTT client = mqtt.Client() client.connect(MQTT_HOST, 1883, 60) client.loop_start() # 发布 discovery，HA 会自动创建传感器 discovery = { "name": "除湿机温度(本地)", "state_topic": "dehumi_local/state", "value_template": "{{ value_json.temperature }}", "unit_of_measurement": "°C", "device_class": "temperature", "state_class": "measurement", "unique_id": "dehumi_local_temp_001", } client.publish("homeassistant/sensor/dehumi_local_temp/config", json.dumps(discovery), retain=True) # 湿度同理，略 dev = MiotDevice(ip=DEV_IP, token=DEV_TOKEN, mapping={}) while True: try: temp = dev.get_property_by(3, 2)[0]["value"] humid = dev.get_property_by(3, 1)[0]["value"] # 一次发一个 JSON，HA 用 value_template 拆分 payload = json.dumps({"temperature": temp, "humidity": humid}) client.publish("dehumi_local/state", payload, retain=True) print(f"{time.strftime('%H:%M:%S')} 温度={temp}°C 湿度={humid}%") except Exception as e: print(f"采集失败: {e}") time.sleep(INTERVAL) ```plain HA 那边只要装了 MQTT 集成（连同一个 broker），几秒内就会自动出现「除湿机温度(本地)」「除湿机湿度(本地)」两个传感器，**10 秒刷新一次**。 --- ## 四、效果对比 | | 官方集成（云端） | 本地直连（python-miio+MQTT） | |--|--|--| | 更新频率 | 2-3 分钟 | **10 秒（可调更短）** | | 数据准确性 | 依赖云端（偶发错误） | **直读设备，准** | | 断网能否工作 | ❌ | ✅ | | 响应延迟 | 分钟级 | **秒级** | | 部署复杂度 | 一键装集成 | 需要写脚本 + broker | --- ## 五、踩坑记录 1. **netifaces 编译失败**：python-miio 依赖 netifaces，在 `python:3-slim` 镜像里没有 gcc 会编译失败。解决：用完整的 `python:3` 镜像，或装 `gcc python3-dev`。 2. **新版 python-miio 的 API 变了**：网上的老教程用 `get_properties_by`，新版改成了 `get_property_by(siid, piid)`，而且 `MiotDevice` 创建时必须传 `mapping={}`（否则报 "Neither the class nor the parameter defines the mapping"）。 3. **`miiocli` 命令找不到**：pip 装完 python-miio 后，`miiocli` 有时不在这个 PATH。直接用 Python API 调用更稳。 4. **MQTT 集成配置方式**：新版 HA 不能在 `configuration.yaml` 里写 `mqtt: broker: ...` 了（会报 invalid option），必须通过「设置 → 集成 → 添加 MQTT」用 UI 配置，或直接写 config_entries。 5. **discovery 的 entity_id 是中文名 slugify**：如果 discovery 里 `name` 写中文，HA 生成的 entity_id 会是拼音（如 `chu_shi_ji_wen_du`），自动化里引用要注意。 6. **设备 MAC 随机化**：现在很多设备开启了 MAC 随机化，没法靠厂商 OUI 识别。用 token 遍历 IP 试连最靠谱。 --- ## 六、总结 本地直连的本质就三件事：**拿到 token → 找到 IP → 用 miio 协议读写**。 适合的场景： - 对数据实时性要求高（自动化、监控） - 米家云数据不稳/不准 - 想完全本地化、断网可控 不适合的场景： - 蓝牙/Zigbee 设备（不是 IP 设备，走不了 miio） - 不想折腾、一键党（直接用官方集成就行） 如果你的核心诉求是"数据又快又准"，这套方案值得搞。**我的除湿机从 2-3 分钟更新一次，变成了 10 秒一次，而且云端报错温度时本地依然准确** —— 这就是本地直连的价值。 --- **参考资料** - [python-miio](https://github.com/rytilahti/python-miio) - [MIoT Spec 查询](https://home.miot-spec.com/) - [HA MQTT Discovery 文档](https://www.home-assistant.io/docs/mqtt/discovery/) - [米家官方 HA 集成](https://github.com/XiaoMi/ha_xiaomi_home)

第一篇 Hugo 博客文章。