Skip to content

feat: add V1 feature flag bits needed to gate dock and cleaning options - #1054

Open
infy1995 wants to merge 5 commits into
Python-roborock:mainfrom
infy1995:feat/v1-new-feature-bits-from-app
Open

infy1995 wants to merge 5 commits into
Python-roborock:mainfrom
infy1995:feat/v1-new-feature-bits-from-app

Conversation

@infy1995

@infy1995 infy1995 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Depends on #1046 because it uses the BerylLite and CoralProSAw nicknames that #1046 adds. Until #1046 is merged, this diff also contains its commits. Only the commits after them are new here.

Summary

Adds firmware capability flags that DeviceFeatures did not expose yet. Later dock and cleaning mode PRs need them to offer options only on robots that support them.

  • 41 new NewFeatureStrBit members: bit 6 and bits 121-169. Their names are the flag names used in the Roborock app plugins, without a trailing Supported (SmartWaterSupported becomes SMART_WATER). Each has a DeviceFeatures field named is_<bit name>_supported, the same pattern as the existing bits.
  • robotFeatures ids 111 (is_fds_endpoint_supported), 112 (is_auto_split_segments_supported), 114 (is_order_segment_clean_supported) and 116 (is_map_segment_supported).

No existing bit, id or field changes meaning. The bit numbers were compared with all 24 Roborock app V1 plugins; none of them disagrees with another plugin or with the library.

Model rules

Three fields combine the firmware flag with another signal, so a consumer can use the field directly:

  • is_map_segment_supported is true for every model except RubySC and RubyPlus. Those two older models support map segments only when they report feature id 116. It is also true when the model is unknown.
  • is_support_wash_phase_pumping_supported is also true for BerylLite and CoralProSAw, which support the pumping wash phase without bit 148.
  • is_smart_water_supported needs both bit 166 and the roller-mop bit (128), because smart mop water is a roller-mop option.

Some flags only apply together with conditions the library cannot check, so those fields report the firmware signal alone. Comments in the code and docs/V1_DEVICE_FEATURES.md say so:

  • the account region for zone replenish cleaning (bits 132 and 154)
  • the Shell4S or Shell4SA dock for mop changing (bit 129). is_change_mop_supported tells whether the robot can change mops. Changing them also needs one of those docks, so a consumer that shows a mop-change control should check the dock too.
  • AES encryption support for backup and restore (bit 151)

The photo-upload mask in robotNewFeatures (65536) is left out. It only applies to three older models in the China app, and the library cannot check the app region.

Cache

DeviceFeatures.from_dict returns None when a cached entry is missing any bool field. So after upgrading, cached features are discovered again from the device once. This is the existing behavior for new fields.

Tests

  • A table-driven test sets each new bit by itself and checks that it turns on only its own field. Smart water gets the roller-mop bit too. A second test sets all of them together.
  • Tests for the new robotFeatures ids, the map segment rule, the BerylLite and CoralProSAw rule, and smart water with and without the roller-mop bit.
  • Snapshot updates add the new keys. For devices with known models, is_map_segment_supported is true.
  • docs/V1_DEVICE_FEATURES.md has entries for the new fields. It also adds the is_roller_mop_supported entry, which was missing.

Related issues

Part of #738

Add the 41 new_feature_str bits, robotFeatures 111/112/114/116 and robotNewFeatures 65536 that the newest app plugins read, with the app's extra rules for map segments, wash phase pumping and smart mop water.
@infy1995 infy1995 changed the title feat: add V1 feature flag bits from the Roborock app feat: add V1 feature flag bits needed to gate dock and cleaning options Nov 17, 2026
@Lash-L Lash-L added Data model changes Changes to data models, device info, or feature mappings Feature New feature V1 V1 platform labels Nov 18, 2026

@Lash-L Lash-L left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated code review by Gemini 4 Hydrogen in Antigravity using our /review (/code-review) skill (.agents/skills/code-review/SKILL.md / AGENTS.md).

Scope & Stacking

