Skip to content

feat(cleaning): add room-specific cleaning settings - #87

Merged
sjmotew merged 5 commits into
sjmotew:masterfrom
Sean-StarLabs:sean/narwal-room-settings-20260822
Sep 5, 2026
Merged

feat(cleaning): add room-specific cleaning settings#87
sjmotew merged 5 commits into
sjmotew:masterfrom
Sean-StarLabs:sean/narwal-room-settings-20260822

Conversation

@Sean-StarLabs

@Sean-StarLabs Sean-StarLabs commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Summary

  • add route-aware global and per-room Narwal clean profiles
  • preserve independent room modes in mixed whole-map and selected-room jobs using Narwal custom-clean task type 6
  • expose work mode, suction, water, mop strength, route, passes, and integration-owned room selection entities
  • make native vacuum.start clean selected rooms, falling back to all known rooms and their individual profiles
  • add explicit narwal.clean_rooms and vacuum.clean_segments command surfaces that do not depend on UI selection
  • decode custom-clean status 17 so live room and progress telemetry remain available
  • persist raw global/room settings and explicit room selections independently of entity availability and display labels
  • keep pending setup controls editable while the robot is unreachable and gate live controls by the accepted room profile

Why

Room cleaning needs a complete CleanParam payload, not just a room id. Narwal uses task type 6 for custom jobs containing different per-room modes; uniform jobs retain their normal work-mode task type. This preserves each room's configured behavior instead of flattening a mixed floor into one global mode. Untouched room fields follow the global profile until the user explicitly configures them.

Structured restore data stores protocol enum values rather than visible labels. That keeps unavailable startup states and later presentation-only label changes from altering the cleaning behavior that Home Assistant restores.

Commit layout

  1. encode per-room settings in the client protocol
  2. model global, room, selected-room, and active profiles in the coordinator
  3. add explicit room-cleaning services
  4. expose and restore cleaning-profile entities
  5. apply selected/all-room profiles through native vacuum starts

Runtime validation

On Flow 2 hardware running v01.09.09.05, native vacuum.start accepted one seven-room task containing five vacuum-only rooms and two vacuum-and-mop rooms. The robot reported task type 6 and retained each room's requested mode, suction, route, and two-pass setting. Home Assistant reported the active room and progress, including after a restart during the job.

A separate restart while every room profile and selection entity was unavailable retained the explicit Bathroom profile and the one-room selection through structured restore data; all values returned unchanged after the robot was stopped and docked.

Stack

#85 and #86 are already merged. This branch contains the five room-settings commits ending at a00e31c.

@sjmotew

sjmotew commented Sep 1, 2026

Copy link
Copy Markdown
Owner

One question before this and #88/#89 can land, and it may be good news.

These three PRs cite runtime validation on a Freo X Ultra. Our own compatibility table says that model can't talk to this integration at all:

| Freo X Ultra (AX18/AX19) | Not Compatible | Uses ZeroMQ (port 6789) + Tuya cloud, not WebSocket (#4) |

const.py agrees — LnugwMG9ss (AX18) and 5OMbqk58Sc (AX19) are both filed under "confirmed cloud-only, no WebSocket", from @ManivannanBA's testing in #4.

One of those two things is wrong, and I'd like to know which:

What product key and firmware does your X Ultra report? The setup log line is Topic prefix from broadcast: /<key>, and nmap -p 9002 <robot-ip> answers the other half.

Three possible outcomes, and two of them are interesting:

  1. It reports LnugwMG9ss/5OMbqk58Sc and 9002 is open — then our "Not Compatible" verdict is wrong, and that's a significant finding. Freo X Ultra #4 and [Feature]: Narwal Freo Z Ultra support #5 have people waiting on exactly this. It would be the headline of the next release, credited to you.
  2. It reports some other key — then your robot is a locally-capable model marketed as X Ultra in your region, and the PR bodies just need the name corrected. Narwal's naming is genuinely a mess; we already have AX26 sold as both "Z10 Turbo" and "Z10 Pro" on identical firmware, and CX7 carrying the cloud identity J5.
  3. Something else, in which case I'd like to understand it.

I'm not asking to be difficult. I cited your runtime evidence approvingly in earlier reviews, and I shouldn't have leaned on it that hard without reconciling it against our own compatibility data first — that's my error. But I can't merge changes whose stated validation contradicts the table we tell users to trust, and if outcome 1 is what's happening then that table needs fixing today.

#86 is unaffected — it cites Flow 2 hardware, which is squarely supported. I have no other objections to it and it can go whenever you're ready.

@Sean-StarLabs
Sean-StarLabs force-pushed the sean/narwal-room-settings-20260822 branch 3 times, most recently from 170f403 to 874fa93 Compare September 1, 2026 12:21
@Sean-StarLabs
Sean-StarLabs force-pushed the sean/narwal-room-settings-20260822 branch 15 times, most recently from c7705e8 to a842cb6 Compare September 5, 2026 10:16
Model Narwal room-clean parameters and task state in the client, and encode explicit room selections with their individual cleaning profiles. Keep the vendored client copy synchronized with the standalone package.
@Sean-StarLabs
Sean-StarLabs force-pushed the sean/narwal-room-settings-20260822 branch from a842cb6 to 8a751f7 Compare September 5, 2026 10:30
Track whole-floor and per-room cleaning profiles in coordinator data, retain user selections across updates, and expose task context needed by Home Assistant entities.
Register Home Assistant services for whole-floor and selected-room cleaning, validate their parameters, and route them through the coordinator's cleaning profile contract.
Expose whole-floor and per-room route, suction, water, mop, and cycle controls. Persist raw protocol values so unavailable startup states and future display-label changes do not alter the selected cleaning behavior.
@Sean-StarLabs
Sean-StarLabs force-pushed the sean/narwal-room-settings-20260822 branch 2 times, most recently from 34f59ee to db66495 Compare September 5, 2026 11:59
Make vacuum start honor selected rooms and their profiles while preserving native whole-floor behavior when no rooms are selected.
@Sean-StarLabs
Sean-StarLabs force-pushed the sean/narwal-room-settings-20260822 branch from db66495 to cb78d7c Compare September 5, 2026 12:10
@sjmotew
sjmotew merged commit 4a05395 into sjmotew:master Sep 5, 2026
3 checks passed
sjmotew added a commit that referenced this pull request Sep 5, 2026
Per-room cleaning profiles (#87), state-aware vacuum features and
attributes (#88), native map trails (#89, closes #75), app-matching
suction labels (#91), dock task switches (#86), product-prefix
preservation (#85), diagnostics dump, product-key aliases (#81) and the
bare get_map ack fix (#93).

Two breaking changes, documented first in the notes: the current_room
sensor moves onto the vacuum entity, and the suction tiers are renamed
to the Narwal app's labels with the old names still accepted.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VLhr2iHzsVosRX5w2eD6e1
sjmotew added a commit that referenced this pull request Sep 5, 2026
… registry

Per-room profiles (#87) put 168 entities on a 24-room install. This emits
Lovelace YAML that shows one room at a time behind an input_select, a
Whole-house panel for the global defaults, a script that cleans a single
room with its own profile, and a dock-tasks grid. Driven by the registry
because entity_ids are minted from room names at first registration and
never change, while unique_ids carry the stable map/room key.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VLhr2iHzsVosRX5w2eD6e1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants