sytchi/NarwalIntegration

# Narwal 扫地机器人 — Home Assistant 集成 [](https://github.com/hacs/integration) [](https://github.com/sytchi/NarwalIntegration/releases) [](https://github.com/sytchi/NarwalIntegration/releases) [](https://github.com/sytchi/NarwalIntegration/actions/workflows/validate.yml) [](LICENSE) 一个完全**本地化、不依赖云端**的 [Home Assistant](https://www.home-assistant.io/) Narwal 扫地机器人自定义集成。通过 WebSocket 在本地网络上直接与您的扫地机器人通信——无需云端账户或互联网连接。 这是 [sjmotew/NarwalIntegration](https://github.com/sjmotew/NarwalIntegration) 的积极维护分支，新增了清洁模式、区域清扫、按房间清扫、基站控制、额外传感器、可读的错误状态以及多项固件兼容性修复。请参阅[此分支的新增功能](#what-this-fork-adds)和[更新日志](CHANGELOG.md)。 [](https://my.home-assistant.io/redirect/hacs_repository/?owner=sytchi&repository=NarwalIntegration&category=integration)

## 设备兼容性 此集成使用**本地 WebSocket 连接（端口 9002）**。仅支持开放此端口的型号。 **唯一完全支持且积极维护的型号是 Narwal Flow**——这是我拥有、用于开发并测试每次发布的型号。以下其他型号被标记为*可能正常工作*：它们在此分支之前的原始上游集成中可以正常工作，但我无法重新测试它们，因此此分支的新功能和修复未在这些型号上得到验证。非常欢迎反馈（无论好坏）。 | 型号 | 状态 | 备注 | |-------|--------|-------| | **Narwal Flow** (AX12) | ✅ **完全支持** | 唯一支持且维护的型号。所有功能均在此开发并验证，适用固件版本至 v01.08.03。 | | **Narwal Flow 2** | 🟡 可能正常工作 | 在此分支之前的上游集成中可正常工作；此处未重新测试。房间标签使用 Flow 2 的名称（[upstream #22](https://github.com/sjmotew/NarwalIntegration/issues/22)）。 | | **Freo Z10 Ultra** (CX4) | 🟡 可能正常工作 | 在此分支之前的上游集成中经社区确认；此处未重新测试。 | | **Freo X10 Pro** (AX15) | 🟡 可能正常工作 | 在此分支之前的上游集成中经社区确认；此处未重新测试（[upstream #12](https://github.com/sjmotew/NarwalIntegration/issues/12)）。 | | **Freo Z Ultra** (CX7) | ❌ 不兼容 | 端口 9002 开放但没有本地广播；仅限云端（[upstream #5](https://github.com/sjmotew/NarwalIntegration/issues/5)） | | **Freo X Ultra** (AX18/AX19) | ❌ 不兼容 | 使用 ZeroMQ（端口 6789）+ Tuya 云，非 WebSocket（[upstream #4](https://github.com/sjmotew/NarwalIntegration/issues/4)） | | **Freo X Plus** | ❌ 不兼容 | 仅限云端——无本地 API | | **Narwal J 系列** (J1/J4/J5) | ❌ 不兼容 | J1：仅限 HTTP（端口 8080）；J4/J5：仅限云端（Tuya） | 标记为**不兼容**的型号使用了不同的协议或仅限云端。这是硬件/固件限制。 **其他型号？** 使用 `nmap -p 9002 ` 进行检查。如果端口开放，请[提交一个 issue](https://github.com/sytchi/NarwalIntegration/issues/new/choose) 并附上您的型号和结果。 ## 功能 ### 扫地机器人控制 - **启动 / 停止 / 暂停 / 继续** — 所有命令均已在硬件上验证 - **清洁模式** — 吸尘、拖地、吸尘 + 拖地，或**先吸后拖**（顺序双次清洁） - **房间清扫** — 通过 `narwal.clean_rooms` 服务或地图卡片清扫选定的房间 - **区域清扫** — 在地图卡片上绘制任意矩形，机器人仅清扫这些区域 - **返回基站** / **定位**（机器人播报“机器人在这”） - **风扇速度** — 安静、正常、强力、最大（仅限设置；机器人不播报当前档位） ### 基站控制 - 按钮：**洗拖布**、**烘干拖布**、**倒尘**、**唤醒机器人** - **拖布湿度**选择（干燥 / 正常 / 湿润） - **基站活动**传感器（空闲 / 洗拖布中 / 烘干拖布中 / 倒尘中） ### 传感器 - 电池电量、清扫面积、清扫时间、固件版本 - **清洁进度**（清扫时的百分比），**尘袋健康度** - **错误传感器**具有可读状态 — 48 个已知的 Narwal 故障代码已翻译为 英语 / 法语 / 波兰语，并提供用于自动化的 `code`、`code_hex`、`help_url`、`message` 和 `severity` 属性 - 在基站（二进制传感器），充电状态（充电中 / 已充满 / 未充电） ### 实时地图 (HD) **`camera.*_map_hd`** 实体渲染机器人的地图：默认情况下网格放大 4 倍（在集成选项中可配置为 2–6 倍），房间采用清晰的 NEAREST（最近邻）放大，矢量叠加层经过抗锯齿处理，并提供真实的 **`calibration_points`** 属性供地图卡片使用。 绘制在地图上的图层（每一层均可通过开关实体切换）： - 带有房间标签（用户命名和自动生成）的颜色编码平面图 - 来自机器人存储地图的**家具** — 带半透明填充的旋转轮廓和 防碰撞标签 - **机器人轨迹** — 机器人自身记录的路径（display_map 轨道中线）， 最新的尾部根据实时位置进行重建 - **已清扫区域** — 机器人报告的刚刚吸尘过的 11.4 厘米精确轨迹 （display_map “轨道”之间的条带） - **Lidar 单元** — 机器人在行驶时实际测量到的墙壁/障碍物单元。标记为 地毯的单元在地板上方渲染为浅色调（类似于 Narwal App）；靠近墙壁的单元采用墙壁色调；独立检测物 颜色略深。地毯状态会跨会话保留 - **规划路径** — 显示机器人即将前往位置的细线 - **活动区域覆盖层** — 通过 `narwal.clean_zone` 发送的矩形 - 基站标记和实时机器人位置（约 2 秒刷新一次；在 display_map 数据断连期间，位置会回退到规划轨迹的头部）

   

