refactor: type Q10Status.fault as YXFault, mirroring the Q7 fault field

Retype the fault field from a raw int to YXFault | None and make fault_name
a str accessor, matching B01Props.fault / fault_name on the Q7. Update the
enum provenance notes from live hardware confirmation (10 codes) and drop
the unconfirmed 569 label.

Author: Andrew Yeats

roborock/data/b01_q10/b01_q10_code_mappings.py

@@ -294,25 +294,24 @@ class YXFault(RoborockModeEnum):
 
     ``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.
+    502 = recharge). A non-zero fault is not necessarily a blocking error.
 
     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).
+    for several shared numbers (500, 501, 503, 570) -- so this is a Q10-specific
+    map, not a reuse of ``B01Fault``. Codes marked "hw-confirmed" were observed
+    firing live on a physical ss07 in a context matching the label; the rest are
+    app-sourced only (single device, single app version).
     """
 
     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
+    ROBOT_SUSPENDED = "robot_suspended", 3  # hw-confirmed (wheels lifted off the floor mid-task)
+    CLIFF_SENSOR_ERROR = "cliff_sensor_error", 4  # hw-confirmed (one side lifted mid-task)
     MAIN_BRUSH_STUCK = "main_brush_stuck", 5
     MAIN_WHEELS_STUCK = "main_wheels_stuck", 7
-    ROBOT_TRAPPED = "robot_trapped", 8  # seen live
+    ROBOT_TRAPPED = "robot_trapped", 8  # hw-confirmed
     CHECK_DUSTBIN_FILTER = "check_dustbin_filter", 9
     LOW_BATTERY = "low_battery", 12
     TEMPERATURE_THRESHOLD = "temperature_threshold", 14
@@ -328,17 +327,16 @@ class YXFault(RoborockModeEnum):
     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
+    SENSOR_NEEDS_CLEANING = "sensor_needs_cleaning", 304  # hw-confirmed (fired during auto-empty)
+    DUST_BAG_FULL = "dust_bag_full", 310  # inferred from auto-empty context; not hw-confirmed
+    STARTING_SCHEDULED_CLEAN = "starting_scheduled_clean", 400  # hw-confirmed x3; 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)
+    EMPTY_DUSTBIN = "empty_dustbin", 500  # ss07 != Q7 B01Fault (lidar_blocked); app-sourced
+    CLEANING_COMPLETED_RETURNING = "cleaning_completed_returning", 501  # hw-confirmed; ss07 != Q7 (robot_suspended)
+    LOW_BATTERY_RESUME = "low_battery_resume", 502  # hw-confirmed; lifecycle
+    DOCKING_ERROR = "docking_error", 503  # hw-confirmed; ss07 != Q7 (dustbin_not_installed)
+    POSITIONING_FAILED = "positioning_failed", 556  # hw-confirmed; relocalization
+    CANNOT_REACH_TARGET = "cannot_reach_target", 570  # hw-confirmed; 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

roborock/data/b01_q10/b01_q10_containers.py

@@ -166,7 +166,7 @@ class Q10Status(RoborockBase):
     clean_task_type: YXDeviceCleanTask | None = field(default=None, metadata={"dps": B01_Q10_DP.CLEAN_TASK_TYPE})
     back_type: YXBackType | None = field(default=None, metadata={"dps": B01_Q10_DP.BACK_TYPE})
     cleaning_progress: int | None = field(default=None, metadata={"dps": B01_Q10_DP.CLEAN_PROGRESS})
-    fault: int | None = field(default=None, metadata={"dps": B01_Q10_DP.FAULT})
+    fault: YXFault | None = field(default=None, metadata={"dps": B01_Q10_DP.FAULT})
 
     # Additional state reported in the device's full status dump.
     clean_line: YXCleanLine | None = field(default=None, metadata={"dps": B01_Q10_DP.CLEAN_LINE})
@@ -205,17 +205,9 @@ class Q10Status(RoborockBase):
     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)
+    def fault_name(self) -> str | None:
+        """Returns the name of the current fault."""
+        return self.fault.value if self.fault is not None else None
 
 
 @dataclass

tests/data/b01_q10/test_b01_q10_code_mappings.py

@@ -49,14 +49,24 @@ def test_q10_fault_codes_map_to_ss07_labels(code: int, expected: YXFault) -> Non
     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
+def test_q10_status_fault_field_and_name() -> None:
+    """``fault`` is a typed ``YXFault`` field; ``fault_name`` mirrors the Q7 accessor."""
+    status = Q10Status(fault=YXFault.CANNOT_REACH_TARGET)
+    assert status.fault is YXFault.CANNOT_REACH_TARGET
+    assert status.fault_name == "cannot_reach_target"
 
     assert Q10Status(fault=None).fault_name is None
+
+
+def test_q10_status_fault_decodes_from_dict() -> None:
+    """A raw dpFault int decodes to the enum through the standard conversion path."""
+    status = Q10Status.from_dict({"fault": 503})
+    assert status is not None
+    assert status.fault is YXFault.DOCKING_ERROR
+
+    # An unmapped code follows the library-wide enum-field behavior:
+    # the failed conversion is logged and the field is left None.
+    unmapped = Q10Status.from_dict({"fault": 99999})
+    assert unmapped is not None
+    assert unmapped.fault is None
+    assert unmapped.fault_name is None

tests/devices/traits/b01/q10/test_status.py

@@ -18,6 +18,7 @@
     YXDeviceDustCollectionFrequency,
     YXDeviceState,
     YXFanLevel,
+    YXFault,
     YXWaterLevel,
 )
 from roborock.data.b01_q10.b01_q10_containers import dpNetInfo, dpNotDisturbExpand, dpTimeZone
@@ -150,7 +151,7 @@ async def test_status_trait_refresh(
     assert q10_api.consumable.filter_life == 0
     assert q10_api.consumable.sensor_life == 0
     assert q10_api.status.cleaning_progress == 100
-    assert q10_api.status.fault == 0
+    assert q10_api.status.fault is YXFault.NONE
     assert q10_api.status.clean_mode == YXCleanType.VAC_AND_MOP
     assert q10_api.status.water_level == YXWaterLevel.LOW