botslab360 0.4.2__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: botslab360
-Version: 0.4.2
+Version: 0.6.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
@@ -191,6 +192,27 @@ async with Botslab360Client(q, t) as client:
     await client.locate(robot)
 ```
 
+### Mop hardware and mop-only mode
+
+`RobotStatus.mop_status` exposes the raw integer reported by status command
+`20001`. On the tested S9-P, `0` means that the wiping assembly is absent and
+`1` means that it is present. Other integer values are preserved without an
+assumed meaning because their semantics may be model-dependent.
+
+Mop-only mode can be controlled through the public API:
+
+```python
+await client.set_mop_only(robot, False)  # Sweep, or sweep and mop with hardware
+await client.set_mop_only(robot, True)  # Mop only
+```
+
+Disabling mop-only sends the verified vendor switch value `1`; enabling it
+sends value `2`. With value `1`, the effective mode depends on whether wiping
+hardware is installed. The current mop-only switch value is not exposed by the
+known status payload, so the library does not fabricate a synchronized
+`mop_only` state or derived cleaning mode. Water level remains an independent
+room setting.
+
 ### Room cleaning
 
 Room cleaning always fetches the current map before validating and sending the
@@ -217,13 +239,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 +254,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 +270,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
 
@@ -268,6 +294,7 @@ Depending on the robot model, status information may include:
 - Cleaning time in seconds
 - Error code
 - Online state
+- Wiping assembly status (`mop_status`)
 
 Example:
 
@@ -283,6 +310,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.6.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
@@ -171,6 +172,27 @@ async with Botslab360Client(q, t) as client:
     await client.locate(robot)
 ```
 
+### Mop hardware and mop-only mode
+
+`RobotStatus.mop_status` exposes the raw integer reported by status command
+`20001`. On the tested S9-P, `0` means that the wiping assembly is absent and
+`1` means that it is present. Other integer values are preserved without an
+assumed meaning because their semantics may be model-dependent.
+
+Mop-only mode can be controlled through the public API:
+
+```python
+await client.set_mop_only(robot, False)  # Sweep, or sweep and mop with hardware
+await client.set_mop_only(robot, True)  # Mop only
+```
+
+Disabling mop-only sends the verified vendor switch value `1`; enabling it
+sends value `2`. With value `1`, the effective mode depends on whether wiping
+hardware is installed. The current mop-only switch value is not exposed by the
+known status payload, so the library does not fabricate a synchronized
+`mop_only` state or derived cleaning mode. Water level remains an independent
+room setting.
+
 ### Room cleaning
 
 Room cleaning always fetches the current map before validating and sending the
@@ -197,13 +219,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 +234,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 +250,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
 
@@ -248,6 +274,7 @@ Depending on the robot model, status information may include:
 - Cleaning time in seconds
 - Error code
 - Online state
+- Wiping assembly status (`mop_status`)
 
 Example:
 
@@ -263,6 +290,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.6.0}/pyproject.toml

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

{botslab360-0.4.2 → botslab360-0.6.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.6.0}/src/botslab360/client.py

@@ -17,6 +17,8 @@ import httpx
 from .auth import SMART_HOME_BASE_URL, BotslabAuth, credentials_from_tokens
 from .commands import (
     LOCATE,
+    MOP_ONLY_OFF,
+    MOP_ONLY_ON,
     PAUSE,
     RESUME,
     RETURN_TO_DOCK,
@@ -29,6 +31,7 @@ from .models import (
     CaptchaChallenge,
     Device,
     DeviceIdentity,
+    NetworkInfo,
     QihooCredentials,
     RobotStatus,
     Room,
@@ -45,6 +48,7 @@ from .protocol import (
     DEFAULT_PUSH_HEARTBEAT_TIMEOUT,
     DEFAULT_PUSH_HOST,
     DEFAULT_PUSH_PORT,
+    NETWORK_INFO_TYPE,
     STATUS_INFO_TYPE,
     PushClient,
 )
@@ -560,6 +564,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,
@@ -776,6 +834,14 @@ class Botslab360Client:
 
         await self._execute_command(device, LOCATE, "locate robot")
 
+    async def set_mop_only(self, device: Device | str, enabled: bool) -> None:
+        """Enable or disable mop-only cleaning."""
+
+        if not isinstance(enabled, bool):
+            raise TypeError("enabled must be a bool")
+        command = MOP_ONLY_ON if enabled else MOP_ONLY_OFF
+        await self._execute_command(device, command, "set mop-only mode")
+
     async def _execute_command(
         self,
         device: Device | str,

{botslab360-0.4.2 → botslab360-0.6.0}/src/botslab360/commands.py

@@ -26,3 +26,11 @@ LOCATE = CommandSpec(
     data='{"ctrlCode":3010}',
     requires_task_id=False,
 )
+MOP_ONLY_OFF = CommandSpec(
+    info_type="21024",
+    data='{"cmd":"setMopSwitch","value":1}',
+)
+MOP_ONLY_ON = CommandSpec(
+    info_type="21024",
+    data='{"cmd":"setMopSwitch","value":2}',
+)

{botslab360-0.4.2 → botslab360-0.6.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
@@ -165,6 +188,7 @@ class RobotStatus:
     cleaned_area_m2: int | None
     cleaning_time_seconds: int | None
     error_code: int
+    mop_status: int | None = None
 
     @property
     def cleaned_area(self) -> int | None:

{botslab360-0.4.2 → botslab360-0.6.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,
     *,
@@ -178,6 +258,7 @@ def parse_status_event(
             field="cleanTime",
         ),
         error_code=error_code,
+        mop_status=_optional_int(status.get("mopStatus"), field="mopStatus"),
     )
 
 
@@ -619,6 +700,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.6.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(