pycentauri 0.6.1__tar.gz → 0.6.3__tar.gz

{pycentauri-0.6.1 → pycentauri-0.6.3}/CHANGELOG.md

@@ -6,6 +6,51 @@ Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.3] - 2026-07-05
+
+### Changed
+- **CC2 speed pinning now tells a human's balanced apart from a firmware
+  reset — no more Auto escape hatch.** The firmware resets speed_mode to
+  balanced as the leading edge of every Canvas filament switch, a few
+  seconds before the head parks; measured reset→park lead times are
+  tight (6–8 s, never above ~9 s). pycentauri uses that: a drop to
+  balanced followed by a park within ~12 s is the firmware and the
+  pinned mode is re-applied when the switch completes; a drop that sits
+  at balanced for ~12 s with no park is a human tapping balanced on the
+  touchscreen, so the pin is released and balanced is honored. A
+  sustained non-balanced touchscreen mode is still adopted as the pin
+  outright. Both paths live-verified 2026-07-05 (firmware re-apply and
+  human release, each with journal-logged decisions).
+- **Removed the `auto` speed mode / Auto button.** It existed only to
+  release the pin for the touchscreen-balanced case, which is now
+  detected automatically. `speed auto`, `{"mode": "auto"}`, and the web
+  UI Auto button are gone.
+
+
+## [0.6.2] - 2026-07-05
+
+### Changed
+- **CC2 speed-mode persistence redesigned as pin-and-enforce.** The
+  0.6.1 snapshot-per-switch restore lost an arms race with the
+  firmware: after eight consecutive successful restores, a reset whose
+  lead time exceeded the debounce window poisoned the baseline and
+  silently disabled every restore after it. The firmware resets
+  `speed_mode` to balanced as part of every Canvas filament switch —
+  the reset fires several seconds before the head parks, while the
+  status still reads "printing", and its lead time varies — and it only
+  ever resets TO balanced. So the model is now timing-agnostic: the
+  mode you set is pinned (immediately via pycentauri; after holding a
+  few seconds when set from the touchscreen, since a non-balanced mode
+  can only come from a human), and any disagreement lasting 12 s while
+  printing is re-applied, at most every 30 s. One consequence,
+  deliberate: while a mode is pinned, selecting *balanced* from the
+  touchscreen is byte-identical on the wire to a firmware reset and will
+  be reverted — switch to balanced through pycentauri instead (which
+  re-pins), or release the pin. Pins clear when the print ends, and
+  ``speed auto`` (CLI), ``{"mode": "auto"}`` (HTTP), or the web UI's
+  Auto button release the pin explicitly, returning speed control to
+  the printer.
+
 ## [0.6.1] - 2026-07-05
 
 ### Fixed

