feat: decode Q10 (B01/ss07) dpFault codes into a YXFault map

Add a Q10-specific YXFault enum (seeded from the ss07 app fault i18n) and an
additive Q10Status.fault_name property. The raw fault int is untouched, so
unknown/new codes are never lost. Addresses #855.

Author: andrewlyeats

roborock/data/b01_q10/b01_q10_code_mappings.py

@@ -289,6 +289,64 @@ class YXCarpetCleanType(RoborockModeEnum):
     CROSS = "cross", 3
 
 
+class YXFault(RoborockModeEnum):
+    """Q10 (B01/ss07) ``dpFault`` (90) codes, seeded from the ss07 app's fault i18n.
+
+    ``dpFault`` is *overloaded*: several values are lifecycle/status rather than
+    errors (e.g. 400 = scheduled clean starting, 501 = returning to dock,
+    502 = recharge). A non-zero fault is only a *blocking* error when the app
+    routes the code into its ``D_ErrorCode`` bucket; alert/offline codes are softer.
+
+    These labels follow the ss07 app text, which differs from the Q7 ``B01Fault``
+    for several shared numbers (500, 501, 503, 569, 570) -- so this is a
+    Q10-specific map, not a reuse of ``B01Fault``. Codes marked "seen live" were
+    observed as raw ``dpFault`` values on a physical ss07; the rest are
+    app-sourced only (n=1, not hardware-confirmed).
+    """
+
+    UNKNOWN = "unknown", -1
+    NONE = "none", 0
+    LIDAR_BLOCKED = "lidar_blocked", 1
+    BUMPER_STUCK = "bumper_stuck", 2
+    ROBOT_SUSPENDED = "robot_suspended", 3
+    CLIFF_SENSOR_ERROR = "cliff_sensor_error", 4
+    MAIN_BRUSH_STUCK = "main_brush_stuck", 5
+    MAIN_WHEELS_STUCK = "main_wheels_stuck", 7
+    ROBOT_TRAPPED = "robot_trapped", 8  # seen live
+    CHECK_DUSTBIN_FILTER = "check_dustbin_filter", 9
+    LOW_BATTERY = "low_battery", 12
+    TEMPERATURE_THRESHOLD = "temperature_threshold", 14
+    ROBOT_TILTED = "robot_tilted", 16
+    LIDAR_COVER_OBSTRUCTED = "lidar_cover_obstructed", 21
+    NO_GO_ZONE_DETECTED = "no_go_zone_detected", 24
+    MOPPING_MODULE_STUCK = "mopping_module_stuck", 27
+    CARPET_AVOIDANCE = "carpet_avoidance", 28
+    CANNOT_CROSS_CARPET = "cannot_cross_carpet", 29
+    INSTALL_DUST_BAG = "install_dust_bag", 46
+    MOP_MOUNT_FELL_OFF = "mop_mount_fell_off", 54
+    LIDAR_DIRTY = "lidar_dirty", 58
+    FILTER_SERVICE_LIFE = "filter_service_life", 301
+    MAIN_BRUSH_SERVICE_LIFE = "main_brush_service_life", 302
+    SIDE_BRUSH_SERVICE_LIFE = "side_brush_service_life", 303
+    SENSOR_NEEDS_CLEANING = "sensor_needs_cleaning", 304
+    DUST_BAG_FULL = "dust_bag_full", 310
+    STARTING_SCHEDULED_CLEAN = "starting_scheduled_clean", 400  # seen live; lifecycle, not an error
+    CLEANING_IN_PROGRESS = "cleaning_in_progress", 407
+    EMPTY_DUSTBIN = "empty_dustbin", 500  # ss07 != Q7 B01Fault (lidar_blocked)
+    CLEANING_COMPLETED_RETURNING = "cleaning_completed_returning", 501  # ss07 != Q7 (robot_suspended)
+    LOW_BATTERY_RESUME = "low_battery_resume", 502
+    DOCKING_ERROR = "docking_error", 503  # seen live; ss07 != Q7 (dustbin_not_installed)
+    POSITIONING_FAILED = "positioning_failed", 556  # seen live; relocalization
+    TOO_FREQUENT_EMPTYING = "too_frequent_emptying", 569  # ss07 != Q7 (main_wheels_entangled)
+    CANNOT_REACH_TARGET = "cannot_reach_target", 570  # seen live; ss07 != Q7 (main_brush_entangled)
+    OFFLINE_WARNING_ASLEEP = "offline_warning_asleep", 588
+    OFFLINE_WARNING_LOW_BATTERY = "offline_warning_low_battery", 589
+    DND_AUTO_TOPUP_DISABLED = "dnd_auto_topup_disabled", 591
+    CLEAN_CARPET_ULTRASONIC_SENSORS = "clean_carpet_ultrasonic_sensors", 707
+    ROBOT_ERROR_RESET = "robot_error_reset", 1002
+    VOICE_PACK_UPDATE_AVAILABLE = "voice_pack_update_available", 3001
+
+
 class RemoteCommand(IntEnum):
     FORWARD = 0
     LEFT = 2

