botslab360 0.4.2__tar.gz → 0.5.0__tar.gz

{botslab360-0.4.2/src/botslab360.egg-info → botslab360-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: botslab360
-Version: 0.4.2
+Version: 0.5.0
 Summary: Async Python client for Botslab/360 robot vacuums
 License-Expression: MIT
 Project-URL: Source, https://github.com/placix/python-botslab360
@@ -26,7 +26,7 @@ This project provides an unofficial Python interface for selected 360 robot vacu
 
 > [!WARNING]
 > This project is unofficial and not affiliated with Botslab, Qihoo 360 or 360 Smart Home.
-> Version `0.4.1` should be considered experimental.
+> This project should be considered experimental.
 
 ## Features
 
@@ -39,6 +39,7 @@ Currently implemented:
 - Automatic Smart Home SID refresh
 - Device discovery
 - Robot status retrieval
+- Robot station network-information retrieval
 - TCP / push protocol communication
 - AES decryption of push messages
 - Current room discovery from the robot map
@@ -217,13 +218,12 @@ map coordinate system (integer millimetres, original point order). Missing or
 malformed polygons are exposed as `None`; raw MapInfo data is not exposed.
 
 The Android room-attribute UI defines one or two cleaning passes, four suction
-modes, three mopping water levels, and three cleaning modes. Optional settings
-can override the current attributes for selected rooms in one cleaning request:
+modes, and three mopping water levels. Optional settings can override these
+verified attributes for selected rooms in one cleaning request:
 
 ```python
 from botslab360 import (
     RoomCleaningSettings,
-    RoomCleaningMode,
     RoomFanMode,
     RoomWaterLevel,
 )
@@ -233,7 +233,6 @@ await client.clean_rooms(
     [1],
     room_settings={
         1: RoomCleaningSettings(
-            mode=RoomCleaningMode.SWEEP,
             clean_times=2,
             fan_mode=RoomFanMode.STRONG,
             water_pump=RoomWaterLevel.MEDIUM,
@@ -250,11 +249,17 @@ Water levels are `1` (low), `2` (medium), and `3` (high). An existing vendor
 `waterPump=0` value is preserved when not overridden, but `0` is not exposed as
 an "off" choice because that meaning has not been confirmed.
 
-Cleaning modes are `1` (sweep and mop), `2` (sweep), and `3` (mop). Mode `2`
-has been verified on a real robot; the assignments for modes `1` and `3` remain
-provisional pending real-device verification. `Room.mode` preserves unknown
-integer values reported by future vendor firmware, while outgoing overrides are
-limited to the currently supported values.
+`Room.mode` preserves the optional raw `SweepArea.mode` vendor string. Analysis
+of the Android app found carpet-related values such as `mode_big_carpet` and
+`mode_tiny_carpet`; this field is not a verified room sweep/mop selector. The
+deprecated `RoomCleaningMode` compatibility enum and
+`RoomCleaningSettings.mode` field must not be used for new code. Setting
+`RoomCleaningSettings.mode` is rejected rather than writing an unverified value
+to a cleaning request.
+
+The Android app also has a separate `SweepStrategy.cleanMode` field with partial
+evidence for mop and sweep values, but its relationship to room-cleaning
+requests has not yet been verified.
 
 ## Status information
 
@@ -283,6 +288,23 @@ Cleaning time: 157
 Error code: 0
 ```
 
+## Network information
+
+The robot can report its current station network identity through the public
+API. Missing vendor fields are returned as `None`, and MAC addresses are
+normalized to lowercase colon-separated form.
+
+```python
+network_info = await client.get_network_info(robot)
+
+print(network_info.station_ip)
+print(network_info.station_mac)
+print(network_info.station_signal)
+```
+
+Treat SSIDs as potentially sensitive when displaying or logging
+`network_info.station_ssid`.
+
 ## Session handling
 
 The library distinguishes between the Qihoo account session and the Smart Home session.

{botslab360-0.4.2 → botslab360-0.5.0}/README.md

@@ -6,7 +6,7 @@ This project provides an unofficial Python interface for selected 360 robot vacu
 
 > [!WARNING]
 > This project is unofficial and not affiliated with Botslab, Qihoo 360 or 360 Smart Home.
-> Version `0.4.1` should be considered experimental.
+> This project should be considered experimental.
 
 ## Features
 
@@ -19,6 +19,7 @@ Currently implemented:
 - Automatic Smart Home SID refresh
 - Device discovery
 - Robot status retrieval
+- Robot station network-information retrieval
 - TCP / push protocol communication
 - AES decryption of push messages
 - Current room discovery from the robot map
@@ -197,13 +198,12 @@ map coordinate system (integer millimetres, original point order). Missing or
 malformed polygons are exposed as `None`; raw MapInfo data is not exposed.
 
 The Android room-attribute UI defines one or two cleaning passes, four suction
-modes, three mopping water levels, and three cleaning modes. Optional settings
-can override the current attributes for selected rooms in one cleaning request:
+modes, and three mopping water levels. Optional settings can override these
+verified attributes for selected rooms in one cleaning request:
 
 ```python
 from botslab360 import (
     RoomCleaningSettings,
-    RoomCleaningMode,
     RoomFanMode,
     RoomWaterLevel,
 )
@@ -213,7 +213,6 @@ await client.clean_rooms(
     [1],
     room_settings={
         1: RoomCleaningSettings(
-            mode=RoomCleaningMode.SWEEP,
             clean_times=2,
             fan_mode=RoomFanMode.STRONG,
             water_pump=RoomWaterLevel.MEDIUM,
@@ -230,11 +229,17 @@ Water levels are `1` (low), `2` (medium), and `3` (high). An existing vendor
 `waterPump=0` value is preserved when not overridden, but `0` is not exposed as
 an "off" choice because that meaning has not been confirmed.
 
-Cleaning modes are `1` (sweep and mop), `2` (sweep), and `3` (mop). Mode `2`
-has been verified on a real robot; the assignments for modes `1` and `3` remain
-provisional pending real-device verification. `Room.mode` preserves unknown
-integer values reported by future vendor firmware, while outgoing overrides are
-limited to the currently supported values.
+`Room.mode` preserves the optional raw `SweepArea.mode` vendor string. Analysis
+of the Android app found carpet-related values such as `mode_big_carpet` and
+`mode_tiny_carpet`; this field is not a verified room sweep/mop selector. The
+deprecated `RoomCleaningMode` compatibility enum and
+`RoomCleaningSettings.mode` field must not be used for new code. Setting
+`RoomCleaningSettings.mode` is rejected rather than writing an unverified value
+to a cleaning request.
+
+The Android app also has a separate `SweepStrategy.cleanMode` field with partial
+evidence for mop and sweep values, but its relationship to room-cleaning
+requests has not yet been verified.
 
 ## Status information
 
@@ -263,6 +268,23 @@ Cleaning time: 157
 Error code: 0
 ```
 
+## Network information
+
+The robot can report its current station network identity through the public
+API. Missing vendor fields are returned as `None`, and MAC addresses are
+normalized to lowercase colon-separated form.
+
+```python
+network_info = await client.get_network_info(robot)
+
+print(network_info.station_ip)
+print(network_info.station_mac)
+print(network_info.station_signal)
+```
+
+Treat SSIDs as potentially sensitive when displaying or logging
+`network_info.station_ssid`.
+
 ## Session handling
 
 The library distinguishes between the Qihoo account session and the Smart Home session.

{botslab360-0.4.2 → botslab360-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "botslab360"
-version = "0.4.2"
+version = "0.5.0"
 description = "Async Python client for Botslab/360 robot vacuums"
 readme = "README.md"
 requires-python = ">=3.10"

{botslab360-0.4.2 → botslab360-0.5.0}/src/botslab360/__init__.py

@@ -16,6 +16,7 @@ from .models import (
     CaptchaChallenge,
     Device,
     DeviceIdentity,
+    NetworkInfo,
     QihooCredentials,
     RobotStatus,
     Room,
@@ -39,6 +40,7 @@ __all__ = [
     "Device",
     "DeviceIdentity",
     "InvalidSessionError",
+    "NetworkInfo",
     "QihooCredentials",
     "QucAuthenticationError",
     "RobotStatus",

{botslab360-0.4.2 → botslab360-0.5.0}/src/botslab360/client.py

@@ -29,6 +29,7 @@ from .models import (
     CaptchaChallenge,
     Device,
     DeviceIdentity,
+    NetworkInfo,
     QihooCredentials,
     RobotStatus,
     Room,
@@ -45,6 +46,7 @@ from .protocol import (
     DEFAULT_PUSH_HEARTBEAT_TIMEOUT,
     DEFAULT_PUSH_HOST,
     DEFAULT_PUSH_PORT,
+    NETWORK_INFO_TYPE,
     STATUS_INFO_TYPE,
     PushClient,
 )
@@ -560,6 +562,60 @@ class Botslab360Client:
         )
         return list(room_map.rooms)
 
+    async def get_network_info(
+        self,
+        device: Device | str,
+        *,
+        timeout: float = 30.0,
+    ) -> NetworkInfo:
+        """Return station network information reported by one robot."""
+
+        device_id = _device_id(device)
+        task_id = str(uuid4())
+        return await self._with_session_refresh(
+            lambda: self._get_network_info_once(
+                device_id=device_id,
+                task_id=task_id,
+                timeout=timeout,
+            )
+        )
+
+    async def _get_network_info_once(
+        self,
+        *,
+        device_id: str,
+        task_id: str,
+        timeout: float,
+    ) -> NetworkInfo:
+        if self._session is None:
+            raise AuthenticationError(
+                "Authentication is required before requesting network info",
+                phase="authentication",
+            )
+
+        push = PushClient(
+            self._session.sid,
+            self._session.push_key,
+            host=self._push_host,
+            port=self._push_port,
+            client_version=self._push_client_version,
+            heartbeat_timeout=self._push_heartbeat_timeout,
+            heartbeat_interval=self._push_heartbeat_interval,
+        )
+        async with push:
+            await self._post_robot_request(
+                device_id=device_id,
+                info_type=NETWORK_INFO_TYPE,
+                data="",
+                task_id=task_id,
+                operation="network info request",
+            )
+            return await push.wait_for_network_info(
+                device_id=device_id,
+                task_id=task_id,
+                timeout=timeout,
+            )
+
     async def clean_rooms(
         self,
         device: Device | str,

{botslab360-0.4.2 → botslab360-0.5.0}/src/botslab360/models.py

@@ -100,6 +100,21 @@ class Device:
     online: bool
 
 
+@dataclass(frozen=True, slots=True)
+class NetworkInfo:
+    """Station network information reported by a Botslab/360 robot."""
+
+    station_ip: str | None
+    station_mac: str | None
+    station_ssid: str | None
+    station_signal: int | None
+    ap_id: str | None = None
+    ap_ip: str | None = None
+    compile_version: int | None = None
+    mcu_version: str | None = None
+    rssi: int | None = None
+
+
 @dataclass(frozen=True, slots=True)
 class Room:
     """A room from the robot's current smart-area map."""
@@ -111,7 +126,7 @@ class Room:
     fan_mode: str | None
     water_pump: int | None
     vertices: tuple[tuple[int, int], ...] | None = None
-    mode: int | None = None
+    mode: str | None = None
 
 
 class RoomFanMode(str, Enum):
@@ -132,7 +147,11 @@ class RoomWaterLevel(IntEnum):
 
 
 class RoomCleaningMode(IntEnum):
-    """Cleaning modes supported by the Android room-attribute UI."""
+    """Deprecated unverified numeric cleaning-mode values.
+
+    Retained for import compatibility with 0.4.2. These values must not be
+    written to the vendor ``SweepArea.mode`` field.
+    """
 
     SWEEP_AND_MOP = 1
     SWEEP = 2
@@ -144,7 +163,11 @@ ROOM_CLEAN_TIMES = (1, 2)
 
 @dataclass(frozen=True, slots=True)
 class RoomCleaningSettings:
-    """Optional cleaning attributes for one room."""
+    """Optional cleaning attributes for one room.
+
+    ``mode`` is retained for 0.4.2 API compatibility but is unsupported and
+    rejected when set because the vendor request field was misidentified.
+    """
 
     clean_times: int | None = None
     fan_mode: str | None = None

{botslab360-0.4.2 → botslab360-0.5.0}/src/botslab360/protocol.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import ipaddress
 import json
+import re
 import time
 from contextlib import suppress
 from dataclasses import dataclass
@@ -15,7 +17,7 @@ from cryptography.hazmat.primitives import padding
 from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 
 from .exceptions import ApiError
-from .models import RobotStatus
+from .models import NetworkInfo, RobotStatus
 
 DEFAULT_PUSH_HOST = "47.254.151.104"
 DEFAULT_PUSH_PORT = 443
@@ -28,10 +30,13 @@ ANDROID_360_PUSH_HEARTBEAT_TIMEOUT = 20
 ANDROID_360_PUSH_HEARTBEAT_INTERVAL = 15.0
 PUSH_PRODUCT = "60009"
 STATUS_INFO_TYPE = "20001"
+NETWORK_INFO_TYPE = "21019"
+COMMAND_RESPONSE_EVENT = "10"
 PUSH_PROTOCOL_VERSION = 5
 PUSH_BIND_ACK_OPCODE = 6
 PUSH_MESSAGE_OPCODE = 3
 PUSH_READY_TIMEOUT = 15.0
+_MAC_PATTERN = re.compile(r"(?:[0-9a-fA-F]{2}[:-]){5}[0-9a-fA-F]{2}|[0-9a-fA-F]{12}")
 
 
 def _protocol_error(message: str, *, phase: str = "protocol") -> ApiError:
@@ -120,6 +125,81 @@ def _optional_int(value: object, *, field: str) -> int | None:
     return value
 
 
+def _optional_text(value: object, *, field: str) -> str | None:
+    if value in (None, ""):
+        return None
+    if not isinstance(value, str):
+        raise _protocol_error(f"Network info field {field} is invalid")
+    return value
+
+
+def _optional_ip(value: object, *, field: str) -> str | None:
+    text = _optional_text(value, field=field)
+    if text is None:
+        return None
+    try:
+        return str(ipaddress.ip_address(text))
+    except ValueError as exc:
+        raise _protocol_error(f"Network info field {field} is invalid") from exc
+
+
+def _optional_mac(value: object, *, field: str) -> str | None:
+    text = _optional_text(value, field=field)
+    if text is None:
+        return None
+    if _MAC_PATTERN.fullmatch(text) is None:
+        raise _protocol_error(f"Network info field {field} is invalid")
+    compact = text.replace(":", "").replace("-", "").lower()
+    return ":".join(compact[index : index + 2] for index in range(0, 12, 2))
+
+
+def _optional_network_int(value: object, *, field: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise _protocol_error(f"Network info field {field} is invalid")
+    return value
+
+
+def parse_network_info_event(
+    event: object,
+    *,
+    device_id: str,
+    task_id: str,
+) -> NetworkInfo | None:
+    """Return network info only for a matching command response."""
+
+    if not isinstance(event, dict):
+        raise _protocol_error("Push event is invalid")
+    if event.get("sn") != device_id or event.get("taskid") != task_id:
+        return None
+    if str(event.get("event")) != COMMAND_RESPONSE_EVENT:
+        return None
+
+    protocol = _json_object(event.get("data"), field="protocol")
+    if str(protocol.get("infoType")) != NETWORK_INFO_TYPE:
+        return None
+    payload = _json_object(protocol.get("data"), field="network info data")
+
+    return NetworkInfo(
+        station_ip=_optional_ip(payload.get("staIp"), field="staIp"),
+        station_mac=_optional_mac(payload.get("staMac"), field="staMac"),
+        station_ssid=_optional_text(payload.get("staId"), field="staId"),
+        station_signal=_optional_network_int(
+            payload.get("staSignal"),
+            field="staSignal",
+        ),
+        ap_id=_optional_text(payload.get("apId"), field="apId"),
+        ap_ip=_optional_ip(payload.get("apIp"), field="apIp"),
+        compile_version=_optional_network_int(
+            payload.get("compileVer"),
+            field="compileVer",
+        ),
+        mcu_version=_optional_text(payload.get("mcuVer"), field="mcuVer"),
+        rssi=_optional_network_int(payload.get("rssi"), field="rssi"),
+    )
+
+
 def parse_status_event(
     event: object,
     *,
@@ -619,6 +699,45 @@ class PushClient:
                 phase="timeout",
             ) from exc
 
+    async def wait_for_network_info(
+        self,
+        *,
+        device_id: str,
+        task_id: str,
+        timeout: float,
+    ) -> NetworkInfo:
+        """Wait for one matching network-info command response."""
+
+        try:
+            return await asyncio.wait_for(
+                self._wait_for_network_info(device_id=device_id, task_id=task_id),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError as exc:
+            raise _protocol_error(
+                "Timed out waiting for robot network info",
+                phase="timeout",
+            ) from exc
+
+    async def _wait_for_network_info(
+        self,
+        *,
+        device_id: str,
+        task_id: str,
+    ) -> NetworkInfo:
+        if self._reader is None or self._writer is None:
+            raise _protocol_error("Push client is not connected", phase="transport")
+
+        while True:
+            event = await self.read_event()
+            network_info = parse_network_info_event(
+                event,
+                device_id=device_id,
+                task_id=task_id,
+            )
+            if network_info is not None:
+                return network_info
+
     async def _wait_for_status(
         self,
         *,

{botslab360-0.4.2 → botslab360-0.5.0}/src/botslab360/rooms.py

@@ -18,7 +18,6 @@ from .exceptions import ApiError
 from .models import (
     ROOM_CLEAN_TIMES,
     Room,
-    RoomCleaningMode,
     RoomCleaningSettings,
     RoomFanMode,
     RoomWaterLevel,
@@ -74,7 +73,6 @@ class RoomMap:
 
 _ROOM_FAN_MODE_VALUES = frozenset(mode.value for mode in RoomFanMode)
 _ROOM_WATER_LEVEL_VALUES = frozenset(level.value for level in RoomWaterLevel)
-_ROOM_CLEANING_MODE_VALUES = frozenset(mode.value for mode in RoomCleaningMode)
 
 
 def validate_room_cleaning_settings(settings: object) -> RoomCleaningSettings:
@@ -104,8 +102,10 @@ def validate_room_cleaning_settings(settings: object) -> RoomCleaningSettings:
     if settings.mode is not None:
         if isinstance(settings.mode, bool) or not isinstance(settings.mode, int):
             raise TypeError("mode must be an integer")
-        if settings.mode not in _ROOM_CLEANING_MODE_VALUES:
-            raise ValueError("mode must be 1, 2, or 3")
+        raise ValueError(
+            "mode overrides are unsupported because SweepArea.mode is not a "
+            "verified cleaning-mode field"
+        )
     return settings
 
 
@@ -280,7 +280,7 @@ def parse_room_map(map_info: object) -> RoomMap:
                 fan_mode=_optional_str(area.get("windMode")),
                 water_pump=_optional_int(area.get("waterPump")),
                 vertices=_room_vertices(area.get("vertexs")),
-                mode=_optional_int(area.get("mode")),
+                mode=_optional_str(area.get("mode")),
             )
         )
     return RoomMap(
@@ -307,8 +307,6 @@ def _apply_room_settings(
             area["windMode"] = settings.fan_mode
         if settings.water_pump is not None:
             area["waterPump"] = settings.water_pump
-        if settings.mode is not None:
-            area["mode"] = settings.mode
 
 
 def prepare_area_setting(

{botslab360-0.4.2 → botslab360-0.5.0/src/botslab360.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: botslab360
-Version: 0.4.2
+Version: 0.5.0
 Summary: Async Python client for Botslab/360 robot vacuums
 License-Expression: MIT
 Project-URL: Source, https://github.com/placix/python-botslab360
@@ -26,7 +26,7 @@ This project provides an unofficial Python interface for selected 360 robot vacu
 
 > [!WARNING]
 > This project is unofficial and not affiliated with Botslab, Qihoo 360 or 360 Smart Home.
-> Version `0.4.1` should be considered experimental.
+> This project should be considered experimental.
 
 ## Features
 
@@ -39,6 +39,7 @@ Currently implemented:
 - Automatic Smart Home SID refresh
 - Device discovery
 - Robot status retrieval
+- Robot station network-information retrieval
 - TCP / push protocol communication
 - AES decryption of push messages
 - Current room discovery from the robot map
@@ -217,13 +218,12 @@ map coordinate system (integer millimetres, original point order). Missing or
 malformed polygons are exposed as `None`; raw MapInfo data is not exposed.
 
 The Android room-attribute UI defines one or two cleaning passes, four suction
-modes, three mopping water levels, and three cleaning modes. Optional settings
-can override the current attributes for selected rooms in one cleaning request:
+modes, and three mopping water levels. Optional settings can override these
+verified attributes for selected rooms in one cleaning request:
 
 ```python
 from botslab360 import (
     RoomCleaningSettings,
-    RoomCleaningMode,
     RoomFanMode,
     RoomWaterLevel,
 )
@@ -233,7 +233,6 @@ await client.clean_rooms(
     [1],
     room_settings={
         1: RoomCleaningSettings(
-            mode=RoomCleaningMode.SWEEP,
             clean_times=2,
             fan_mode=RoomFanMode.STRONG,
             water_pump=RoomWaterLevel.MEDIUM,
@@ -250,11 +249,17 @@ Water levels are `1` (low), `2` (medium), and `3` (high). An existing vendor
 `waterPump=0` value is preserved when not overridden, but `0` is not exposed as
 an "off" choice because that meaning has not been confirmed.
 
-Cleaning modes are `1` (sweep and mop), `2` (sweep), and `3` (mop). Mode `2`
-has been verified on a real robot; the assignments for modes `1` and `3` remain
-provisional pending real-device verification. `Room.mode` preserves unknown
-integer values reported by future vendor firmware, while outgoing overrides are
-limited to the currently supported values.
+`Room.mode` preserves the optional raw `SweepArea.mode` vendor string. Analysis
+of the Android app found carpet-related values such as `mode_big_carpet` and
+`mode_tiny_carpet`; this field is not a verified room sweep/mop selector. The
+deprecated `RoomCleaningMode` compatibility enum and
+`RoomCleaningSettings.mode` field must not be used for new code. Setting
+`RoomCleaningSettings.mode` is rejected rather than writing an unverified value
+to a cleaning request.
+
+The Android app also has a separate `SweepStrategy.cleanMode` field with partial
+evidence for mop and sweep values, but its relationship to room-cleaning
+requests has not yet been verified.
 
 ## Status information
 
@@ -283,6 +288,23 @@ Cleaning time: 157
 Error code: 0
 ```
 
+## Network information
+
+The robot can report its current station network identity through the public
+API. Missing vendor fields are returned as `None`, and MAC addresses are
+normalized to lowercase colon-separated form.
+
+```python
+network_info = await client.get_network_info(robot)
+
+print(network_info.station_ip)
+print(network_info.station_mac)
+print(network_info.station_signal)
+```
+
+Treat SSIDs as potentially sensitive when displaying or logging
+`network_info.station_ssid`.
+
 ## Session handling
 
 The library distinguishes between the Qihoo account session and the Smart Home session.

{botslab360-0.4.2 → botslab360-0.5.0}/src/botslab360.egg-info/SOURCES.txt

@@ -22,6 +22,8 @@ tests/test_commands.py
 tests/test_compare_android_quc.py
 tests/test_credentials_auth_example.py
 tests/test_devices.py
+tests/test_network_info.py
+tests/test_network_info_diagnostic.py
 tests/test_protocol.py
 tests/test_public_robot360_auth_diagnostic.py
 tests/test_public_room_api_diagnostic.py

botslab360-0.5.0/tests/test_network_info.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from urllib.parse import parse_qs
+from uuid import UUID
+
+import httpx
+import pytest
+
+import botslab360.client as client_module
+from botslab360 import ApiError, Botslab360Client, NetworkInfo
+from botslab360.protocol import parse_network_info_event
+
+QID = "1234567890"
+Q = f"u=360H{QID}&n=synthetic&m=not-a-real-token"
+T = "s=synthetic-session&t=1700000000&v=2.0"
+SID = "synthetic-smart-sid"
+PUSH_KEY = "synthetic-push-key"
+
+
+def _event(
+    payload: object,
+    *,
+    device_id: str = "synthetic-device",
+    task_id: str = "synthetic-task",
+    info_type: str = "21019",
+    event: int = 10,
+) -> dict[str, object]:
+    return {
+        "event": event,
+        "sn": device_id,
+        "taskid": task_id,
+        "data": json.dumps({"infoType": info_type, "data": payload}),
+    }
+
+
+def test_parse_network_info_response_and_normalize_mac() -> None:
+    result = parse_network_info_event(
+        _event(
+            json.dumps(
+                {
+                    "staIp": "192.168.1.176",
+                    "staMac": "B0-59-47-C1-2E-C1",
+                    "staId": "Private SSID",
+                    "staSignal": -51,
+                    "apId": "robot-ap",
+                    "apIp": "192.168.10.1",
+                    "compileVer": 123,
+                    "mcuVer": "456",
+                    "rssi": -52,
+                }
+            )
+        ),
+        device_id="synthetic-device",
+        task_id="synthetic-task",
+    )
+
+    assert result == NetworkInfo(
+        station_ip="192.168.1.176",
+        station_mac="b0:59:47:c1:2e:c1",
+        station_ssid="Private SSID",
+        station_signal=-51,
+        ap_id="robot-ap",
+        ap_ip="192.168.10.1",
+        compile_version=123,
+        mcu_version="456",
+        rssi=-52,
+    )
+
+
+def test_parse_network_info_allows_missing_optional_fields() -> None:
+    assert parse_network_info_event(
+        _event({}),
+        device_id="synthetic-device",
+        task_id="synthetic-task",
+    ) == NetworkInfo(None, None, None, None)
+
+
+@pytest.mark.parametrize(
+    ("field", "value"),
+    [
+        ("staIp", "not-an-ip"),
+        ("staMac", "not-a-mac"),
+        ("staId", 123),
+        ("staSignal", "strong"),
+        ("compileVer", True),
+    ],
+)
+def test_parse_network_info_rejects_malformed_optional_values(field, value) -> None:
+    with pytest.raises(ApiError) as raised:
+        parse_network_info_event(
+            _event({field: value}),
+            device_id="synthetic-device",
+            task_id="synthetic-task",
+        )
+
+    assert raised.value.phase == "protocol"
+
+
+def test_parse_network_info_requires_matching_correlation() -> None:
+    payload = {"staIp": "192.168.1.176"}
+    assert (
+        parse_network_info_event(
+            _event(payload, task_id="other"),
+            device_id="synthetic-device",
+            task_id="synthetic-task",
+        )
+        is None
+    )
+    assert (
+        parse_network_info_event(
+            _event(payload, info_type="20001"),
+            device_id="synthetic-device",
+            task_id="synthetic-task",
+        )
+        is None
+    )
+    assert (
+        parse_network_info_event(
+            _event(payload, event=4),
+            device_id="synthetic-device",
+            task_id="synthetic-task",
+        )
+        is None
+    )
+
+
+def test_get_network_info_posts_21019_and_waits_for_push(monkeypatch) -> None:
+    async def scenario() -> None:
+        events: list[str] = []
+        expected = NetworkInfo(
+            "192.168.1.176",
+            "b0:59:47:c1:2e:c1",
+            None,
+            -50,
+        )
+
+        class FakePushClient:
+            def __init__(self, sid, push_key, **kwargs):
+                assert sid == SID
+                assert push_key == PUSH_KEY
+
+            async def __aenter__(self):
+                events.append("push-connected")
+                return self
+
+            async def __aexit__(self, *args):
+                events.append("push-closed")
+
+            async def wait_for_network_info(self, *, device_id, task_id, timeout):
+                assert events == ["push-connected", "http-requested"]
+                assert device_id == "synthetic-device"
+                UUID(task_id)
+                assert timeout == 7.5
+                return expected
+
+        monkeypatch.setattr(client_module, "PushClient", FakePushClient)
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            if request.url.path == "/common/user/login":
+                return httpx.Response(
+                    200,
+                    json={"errno": 0, "data": {"sid": SID, "pushKey": PUSH_KEY}},
+                )
+            events.append("http-requested")
+            form = parse_qs((await request.aread()).decode(), keep_blank_values=True)
+            assert request.url.path == "/clean/cmd/send"
+            assert form["infoType"] == ["21019"]
+            assert form["data"] == [""]
+            assert form["sn"] == ["synthetic-device"]
+            UUID(form["taskid"][0])
+            return httpx.Response(200, json={"errno": 0})
+
+        async with httpx.AsyncClient(
+            transport=httpx.MockTransport(handler)
+        ) as http_client:
+            client = Botslab360Client(Q, T, http_client=http_client)
+            await client.authenticate()
+            result = await client.get_network_info(
+                "synthetic-device",
+                timeout=7.5,
+            )
+
+        assert result == expected
+        assert events == ["push-connected", "http-requested", "push-closed"]
+
+    asyncio.run(scenario())
+
+
+def test_wait_for_network_info_timeout_is_api_error() -> None:
+    async def scenario() -> None:
+        from botslab360.protocol import PushClient
+
+        class FakePush(PushClient):
+            def __init__(self) -> None:
+                self._reader = object()
+                self._writer = object()
+
+            async def read_event(self):
+                await asyncio.Future()
+
+        with pytest.raises(ApiError) as raised:
+            await FakePush().wait_for_network_info(
+                device_id="synthetic-device",
+                task_id="synthetic-task",
+                timeout=0.001,
+            )
+
+        assert raised.value.phase == "timeout"
+
+    asyncio.run(scenario())

botslab360-0.5.0/tests/test_network_info_diagnostic.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import ast
+import asyncio
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+from botslab360 import AuthBackend, Device, DeviceIdentity, NetworkInfo
+
+IDENTITY = DeviceIdentity(
+    mid="0123456789abcdef0123456789abcdef",
+    android_id="0123456789abcdef",
+    m2="12345678-1234-5678-9234-567812345678",
+)
+DEVICE = Device("synthetic-device", "Upstairs", "360 S9-P", True)
+
+
+def _script_path() -> Path:
+    return Path(__file__).parents[1] / "diagnostics" / "test_network_info.py"
+
+
+def _load_diagnostic() -> ModuleType:
+    spec = importlib.util.spec_from_file_location(
+        "network_info_diagnostic",
+        _script_path(),
+    )
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_script_uses_only_public_botslab360_api() -> None:
+    tree = ast.parse(_script_path().read_text(encoding="utf-8"))
+    botslab_imports = [
+        node
+        for node in ast.walk(tree)
+        if isinstance(node, ast.ImportFrom)
+        and node.module is not None
+        and node.module.startswith("botslab360")
+    ]
+
+    assert len(botslab_imports) == 1
+    assert botslab_imports[0].module == "botslab360"
+    assert {alias.name for alias in botslab_imports[0].names} == {
+        "ApiError",
+        "AuthBackend",
+        "Botslab360Client",
+        "CaptchaRequired",
+        "Device",
+        "DeviceIdentity",
+        "NetworkInfo",
+    }
+
+
+def test_live_flow_uses_public_api_and_redacts_sensitive_values(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    module = _load_diagnostic()
+    calls: list[object] = []
+
+    class FakeClient:
+        @classmethod
+        def from_credentials(cls, **kwargs):
+            calls.append(("factory", kwargs))
+            return cls()
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            pass
+
+        async def authenticate(self):
+            calls.append("authenticate")
+
+        async def get_devices(self):
+            calls.append("get_devices")
+            return [Device("other", "Other", "X90", True), DEVICE]
+
+        async def get_network_info(self, device, *, timeout):
+            calls.append(("get_network_info", device, timeout))
+            return NetworkInfo(
+                station_ip="192.168.4.20",
+                station_mac="aa:bb:cc:dd:ee:ff",
+                station_ssid="Private Home",
+                station_signal=-48,
+            )
+
+    monkeypatch.setattr(module, "Botslab360Client", FakeClient)
+
+    result = asyncio.run(
+        module.run_network_info_test(
+            "private-account",
+            "private-password",
+            IDENTITY,
+        )
+    )
+
+    assert result == 0
+    assert calls == [
+        (
+            "factory",
+            {
+                "email": "private-account",
+                "password": "private-password",
+                "backend": AuthBackend.ROBOT360,
+                "device_identity": IDENTITY,
+            },
+        ),
+        "authenticate",
+        "get_devices",
+        ("get_network_info", DEVICE, 30.0),
+    ]
+    output = capsys.readouterr().out
+    assert "Device: 360 S9-P" in output
+    assert "Station IP: 192.168.4.20" in output
+    assert "Station MAC: aa:bb:cc:dd:ee:ff" in output
+    assert "OUI: aa:bb:cc" in output
+    assert "SSID: present (redacted)" in output
+    assert "NETWORK INFO DIAGNOSTIC STATUS: PASS" in output
+    for secret in (
+        "private-account",
+        "private-password",
+        "Private Home",
+    ):
+        assert secret not in output

{botslab360-0.4.2 → botslab360-0.5.0}/tests/test_public_room_api_diagnostic.py

@@ -24,7 +24,17 @@ IDENTITY = DeviceIdentity(
     m2="12345678-1234-5678-9234-567812345678",
 )
 DEVICE = Device("synthetic-device", "Synthetic Robot", "test", True)
-ROOMS = [Room(1, "Bad", "bathroom", 1, "max", 2)]
+ROOMS = [
+    Room(
+        1,
+        "Bad",
+        "bathroom",
+        clean_times=2,
+        fan_mode="max",
+        water_pump=1,
+        mode="mode_tiny_carpet",
+    )
+]
 
 
 def _script_path() -> Path:
@@ -133,6 +143,11 @@ def test_public_room_flow_uses_only_public_operations(
     ]
     output = capsys.readouterr().out
     assert "Public get_rooms(): success" in output
+    assert (
+        "ID / Name / room_type / vendor_mode / clean_times / fan_mode / water_pump"
+        in output
+    )
+    assert "1 / Bad / bathroom / mode_tiny_carpet / 2 / max / 1" in output
     assert "Public clean_rooms([1]): success" in output
     assert "PUBLIC ROOM API LIVE STATUS: PASS" in output
     for secret in (
@@ -145,6 +160,67 @@ def test_public_room_flow_uses_only_public_operations(
         assert secret not in output
 
 
+def test_rooms_only_prints_profiles_without_cleaning(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    module = _load_diagnostic()
+    calls: list[object] = []
+
+    class FakeClient:
+        session = SimpleNamespace()
+
+        @classmethod
+        def from_credentials(cls, **kwargs: object) -> FakeClient:
+            return cls()
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args: object):
+            pass
+
+        async def authenticate(self):
+            calls.append("authenticate")
+
+        async def get_devices(self):
+            calls.append("get_devices")
+            return [DEVICE]
+
+        async def get_rooms(self, device: Device):
+            calls.append(("get_rooms", device))
+            return ROOMS
+
+        async def clean_rooms(self, device: Device, room_ids: list[int]):
+            calls.append(("clean_rooms", device, room_ids))
+
+    monkeypatch.setattr(module, "Botslab360Client", FakeClient)
+    monkeypatch.setattr(
+        module,
+        "input",
+        lambda prompt: pytest.fail(f"Unexpected input prompt: {prompt}"),
+        raising=False,
+    )
+
+    result = asyncio.run(
+        module.run_room_api_test(
+            "private-account",
+            "private-password",
+            IDENTITY,
+            rooms_only=True,
+        )
+    )
+
+    assert result == 0
+    assert calls == ["authenticate", "get_devices", ("get_rooms", DEVICE)]
+    output = capsys.readouterr().out
+    assert "1 / Bad / bathroom / mode_tiny_carpet / 2 / max / 1" in output
+    assert "Room cleaning: not requested (--rooms-only)" in output
+    assert "PUBLIC ROOM PROFILE DIAGNOSTIC STATUS: PASS" in output
+    assert "private-account" not in output
+    assert "private-password" not in output
+
+
 def test_cleaning_requires_exact_confirmation(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:

{botslab360-0.4.2 → botslab360-0.5.0}/tests/test_rooms.py

@@ -57,7 +57,7 @@ def smart_area() -> dict:
             "forbidType": "none",
             "id": room_id,
             "material": 0,
-            "mode": 2,
+            "mode": "mode_tiny_carpet",
             "name": encoded_name(f"Room {room_id}"),
             "radius": 0,
             "relativeRoom": -1,
@@ -144,7 +144,7 @@ def test_map_info_parses_ten_public_rooms() -> None:
         clean_times=2,
         fan_mode="max",
         water_pump=2,
-        mode=2,
+        mode="mode_tiny_carpet",
     )
     assert parsed.rooms[9].room_type is None
     assert parsed.map_id == 1
@@ -218,17 +218,24 @@ def test_room_model_remains_compatible_without_vertices() -> None:
     assert room.mode is None
 
 
-@pytest.mark.parametrize("mode", [1, 2, 3, 99])
-def test_room_mode_parsing_preserves_supported_and_unknown_values(mode: int) -> None:
+@pytest.mark.parametrize("mode", ["mode_big_carpet", "mode_tiny_carpet"])
+def test_room_mode_parsing_preserves_vendor_strings(mode: str) -> None:
     payload = map_info()
     payload["smartArea"]["value"][1]["mode"] = mode
 
     assert parse_room_map(payload).rooms[1].mode == mode
 
 
-def test_room_mode_parsing_ignores_malformed_values() -> None:
+def test_room_mode_parsing_does_not_infer_numeric_cleaning_semantics() -> None:
     payload = map_info()
-    payload["smartArea"]["value"][1]["mode"] = "future-mode"
+    payload["smartArea"]["value"][1]["mode"] = 2
+
+    assert parse_room_map(payload).rooms[1].mode is None
+
+
+def test_missing_room_mode_remains_none() -> None:
+    payload = map_info()
+    payload["smartArea"]["value"][1].pop("mode")
 
     assert parse_room_map(payload).rooms[1].mode is None
 
@@ -242,19 +249,34 @@ def test_public_room_setting_choices_match_android_values() -> None:
         "max",
     ]
     assert [level.value for level in RoomWaterLevel] == [1, 2, 3]
+    # Retained only so imports written against 0.4.2 keep working.
     assert [mode.value for mode in RoomCleaningMode] == [1, 2, 3]
 
 
 @pytest.mark.parametrize("mode", [1, 2, 3])
-def test_prepare_area_setting_accepts_supported_cleaning_modes(mode: int) -> None:
+def test_prepare_area_setting_rejects_unverified_cleaning_modes(mode: int) -> None:
     room_map = parse_room_map(map_info())
 
-    result = json.loads(
+    with pytest.raises(ValueError, match="unsupported"):
         prepare_area_setting(room_map, [1], {1: RoomCleaningSettings(mode=mode)})
+
+
+def test_prepare_area_setting_preserves_vendor_mode_without_injecting_it() -> None:
+    payload = map_info()
+    payload["smartArea"]["value"][1]["mode"] = "mode_big_carpet"
+    payload["smartArea"]["value"][2].pop("mode")
+    room_map = parse_room_map(payload)
+
+    result = json.loads(
+        prepare_area_setting(
+            room_map,
+            [1, 2],
+            {1: RoomCleaningSettings(clean_times=1)},
+        )
     )
 
-    assert result["value"][1]["mode"] == mode
-    assert result["value"][0] == room_map.area_setting["value"][0]
+    assert result["value"][1]["mode"] == "mode_big_carpet"
+    assert "mode" not in result["value"][2]
 
 
 @pytest.mark.parametrize(
@@ -263,19 +285,16 @@ def test_prepare_area_setting_accepts_supported_cleaning_modes(mode: int) -> Non
         (RoomCleaningSettings(clean_times=1), {"cleanTimes": 1}),
         (RoomCleaningSettings(fan_mode="quiet"), {"windMode": "quiet"}),
         (RoomCleaningSettings(water_pump=3), {"waterPump": 3}),
-        (RoomCleaningSettings(mode=2), {"mode": 2}),
         (
             RoomCleaningSettings(
                 clean_times=1,
                 fan_mode=RoomFanMode.AUTO,
                 water_pump=RoomWaterLevel.LOW,
-                mode=RoomCleaningMode.SWEEP_AND_MOP,
             ),
             {
                 "cleanTimes": 1,
                 "windMode": "auto",
                 "waterPump": 1,
-                "mode": 1,
             },
         ),
     ],
@@ -338,6 +357,9 @@ def test_prepare_area_setting_supports_different_selected_room_settings() -> Non
         (RoomCleaningSettings(water_pump=4), ValueError),
         (RoomCleaningSettings(water_pump=True), TypeError),
         (RoomCleaningSettings(water_pump="1"), TypeError),  # type: ignore[arg-type]
+        (RoomCleaningSettings(mode=1), ValueError),
+        (RoomCleaningSettings(mode=2), ValueError),
+        (RoomCleaningSettings(mode=3), ValueError),
         (RoomCleaningSettings(mode=0), ValueError),
         (RoomCleaningSettings(mode=4), ValueError),
         (RoomCleaningSettings(mode=True), TypeError),
@@ -519,15 +541,13 @@ def test_clean_rooms_sends_per_room_overrides_through_public_api(
         (RoomCleaningSettings(clean_times=1), {"cleanTimes": 1}),
         (RoomCleaningSettings(fan_mode="quiet"), {"windMode": "quiet"}),
         (RoomCleaningSettings(water_pump=3), {"waterPump": 3}),
-        (RoomCleaningSettings(mode=2), {"mode": 2}),
         (
             RoomCleaningSettings(
                 clean_times=1,
                 fan_mode="strong",
                 water_pump=3,
-                mode=3,
             ),
-            {"cleanTimes": 1, "windMode": "strong", "waterPump": 3, "mode": 3},
+            {"cleanTimes": 1, "windMode": "strong", "waterPump": 3},
         ),
     ],
 )
@@ -647,6 +667,9 @@ def test_clean_rooms_preserves_vendor_water_pump_zero(monkeypatch) -> None:
         ([1], {1: RoomCleaningSettings(water_pump=0)}, ValueError),
         ([1], {1: RoomCleaningSettings(water_pump=4)}, ValueError),
         ([1], {1: RoomCleaningSettings(water_pump=True)}, TypeError),
+        ([1], {1: RoomCleaningSettings(mode=1)}, ValueError),
+        ([1], {1: RoomCleaningSettings(mode=2)}, ValueError),
+        ([1], {1: RoomCleaningSettings(mode=3)}, ValueError),
         ([1], {1: RoomCleaningSettings(mode=0)}, ValueError),
         ([1], {1: RoomCleaningSettings(mode=4)}, ValueError),
         ([1], {1: RoomCleaningSettings(mode=True)}, TypeError),