{pycentauri-0.6.1 → pycentauri-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycentauri
-Version: 0.6.1
+Version: 0.6.3
 Summary: Local-network toolkit for Elegoo Centauri Carbon 3D printers: async Python client, CLI, MCP server, REST/SSE HTTP server, web UI, and RTSP bridge
 Project-URL: Homepage, https://github.com/bjan/pycentauri
 Project-URL: Repository, https://github.com/bjan/pycentauri
@@ -166,6 +166,42 @@ are silently ignored by the firmware:
 
 Speed changes only take effect while a print is actively running.
 
+#### CC2 speed pinning (the firmware fights you, so pycentauri fights back)
+
+The CC2 firmware **resets the speed mode back to balanced on every
+Canvas filament switch.** On a multi-color print that switch happens
+every couple of minutes, so set sport once and the printer quietly
+drops you to balanced at the next color change. This is firmware
+behavior; it happens whether you set the speed from pycentauri or from
+the printer's own touchscreen.
+
+pycentauri works around it with **pin-and-enforce** (CC2 only, requires
+`--enable-control`):
+
+- **Whatever mode you select gets pinned.** Set it via pycentauri (pins
+  immediately) or on the touchscreen (pinned after it holds ~8 seconds —
+  the firmware never *resets* to a non-balanced mode, so a sustained
+  sport/ludicrous/silent must be a human).
+- **A firmware reset is re-applied.** The reset fires a few seconds
+  *before* the head parks at the chute, so when the speed drops to
+  balanced pycentauri waits to see what follows: a filament switch
+  (the head parking) within ~12 seconds means it was the firmware, and
+  the pinned mode is re-applied as soon as the switch completes.
+- **A human's balanced is honored.** If the speed drops to balanced and
+  *no* switch follows within ~12 seconds, that was you tapping balanced
+  on the touchscreen — the pin is released and balanced stays. (On the
+  wire a human tap is byte-identical to a firmware reset; the presence
+  or absence of the following switch is what tells them apart. Measured
+  reset→park lead times cluster at 6–8 s, well inside the window.)
+- **The pin clears when the print ends.**
+
+So both paths just work: set any speed from either the app or the
+printer and it sticks across filament switches, and you can always
+drop back to balanced from the touchscreen whenever you want.
+
+The CC1 has none of this — its speed mode stays where you put it, so
+`set_print_speed` is a plain one-shot there.
+
 ## Python library
 
 ```python
@@ -407,10 +443,12 @@ reports code 27 the entire time the head is parked there mid-print.
   cooldown of a few seconds during which the broker silently drops
   responses. pycentauri's polling cadence stays under it; your scripts
   should too.
-- **Canvas filament switches reset the speed mode.** Every mid-print
-  switch silently drops the printer back to balanced. pycentauri
-  detects the switch ending and re-applies whatever mode was active
-  before it (needs `--enable-control`).
+- **The firmware resets the speed mode to balanced on every Canvas
+  filament switch.** pycentauri pins your chosen mode and re-applies it
+  automatically, while still honoring a deliberate balanced from the
+  touchscreen — see
+  [CC2 speed pinning](#cc2-speed-pinning-the-firmware-fights-you-so-pycentauri-fights-back)
+  above for how it tells the two apart.
 - **Registrations expire without an app-level PING.** The printer
   forgets a registered client after several quiet minutes and silently
   stops answering that session's requests — the MQTT connection itself

{pycentauri-0.6.1 → pycentauri-0.6.3}/README.md

@@ -116,6 +116,42 @@ are silently ignored by the firmware:
 
 Speed changes only take effect while a print is actively running.
 
+#### CC2 speed pinning (the firmware fights you, so pycentauri fights back)
+
+The CC2 firmware **resets the speed mode back to balanced on every
+Canvas filament switch.** On a multi-color print that switch happens
+every couple of minutes, so set sport once and the printer quietly
+drops you to balanced at the next color change. This is firmware
+behavior; it happens whether you set the speed from pycentauri or from
+the printer's own touchscreen.
+
+pycentauri works around it with **pin-and-enforce** (CC2 only, requires
+`--enable-control`):
+
+- **Whatever mode you select gets pinned.** Set it via pycentauri (pins
+  immediately) or on the touchscreen (pinned after it holds ~8 seconds —
+  the firmware never *resets* to a non-balanced mode, so a sustained
+  sport/ludicrous/silent must be a human).
+- **A firmware reset is re-applied.** The reset fires a few seconds
+  *before* the head parks at the chute, so when the speed drops to
+  balanced pycentauri waits to see what follows: a filament switch
+  (the head parking) within ~12 seconds means it was the firmware, and
+  the pinned mode is re-applied as soon as the switch completes.
+- **A human's balanced is honored.** If the speed drops to balanced and
+  *no* switch follows within ~12 seconds, that was you tapping balanced
+  on the touchscreen — the pin is released and balanced stays. (On the
+  wire a human tap is byte-identical to a firmware reset; the presence
+  or absence of the following switch is what tells them apart. Measured
+  reset→park lead times cluster at 6–8 s, well inside the window.)
+- **The pin clears when the print ends.**
+
+So both paths just work: set any speed from either the app or the
+printer and it sticks across filament switches, and you can always
+drop back to balanced from the touchscreen whenever you want.
+
+The CC1 has none of this — its speed mode stays where you put it, so
+`set_print_speed` is a plain one-shot there.
+
 ## Python library
 
 ```python
@@ -357,10 +393,12 @@ reports code 27 the entire time the head is parked there mid-print.
   cooldown of a few seconds during which the broker silently drops
   responses. pycentauri's polling cadence stays under it; your scripts
   should too.
-- **Canvas filament switches reset the speed mode.** Every mid-print
-  switch silently drops the printer back to balanced. pycentauri
-  detects the switch ending and re-applies whatever mode was active
-  before it (needs `--enable-control`).
+- **The firmware resets the speed mode to balanced on every Canvas
+  filament switch.** pycentauri pins your chosen mode and re-applies it
+  automatically, while still honoring a deliberate balanced from the
+  touchscreen — see
+  [CC2 speed pinning](#cc2-speed-pinning-the-firmware-fights-you-so-pycentauri-fights-back)
+  above for how it tells the two apart.
 - **Registrations expire without an app-level PING.** The printer
   forgets a registered client after several quiet minutes and silently
   stops answering that session's requests — the MQTT connection itself

{pycentauri-0.6.1 → pycentauri-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycentauri"
-version = "0.6.1"
+version = "0.6.3"
 description = "Local-network toolkit for Elegoo Centauri Carbon 3D printers: async Python client, CLI, MCP server, REST/SSE HTTP server, web UI, and RTSP bridge"
 readme = "README.md"
 license = "Apache-2.0"

{pycentauri-0.6.1 → pycentauri-0.6.3}/src/pycentauri/__init__.py

@@ -39,4 +39,4 @@ __all__ = [
     "discover",
 ]
 
-__version__ = "0.6.1"
+__version__ = "0.6.3"

{pycentauri-0.6.1 → pycentauri-0.6.3}/src/pycentauri/cc2.py

@@ -40,11 +40,22 @@ log = logging.getLogger(__name__)
 MQTT_PORT = 1883
 CC2_USERNAME = "elegoo"
 PING_INTERVAL_S = 30.0
-# A speed mode must hold this long before it becomes the restore baseline —
-# the firmware resets speed_mode several seconds BEFORE the head parks for a
-# filament switch (observed 2026-07-05: reset at T-6s), and without the hold
-# that transient poisons the baseline.
-BASELINE_HOLD_S = 15.0
+# Speed-mode pinning. The firmware resets speed_mode TO balanced (1) — never
+# to any other mode — as the leading edge of every Canvas filament switch:
+# the reset fires a few seconds before the head parks at the chute, while the
+# status still reads "printing". Measured lead times (reset -> park) cluster
+# tightly at 6-10 s (2026-07-05). We exploit that to tell a firmware reset
+# apart from a human tapping "balanced" on the touchscreen (byte-identical on
+# the wire): a drop to balanced followed by a park within HUMAN_WINDOW_S is
+# the firmware and the pinned mode is re-applied when the switch completes;
+# a drop that sits at balanced for HUMAN_WINDOW_S with NO switch is a human,
+# and the pin is released. 12 s is ~1.5x the 8 s max lead time from the
+# precise (sub-second) captures on 2026-07-05. A non-balanced mode from the
+# touchscreen (held PIN_LEARN_S) is adopted as the new pin outright, since
+# the firmware never produces one.
+PIN_LEARN_S = 8.0
+HUMAN_WINDOW_S = 12.0
+ENFORCE_MIN_INTERVAL_S = 30.0
 # Lifecycle commands (start/pause/stop/resume) are answered only after the
 # firmware finishes the mechanical sequence — a resume reheats and unparks
 # before responding, easily exceeding the default 15 s request timeout
@@ -270,14 +281,16 @@ class CC2Printer(Printer):
         self._last_full_result: dict[str, Any] | None = None
         self._connect_error: str | None = None
         self._ping_task: asyncio.Task[None] | None = None
-        # Speed-mode restore across Canvas filament switches: the firmware
-        # resets speed_mode to balanced (1) on every mid-print switch
-        # (verified 2026-07-05 — mode stays 1 after the switch completes).
-        self._speed_mode_during_print: int | None = None
-        self._speed_mode_to_restore: int | None = None
-        self._restore_task: asyncio.Task[None] | None = None
-        self._mode_candidate: int | None = None
-        self._mode_candidate_since: float = 0.0
+        # Speed-mode pinning (see module constants for the rationale).
+        self._pinned_mode: int | None = None
+        self._pin_candidate: int | None = None
+        self._pin_candidate_since: float = 0.0
+        # Adjudicating a drop-to-balanced: when it started, and whether a
+        # filament switch (a park at the chute) has been seen since.
+        self._pending_since: float | None = None
+        self._switch_seen: bool = False
+        self._last_enforce: float = float("-inf")
+        self._enforce_task: asyncio.Task[None] | None = None
         self._now = time.monotonic  # overridable for tests
 
     @classmethod
@@ -463,12 +476,11 @@ class CC2Printer(Printer):
                     f"{sorted(self.PRINT_SPEED_MODES.values())}"
                 )
         result = await self._cc2_request(1031, {"mode": value})
-        # The user's explicit choice supersedes any pending post-switch
-        # restore and becomes the new baseline.
-        self._speed_mode_during_print = value
-        self._mode_candidate = None
-        if self._speed_mode_to_restore is not None:
-            self._speed_mode_to_restore = value
+        # An explicit choice through pycentauri pins the mode.
+        self._pinned_mode = value
+        self._pin_candidate = None
+        self._pending_since = None
+        self._switch_seen = False
         return self._wrap_result(1031, result)
 
     async def set_fan_speed(
@@ -534,7 +546,7 @@ class CC2Printer(Printer):
         if self._closed:
             return
         self._closed = True
-        for task in (self._ping_task, self._restore_task):
+        for task in (self._ping_task, self._enforce_task):
             if task is not None and not task.done():
                 task.cancel()
                 with contextlib.suppress(asyncio.CancelledError, Exception):
@@ -657,73 +669,116 @@ class CC2Printer(Printer):
             log.exception("failed to handle CC2 status push")
 
     def _track_speed_mode(self, payload: dict[str, Any]) -> None:
-        """Restore the speed mode after a Canvas filament switch.
-
-        The firmware resets ``speed_mode`` to balanced on every mid-print
-        filament switch (verified 2026-07-05). We snapshot the mode in
-        effect when a switch starts (print_status 27) and re-apply it once
-        printing resumes, so the user's selection — made from any surface,
-        including the touchscreen — survives the switch. Requires
-        ``enable_control``; read-only sessions just log the reset.
+        """Pin-and-enforce the user's speed mode (runs on the asyncio loop).
+
+        See the module-level constants for the firmware behaviour this
+        works around. In short: a non-balanced mode set anywhere is pinned
+        (from the touchscreen after a brief hold) and re-applied after each
+        filament switch resets it; a drop to balanced is adjudicated by
+        whether a switch follows within ``HUMAN_WINDOW_S`` — switch means
+        firmware (re-apply), no switch means a human chose balanced
+        (release the pin).
         """
         print_status = payload.get("PrintInfo", {}).get("Status")
         speed_mode = payload.get("_cc2", {}).get("speed_mode")
         if not isinstance(speed_mode, int) or print_status is None:
             return
-        if print_status == 27:
-            if self._speed_mode_to_restore is None and self._speed_mode_during_print is not None:
-                self._speed_mode_to_restore = self._speed_mode_during_print
+
+        if print_status in (0, 8, 9, 14):
+            # Print over (idle/stopped/completed/error): the pin dies with it.
+            self._pinned_mode = None
+            self._pin_candidate = None
+            self._pending_since = None
+            self._switch_seen = False
             return
+
         if print_status != 13:
+            # Filament switch (27) / pausing / etc. A park during an
+            # in-flight adjudication is the firmware signature.
+            if print_status == 27 and self._pending_since is not None:
+                self._switch_seen = True
             return
-        want = self._speed_mode_to_restore
-        if want is not None:
-            self._speed_mode_to_restore = None
-            if want != speed_mode:
-                if self.enable_control:
-                    self._restore_task = asyncio.create_task(
-                        self._restore_speed_mode(want),
-                        name=f"pycentauri-cc2-speedrestore-{self.host}",
-                    )
-                else:
-                    log.warning(
-                        "filament switch reset speed_mode %d -> %d; "
-                        "enable_control is off so it will not be restored",
-                        want,
-                        speed_mode,
-                    )
-                return
-        # Track the running mode, but not while a restore is in flight —
-        # the firmware still reports the reset value for a poll or two.
-        if self._restore_task is not None and not self._restore_task.done():
+
+        # --- printing (status 13) ---
+        now = self._now()
+
+        # A non-balanced mode we're not already pinned to can only be a
+        # human (the firmware never sets one) — adopt it after a brief hold.
+        if speed_mode != 1 and speed_mode != self._pinned_mode:
+            if self._pin_candidate == speed_mode:
+                if now - self._pin_candidate_since >= PIN_LEARN_S:
+                    self._pinned_mode = speed_mode
+                    self._pin_candidate = None
+                    self._pending_since = None
+                    self._switch_seen = False
+            else:
+                self._pin_candidate = speed_mode
+                self._pin_candidate_since = now
             return
-        if self._speed_mode_during_print is None:
-            # Bootstrap: first observation is the baseline.
-            self._speed_mode_during_print = speed_mode
+
+        self._pin_candidate = None
+
+        # Nothing to defend, or the pin is satisfied.
+        if self._pinned_mode is None or speed_mode == self._pinned_mode:
+            self._pending_since = None
+            self._switch_seen = False
             return
-        if speed_mode == self._speed_mode_during_print:
-            self._mode_candidate = None
+
+        # speed_mode == 1 (balanced) while pinned to a faster mode: the
+        # ambiguous case. Adjudicate by whether a switch follows.
+        if self._pending_since is None:
+            self._pending_since = now
+            self._switch_seen = False
             return
-        # Debounce: a changed mode must hold BASELINE_HOLD_S before it
-        # becomes the restore baseline, so the firmware's pre-switch reset
-        # (which fires seconds before the head parks) never gets adopted.
-        now = self._now()
-        if speed_mode != self._mode_candidate:
-            self._mode_candidate = speed_mode
-            self._mode_candidate_since = now
-        elif now - self._mode_candidate_since >= BASELINE_HOLD_S:
-            self._speed_mode_during_print = speed_mode
-            self._mode_candidate = None
-
-    async def _restore_speed_mode(self, mode: int) -> None:
+
+        if self._switch_seen:
+            # Firmware reset confirmed by the switch — re-apply, and keep
+            # re-applying (rate-limited) until it takes. Do NOT clear
+            # _pending_since here: only a match (above) clears it.
+            self._enforce(speed_mode, now)
+            return
+
+        if now - self._pending_since >= HUMAN_WINDOW_S:
+            # Balanced held this long with no switch: a human chose it.
+            log.info(
+                "balanced held %0.0fs with no filament switch — releasing "
+                "the speed-mode pin (was %d)",
+                now - self._pending_since,
+                self._pinned_mode,
+            )
+            self._pinned_mode = None
+            self._pending_since = None
+            self._switch_seen = False
+            return
+        # Still inside the window with no switch yet — keep waiting.
+
+    def _enforce(self, current_mode: int, now: float) -> None:
+        assert self._pinned_mode is not None
+        if self._enforce_task is not None and not self._enforce_task.done():
+            return
+        if now - self._last_enforce < ENFORCE_MIN_INTERVAL_S:
+            return
+        self._last_enforce = now
+        if self.enable_control:
+            self._enforce_task = asyncio.create_task(
+                self._apply_pinned_mode(self._pinned_mode),
+                name=f"pycentauri-cc2-speedpin-{self.host}",
+            )
+        else:
+            log.warning(
+                "speed_mode drifted to %d but pin is %d; enable_control is off "
+                "so it will not be re-applied",
+                current_mode,
+                self._pinned_mode,
+            )
+
+    async def _apply_pinned_mode(self, mode: int) -> None:
         await asyncio.sleep(2.0)  # let the firmware settle after the switch
         try:
             await self._cc2_request(1031, {"mode": mode})
-            log.info("restored speed_mode %d after filament switch", mode)
+            log.info("re-applied pinned speed_mode %d after filament switch", mode)
         except Exception:
-            log.warning(
-                "could not restore speed_mode %d after filament switch", mode, exc_info=True
-            )
+            log.warning("could not re-apply pinned speed_mode %d", mode, exc_info=True)
 
     def _publish_register(self) -> None:
         topic = f"elegoo/{self._serial_number}/api_register"

{pycentauri-0.6.1 → pycentauri-0.6.3}/tests/test_cc2_mapping.py

@@ -272,90 +272,156 @@ def test_canvas_parse_survives_malformed_payloads() -> None:
     assert CanvasStatus.from_payload({"canvas_info": {"canvas_list": "bogus"}}).tray_count == 0
 
 
-# --- speed-mode restore across filament switches -------------------------------
+# --- speed-mode pin, enforce & human/firmware adjudication ----------------
 
 
 def _payload(status: int, mode: int) -> dict[str, Any]:
     return {"PrintInfo": {"Status": status}, "_cc2": {"speed_mode": mode}}
 
 
-def _printer(enable_control: bool = False) -> Any:
+def _printer(enable_control: bool = True) -> Any:
     from pycentauri.cc2 import CC2Printer
 
-    return CC2Printer("127.0.0.1", access_code="x", enable_control=enable_control)
+    p = CC2Printer("127.0.0.1", access_code="x", enable_control=enable_control)
+    p._fired: list[int] = []
+    p._enforce_calls = 0
 
+    def fake_enforce(current_mode: int, now: float) -> None:
+        # Mirror the real rate-limit + record instead of spawning a task.
+        import pycentauri.cc2 as m
 
-def test_switch_snapshots_and_flags_restore(monkeypatch: Any) -> None:
-    p = _printer(enable_control=False)
-    # Printing at sport (2)
-    p._track_speed_mode(_payload(13, 2))
-    assert p._speed_mode_during_print == 2
-    # Switch begins — snapshot taken
-    p._track_speed_mode(_payload(27, 1))
-    assert p._speed_mode_to_restore == 2
-    # Switch ends with the firmware reset to balanced; control off → no
-    # restore task, but the pending snapshot is consumed.
-    p._track_speed_mode(_payload(13, 1))
-    assert p._speed_mode_to_restore is None
+        if now - p._last_enforce < m.ENFORCE_MIN_INTERVAL_S:
+            return
+        p._last_enforce = now
+        p._fired.append(p._pinned_mode)
+
+    p._enforce = fake_enforce
+    t = [0.0]
+    p._clock = t
+    p._now = lambda: t[0]
+    return p
+
+
+def _tick(p: Any, dt: float, status: int, mode: int) -> None:
+    p._clock[0] += dt
+    p._track_speed_mode(_payload(status, mode))
+
+
+# --- firmware reset: switch follows, mode is re-applied on resume ---------
 
 
-def test_no_restore_when_mode_survives_switch() -> None:
+def test_firmware_reset_reenforced_after_switch() -> None:
     p = _printer()
-    p._track_speed_mode(_payload(13, 3))
-    p._track_speed_mode(_payload(27, 3))
-    assert p._speed_mode_to_restore == 3
-    # Firmware kept the mode: nothing to do, baseline continues
-    p._track_speed_mode(_payload(13, 3))
-    assert p._speed_mode_to_restore is None
-    assert p._speed_mode_during_print == 3
+    p._pinned_mode = 2
+    _tick(p, 0, 13, 2)  # printing at sport
+    _tick(p, 3, 13, 1)  # pre-switch reset (T=3)
+    _tick(p, 4, 13, 1)  # still no park; within window, wait
+    assert p._fired == []
+    _tick(p, 2, 27, 1)  # head parks -> switch seen
+    _tick(p, 180, 27, 1)  # switch runs for 3 min
+    assert p._fired == []  # never released, never enforced mid-switch
+    _tick(p, 1, 13, 1)  # resume, still balanced -> re-apply sport
+    assert p._fired == [2]
+
+
+def test_park_within_window_prevents_human_release() -> None:
+    """A park inside the window must stop the human-release clock."""
+    p = _printer()
+    p._pinned_mode = 2
+    _tick(p, 0, 13, 2)
+    _tick(p, 5, 13, 1)  # reset at T=5
+    _tick(p, 4, 27, 1)  # park inside the window -> switch seen
+    _tick(p, 20, 27, 1)  # long switch, we are not printing
+    _tick(p, 1, 13, 1)  # resume -> firmware, re-apply
+    assert p._pinned_mode == 2
+    assert p._fired == [2]
+
 
+# --- human balanced: no switch, pin released ------------------------------
 
-def test_snapshot_not_overwritten_mid_switch() -> None:
+
+def test_human_balanced_releases_pin_after_window() -> None:
+    p = _printer()
+    p._pinned_mode = 2
+    _tick(p, 0, 13, 2)  # printing at sport
+    _tick(p, 2, 13, 1)  # user taps balanced (T=2)
+    _tick(p, 5, 13, 1)  # T=7, no switch, still waiting
+    assert p._pinned_mode == 2
+    assert p._fired == []
+    _tick(p, 6, 13, 1)  # still waiting (inside the window)
+    assert p._pinned_mode == 2
+    _tick(p, 5, 13, 1)  # past the window, no switch -> release
+    assert p._pinned_mode is None
+    assert p._fired == []
+
+
+def test_human_balanced_never_yanked_during_window() -> None:
+    """The mode must stay balanced (no enforce) throughout the wait."""
     p = _printer()
-    p._track_speed_mode(_payload(13, 2))
-    p._track_speed_mode(_payload(27, 1))
-    p._track_speed_mode(_payload(27, 1))  # more switch polls
-    assert p._speed_mode_to_restore == 2
+    p._pinned_mode = 2
+    _tick(p, 0, 13, 2)
+    _tick(p, 1, 13, 1)
+    for _ in range(6):
+        _tick(p, 2, 13, 1)  # poll every 2s up to ~13s
+    assert p._fired == []  # never re-applied sport while adjudicating
 
 
-def test_idle_states_do_not_touch_tracking() -> None:
+# --- touchscreen non-balanced override ------------------------------------
+
+
+def test_screen_change_to_nonbalanced_becomes_pin() -> None:
     p = _printer()
-    p._track_speed_mode(_payload(13, 2))
-    p._track_speed_mode(_payload(0, 1))  # idle
-    p._track_speed_mode(_payload(6, 1))  # paused
-    assert p._speed_mode_during_print == 2
-    assert p._speed_mode_to_restore is None
+    _tick(p, 0, 13, 1)  # printing, nothing pinned
+    _tick(p, 5, 13, 3)  # user picks ludicrous on the touchscreen
+    assert p._pinned_mode is None
+    _tick(p, 9, 13, 3)  # held > PIN_LEARN_S -> adopted
+    assert p._pinned_mode == 3
+    assert p._fired == []
 
 
-def test_pre_switch_reset_does_not_poison_baseline() -> None:
-    """Replicates the live trace from 2026-07-05 14:10: the firmware
-    resets speed_mode ~6 s BEFORE the head parks for the switch."""
+def test_screen_override_beats_release_when_pinned() -> None:
+    """Screen change sport->ludicrous while sport is pinned: adopt ludicrous,
+    never release or enforce."""
     p = _printer()
-    t = [0.0]
-    p._now = lambda: t[0]
-    p._track_speed_mode(_payload(13, 2))  # printing at sport (bootstrap)
-    t[0] = 120.0
-    p._track_speed_mode(_payload(13, 2))  # still sport
-    # Pre-switch reset: mode drops while status is still 13
-    t[0] = 126.0
-    p._track_speed_mode(_payload(13, 1))
-    t[0] = 129.0
-    p._track_speed_mode(_payload(13, 1))  # held only 3 s — not promoted
-    assert p._speed_mode_during_print == 2
-    # Head parks, switch state
-    t[0] = 132.0
-    p._track_speed_mode(_payload(27, 1))
-    assert p._speed_mode_to_restore == 2  # snapshot is the REAL baseline
-
-
-def test_sustained_mode_change_becomes_baseline() -> None:
+    p._pinned_mode = 2
+    _tick(p, 0, 13, 2)
+    _tick(p, 2, 13, 3)  # user picks ludicrous
+    _tick(p, 9, 13, 3)  # held -> adopted as new pin
+    assert p._pinned_mode == 3
+    assert p._fired == []
+
+
+# --- lifecycle ------------------------------------------------------------
+
+
+def test_no_pin_no_action() -> None:
     p = _printer()
-    t = [0.0]
-    p._now = lambda: t[0]
-    p._track_speed_mode(_payload(13, 1))  # bootstrap balanced
-    t[0] = 10.0
-    p._track_speed_mode(_payload(13, 3))  # user sets ludicrous on screen
-    assert p._speed_mode_during_print == 1  # not yet promoted
-    t[0] = 26.0
-    p._track_speed_mode(_payload(13, 3))  # held 16 s → promoted
-    assert p._speed_mode_during_print == 3
+    _tick(p, 0, 13, 1)
+    _tick(p, 60, 13, 1)
+    assert p._fired == []
+    assert p._pinned_mode is None
+
+
+def test_print_end_clears_pin() -> None:
+    p = _printer()
+    p._pinned_mode = 2
+    _tick(p, 0, 13, 2)
+    _tick(p, 5, 9, 1)  # completed
+    assert p._pinned_mode is None
+    _tick(p, 5, 13, 1)  # a fresh print at balanced
+    _tick(p, 60, 13, 1)
+    assert p._fired == []
+
+
+def test_enforce_rate_limited_across_repeated_switches() -> None:
+    p = _printer()
+    p._pinned_mode = 2
+    _tick(p, 0, 13, 2)
+    _tick(p, 3, 13, 1)  # reset
+    _tick(p, 4, 27, 1)  # park
+    _tick(p, 60, 13, 1)  # resume -> enforce (T=67)
+    assert p._fired == [2]
+    _tick(p, 5, 13, 1)  # still balanced (enforce not "taken" in this fake)
+    assert p._fired == [2]  # within 30s cooldown, no repeat
+    _tick(p, 30, 13, 1)  # cooldown elapsed -> enforce again
+    assert p._fired == [2, 2]