roborock/data/b01_q10/b01_q10_containers.py

@@ -23,6 +23,7 @@
     YXDeviceDustCollectionFrequency,
     YXDeviceState,
     YXFanLevel,
+    YXFault,
     YXStartMethod,
     YXWaterLevel,
 )
@@ -203,6 +204,19 @@ class Q10Status(RoborockBase):
     filter_life: int | None = field(default=None, metadata={"dps": B01_Q10_DP.FILTER_LIFE})
     sensor_life: int | None = field(default=None, metadata={"dps": B01_Q10_DP.SENSOR_LIFE})
 
+    @property
+    def fault_name(self) -> YXFault | None:
+        """Decoded ``dpFault`` label, or ``None`` for an unmapped code.
+
+        Additive: ``fault`` keeps the raw integer so unknown/new codes are never
+        lost; this is the decoded companion. ``dpFault`` is overloaded (see
+        :class:`~roborock.data.b01_q10.YXFault`), so a non-``NONE`` value is not
+        necessarily an error.
+        """
+        if self.fault is None:
+            return None
+        return YXFault.from_code_optional(self.fault)
+
 
 @dataclass
 class SoundVolume(RoborockBase):

tests/data/b01_q10/test_b01_q10_code_mappings.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from roborock.data.b01_q10 import YXDeviceState
+from roborock.data.b01_q10 import Q10Status, YXDeviceState, YXFault
 
 
 @pytest.mark.parametrize(
@@ -33,3 +33,30 @@ def test_q10_status_values_are_canonical(state: YXDeviceState, string: str) -> N
 def test_q10_status_codes_map_to_canonical_values(code: int, expected_state: YXDeviceState) -> None:
     """Code-based mapping should return canonical status values."""
     assert YXDeviceState.from_code(code) is expected_state
+
+
+@pytest.mark.parametrize(
+    "code, expected",
+    [
+        (0, YXFault.NONE),
+        (503, YXFault.DOCKING_ERROR),  # ss07 docking error, not the Q7 "dustbin_not_installed"
+        (570, YXFault.CANNOT_REACH_TARGET),  # ss07 cannot-reach, not the Q7 "main_brush_entangled"
+        (556, YXFault.POSITIONING_FAILED),
+    ],
+)
+def test_q10_fault_codes_map_to_ss07_labels(code: int, expected: YXFault) -> None:
+    """dpFault codes should decode to the ss07-correct labels."""
+    assert YXFault.from_code(code) is expected
+
+
+def test_q10_fault_name_is_additive_and_preserves_raw_int() -> None:
+    """``fault_name`` decodes the label without ever losing the raw ``fault`` int."""
+    status = Q10Status(fault=570)
+    assert status.fault_name is YXFault.CANNOT_REACH_TARGET
+    assert status.fault == 570
+
+    unmapped = Q10Status(fault=99999)
+    assert unmapped.fault_name is None  # unknown code -> None, no crash
+    assert unmapped.fault == 99999
+
+    assert Q10Status(fault=None).fault_name is None