[PLAN] Roborock Curv 2 Flow Integration & Matter Surface Probing

[Coldaine]

Project Goal: Roborock Curv 2 Flow Support Expansion

This issue tracks the phased execution plan for probing and documenting the Roborock Curv 2 Flow (Qrevo Curv) API surface, both via the standard Cloud/Local protocol and the new Matter surface.

---

Phase 1: Roborock Cloud/Local API Surface (python-roborock)

Step 1 — Install the CLI and authenticate

pipx install python-roborock
roborock login   # OAuth with your Roborock account
roborock list-devices  # dumps device ID, model string, IP, token

This immediately tells you your vacuum's internal model ID (something like roborock.vacuum.a??), which you can cross-reference against the python-roborock supported model list.

Step 2 — Enumerate what the device responds to

The CLI has a raw command interface. Blast the documented command list at your device and note which ones return data vs. errors:

# Get current status
roborock get-prop --device-id <id> get_status

# Try all property getters in a loop
for cmd in get_status get_prop get_consumable get_summary get_clean_record get_room_mapping; do
  echo "=== $cmd ===" && roborock send-command --device-id <id> $cmd
done

Commands that return {"error": ...} or no data are your unsupported surface.

Step 3 — Enable HA debug logging and trigger actions

Once HA is connected (even if partial), go to Settings → System → Logs → Enable Debug for the roborock integration and python_roborock library. Then:

1. Call roborock.get_maps from Developer Tools → Actions — this dumps room segment IDs and names.
2. Trigger a run via the UI and watch the debug log to see what properties are polled and what payloads come back.
3. Download the Diagnostics file from the device page (Settings → Devices → your vacuum → Download Diagnostics) — this is a JSON dump of every entity HA was able to populate.

The diagnostics file is your ground truth for what's actually working vs. showing as unavailable.

---

Phase 2: Matter Surface Probe

Step 1 — Commission via chip-tool

Install chip-tool on your Linux home lab machine and commission the Curv 2 Flow to a local Matter fabric:

# Install via snap (easiest on Linux)
sudo snap install chip-tool

# Commission with your device's setup code (shown in the Roborock app)
chip-tool pairing code <node-id> <setup-code>

Step 2 — Read the device descriptor to discover supported clusters

This is the most important step — it dumps the full cluster manifest:

# Read descriptor cluster to list all supported clusters/endpoints
chip-tool descriptor read device-type-list <node-id> 0xFFFF
chip-tool descriptor read server-list <node-id> 1

For a robot vacuum, Matter defines the RVC (Robotic Vacuum Cleaner) device type (0x0075) with these candidate clusters:

• RVCRunMode — cleaning modes (Eco, Turbo, etc.)
• RVCCleanMode — vacuum vs. mop vs. hybrid
• OperationalState — start/stop/pause/dock
• ServiceArea — room/zone targeting (Matter 1.4+)

Step 3 — Read and probe each cluster

# Check operational state
chip-tool operationalstate read current-state <node-id> 1

# List available run modes
chip-tool rvcrunmode read supported-modes <node-id> 1

# List available clean modes
chip-tool rvccleanmode read supported-modes <node-id> 1

# Check if ServiceArea (room targeting) is implemented
chip-tool servicearea read supported-areas <node-id> 1

Anything that returns actual data is part of your live Matter surface. Anything that returns UNSUPPORTED_ATTRIBUTE or UNSUPPORTED_CLUSTER is not implemented by Roborock's firmware yet.

---

Phase 3: Document and Contribute Back

Once you have your findings — especially the model ID, which commands return valid data, and what the Diagnostics JSON looks like — you're in a position to open a GitHub issue or PR on python-roborock. The maintainer explicitly said for the Qrevo Curv line that they rely entirely on user-provided data since they don't have the hardware themselves. Your diagnostic dump could directly unblock support for your model for everyone.

[Coldaine]

🔍 Codebase Analysis & Blind Spots — March 1, 2026

Auth succeeded (uv run roborock login). Now documenting everything found from the full codebase and upstream PR review before moving forward.

---

What We Know For Certain

Architecture

• The library uses 4 distinct protocols: V1 (most vacuums), A01 (Dyad/Zeo), B01-Q7, B01-Q10 — assigned by the pv field in home data
• The Qrevo Curv (and likely Curv 2 Flow) will be V1 protocol (pv: "1.0")
• Feature detection uses three stacked encoding schemes embedded in featureSet/newFeatureSet hex strings returned by the API

Original Qrevo Curv (roborock.vacuum.a135) — Fully Implemented

• Has dedicated QRevoCurvStatus with RoborockFanSpeedQRevoCurv, RoborockMopIntensityQRevoCurv, RoborockMopModeQRevoCurv
• Dock type qrevo_curv_dock = 17 is in WASH_N_FILL_DOCK_TYPES ✅
• Product group VIVIAN → PEARL_PLUS_FEATURES (RGB camera, spin mop, remote back, max_plus mode)

Qrevo Curv 2 Flow — NOT YET IN THE CODEBASE

The VIVIAN product group (RoborockProductNickname.VIVIAN) reserves short models (a134, a135, a155, a156). Slots a155 and a156 exist in the group but had no constants, no ModelStatus entries before our fixes today.

---

Fixes Applied Today

Fix	File	Status
saros_10_dock missing from WASH_N_FILL_DOCK_TYPES (confirmed bug — Saros 10 has wash+fill dock)	device_features.py	✅ Fixed
MOP_ROLLER_MODULE added to ProductFeatures enum	device_features.py	✅ Added
MOP_ROLLER_MODULE added to is_support_water_mode, is_clean_route_setting_supported, is_customized_clean_supported metadata	device_features.py	✅ Updated
Constants added for a155, a156 (unconfirmed Curv 2 variants), a158, a159 (VivianC)	const.py	✅ Added
ModelStatus entries added for all 4 new models (using QRevoCurvStatus as best-guess fallback)	data/v1/v1_containers.py	✅ Added
All 368 tests pass after changes	—	✅ Green

---

🚦 Blind Spots — What We MUST Confirm Before Final Implementation

1. Model ID (BLOCKER)

We do not yet know if the Curv 2 Flow is a155, a156, or an entirely new ID.

uv run roborock list-devices

The model field output (e.g. roborock.vacuum.a155) resolves this immediately. Until then, ROBOROCK_QREVO_CURV_A155/A156 are provisional placeholders.

2. Dock Type (HIGH PRIORITY)

The original Curv uses qrevo_curv_dock = 17. The Curv 2 Flow has a new dock with roller-mop cleaning hardware (SpiraFlow). It may use:

• The same dock type 17 (unlikely given different hardware)
• A new dock type not yet in the enum
• Or dock type 17 intentionally (Roborock sometimes reuses dock codes)

If it's a new dock type, it won't be in WASH_N_FILL_DOCK_TYPES and mop-wash HA entities won't appear. The HA Diagnostics file will reveal the dock_type integer.

3. featureSet / newFeatureSet Hex Strings (HIGH PRIORITY)

The 100+ boolean DeviceFeatures fields (camera type, AI recognition, Matter support, mop features, etc.) are decoded from these hex strings. Without the actual values from your device, we're guessing.

The HA Diagnostics JSON contains these. Example from Saros 10R:

"newFeatureSet": "0005075028ED3EDDCFFF8F7F7EFEFFFF"

4. New Mop Mode / Intensity Codes for Roller Mop

The SpiraFlow roller mop is architecturally different from the original Curv's vibrarise spin-mop. It may have:

• Different mop_mode codes (e.g., new "roller speed" options)
• Different water_box_mode codes (roller vs. drip delivery)

Currently QRevoCurvStatus reuses the original Curv's enums. This may work or may produce wrong labels/missing modes.

5. Matter Support Flag

is_matter_supported is determined by NewFeatureStrBit.MATTER = 67 in the newFeatureSet hex string. Only the device's own hex string will tell us if the Curv 2 Flow supports Matter natively.

---

Upstream HA PR #163373 — Dock Controls (Relevant to Our Device)

This open draft PR on home-assistant/core adds:

• button.dock_empty (APP_START_COLLECT_DUST)
• button.dock_wash_mop (APP_START_WASH)
• button.dock_stop_drying (APP_STOP_WASH)
• select.mop_wash_mode (SET_WASH_TOWEL_MODE)

All 4 commands already exist in python-roborock. Key open issues on the PR:

• stop_drying naming — may be wrong; APP_STOP_WASH could stop the wash cycle, not drying
• EntityCategory.CONFIG missing from dock buttons
• entity_registry_enabled_default=False not set (entities will be noisy)
• Zeo entity snapshot regressions (unrelated but blocking)

This PR matters for us because the Curv 2 Flow's wash dock is new and may expose these commands differently. Once we have device data, we can confirm and potentially help unblock the PR.

---

Immediate Next Steps

1. Run uv run roborock list-devices and paste the output here → gives model ID, IP, dock type
2. Download HA Diagnostics JSON from Settings → Devices → your vacuum → Download Diagnostics → paste the featureSet, newFeatureSet, dockType fields
3. Run the command probe loop from Phase 1 Step 2 to see which commands respond
4. With model ID confirmed, rename ROBOROCK_QREVO_CURV_A155/A156 to the real name and create device-specific fan/mop enums if codes differ from original Curv