hannes813/miele-xkm3000z-reverse-engineering

# 适用于 Home Assistant 的 Miele XKM3000Z 本地 Zigbee Bridge 针对配备 XKM3000Z Zigbee 通信模块的老款 Miele 洗衣机逆向工程实现的本地集成，已在 Miele WPS 820 世代设备上完成测试。 本仓库仅专注于 Miele XKM3000Z 模块、其本地 Zigbee 遥测、部分写入实验、MQTT 发布以及 Home Assistant 发现场景。它刻意不涵盖任何单独的智能家居网关迁移主题。 ## 文档 - [完整协议文档](docs/Miele_XKM3000Z_Protokoll_Dokumentation_final.md) - [Home Assistant 示例](homeassistant/) - [Docker 示例](examples/docker-run.sh) ## 截图 ### 逆向工程环境  ### Home Assistant 仪表板  ### Zigbee 流量  ## 当前状态 工作正常 / 已确认： - 通过兼容 Texas Instruments ZNP 的 Zigbee 适配器进行本地读取。 - 发布 MQTT 并支持 Home Assistant MQTT 发现场景。 - 状态解码：关机、就绪、延时启动、运行中、已完成、故障、已取消、服务测试模式。 - 已知程序 ID 的程序解码。 - 剩余时间与启动延时解码。 - 通过确认将延时启动重置为 0 分钟实现立即启动。 - 通过原始事件 cluster `0x0B02` 获取机门打开/关闭事件。 - 通过 `status_code=8` 和阶段字节 `B0=0x0A` 识别故障/警报。 - 通过 `status_code=8`、`B0=0x0A`、`B1=4` 推测进水故障。 - 包含当前滚筒转速与最大脱水转速的参数块解码。 - 所选程序的“额外水量”(Water Plus) 可用性。 实验性 / 未确认： - 程序选择写入。 - 暂停/取消控制命令。 - Short 选项位。 - 直接温度读取。 - 直接读取 NTC、浮球开关、锁定状态与执行器状态。 - 服务诊断容器 `FD01/0x0020`，当前返回 `0x8F`。 ## 架构 ``` Miele washing machine + XKM3000Z │ Zigbee TI ZNP adapter / TCP serial bridge │ Python bridge │ MQTT Home Assistant MQTT discovery ``` ``` flowchart LR A[Miele Washing Machine] --> B[XKM3000Z] B --> C[SLZB-06
TI ZNP Adapter] C --> D[Python MQTT Bridge] D --> E[MQTT Broker] E --> F[Home Assistant] F --> G[Dashboard] F --> H[Automations] F --> I[Notifications] ``` ## 快速开始 将仓库复制到您的 Zigbee2MQTT/docker 工作文件夹中，或将其挂载到 Python 容器内。 示例： ``` docker run --rm -it --network host \ -v /volume2/docker/zigbee2mqtt:/work \ -e MIELE_ZNP_HOST='192.xxx.xx.xxx' \ -e MIELE_ZNP_PORT='xxxx' \ -e MIELE_TARGET_NWK=0x537D \ -e MQTT_HOST='192.xxx.xx.xxx' \ -e MQTT_USER='your mqtt User' \ -e MQTT_PASS='your-password' \ python:3.12-alpine \ sh -c "apk add --no-cache mosquitto-clients && python /work/src/miele_gateway_mqtt.py" ``` ## 环境变量 | 变量 | 默认值 | 含义 | |---|---:|---| | `MIELE_ZNP_HOST` | `'192.xxx.xx.xxx'` | ZNP 适配器的 TCP 主机 | | `MIELE_ZNP_PORT` | `'xxxx'` | ZNP 适配器的 TCP 端口 | | `MIELE_TARGET_NWK` | `0x537D` | Miele 模块的 Zigbee NWK 地址 | | `MQTT_HOST` | `'192.xxx.xx.xxx'` | MQTT broker 主机 | | `MQTT_USER` | 'User' | MQTT 用户名 | | `MQTT_PASS` | 'Password' | MQTT 密码 | | `MQTT_BASE` | `miele_xkm3000z` | MQTT topic 基础前缀 | | `MIELE_POLL_INTERVAL` | `30` | 轮询间隔（以秒为单位） | | `MIELE_ENABLE_TIME_SYNC` | `true` | 启用 Zigbee Time Cluster 同步 | ## 重要发现 ### 状态码 | 代码 | 含义 | |---:|---| | `1` | 关机 | | `3` | 就绪 | | `4` | 延时启动激活 | | `5` | 运行中 | | `7` | 已完成 | | `8` | 故障/警报 | | `9` | 已取消 | | `12` | 服务测试模式 | ### 程序阶段字节 B0 / `phase_a` | B0 | 含义 | |---:|---| | `1` | 关机 | | `2` | 初始化 / 唤醒 | | `3` | 正常开启 | | `4` | 关机转换 | | `7` | 特殊状态，在服务测试模式下观察到 | | `10 / 0x0A` | 故障 / 警报 | ### 进水故障候选 进水故障不仅仅通过 `phase_b=4` 推断；修正后的规则如下： ``` status_code = 8 phase_a / B0 = 0x0A phase_b / B1 = 4 ``` 这用于识别洗涤/进水场景下的故障/警报。目前尚未通过 Zigbee 观察到特定的 Miele 内部 F 代码。 ### 门事件 原始事件 cluster 为 `0x0B02`。 观察到的值： | Payload 结尾 | 含义 | |---|---| | `... 00 01 00` | 门已关闭 | | `... 00 11 00` | 门已打开 | | `... 02 01 00` | 在另一个运行时/服务上下文中门已关闭 | | `... 02 11 00` | 在另一个运行时/服务上下文中门已打开 | 目前尚未发现单独的锁定/门锁状态。 ### 参数块 参数块包含几个有用的字段： - B5 = 当前滚筒转速，单位为 `rpm / 10`。 - B6/B7 = 最大脱水转速，大端序。 - Water Plus 位 = 当前程序中 Water Plus 的可用性。 - Short 位 = 未确定的候选项；未观察到可靠的状态变化。 ### 时间同步 Bridge 默认保持启用 Zigbee Time Cluster 同步。设备会与 cluster `0x000A` 进行交互；在具有有效时间基准的情况下，预期延时启动行为会更加稳定。可通过以下方式禁用： ``` -e MIELE_ENABLE_TIME_SYNC=false ``` ## 仓库布局 ``` src/miele_gateway_mqtt.py Main MQTT/Home Assistant bridge tools/miele_raw_aps_zcl_monitor.py Passive raw APS/ZCL monitor tools/miele_full_cluster_attribute_scanner.py Read-only scanner for research docs/protocol-notes.md Current protocol notes examples/docker-run.sh Example container start homeassistant/automation_finished.yaml Example finished notification automation ``` ## 安全提示 这是研究型软件。Bridge 包含实验性的写入功能，但生产环境的集成设计主要围绕数据读取以及已确认的启动延时写入。请勿同时针对同一个适配器运行多个扫描器/bridge。 ## 许可证 MIT。详见 `LICENSE`。

标签：Home Assistant, Miele, Zigbee, 云资产清单, 智能家居, 物联网, 请求拦截, 逆向工具, 逆向工程