This PR is stacked on #1046 (0a153bee, b2b0258f, ccf43c0f). This review covers only PR #1054's own commit 7c5fd01e.

Summary by Architectural Layer

  • Layer 1 (Public Trait APIs & Capability Model — roborock/device_features.py, docs/V1_DEVICE_FEATURES.md):
    • All 41 new NewFeatureStrBit indices (6, 121–169), robotFeatures IDs (111, 112, 114, 116), robotNewFeatures mask (65536), and the model rules for RubySC/RubyPlus (is_map_segment_supported) and BerylLite/CoralProSAw (is_support_wash_phase_pumping_supported) match the Roborock app.
    • 1 issue found: is_smart_water_supported uses |= kwargs["is_roller_mop_supported"] in DeviceFeatures.from_feature_flags, whereas the app's isSmartMopWaterSupported requires both bit 166 (SmartWaterSupported) and isSupportRollerMop (&&, not ||).
  • Layer 2 & 3 (State, Cache & Feature Decoding):
    • DeviceFeatures.from_dict continues to reject stale cached entries missing new boolean fields, triggering clean re-discovery.
  • Tests & Snapshots (tests/test_supported_features.py, tests/**/__snapshots__/*.ambr):
    • Targeted tests (test_supported_features.py, test_device_manager.py, test_file_cache.py, test_v1_device.py, tests/conformance/ — 664 passed, 53 xfailed, 99 snapshots passed), ruff check, and mypy all pass on 7c5fd01e. Snapshot updates consistently add only the new keys (with tests/test_supported_features.py asserting the |= behavior on is_smart_water_supported, which should be updated alongside the fix).

Comment thread roborock/device_features.py Outdated
kwargs["is_map_segment_supported"] |= product_nickname in _MAP_SEGMENT_MODELS
kwargs["is_support_wash_phase_pumping_supported"] |= product_nickname in _WASH_PHASE_PUMPING_MODELS
# The app offers smart mop water for roller mops even without the smart-water bit.
kwargs["is_smart_water_supported"] |= kwargs["is_roller_mop_supported"]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Layer 1 — Capability Gating (is_smart_water_supported uses OR instead of AND with roller mop)

In the app, isSmartMopWaterSupported requires both NewFeatureStrBit 166 (SmartWaterSupported) and isSupportRollerMop (bit 128), i.e. logical &&, not ||. Using |= here enables is_smart_water_supported for any roller-mop device even when bit 166 is unset.

Suggested fix: Either remove |= so is_smart_water_supported reports bit 166 directly (like is_change_mop_supported for bit 129) and note in the field comment and docs/V1_DEVICE_FEATURES.md that consumers should also check is_roller_mop_supported, or gate it with &=:

# Option A: report bit 166 directly (keeps single-bit tests passing; document that app also requires is_roller_mop_supported)
# (remove lines 849-850)

# Option B: match app's isSmartMopWaterSupported directly (update test_new_feature_str_bits_from_app & test_mop_support_from_roller_mop_bit)
kwargs["is_smart_water_supported"] &= kwargs["is_roller_mop_supported"]

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, you are right. Smart mop water needs both bit 166 and the roller-mop bit. Fixed in f75284d with &=, and there is a test for all four combinations of bits 128 and 166.

While checking this against the app plugin I found two more rules that were wrong, and the same commit fixes them:

  • is_map_segment_supported had the logic inverted. Map segments are supported on every model except RubySC and RubyPlus, which need robotFeatures 116.
  • is_photo_upload_supported is removed. The 65536 mask only applies to three older models in the China app, and the library cannot check the app region.

The PR description is updated to match.

@Lash-L Lash-L added the /review run Code review skill (/review) has been run label Nov 18, 2026
Smart mop water needs both bit 166 and the roller-mop bit. Map segments are supported on every model except RubySC and RubyPlus, which need robotFeatures 116. The photo-upload mask only applies to three older models in the China app, so it is removed.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Data model changes Changes to data models, device info, or feature mappings Feature New feature /review run Code review skill (/review) has been run V1 V1 platform

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants