Skip to content

Commit a01cb61

Browse files
authored
Merge branch 'main' into codex/p30-pro-status-support
2 parents 397c7c1 + 09c529e commit a01cb61

9 files changed

Lines changed: 252 additions & 33 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,33 @@
22

33
<!-- version list -->
44

5+
## v7.12.4 (2026-10-17)
6+
7+
### Bug Fixes
8+
9+
- Classify in-between water slide positions in cleaning mode
10+
([#961](https://github.com/Python-roborock/python-roborock/pull/961),
11+
[`edc2e49`](https://github.com/Python-roborock/python-roborock/commit/edc2e4980ee0d2c911da1bda168084682065a0fa))
12+
13+
- Preserve water-slide codes in cleaning-mode commands and status
14+
([#961](https://github.com/Python-roborock/python-roborock/pull/961),
15+
[`edc2e49`](https://github.com/Python-roborock/python-roborock/commit/edc2e4980ee0d2c911da1bda168084682065a0fa))
16+
17+
### Documentation
18+
19+
- Document camera live view WebRTC signaling protocol for V1 vacuums
20+
([#980](https://github.com/Python-roborock/python-roborock/pull/980),
21+
[`6a0aab0`](https://github.com/Python-roborock/python-roborock/commit/6a0aab0543d6812c3eafa92571605444ab74cdb3))
22+
23+
- Document water_box_custom_mode values (fixes #225)
24+
([#979](https://github.com/Python-roborock/python-roborock/pull/979),
25+
[`d68fbad`](https://github.com/Python-roborock/python-roborock/commit/d68fbad365e0139b8810edf9daff69995e550ef3))
26+
27+
- Fix end of file in V1_API_COMMANDS.md
28+
([#979](https://github.com/Python-roborock/python-roborock/pull/979),
29+
[`d68fbad`](https://github.com/Python-roborock/python-roborock/commit/d68fbad365e0139b8810edf9daff69995e550ef3))
30+
31+
532
## v7.12.3 (2026-10-12)
633

734
### Bug Fixes

‎docs/V1_API_COMMANDS.md‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1724,15 +1724,17 @@ Example:
17241724

17251725
### get_water_box_custom_mode
17261726

1727-
Description: Get water box mode.
1727+
Description: Get the current water box / flow mode.
17281728

17291729
Parameters: None
17301730

1731-
Returns: Enumeration for water box mode. 203
1731+
Returns: Integer code representing the water box mode (e.g. `200`, `201`, `202`, `203`, `209`). See `set_water_box_custom_mode` below for the full mode enumeration.
17321732

1733-
<!--
1734-
Not clear what this does - require Enumeration
1735-
-->
1733+
**Supported devices:**
1734+
1735+
* Roborock S7 MaxV Ultra: ✅
1736+
* Roborock S8 Pro Ultra: ✅
1737+
* Roborock S8 MaxV Ultra: ✅
17361738

17371739

17381740
### get_clean_follow_ground_material_status
@@ -1747,16 +1749,37 @@ Parameters: None
17471749

17481750
### set_water_box_custom_mode
17491751

1750-
Description: Set the water box mode.
1752+
Description: Set the water box / mopping water flow mode. Setting mode `200` turns off water dispensing completely (used for vacuum-only cleaning). To perform mop-only cleaning without vacuuming, pair water mode with turning off the vacuum fan (`set_custom_mode` to `105` / `VacuumModes.OFF`).
17511753

1752-
Parameters: {'water_box_mode': 203}
1754+
Parameters: Integer mode code inside a list or dictionary, e.g. `[200]` or `{'water_box_mode': 200}`.
17531755

1754-
Returns: ok or error
1756+
CLI Example:
17551757

1756-
<!--
1757-
Not clear what this does - require Enumeration
1758-
-->
1758+
```bash
1759+
roborock -d command --device_id <DeviceID> --cmd set_water_box_custom_mode --params '[200]'
1760+
```
1761+
1762+
**Standard Water Box Modes (`WaterModes`):**
1763+
1764+
| Code | Name | Description |
1765+
| :--- | :--- | :--- |
1766+
| `200` | Off | No water flow (used for vacuum only) |
1767+
| `201` | Low / Mild | Low water flow |
1768+
| `202` | Medium / Standard | Medium water flow |
1769+
| `203` | High / Intense | High water flow |
1770+
| `204` | Customized | Device-customized setting |
1771+
| `205` | Min | Minimum water flow |
1772+
| `206` | Max | Maximum water flow |
1773+
| `207` | Custom | Custom water flow rate |
1774+
| `208` | Extreme | Extreme water flow |
1775+
| `209` | Smart Mode | SmartPlan / AI automated mode |
1776+
1777+
*Note: Devices with water slide support use positions `221`–`250` (`PURE_WATER_FLOW_*`) for granular slider control.*
1778+
1779+
Returns: `ok` or error
17591780

17601781
**Supported devices:**
17611782

1783+
* Roborock S7 MaxV Ultra: ✅
17621784
* Roborock S8 Pro Ultra: ✅
1785+
* Roborock S8 MaxV Ultra: ✅

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "python-roborock"
3-
version = "7.12.3"
3+
version = "7.12.4"
44
description = "A package to control Roborock vacuums."
55
authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
66
requires-python = ">=3.11, <4"

‎roborock/data/v1/v1_clean_modes.py‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -200,16 +200,22 @@ def get_water_modes(features: DeviceFeatures) -> list[WaterModes]:
200200

201201
def get_water_slide_mode_name(code: int) -> str | None:
202202
"""Get the app's range name for a water slide code, or None if out of range."""
203+
mode = _resolve_water_slide_mode(code)
204+
return mode.value if mode is not None else None
205+
206+
207+
def _resolve_water_slide_mode(code: int) -> WaterModes | None:
208+
"""Resolve a raw slider code to the water mode for its app range."""
203209
if code == 200:
204-
return WaterModes.OFF.value
210+
return WaterModes.OFF
205211
if code == WaterModes.SMART_WATER.code:
206-
return WaterModes.SMART_WATER.value
212+
return WaterModes.SMART_WATER
207213
position = code - 220
208214
if position < 1:
209215
return None
210216
for last_position, mode in _WATER_SLIDE_RANGES:
211217
if position <= last_position:
212-
return mode.value
218+
return mode
213219
return None
214220

215221

@@ -303,7 +309,14 @@ def get_cleaning_mode_parameters(cleaning_mode: CleaningMode, features: DeviceFe
303309
raise RoborockUnsupportedFeature(f"Cleaning mode {cleaning_mode.value!r} is not supported")
304310

305311
fan_power, water_box_mode, mop_mode = _get_clean_motor_mode_params(cleaning_mode, features)
306-
params: dict[str, int] = {"fan_power": fan_power.code, "water_box_mode": water_box_mode.code}
312+
water_code = water_box_mode.code
313+
if features.is_water_slide_mode_supported:
314+
# Aliased water enums retain legacy codes; the device mapping preserves
315+
# slide-specific wire values without changing the user-facing names.
316+
water_code = next(
317+
code for code, name in get_water_mode_mapping(features).items() if name == water_box_mode.value
318+
)
319+
params: dict[str, int] = {"fan_power": fan_power.code, "water_box_mode": water_code}
307320
if features.is_clean_route_setting_supported:
308321
params["mop_mode"] = mop_mode.code
309322
return [params]
@@ -340,6 +353,8 @@ def get_current_cleaning_mode(
340353
return None
341354
clean_mode_enum = _resolve_clean_mode(clean_mode, features)
342355
water_mode_enum = _resolve_mode_code(water_mode, WaterModes)
356+
if features.is_water_slide_mode_supported and isinstance(water_mode, int):
357+
water_mode_enum = _resolve_water_slide_mode(water_mode) or water_mode_enum
343358
mop_mode_enum = _resolve_mode_code(mop_mode, CleanRoutes)
344359
if clean_mode_enum is None or water_mode_enum is None:
345360
return None

‎roborock/map/b01_q10_map_parser.py‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -801,8 +801,8 @@ def parse_packet(self, packet: Q10MapPacket) -> ParsedMapData:
801801
"""
802802
return self.parsed_from_packet(packet)
803803

804-
def parsed_from_packet(self, packet: Q10MapPacket) -> ParsedMapData:
805-
"""Render a (possibly erase-modified) packet into a PNG + ``MapData``."""
804+
def map_data_from_packet(self, packet: Q10MapPacket) -> MapData:
805+
"""Build MapData with a rendered base image, without PNG serialization."""
806806
image = self._render(packet)
807807

808808
map_data = MapData()
@@ -830,8 +830,14 @@ def parsed_from_packet(self, packet: Q10MapPacket) -> ParsedMapData:
830830
if packet.carpet_mask is not None:
831831
map_data.carpet_map = {i for i, value in enumerate(packet.carpet_mask) if value}
832832

833+
return map_data
834+
835+
def parsed_from_packet(self, packet: Q10MapPacket) -> ParsedMapData:
836+
"""Render a (possibly erase-modified) packet into a PNG + ``MapData``."""
837+
map_data = self.map_data_from_packet(packet)
833838
image_bytes = io.BytesIO()
834-
image.save(image_bytes, format=_MAP_FILE_FORMAT)
839+
if map_data.image is not None:
840+
map_data.image.data.save(image_bytes, format=_MAP_FILE_FORMAT)
835841
return ParsedMapData(image_content=image_bytes.getvalue(), map_data=map_data)
836842

837843
def _render(self, packet: Q10MapPacket) -> Image.Image:

‎roborock/map/b01_q10_render.py‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -109,10 +109,9 @@ def render_q10_map(
109109
# areas disappear (as the app shows).
110110
render_packet = erased_packet(packet, cells)
111111

112-
parsed = parser.parsed_from_packet(render_packet)
113-
if parsed.image_content is None or parsed.map_data is None:
112+
map_data = parser.map_data_from_packet(render_packet)
113+
if map_data.image is None:
114114
raise RoborockException("Failed to render Q10 map image")
115-
map_data = parsed.map_data
116115

117116
has_drawables = False
118117
if trace_calibration is not None and trace is not None:
@@ -128,7 +127,9 @@ def render_q10_map(
128127
if has_drawables:
129128
return _draw_map_content(map_data, config=config)
130129

131-
return parsed.image_content
130+
buffer = io.BytesIO()
131+
map_data.image.data.save(buffer, format="PNG")
132+
return buffer.getvalue()
132133

133134

134135
def solve_q10_calibration(

‎tests/devices/traits/v1/test_status.py‎

Lines changed: 122 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -434,7 +434,7 @@ def test_current_cleaning_mode_with_main_brush_lift() -> None:
434434
is_water_slide_mode_supported=True,
435435
)
436436
status_trait.fan_power = VacuumModes.OFF.code
437-
status_trait.water_box_mode = WaterModes.PURE_WATER_FLOW_MIDDLE.code
437+
status_trait.water_box_mode = 235
438438
status_trait.mop_mode = CleanRoutes.STANDARD.code
439439

440440
assert status_trait.current_cleaning_mode == CleaningMode.MOP
@@ -551,7 +551,7 @@ def test_get_cleaning_mode_parameters_qrevo_edge_2() -> None:
551551
assert get_cleaning_mode_parameters(CleaningMode.MOP, status_trait._device_features_trait) == [
552552
{
553553
"fan_power": VacuumModes.OFF.code,
554-
"water_box_mode": WaterModes.PURE_WATER_FLOW_MIDDLE.code,
554+
"water_box_mode": 235,
555555
"mop_mode": CleanRoutes.STANDARD.code,
556556
}
557557
]
@@ -600,19 +600,137 @@ def test_get_cleaning_mode_parameters_water_slide_device() -> None:
600600
assert get_cleaning_mode_parameters(CleaningMode.VAC_AND_MOP, status_trait._device_features_trait) == [
601601
{
602602
"fan_power": VacuumModes.BALANCED.code,
603-
"water_box_mode": WaterModes.PURE_WATER_FLOW_MIDDLE.code,
603+
"water_box_mode": 235,
604604
"mop_mode": CleanRoutes.STANDARD.code,
605605
}
606606
]
607607
assert get_cleaning_mode_parameters(CleaningMode.MOP, status_trait._device_features_trait) == [
608608
{
609609
"fan_power": VacuumModes.OFF.code,
610-
"water_box_mode": WaterModes.PURE_WATER_FLOW_MIDDLE.code,
610+
"water_box_mode": 235,
611611
"mop_mode": CleanRoutes.STANDARD.code,
612612
}
613613
]
614614

615615

616+
@pytest.mark.parametrize("water_box_mode", range(221, 251))
617+
@pytest.mark.parametrize(
618+
("fan_power", "expected_mode"),
619+
[(102, CleaningMode.VAC_AND_MOP), (104, CleaningMode.VAC_AND_MOP), (105, CleaningMode.MOP)],
620+
)
621+
def test_current_cleaning_mode_water_slide_codes(
622+
water_box_mode: int, fan_power: int, expected_mode: CleaningMode
623+
) -> None:
624+
"""Classify every raw slider position without changing the reported water code."""
625+
status_trait = _create_cleaning_mode_status_trait(is_water_slide_mode_supported=True)
626+
status_trait.fan_power = fan_power
627+
status_trait.water_box_mode = water_box_mode
628+
status_trait.mop_mode = 303
629+
630+
assert status_trait.current_cleaning_mode == expected_mode
631+
assert status_trait.current_cleaning_mode_name == expected_mode.value
632+
assert status_trait.water_box_mode == water_box_mode
633+
634+
635+
@pytest.mark.parametrize(
636+
("water_box_mode", "expected_mode"),
637+
[
638+
(200, CleaningMode.VACUUM),
639+
(204, CleaningMode.CUSTOM),
640+
(209, CleaningMode.SMART_MODE),
641+
(220, None),
642+
(251, None),
643+
(999, None),
644+
(None, None),
645+
],
646+
)
647+
def test_current_cleaning_mode_water_slide_legacy_codes(
648+
water_box_mode: int | None, expected_mode: CleaningMode | None
649+
) -> None:
650+
"""Keep legacy and unknown status decoding on water-slide devices."""
651+
status_trait = _create_cleaning_mode_status_trait(is_water_slide_mode_supported=True)
652+
status_trait.fan_power = 102
653+
status_trait.water_box_mode = water_box_mode
654+
status_trait.mop_mode = 300
655+
656+
assert status_trait.current_cleaning_mode == expected_mode
657+
assert status_trait.current_cleaning_mode_name == (expected_mode.value if expected_mode is not None else None)
658+
assert status_trait.water_box_mode == water_box_mode
659+
660+
661+
@pytest.mark.parametrize("water_box_mode", [222, 223, 248])
662+
def test_current_cleaning_mode_without_water_slide_support(water_box_mode: int) -> None:
663+
"""Do not interpret slider positions without the water-slide capability."""
664+
status_trait = _create_cleaning_mode_status_trait(is_water_slide_mode_supported=False)
665+
status_trait.fan_power = 102
666+
status_trait.water_box_mode = water_box_mode
667+
status_trait.mop_mode = 300
668+
669+
assert status_trait.current_cleaning_mode is None
670+
assert status_trait.current_cleaning_mode_name is None
671+
assert status_trait.water_box_mode == water_box_mode
672+
673+
674+
@pytest.mark.parametrize("is_water_slide_mode_supported", [False, True])
675+
@pytest.mark.parametrize(
676+
("water_box_mode", "expected_mode"),
677+
[
678+
(200, CleaningMode.VACUUM),
679+
(201, CleaningMode.VAC_AND_MOP),
680+
(202, CleaningMode.VAC_AND_MOP),
681+
(203, CleaningMode.VAC_AND_MOP),
682+
(None, None),
683+
(999, None),
684+
],
685+
)
686+
def test_current_cleaning_mode_water_code_fallback(
687+
is_water_slide_mode_supported: bool, water_box_mode: int | None, expected_mode: CleaningMode | None
688+
) -> None:
689+
"""Preserve legacy water status codes and unknown-code fallback for both device types."""
690+
status_trait = _create_cleaning_mode_status_trait(is_water_slide_mode_supported=is_water_slide_mode_supported)
691+
status_trait.fan_power = 102
692+
status_trait.water_box_mode = water_box_mode
693+
status_trait.mop_mode = 300
694+
695+
assert status_trait.current_cleaning_mode == expected_mode
696+
697+
698+
@pytest.mark.parametrize("water_mode", [WaterModes.MEDIUM, WaterModes.PURE_WATER_FLOW_MIDDLE])
699+
def test_current_cleaning_mode_water_slide_accepts_enums(water_mode: WaterModes) -> None:
700+
"""Enum inputs remain valid even when they alias a legacy water mode."""
701+
status_trait = _create_cleaning_mode_status_trait(is_water_slide_mode_supported=True)
702+
assert (
703+
get_current_cleaning_mode(102, water_mode, 303, status_trait._device_features_trait) == CleaningMode.VAC_AND_MOP
704+
)
705+
706+
707+
@pytest.mark.parametrize("is_clean_route_setting_supported", [False, True])
708+
@pytest.mark.parametrize(
709+
("cleaning_mode", "fan_power", "water_box_mode"),
710+
[("vacuum", 102, 200), ("vac_and_mop", 102, 235), ("mop", 105, 235)],
711+
)
712+
async def test_set_cleaning_mode_water_slide_wire_payload(
713+
mock_rpc_channel: AsyncMock,
714+
is_clean_route_setting_supported: bool,
715+
cleaning_mode: str,
716+
fan_power: int,
717+
water_box_mode: int,
718+
) -> None:
719+
"""Assert the public trait emits valid slide RPC integers, with optional mop route."""
720+
status_trait = _create_cleaning_mode_status_trait(
721+
is_water_slide_mode_supported=True,
722+
is_clean_route_setting_supported=is_clean_route_setting_supported,
723+
)
724+
status_trait._rpc_channel = mock_rpc_channel # type: ignore[assignment]
725+
726+
await status_trait.set_cleaning_mode(cleaning_mode)
727+
728+
expected = {"fan_power": fan_power, "water_box_mode": water_box_mode}
729+
if is_clean_route_setting_supported:
730+
expected["mop_mode"] = 300
731+
mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.SET_CLEAN_MOTOR_MODE, params=[expected])
732+
733+
616734
def test_cleaning_mode_options_water_slide_device() -> None:
617735
"""Water-slide devices should not expose unsupported custom or smart water modes."""
618736
status_trait = _create_cleaning_mode_status_trait(

0 commit comments

Comments
 (0)