_{Left: idle floor plan. Middle: early in a clean — trail, vacuumed strip, planned path and lidar wall marks. Right: the same map late into a whole-house run, with every layer accumulated.}

地图图层在清扫过程中会累积，但采用**增量**绘制方式，因此无论清扫时长如何，每帧的渲染成本保持平稳——有关压力测试结果，请参阅[地图渲染性能](docs/performance.md)。 ### 连接性 - 实时 WebSocket 推送更新，带指数退避的自动重连机制 - 唤醒系统（用于休眠中的机器人）+ 保持存活的心跳包 - 60 秒轮询回退机制 ## 此分支的新增功能 以下所有内容均基于上游 v1.0.0 —— 确切的历史记录请参阅 [更新日志](CHANGELOG.md)： | 领域 | 新增内容 | |------|-----------| | 清扫 | 清洁模式选择（包括顺序执行的**先吸后拖**）、`narwal.clean_zone`（带有自动生成覆盖路径的矩形区域）、`narwal.clean_rooms`（按 segment id 的单房间清扫）、遵循所选模式的全屋清扫 —— 以上全部通过 `clean/start_clean` 执行，这是最新固件唯一真正接受参数的命令路径 | | 基站 | 洗拖布 / 烘干拖布 / 倒尘 / 唤醒按钮，拖布湿度选择，基站活动传感器 | | 诊断 | 错误传感器，包含 48 个已翻译为可读状态的故障代码（英语/法语/波兰语），尘袋健康度，清扫进度 | | 地图 | 高分辨率 **Map HD** 摄像头（可配置比例、抗锯齿叠加层、兼容波兰语变音符号的内置字体、用于地图卡片的 `calibration_points`），机器人记录的轨迹 + 刚刚吸过的条带，规划路径线，Lidar 墙壁标记，带有防碰撞标签的旋转且填充的家具，活动区域覆盖层，逐层可见性开关 | | 稳定性 | `narwal.resume` 服务（恢复误报的“机器人被抱起”暂停状态），修复了固件 v01.08.03+ 上正确的在基站/暂停检测，`map_id` 解析修复（vacuum.start 崩溃） | | 本地化 | 完整的波兰语翻译 | ## 安装说明 ### HACS（推荐） [](https://my.home-assistant.io/redirect/hacs_repository/?owner=sytchi&repository=NarwalIntegration&category=integration) 或者手动安装： 1. 打开 **HACS** > 三个点的菜单 > **Custom repositories** 2. 添加：`https://github.com/sytchi/NarwalIntegration`（类型：Integration） 3. 找到 **Narwal Flow Robot Vacuum** 并点击 **Download** 4. **重启 Home Assistant** ### 手动安装 1. 将 `custom_components/narwal/` 复制到您的 HA `config/custom_components/` 目录中 2. **重启 Home Assistant** ### 设置 1. **Settings > Devices & Services > Add Integration** > 搜索 “Narwal” 2. 输入您的扫地机器人 IP 地址并选择您的型号 3. 实体将自动创建 ### 选项 设置完成后，打开集成的 **Configure** 对话框进行调整： | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `map_scale` | 4 | HD 地图摄像头的放大因子（2–6）。数值越高 = 图像越清晰，每次渲染消耗的 CPU 越多。 | ## 实体 | 实体 | 类型 | 备注 | |--------|------|-------| | `vacuum.*` | vacuum | 启动 / 停止 / 暂停 / 返回 / 定位 / 风扇速度 | | `camera.*_map_hd` | camera | 高分辨率实时地图（包含所有图层，`calibration_points`） | | `switch.*_draw_trail`, `*_draw_cleaned_area`, `*_draw_furniture`, `*_draw_lidar_walls` | switch | 地图图层可见性（重启后恢复） | | `select.*_clean_mode` | select | sweep / mop / sweep_mop / sweep_then_mop | | `select.*_mop_humidity` | select | dry / normal / wet | | `button.*_wash_mop`, `*_dry_mop`, `*_empty_dustbin`, `*_wake_robot` | button | 基站命令 | | `sensor.*_battery`, `*_cleaning_area`, `*_cleaning_time`, `*_firmware_version` | sensor | 基础信息 | | `sensor.*_cleaning_progress` | sensor | % — 仅在清扫时显示 | | `sensor.*_dust_bag_health` | sensor | 100 = 健康 | | `sensor.*_station_activity` | sensor | idle / mop_washing / mop_drying / dust_emptying | | `sensor.*_error` | sensor | 可读状态 + `code` / `code_hex` / `help_url` 属性 | | `sensor.*_charging` | sensor | 充电状态 | | `binary_sensor.*_docked` | binary sensor | 位于基站 | ## 服务 ### `narwal.clean_rooms` 在当前选定的清洁模式下清扫特定房间（地图中的 segment id）。机器人必须位于基站。 ``` action: narwal.clean_rooms target: entity_id: vacuum.narwal_flow_vacuum data: rooms: [1, 4] ``` 房间 segment id 与 Narwal App / `vacuum/get_segments` 中的数字相匹配。 ### `narwal.clean_zone` 清扫一个或多个矩形。角点顺序无关紧要。数值为**机器人 世界（地图坐标系）坐标** —— 正是 `xiaomi-vacuum-map-card` 在使用 HD 摄像头的 `calibration_points` 属性作为 `calibration_source: {camera: true}` 时， 生成 `[[selection]]` 所输出的内容（此处出现负值是正常的 — 地图原点并非地图角落）。 ``` action: narwal.clean_zone target: entity_id: vacuum.narwal_flow_vacuum data: zone: [[-21, -23, 29, 29]] fan_speed: normal # optional: quiet / normal / strong / max ``` 任务运行期间，请求的矩形将作为琥珀色覆盖层绘制在 HD 地图上， 因此您可以在仪表板上准确看到要求机器人清扫的 区域：

