Add StationErrorEvent for base station errors

deebot_client/capabilities.py

@@ -43,6 +43,7 @@
     RoomsEvent,
     SafeProtectEvent,
     StateEvent,
+    StationErrorEvent,
     StationEvent,
     StatsEvent,
     SweepModeEvent,
@@ -242,6 +243,7 @@ class CapabilityStation:
         auto_empty.Frequency,
     ]
     state: CapabilityEvent[StationEvent]
+    error: CapabilityEvent[StationErrorEvent] | None = None
 
 
 @dataclass(frozen=True, kw_only=True)

deebot_client/events/__init__.py

@@ -28,7 +28,7 @@
     PositionsEvent,
 )
 from .network import NetworkInfoEvent
-from .station import StationEvent
+from .station import StationErrorEvent, StationEvent
 from .work_mode import WorkMode, WorkModeEvent
 
 if TYPE_CHECKING:
@@ -58,6 +58,7 @@
     "NetworkInfoEvent",
     "Position",
     "PositionsEvent",
+    "StationErrorEvent",
     "StationEvent",
     "SweepModeEvent",
     "WorkMode",

deebot_client/events/station.py

@@ -7,7 +7,7 @@
 
 from .base import Event as _Event
 
-__all__ = ["State", "StationEvent"]
+__all__ = ["State", "StationErrorEvent", "StationEvent"]
 
 
 @unique
@@ -25,3 +25,16 @@ class StationEvent(_Event):
     """Base Station Event representation."""
 
     state: State
+
+
+@dataclass(frozen=True)
+class StationErrorEvent(_Event):
+    """Errors reported by the base station, e.g. a water-tank condition.
+
+    ``errors`` holds the raw Ecovacs codes exactly as reported, including the
+    0/100 "no error" sentinels; map them via
+    :data:`deebot_client.const.ERROR_CODES`. An empty tuple means the station
+    reported an empty error list.
+    """
+
+    errors: tuple[int, ...]

deebot_client/messages/json/station_state.py

@@ -4,15 +4,43 @@
 
 from typing import TYPE_CHECKING, Any
 
-from deebot_client.events.station import State, StationEvent
+from deebot_client.events.station import State, StationErrorEvent, StationEvent
 from deebot_client.message import HandlingResult, MessageBodyDataDict
 
 if TYPE_CHECKING:
     from deebot_client.event_bus import EventBus
 
 
+def _parse_error_codes(value: Any) -> tuple[int, ...] | None:
+    """Return the station error codes, or None when no codes are usable.
+
+    An empty list means "no current errors" and clears a previously reported
+    fault. None means the error channel is absent, is not a list, or held no
+    usable code -- the last known fault must be preserved rather than cleared.
+    """
+    if not isinstance(value, list):
+        return None
+
+    codes: list[int] = []
+    for entry in value:
+        if isinstance(entry, bool):
+            continue
+        if isinstance(entry, int):
+            codes.append(entry)
+        elif isinstance(entry, str):
+            try:
+                codes.append(int(entry))
+            except ValueError:
+                continue
+
+    if value and not codes:
+        # A non-empty list with nothing usable is "unknown", not "all clear".
+        return None
+    return tuple(codes)
+
+
 class OnStationState(MessageBodyDataDict):
-    """On battery message."""
+    """On station state message."""
 
     NAME = "onStationState"
 
@@ -27,19 +55,26 @@ def _handle_body_data_dict(
         # "body":{"data":{"content":{"error":[],"type":0},"state":0},"code":0,"msg":"ok"} - Idle
         # "body":{"data":{"content":{"error":[],"type":1,"motionState":1},"state":1},"code":0,"msg":"ok"} - Emptying
         # "body":{"data":{"content":{"error":[],"type":2,"motionState":1},"state":1},"code":0,"msg":"ok"} - Drying mop
+        content = data.get("content")
+        if isinstance(content, dict):
+            # Report station errors first, so an unrecognised activity state
+            # cannot swallow a water-tank or other station fault.
+            errors = _parse_error_codes(content.get("error"))
+            if errors is not None:
+                event_bus.notify(StationErrorEvent(errors))
 
         if (state := data.get("state")) == 0:
             reported_state = State.IDLE
         elif (
             state == 1
-            and (content := data.get("content"))
+            and content
             and content.get("type") == 1
             and content.get("motionState") == 1
         ):
             reported_state = State.EMPTYING_DUSTBIN
         elif (
             state == 1
-            and (content := data.get("content"))
+            and content
             and content.get("type") == 2
             and content.get("motionState") == 1
         ):

tests/commands/json/test_station_state.py

@@ -5,7 +5,7 @@
 import pytest
 
 from deebot_client.commands.json.station_state import GetStationState
-from deebot_client.events.station import State, StationEvent
+from deebot_client.events.station import State, StationErrorEvent, StationEvent
 from deebot_client.message import HandlingResult, HandlingState
 from tests.helpers import get_request_json, get_success_body
 
@@ -34,14 +34,40 @@ async def test_GetStationState(
         )
     )
     await assert_command(
-        GetStationState(), json, (firmware_event, StationEvent(expected))
+        GetStationState(),
+        json,
+        (firmware_event, StationErrorEvent(()), StationEvent(expected)),
+    )
+
+
+async def test_GetStationState_reports_errors() -> None:
+    """Poll responses surface the station error tuple too."""
+    json, firmware_event = get_request_json(
+        get_success_body({"content": {"error": [301, 314], "type": 0}, "state": 0})
+    )
+    await assert_command(
+        GetStationState(),
+        json,
+        (firmware_event, StationErrorEvent((301, 314)), StationEvent(State.IDLE)),
+    )
+
+
+async def test_GetStationState_without_error_field() -> None:
+    """A poll without an error key means 'unknown', not 'no errors'."""
+    json, firmware_event = get_request_json(
+        get_success_body({"content": {"type": 0}, "state": 0})
+    )
+    await assert_command(
+        GetStationState(),
+        json,
+        (firmware_event, StationEvent(State.IDLE)),
     )
 
 
 @pytest.mark.parametrize(
     ("state", "additional_content"),
     [
-        # content missing
+        # no type or motionState
         (1, {}),
         # type present but motionState missing
         (1, {"type": 2}),
@@ -67,6 +93,6 @@ async def test_GetStationState_analyse(
     await assert_command(
         GetStationState(),
         json,
-        firmware_event,
+        (firmware_event, StationErrorEvent(())),
         handling_result=HandlingResult(HandlingState.ANALYSE_LOGGED),
     )