feat(messages): add OnMapTrace for mower firmware (LZMA-wrapped variant)

Mower firmwares (observed: GOAT A1600 RTK fw 1.15.13) push spontaneous
``onMapTrace`` messages whose body schema is completely different from
the existing ``GetMapTrace`` response:

    {
      "header": {"fwVer": "1.15.13", ...},
      "body": {"data": {
        "mid": "...", "batid": "...", "serial": "1",
        "index": "0", "type": "4",
        "info": "<base64 of LZMA1 compressed JSON>",
        "infoSize": 3455
      }}
    }

The compressed ``info`` field, once decompressed, is a JSON list of
trajectory groups: ``[[group_id, "0;x1,y1;x2,y2;...;", "0;x,y;..."], ...]``
with negative-and-positive integer coordinates (relative to a map origin).

This adds a dedicated ``OnMapTrace`` message handler that:

1. Detects the new format via the presence of ``info``.
2. Decompresses via the existing Rust ``decompress_base64_data`` helper
   (which already handles the firmware's trimmed 9-byte LZMA header).
3. Parses the JSON, drops the leading ``"0"`` anchor of each segment,
   and concatenates the remaining points across groups.
4. Notifies ``MapTraceEvent`` using the firmware ``serial`` as ``start``
   so the ``Map`` Rust helper does not clear the trace on every push.

Registered alongside the other JSON map messages so it is dispatched
*before* the legacy ``getMapTrace`` fallback (which still serves vacuum
firmwares unchanged).

Tests:

- Happy paths (single group, multi-group, multi-segment).
- ``info`` missing → ANALYSE (defer to legacy handler).
- Empty groups → ANALYSE (no event emitted).
- Corrupt ``info`` (invalid base64, too short, decompresses to non-JSON) → ANALYSE (no exception escapes).
- ``serial`` propagates as ``MapTraceEvent.start``.
- Full suite: 705/705 pass, no regression.

Refs:

- #1376 (Disable getMapTrace for Goat) — this PR
  is the proper alternative: instead of disabling, the message is now
  parsed and surfaces as a usable trajectory.
- Companion to #1565 (skip legacy fallback for mowers) and #1566
  (warn-once rate limit). #1565 still serves as a safety net for any
  remaining unhandled map messages on mowers.

Author: Beennnn

deebot_client/messages/json/__init__.py

@@ -10,7 +10,7 @@
 from .auto_empty import OnAutoEmpty
 from .battery import OnBattery
 from .gps_position import OnGpsPos
-from .map import OnCachedMapInfo, OnMajorMap, OnMapInfoV2, OnMapSetV2
+from .map import OnCachedMapInfo, OnMajorMap, OnMapInfoV2, OnMapSetV2, OnMapTrace
 from .station_state import OnStationState
 from .stats import OnStats, ReportStats
 from .work_state import OnWorkState
@@ -24,6 +24,7 @@
     "OnMajorMap",
     "OnMapInfoV2",
     "OnMapSetV2",
+    "OnMapTrace",
     "OnStats",
     "OnWorkState",
     "ReportStats",
@@ -42,6 +43,7 @@
     OnMajorMap,
     OnMapInfoV2,
     OnMapSetV2,
+    OnMapTrace,
 
     OnStationState,
 

deebot_client/messages/json/map/__init__.py

@@ -2,21 +2,27 @@
 
 from __future__ import annotations
 
+import json as _json
 from typing import TYPE_CHECKING, Any
 
-from deebot_client.events.map import MajorMapEvent, MapInfoEvent, MapSetType
+from deebot_client.events.map import MajorMapEvent, MapInfoEvent, MapSetType, MapTraceEvent
+from deebot_client.logging_filter import get_logger
 from deebot_client.message import HandlingResult, HandlingState, MessageBodyDataDict
+from deebot_client.rs.util import decompress_base64_data
 
 from .cached_map_info import OnCachedMapInfo
 
 if TYPE_CHECKING:
     from deebot_client.event_bus import EventBus
 
+_LOGGER = get_logger(__name__)
+
 __all__ = [
     "OnCachedMapInfo",
     "OnMajorMap",
     "OnMapInfoV2",
     "OnMapSetV2",
+    "OnMapTrace",
 ]
 
 
@@ -91,3 +97,80 @@ def _handle_body_data_dict(
         event_bus.notify(MapInfoEvent(map_id=data["mid"], info=data["info"]))
 
         return HandlingResult.success()
+
+
+class OnMapTrace(MessageBodyDataDict):
+    """On map trace message — variant pushed by mower firmwares (e.g. GOAT 1.15.x).
+
+    The vacuum-style ``getMapTrace`` response carried ``traceValue`` directly.
+    Mower firmwares instead push a compressed envelope:
+
+    .. code-block:: json
+
+        {
+            "mid": "...", "batid": "...", "serial": "1",
+            "index": "0", "type": "4",
+            "info": "<base64 of LZMA-compressed JSON>",
+            "infoSize": 3455
+        }
+
+    The decompressed payload is itself a small JSON document of the form
+    ``[[group_id, "0;x1,y1;x2,y2;..."], ...]`` where each group is a
+    contiguous trajectory segment. We flatten the points across groups
+    into the ``"x,y;x,y;..."`` shape that downstream consumers (the
+    ``Map`` Rust helper in particular) already accept.
+
+    Used in lieu of the legacy ``GetMapTrace`` fallback for these devices.
+    """
+
+    NAME = "onMapTrace"
+
+    @classmethod
+    def _handle_body_data_dict(
+        cls, event_bus: EventBus, data: dict[str, Any]
+    ) -> HandlingResult:
+        """Handle message->body->data and notify the correct event subscribers."""
+        info = data.get("info")
+        if not info:
+            # Not the compressed-envelope variant — leave to legacy GetMapTrace
+            return HandlingResult.analyse()
+
+        try:
+            decompressed = decompress_base64_data(info).decode("utf-8")
+            groups = _json.loads(decompressed)
+        except Exception:
+            _LOGGER.debug(
+                "Could not decompress/parse onMapTrace info field for mid=%s batid=%s "
+                "(probably truncated by upstream logger)",
+                data.get("mid"),
+                data.get("batid"),
+            )
+            return HandlingResult.analyse()
+
+        flat_points: list[str] = []
+        for group in groups:
+            # Each group: [group_id_str, "0;x1,y1;x2,y2;...;", "0;x,y;..." ...]
+            if not isinstance(group, list):
+                continue
+            for segment in group[1:]:
+                if not isinstance(segment, str):
+                    continue
+                # Drop the leading "0" anchor and any empty trailing segment
+                pts = [p for p in segment.split(";") if p and p != "0"]
+                flat_points.extend(pts)
+
+        if not flat_points:
+            return HandlingResult.analyse()
+
+        # Use serial as a stable monotonic ``start`` so ``Map`` does not clear
+        # the trace on every push — only the very first ever (serial == 0)
+        # would trigger the reset, which is the firmware's intent.
+        try:
+            start = int(data.get("serial", 1))
+        except (TypeError, ValueError):
+            start = 1
+
+        event_bus.notify(
+            MapTraceEvent(start=start, total=start, data=";".join(flat_points))
+        )
+        return HandlingResult.success()

tests/messages/json/map/test_on_map_trace.py

@@ -0,0 +1,172 @@
+"""Tests for OnMapTrace — mower variant with LZMA-compressed info field."""
+
+from __future__ import annotations
+
+import base64
+import json as _json
+import lzma
+
+import pytest
+
+from deebot_client.events import FirmwareEvent
+from deebot_client.events.map import MapTraceEvent
+from deebot_client.message import HandlingState
+from deebot_client.messages.json.map import OnMapTrace
+from tests.messages.json import assert_message
+
+
+# ---------------------------------------------------------------------------
+# Helper: encode bytes the same way mower firmware does
+# ---------------------------------------------------------------------------
+#
+# Real GOAT A1600 RTK firmware 1.15.x emits an LZMA1 stream with a
+# *trimmed* 9-byte header (props + dict_size_le + size_le_4_bytes) instead
+# of the standard LZMA1 ALONE 13-byte header. The Rust helper
+# ``decompress_base64_data`` accommodates this by injecting four zero
+# bytes after position 7 to rebuild a valid 13-byte header. Reproduce
+# that on the encoding side here so the round-trip works.
+
+_DICT_SIZE = 1 << 18  # 256 KB — matches what real firmware advertises
+
+
+def _ecovacs_encode(payload: bytes) -> str:
+    raw = lzma.compress(
+        payload,
+        format=lzma.FORMAT_RAW,
+        filters=[{"id": lzma.FILTER_LZMA1,
+                  "preset": lzma.PRESET_DEFAULT,
+                  "dict_size": _DICT_SIZE}],
+    )
+    header = bytes([0x5D]) + _DICT_SIZE.to_bytes(4, "little") + len(payload).to_bytes(4, "little")
+    return base64.b64encode(header + raw).decode("ascii")
+
+
+def _envelope(info_b64: str, info_size: int, fw: str = "1.15.13") -> dict:
+    return {
+        "header": {
+            "pri": 1,
+            "tzm": 120,
+            "ts": "1777450352860644879",
+            "fwVer": fw,
+            "hwVer": "0.0.0",
+        },
+        "body": {
+            "data": {
+                "mid": "123456789",
+                "batid": "hmfald",
+                "serial": "1",
+                "index": "0",
+                "type": "4",
+                "info": info_b64,
+                "infoSize": info_size,
+            }
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Happy path
+# ---------------------------------------------------------------------------
+
+
+def test_OnMapTrace_decompresses_and_flattens_groups() -> None:
+    inner = '[["7","0;100,200;150,250;"]]'
+    data = inner.encode("utf-8")
+    info = _ecovacs_encode(data)
+
+    expected_trace = "100,200;150,250"
+    assert_message(
+        OnMapTrace,
+        _envelope(info, len(data)),
+        (FirmwareEvent("1.15.13"), MapTraceEvent(start=1, total=1, data=expected_trace)),
+        device_class="xmp9ds",
+    )
+
+
+def test_OnMapTrace_concatenates_multiple_groups_and_segments() -> None:
+    inner = (
+        '[["5","0;-11850,-28849;-11800,-28899;","0;-12850,-23699;-12800,-23750;"],'
+        '["6","0;-7899,-39700;-7950,-39649;"]]'
+    )
+    data = inner.encode("utf-8")
+    info = _ecovacs_encode(data)
+    expected_trace = (
+        "-11850,-28849;-11800,-28899;-12850,-23699;-12800,-23750;-7899,-39700;-7950,-39649"
+    )
+    assert_message(
+        OnMapTrace,
+        _envelope(info, len(data)),
+        (FirmwareEvent("1.15.13"), MapTraceEvent(start=1, total=1, data=expected_trace)),
+        device_class="xmp9ds",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Edge cases
+# ---------------------------------------------------------------------------
+
+
+def test_OnMapTrace_no_info_field_returns_analyse() -> None:
+    """Without ``info``, defer to the legacy GetMapTrace handler — analyse, no event."""
+    envelope = _envelope("", 0)
+    envelope["body"]["data"].pop("info")
+    envelope["body"]["data"].pop("infoSize")
+    assert_message(
+        OnMapTrace,
+        envelope,
+        FirmwareEvent("1.15.13"),
+        device_class="xmp9ds",
+        expected_state=HandlingState.ANALYSE_LOGGED,
+    )
+
+
+def test_OnMapTrace_empty_groups_returns_analyse() -> None:
+    """A payload with no actual coordinates is unusable — analyse rather than emit empty event."""
+    inner = "[]"
+    data = inner.encode("utf-8")
+    info = _ecovacs_encode(data)
+    assert_message(
+        OnMapTrace,
+        _envelope(info, len(data)),
+        FirmwareEvent("1.15.13"),
+        device_class="xmp9ds",
+        expected_state=HandlingState.ANALYSE_LOGGED,
+    )
+
+
+@pytest.mark.parametrize(
+    "broken_info",
+    [
+        "@@@not-base64@@@",                    # invalid base64
+        base64.b64encode(b"too short").decode("ascii"),  # too short for LZMA header
+        _ecovacs_encode(b"not json content"),  # decompresses to non-JSON
+    ],
+)
+def test_OnMapTrace_corrupt_info_returns_analyse(broken_info: str) -> None:
+    """Truncated/broken ``info`` (typical when upstream loggers truncate the payload)
+    should not raise — log at debug and return analyse so the message is dropped silently.
+    """
+    assert_message(
+        OnMapTrace,
+        _envelope(broken_info, 0),
+        FirmwareEvent("1.15.13"),
+        device_class="xmp9ds",
+        expected_state=HandlingState.ANALYSE_LOGGED,
+    )
+
+
+def test_OnMapTrace_uses_serial_as_event_start() -> None:
+    """``serial`` becomes the ``MapTraceEvent.start`` so the Map helper does not clear
+    on every push (it only clears when ``start == 0``)."""
+    inner = '[["1","0;1,2;3,4;"]]'
+    data = inner.encode("utf-8")
+    info = _ecovacs_encode(data)
+    envelope = _envelope(info, len(data))
+    envelope["body"]["data"]["serial"] = "42"
+
+    assert_message(
+        OnMapTrace,
+        envelope,
+        (FirmwareEvent("1.15.13"), MapTraceEvent(start=42, total=42, data="1,2;3,4")),
+        device_class="xmp9ds",
+    )