_{A four-rectangle zone clean of a hallway in progress — amber outlines are the zones sent to the robot, the blue trail and light strips show what it has covered so far. The zones came from the map card's predefined selections, so one tap sends the whole set.}

### `nar.resume` 无条件的 `task/resume` —— 即使在实体状态滞后时（例如， 在门垫上误报“机器人被抱起”的暂停状态），它也会唤醒机器人并继续当前任务。可随时安全调用；当没有任务可继续时， 机器人将拒绝该指令。 ``` action: narwal.resume target: entity_id: vacuum.narwal_flow_vacuum ``` **自动化提示：** 当 `sensor.*_error` 变为 `robot_lifted` 时触发，等待 几秒钟，然后调用 `narwal.resume` —— 这可以自动恢复常见的 “机器人在门垫上卡住”误报。 ## 地图卡片（仪表板上的房间 + 区域） 对于交互式地图，我们推荐使用 Piotr Machowski 的 [`xiaomi-vacuum-map-card`](https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card) （可在 HACS 中获取）。HD 摄像头公开了卡片所需的 **`calibration_points`** 属性；选区以机器人世界坐标到达，并 直接输入到 `narwal.clean_zone` / `narwal.clean_rooms` 中。它还公开了 **`rooms`** 属性，因此卡片的 **“Generate rooms config”** 按钮可以 一键为您构建整个 Rooms 模式（请参阅 [自动生成 Rooms 模式](#generating-the-rooms-mode-automatically)）： ``` type: custom:xiaomi-vacuum-map-card entity: vacuum.narwal_flow_vacuum map_source: camera: camera.narwal_flow_map_hd calibration_source: camera: true map_modes: - name: Rooms icon: mdi:floor-plan selection_type: ROOM service_call_schema: service: narwal.clean_rooms service_data: rooms: "[[selection]]" entity_id: "[[entity_id]]" predefined_selections: - id: "1" icon: {name: "mdi:sofa", x: 50, y: -60} outline: [[10, -10], [90, -10], [90, -90], [10, -90]] # one entry per room; outlines in robot world coordinates - name: Zone icon: mdi:select-drag selection_type: MANUAL_RECTANGLE service_call_schema: service: narwal.clean_zone service_data: zone: "[[selection]]" entity_id: "[[entity_id]]" ``` 注意： - 使用摄像头校准时，卡片会根据您配置的 `map_scale` 自动缩放 —— 无需重新校准。 - 地图图层开关（`switch.*_draw_*`）与卡片视图完美搭配 — 将它们作为磁贴添加到地图下方，以便在需要时清理界面。 ### 自动生成 Rooms 模式 HD 摄像头公开了 **`rooms`** 属性 —— 即以世界坐标表示的单房间 轮廓多边形，根据机器人的地图实时计算得出（即使重新映射也能保留）。这正是卡片的 **“Generate rooms config”** 按钮所期望的格式： 1. 在仪表板编辑器中打开卡片（可视化编辑器）。 2. 确保 `map_source.camera` 指向 `camera.*_map_hd`。 3. 点击 **Generate rooms config** —— 卡片会使用每个房间的轮廓、名称和 标签锚点，为（最后一个）ROOM 类型的地图模式填充 `predefined_selections`。将其与调用 `narwal.clean_rooms`（带 `rooms: "[[selection]]"`）的 `service_call_schema` 配对。 ## 环境要求 - Narwal 扫地机器人与 Home Assistant 处于同一本地网络 - 可访问端口 9002（无防火墙拦截） - Home Assistant 2025.1.0+ / Python 3.12+ ## 已知限制 - **从深度睡眠中唤醒不可靠** — 长时间闲置后， 机器人可能无响应。短暂打开 Narwal App（或使用唤醒按钮）可能会有所帮助。 - **单一连接** — 机器人**一次只能与一个 WebSocket 客户端**通信。 在使用 HA 之前请关闭 Narwal App，以免发生冲突。 - **风扇速度仅限设置** — 机器人不播报当前档位。 - **地图可能是旧的** — 机器人可能会返回旧地图。新的清扫周期 通常会刷新地图。 - **固件差异** — 不同固件版本的命令 payload 结构有所不同；此分支主要在 Narwal Flow v01.08.03 上进行了验证。 ## 故障排除 | 问题 | 解决方案 | |---------|----------| | 设置期间显示“Cannot connect” | 验证 IP 地址并确认端口 9002 可访问。机器人必须处于开机状态。 | | 实体显示“Unavailable” | 机器人可能已休眠。短暂打开 Narwal App（或按下唤醒按钮实体）。 | | 地图未显示 | 机器人唤醒后地图才会加载。新的清扫周期会刷新旧地图。 | | 命令无响应 | 关闭 Narwal App — 同一时间只能建立一个 WebSocket 连接。 | | 机器人在清扫中途暂停并显示“robot lifted”错误 | 调用 `narwal.resume`（见[服务](#services)）。 | | 启动 / 区域 / 房间清扫失败并提示 `NOT_READY (code=4)` | 机器人在电量充够之前不会启动 — 通常在长时间清扫后出现（在 23-26% 电量时拒绝，30% 时接受）。让它充电；正在进行的拖布烘干周期*并不是*阻止启动的原因。 | | Z10 Ultra 断开连接 | 重新添加集成并选择正确的型号。 | ## 报告问题 请使用 [issue 模板](https://github.com/sytchi/NarwalIntegration/issues/new/choose) — 它们会收集您的 HA 版本、型号和调试日志，以便更快地进行诊断。 ## 免责声明 这是一个**非官方的**、由社区开发的集成。它不 隶属于 Narwal（云鲸智能科技有限公司），也未获得其认可或赞助。“Narwal”及相关产品名称均为 其各自所有者的商标，此处使用它们仅用于识别兼容设备。 本地协议是通过逆向工程网络流量和 Narwal 移动应用程序得出的，仅出于互操作性目的。 - **使用风险自负。** 不提供任何担保。 - **无云端依赖。** 不进行任何外部数据传输。 - 来自 Narwal 的**固件更新**可能会随时破坏此集成。 ## 许可证 [MIT](LICENSE) — 原创工作 © 2026 sjmotew，分支贡献 © 2026 sytchi。

标签：HACS, Home Assistant, 扫地机器人集成, 智能家居, 物联网, 逆向工具