mejiasd3v/ha-narwal-cx7

# 适用于 Home Assistant 的 Narwal Cloud CX7 用于 Narwal Freo Z Ultra (CX7) 的实验性 Home Assistant 集成和协议工具。 该集成提供了一个 vacuum 实体和电池传感器。启动、停止、暂停、恢复、回充以及实时状态更新使用 Narwal 的云 MQTT 服务。在一次性私有会话引导之后，access token 和 refresh token 会自动轮换。 ## 状态 - 测试型号：Freo Z Ultra / CX7 - Home Assistant 集成类型：cloud push - 实体：vacuum 和电池传感器 - 控制：启动、停止、暂停、恢复、回充 - 依赖项：运行时仅依赖 Python 标准库 - 本地控制：就目前已知的协议而言，CX7 暂不支持 ## 安装说明 1. 将 `custom_components/narwal_cloud_cx7` 复制到 Home Assistant 的 `/config/custom_components/` 目录中。 2. 使用以下工作流创建一个私有会话。 3. 将其安装为 `/config/.storage/narwal_cloud_cx7_session.json`，并将其限制为仅限 Home Assistant 进程访问： chmod 600 /config/.storage/narwal_cloud_cx7_session.json 4. 重启 Home Assistant。 5. 从 **设置 > 设备与服务** 中添加 **Narwal Cloud CX7**。 会话文件必须保持可写状态，因为该集成会以原子方式持久化已轮换的 token。 ## 私有会话引导 Narwal 并未针对此用例公开凭据或协议文档。因此，引导过程需要抓取您自己的官方 Android App 会话。切勿分享或提交生成的文件。 要求： - Android 模拟器，以及通过合法途径获取的 App 构建版本 - `adb`、`mitmproxy`、`frida` 以及 Python 3.11 或更高版本 - 一个测试账号或您自己的 Narwal 账号 启动基础抓包实验室： ``` ./scripts/start-emulator.sh ./scripts/start-mitm.sh ./scripts/configure-proxy.sh ``` 使用 HTTPDNS 的 App 可能会绕过 Android 代理。解析当前的 Narwal HTTPS 和 MQTT 主机，启动合适的 mitmproxy 反向监听器，并将观察到的目标地址传递给 Frida 抓包助手： ``` ./scripts/frida_capture.py \ --https-target \ --mqtt-target ``` 在官方 App 中完成身份验证并执行所需的控制操作后，导出私有会话： ``` mitmdump -nr artifacts/captures/app.flow \ -s scripts/export_http_session.py --set termlog_verbosity=error mitmdump -nr artifacts/captures/mqtt.flow \ -s scripts/export_tcp_streams.py --set termlog_verbosity=error ./scripts/parse_mqtt.py --broker-host ./scripts/merge_http_session.py ``` 生成的 `artifacts/captures/narwal-session.json` 包含凭据、设备作用域的 topic 以及抓取到的命令 payload。该文件会被 Git 忽略，并且以 `0600` 权限模式写入。 完成后停止抓包： ``` ./scripts/clear-proxy.sh ``` ## 开发说明 ``` python3 -m unittest discover -s tests -v ruff check . python3 -m compileall -q narwal_cloud custom_components scripts ``` 协议发现和已知限制记录在 [`docs/protocol.md`](docs/protocol.md) 中。 ## 安全性 抓取的数据可能包含账号 token、设备 ID、地图、Wi-Fi 元数据和命令 payload。在收集或分享诊断信息之前，请查阅 [`SECURITY.md`](SECURITY.md)。 ## 许可证 MIT

标签：Home Assistant, 云服务对接, 抓包代理, 智能家居, 物联网集成, 逆向工具