feat: Flow 2 diagnostics, discovery, and live-state improvements

[StratoGh0st99]

Summary

This PR expands Flow 2 support and improves the integration’s local discovery, diagnostics, and state decoding.

Highlights

• Add new diagnostic entities for:
  • active errors
  • station tank errors
  • clean water tank errors
  • remote control mode
  • user-action-required state
• Add a mop humidity select entity
• Improve config flow discovery via mDNS and DHCP
• Expand model decoding and map rendering for richer live state
• Add capture/probing tools for reverse-engineering and validation
• Improve fan speed handling and add coverage for one-indexed fan levels
• Confirm room-by-room cleaning now works reliably end-to-end

Notes

• Several changes are based on live testing against Flow 2 behavior and Narwal broadcasts.
• This PR is intended to consolidate the fork’s Flow 2 work into upstream.

[StratoGh0st99]

@Anaxagoras-bc I just created a new pr and rebuild my fork.
Room cleaning works and the sensor for the current room also.

[saeft2003]

@StratoGh0st99
How do I start a room cleaning in HA? I have installed the latest version and can also see the current room.

[vpha91]

@StratoGh0st99 Your PR is working quite well, the cleaning activity is more accurate. On a side note, have you figured out what the command for End "dust bag drying/disinfection" is from the app to the robot. Cannot figure out how to stop that process.

[zeanogit]

@StratoGh0st99 How do I start a room cleaning in HA? I have installed the latest version and can also see the current room.

I believe you need to be on Home Assistant 2026.3 at least for the following to work:

Click on "Vacuum" (in Steuerelemente) then at the pop up that opens you should see a button called "Cleaning by area" probably translated to German for you). The first time you click it you should be given the option to assign rooms from the vacuum to the area rooms of your home assistant.
Then going forward you can click the button to clean a specific room. You can then also set up automations etc. to run area specific cleanings if you want.

I tried it once and it initiated fine, I had a weird audio glitch like the vacuum tried to communicate something to me but it cut off and repeated over and over. Lasted for a few seconds then the vacuum cleaned the mop and continued.

[saeft2003]

@zeanogit

Thank you very much for your help. I see that in the pop-up under controls. It looks completely different for you than it does for me. Does version 1.1.13 appear in HA? I did the update but it still shows 1.1.11.

[zeanogit]

@saeft2003 My screenshot is from webview which is probably why it looks different but yeah I also see the old version number, even though I did remember needing to distinctly upgrade to the most recent version once it appeared as an update in HA.

[saeft2003]

@zeanogit

I had to update Home Assistant. However, room cleaning isn't working. Did I do something wrong when assigning the rooms?

[zeanogit]

@saeft2003 silly question but did you try restarting the integration and /or Home Assistant after you assigned the zones?
It seems to send the command to the Vacuum but doesn't tell it what room to clean.

If that doesn't work, you probably need more directed from @StratoGh0st99. Maybe best to open a new issue on his fork repo for it?

[sjmotew]

Thanks for consolidating this work — it's clearly substantial (+3,806 / −313).

To get it merged without a slow back-and-forth, can you split it into separate PRs by feature area? Suggested cuts:

1. mDNS + DHCP discovery (config flow) — orthogonal to everything else, low risk, can ship first
2. Diagnostic entities — active errors, station/clean-water tank errors, remote control mode, user-action-required (relates to Message Watertank #26 water tank request)
3. Mop humidity select + fan speed (1-indexed) handling — relates to Allow configurable clean parameters in _build_room_clean_payload / start_rooms() #23 (configurable clean params)
4. Model decoding + map render improvements — Flow 2 broadcast schema (relates to Bug: Flow 2 room sub-type labels differ from Flow 1 (partial mapping confirmed) #22, start_rooms() crashes Flow 2 — command payload likely incompatible #25)
5. Capture/probe tools under tools/

That lets us ship the safe pieces immediately while we review the larger ones. Diagnostic entities alone would close most of the open Flow 2 feature requests.

If splitting is too much effort I'll review as a monolith, but turnaround will be slower. Also flagging: PR #24 (current_room sensor) and #20 (now merged) touch overlapping areas — wherever there's overlap, the version in master wins to keep history sane.

[saeft2003]

@zeanogit

After restarting Home Assistant, regardless of which room I select in Home Assistant, a cleaning cycle for three rooms is always started. These three rooms are my first shortcut in the Narwal app. Unfortunately, I can't open an issue in the fork; it's not available there.

@StratoGh0st99
Why is this happening?

[sjmotew]

@saeft2003 — I tracked your room-selection report into a separate bug at #37 and shipped a fix on master in 516ed1c. Same firmware-schema root cause as #36 (the whole-house start() regression on Flow v01.07.22+).

start_rooms() now falls back to the v2 room schema when the legacy payload returns NOT_APPLICABLE. Please re-test after pulling master (or wait for the next release) and report back on the issue — full repro steps and what log lines to look for are in #37.

This is orthogonal to the rest of PR #35; my comment about splitting the PR still stands.

[sjmotew]

@StratoGh0st99 — apologies for how long this has sat. Sequencing plan for all the overlapping fork work is now in #66.

Where this PR lands: the room-clean and mop-humidity pieces are superseded by #49 and #50, which trace the root cause to the topic itself (clean/plan/start ignores the payload; clean/start_clean is correct — see #37). That's not a knock on your work, it's three forks arriving at the same place.

But your mDNS/DHCP discovery is not duplicated by anyone, and it's the biggest UX win still outstanding in the repo. #40 has a user who couldn't complete setup at all because the 15s wake timeout expires before the robot answers — discovery plus a longer/adaptive timeout fixes that class of failure outright.

Could you split discovery out as a standalone PR against master? I'll prioritize reviewing it ahead of the rest of the queue. Same for the diagnostic entities in here that survive #52 — happy to look at those separately once the base_status audit lands.

[sjmotew]

Thanks for your patience here — a lot has moved on master since you opened this, and you're owed a straight answer rather than another "please rebase."

Since the merge plan in #66 was posted, the following landed, and each overlaps a chunk of #35:

Landed	Covers
#52 (68b5e0d)	base_status audit + station diagnostics
#67 (029f847)	carpet-map camera, working_status 7 → REMAPPING
#49 (05af870)	room cleaning via clean/start_clean, corrected fan-speed scale
#50, #53, #54	clean-settings entities, last-clean-result, consumable alerts
#61, #62, #63	dock light, map rendering options, live state from working_status

So most of #35's 3,806 lines — the sensors, binary sensors, selects, map renderer, model parsing — now have an equivalent on master, from PRs scoped one concern each. #35 currently conflicts in 27 files, and that isn't something I can resolve maintainer-side without effectively rewriting your branch and guessing at your intent.

What's still uniquely yours, and still wanted: the zeroconf + DHCP discovery. Nothing has landed for it, and it's the biggest outstanding UX win in the tracker — #40 shows setup failing outright on the 15 s wake timeout, which discovery sidesteps entirely.

Could you open a standalone PR against current master with only:

• config_flow.py — async_step_zeroconf / async_step_dhcp plus the discovery host pre-fill
• manifest.json — the zeroconf / dhcp blocks
• strings.json / translations/ — the discovery step strings

One note: tools/ is gitignored in this repo ("RE artifacts, kept locally"), so narwal_capture.py and coverage_probe.py can't land in-tree. If you'd like them public, I'll link them from docs/PROTOCOL.md §12 and credit you there instead — the capture guide in particular is good and I'd rather it were findable.

If you'd rather not do the extraction yourself, say so and I'll cherry-pick the discovery commits with you as author. I'd much rather do that than lose the work.

Leaving #35 open until you've had a chance to reply.

[sjmotew]

@StratoGh0st99 — rather than let this sit waiting on another rebase from you, I've done the extraction I offered: #78, with you as the commit author.

It's the zeroconf + DHCP discovery only, ported onto current master: the manifest declarations, both discovery steps, the host pre-fill, and strings/translations for the discovery card. 12 tests, suite green at 251.

Before merging it I browsed mDNS on my own network against a Flow (AX12), and your identifiers check out exactly:

_app_wss_server_7bb53c._narwal_sweeper._tcp.local.
    server = NARWAL_7bb53c.local.
    addrs  = ['10.0.0.112']   port = 9002

The service type, the instance-name shape, the NARWAL_* hostname pattern — all confirmed rather than taken on trust.

That capture also answered something your implementation had to work around. A configured entry's unique_id is the full device_id read over the WebSocket, which discovery can't see — hence your host check to stop a hand-added robot reappearing as a Discovered card. It turns out the two are linked: this robot's device_id is 71c53f01c14f49088338863e147bb53c and it advertises as NARWAL_7bb53c — the last six hex characters. #78 matches on that suffix instead, which identifies the device rather than the address, and lets a re-discovery at a new IP repoint the existing entry.

Related: the # Update host on the matching entry in case the IP drifted branch rewrote the entry with the same host it had just matched on, so it couldn't do what the comment said. Your intent was right and is now implemented — I'd rather point that out plainly than quietly change it under your name.

Two asks:

1. Review feat(config_flow): discover robots via zeroconf and DHCP (from #35, @StratoGh0st99) #78 — you know this code better than I do, and if I've broken an assumption I'd like to hear it before it merges.
2. If you'd rather carry it yourself, say so and I'll close feat(config_flow): discover robots via zeroconf and DHCP (from #35, @StratoGh0st99) #78 in favour of your branch. The offer to cherry-pick was never meant to take the work away from you.

On the rest of #35: the sensors, binary sensors, selects, map renderer and model parsing all now have equivalents on master from the PRs listed earlier in this thread, so once #78 lands there's nothing left in here that master doesn't have. I'll close #35 then — tell me if you disagree, because you'd know better than the diff does.

The capture tooling still can't land in-tree (tools/ is gitignored), but the offer stands to link and credit narwal_capture.py from docs/PROTOCOL.md §12. It's genuinely good and it should be findable.

[sjmotew]

@StratoGh0st99 — closing this, with the discovery work merged and one piece of it still owed to you.

Merged: the zeroconf + DHCP discovery is on master as of #78 / 16be16e, cherry-picked out of this branch and --author'd to you, so it carries your name in the history. It was field-confirmed by @DeNo64 on #81 — they installed the branch and it found their Flow 2 at the right IP on a network I have no access to.

Why close rather than rebase: this branch's merge base is 33cd23d, which is the #10 era. Master has moved a long way since — the diff reads as 3,800 lines only because it's measured against that ancient base. I checked the specific things that looked unique to this PR and master already has them by other routes: select.py shipped via @Sean-StarLabs' work, tests/test_fan_speed.py came in with the fan-tier rework off #70. Rebasing this would be hours of conflict resolution to arrive at what master already is.

The one genuine exception, and I want to be straight about it rather than claim full coverage: this PR contains tools/narwal_capture.py, tools/coverage_probe.py and tools/CAPTURE_GUIDE.md, and master has no equivalent. They didn't land because tools/ is in this repo's .gitignore (line 42) as a local-only home for reverse-engineering artifacts — a policy decision that predates your PR and has nothing to do with the quality of what you wrote. docs/PROTOCOL.md §12 documents how to capture, but ships no script to do it.

That policy is worth revisiting, and I'd rather revisit it than quietly drop 840 lines of working capture tooling. If you're up for it, say the word and I'll take narwal_capture.py and CAPTURE_GUIDE.md as their own PR under a path that isn't ignored — several open protocol questions on #79 are blocked on people being able to capture easily, and a committed script is exactly what unblocks them. If you'd rather open that PR yourself, better still.

Thank you for the discovery work — it's shipped and it's yours.

[sjmotew]

@StratoGh0st99 — closing out the debt I owed you here. The capture tooling is merged and shipped in v1.0.5, committed under your authorship:

• tools/CAPTURE_GUIDE.md
• tools/narwal_capture.py
• tools/coverage_probe.py

I said nine days ago I'd either land these under a non-ignored path or let you open the PR, and then left it sitting. Landing it was the right call rather than making you do more work for something already written months ago.

What I got wrong originally: when this PR was superseded by #78 I said "nothing else in #35 lacks a master equivalent." That was simply false — these three files had no equivalent anywhere, and the only reason they were never merged is that tools/ was gitignored wholesale as "RE artifacts, kept locally." The ignore was meant for scratch scripts and PNG dumps. It swallowed the one thing in that directory written to be shared. .gitignore now ignores tools/* with explicit exceptions, so this can't quietly happen again.

One change you should know about, because it would have bitten you: the client had stopped emitting the DUMP <topic>: <payload> line both scripts parse out of ha core logs. Landing the tools as-is would have shipped two scripts that run cleanly, exit successfully, and produce nothing. I restored it at DEBUG next to the existing broadcast log, and added two tests that fail if it's removed or promoted above DEBUG — verified by deleting the line and watching them fail, since a test that can't fail wouldn't have caught the original regression either.

I left your 192.168.178.x examples in the guide as-is. They're clearly marked as examples and rewriting someone's working documentation into placeholders is a change without a reason.

Also for the record: #78 shipped as the discovery headline of this release, authored to you, and it was field-validated unprompted by @DeNo64 on a network none of us can reach. Both of your contributions to this project are now in a tagged release.

The tooling matters more than it looks. #79 has four open protocol questions that have gone nowhere for two weeks, entirely because producing a capture was harder than it needed to be. I've pointed that thread at your guide.

Thanks — and sorry it took a second pass to get it in.