openbricks 2.6.2__tar.gz → 2.7.0__tar.gz

{openbricks-2.6.2 → openbricks-2.7.0}/CHANGELOG.md

@@ -3,6 +3,24 @@
 Versions the unified `openbricks` PyPI package (CLI + MuJoCo sim).
 Firmware versions are tracked separately on the `v*` tag namespace.
 
+## 2.7.0 — run is upload-then-run; flash --with-qtr-init
+
+Two CLI changes, both user-requested:
+
+* **`run` stages to the button slot** (reversing the 1.97.0 run-slot
+  split, deliberately different from Pybricks): the script lands at
+  `/program.mpy` before executing, so a run that fails midway stays
+  rerunnable with the start button — no BLE round trip. The accepted
+  price: one-shot tools (calibrations, diagnostics) replace the
+  button program; re-upload your mission afterwards.
+* **`flash --with-qtr-init`** stores a starter QTR calibration at
+  `/qtr.cal` (reference-bench sweep, default pins 1-10, the exact
+  `save_calibration` format) so line-follow examples work on a
+  fresh hub. Re-run `examples/qtr_calibrate.py` for your own mat
+  and lighting.
+
+CLI-side: `pipx upgrade openbricks` (no reflash needed).
+
 ## 2.6.2 — done requires standstill; per-axis settle diagnostics
 
 Bench (the twitch that survived 2.6.0, now measured): the final

{openbricks-2.6.2/openbricks.egg-info → openbricks-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbricks
-Version: 2.6.2
+Version: 2.7.0
 Summary: openbricks — host-side CLI + MuJoCo-backed simulator for the openbricks MicroPython firmware. Flash, list, run, upload, log; ``openbricks sim`` for the physics simulator.
 Author: openbricks contributors
 License: MIT

{openbricks-2.6.2 → openbricks-2.7.0/openbricks.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbricks
-Version: 2.6.2
+Version: 2.7.0
 Summary: openbricks — host-side CLI + MuJoCo-backed simulator for the openbricks MicroPython firmware. Flash, list, run, upload, log; ``openbricks sim`` for the physics simulator.
 Author: openbricks contributors
 License: MIT

{openbricks-2.6.2 → openbricks-2.7.0}/openbricks_dev/__init__.py

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: MIT
 """openbricks — host-side CLI for flashing and running code on hubs."""
 
-__version__ = "2.6.2"
+__version__ = "2.7.0"

{openbricks-2.6.2 → openbricks-2.7.0}/openbricks_dev/cli.py

@@ -77,6 +77,14 @@ def _build_parser():
         "--baud", default="460800",
         help="esptool flash baud rate. Default: 460800.",
     )
+    p_flash.add_argument(
+        "--with-qtr-init", action="store_true",
+        help="After flashing, store a starter QTR line-sensor "
+             "calibration at /qtr.cal (recorded on the reference "
+             "bench, default pins 1-10) so line-follow examples work "
+             "out of the box. Re-run examples/qtr_calibrate.py for a "
+             "calibration measured on your own mat and lighting.",
+    )
     p_flash.add_argument(
         "--skip-erase", action="store_true",
         help="Skip erase_flash (faster dev loop; leaves stale NVS keys).",

{openbricks-2.6.2 → openbricks-2.7.0}/openbricks_dev/flash.py

@@ -364,6 +364,41 @@ def _wait_for_repl(mpremote, port, timeout_s=20):
     )
 
 
+# Starter QTR calibration shipped by ``--with-qtr-init`` — a real
+# bench sweep (2026-08-17, QTRX-HD-15A on the WRO mat, default pins
+# 1-10; the per-element spans from that run's log). Format matches
+# ``QTRArray.save_calibration``: {"pins", "min", "max"}. A starter
+# file gets a fresh flash line-following immediately; heights, mats
+# and lighting differ, so examples/qtr_calibrate.py remains the way
+# to a calibration measured on YOUR rig.
+_QTR_CAL_PATH = "/qtr.cal"
+_QTR_STARTER_CAL = {
+    "pins": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    "min": [9346, 4048, 3888, 3728, 3984, 3888, 3824, 3968, 4593, 8658],
+    "max": [44922, 37849, 36024, 35816, 36056, 36536, 32888, 36552,
+            40057, 43834],
+}
+
+
+def _write_qtr_starter_cal(mpremote, port):
+    """Store the starter QTR calibration on the hub filesystem and
+    verify it parses back — a corrupt or truncated write must fail
+    HERE, not as a RuntimeError in the user's first line-follow."""
+    import json
+    payload = json.dumps(_QTR_STARTER_CAL)
+    snippet = (
+        "f = open(%r, 'w'); f.write(%r); f.close(); "
+        "import json; d = json.load(open(%r)); "
+        "print('qtr-cal-ok', len(d['min']), len(d['max']))"
+    ) % (_QTR_CAL_PATH, payload, _QTR_CAL_PATH)
+    rc, out, err = _mpremote_exec(mpremote, port, snippet)
+    if rc != 0 or "qtr-cal-ok 10 10" not in out:
+        _die("failed to write starter QTR calibration:\n" + (err or out))
+    print("starter QTR calibration written to %s (re-run "
+          "examples/qtr_calibrate.py for your own mat/lighting)"
+          % _QTR_CAL_PATH)
+
+
 def _write_hub_name(mpremote, port, name):
     # The name already passed validation in ``_validate_name``; plain
     # bytes literal is safe.
@@ -645,6 +680,9 @@ def run(args):
         _die("verification failed: wrote %r, read back %r" % (args.name, readback))
     print("hub name %r written and verified" % readback)
 
+    if getattr(args, "with_qtr_init", False):
+        _write_qtr_starter_cal(mpremote, args.port)
+
     flashed_version = _write_fw_marker(mpremote, args.port,
                                        firmware_verdict)
 

{openbricks-2.6.2 → openbricks-2.7.0}/openbricks_dev/run.py

@@ -59,16 +59,15 @@ _TARGET_PATH = "/program.py"
 # removes the other — see _compose_runner(remove_stale=...).
 _MPY_TARGET_PATH = "/program.mpy"
 
-# One-shot runs stage to their OWN slot (CLI >= 1.97.0): ``run`` used
-# to share /program.mpy with ``upload``, so every run — including
-# calibrations and diagnostics — silently replaced the program the
-# BUTTON launches. Bench 2026-08-14: upload aa.py, run
+# ``run`` stages to the BUTTON slot (/program.*) — an upload-then-run
+# (user decision 2026-08-17, reversing the 1.97.0 run-slot split and
+# deliberately different from Pybricks): a run that fails mid-way
+# leaves the program on the hub, so the start button reruns it
+# without another BLE round trip. The accepted price is the 1.97.0
+# hazard returning: running a calibration or diagnostic script
+# replaces the button program (bench 2026-08-14: upload aa.py, run
 # qtr_calibrate, press start -> the robot invisibly re-ran the
-# calibration and the report was "button does nothing". The button
-# never reads /run.*, so the two intents can no longer clobber
-# each other.
-_RUN_TARGET_PATH = "/run.py"
-_RUN_MPY_TARGET_PATH = "/run.mpy"
+# calibration) — re-upload your mission after one-shot tools.
 
 # First firmware whose launcher runs /program.mpy (native exec_mpy).
 _MIN_MPY_FIRMWARE = (1, 92, 0)
@@ -744,7 +743,7 @@ async def _run_session(link, name, user_bytes, mpy_bytes):
         await _enter_raw_repl(blink, link)
         try:
             target, use_mpy, remove_stale = await _pick_staging(
-                blink, link, _RUN_MPY_TARGET_PATH, _RUN_TARGET_PATH)
+                blink, link)
             payload = mpy_bytes if use_mpy else user_bytes
             runner = _compose_runner(target, remove_stale)
             await _stage_file(blink, link, target, payload, name)

{openbricks-2.6.2 → openbricks-2.7.0}/tests/test_cli.py

@@ -232,6 +232,8 @@ class DispatchTests(unittest.TestCase):
             ("stop", ["stop", "-n", "X"]),
             ("log", ["log", "-n", "X"]),
             ("servo_id", ["servo-id", "-p", "/p", "3"]),
+            ("pasteprobe", ["paste-probe", "-n", "X"]),
+            ("docs", ["docs"]),
         ]
         for mod_name, argv in cases:
             seen.clear()

{openbricks-2.6.2 → openbricks-2.7.0}/tests/test_flash.py

@@ -524,6 +524,37 @@ class RunHappyPathTests(unittest.TestCase):
                       stderr=""),
         ])
 
+    def test_full_flow_with_qtr_init_writes_the_cal(self):
+        # --with-qtr-init inserts one mpremote exec between the name
+        # readback and the fw marker: the /qtr.cal write+verify.
+        snippets = []
+
+        def _fake_call(cmd):
+            return 0
+
+        run_responses = iter([
+            MagicMock(returncode=1, stdout="", stderr="no repl"),
+            MagicMock(returncode=0, stdout="ok\n", stderr=""),
+            MagicMock(returncode=0, stdout="wrote: 'RobotA'\n", stderr=""),
+            MagicMock(returncode=0, stdout="RobotA\n", stderr=""),
+            MagicMock(returncode=0, stdout="qtr-cal-ok 10 10\n", stderr=""),
+            MagicMock(returncode=0, stdout="9.9.9\n", stderr=""),
+            MagicMock(returncode=0, stdout="marker: 9.9.9:customized\n",
+                      stderr=""),
+        ])
+
+        def _fake_run(cmd, capture_output=True, text=True, timeout=None):
+            snippets.append(cmd[-1])
+            return next(run_responses)
+
+        with patch("subprocess.call", side_effect=_fake_call), \
+             patch("subprocess.run", side_effect=_fake_run):
+            rc = flash.run(self._run_args(with_qtr_init=True))
+
+        self.assertEqual(rc, 0)
+        self.assertTrue(any("'/qtr.cal'" in sn for sn in snippets),
+                        "qtr cal write never composed")
+
     def test_full_flow_success(self):
         # subprocess.call for erase_flash / write_flash / final reset.
         call_history = []
@@ -703,6 +734,53 @@ class ToolMissingTests(unittest.TestCase):
         self.assertIn("esptool not found", str(ctx.exception))
 
 
+class QtrStarterCalTests(unittest.TestCase):
+    """``flash --with-qtr-init`` stores the reference-bench starter
+    calibration at /qtr.cal in exactly the format
+    ``QTRArray.save_calibration`` writes — pins list included, since
+    ``load_calibration`` refuses a file recorded for other wiring."""
+
+    def test_snippet_writes_valid_cal_json(self):
+        import json as _json
+        captured = {}
+
+        def _fake_run(cmd, capture_output=True, text=True, timeout=None):
+            captured["snippet"] = cmd[-1]
+            return MagicMock(returncode=0,
+                             stdout="qtr-cal-ok 10 10\n", stderr="")
+
+        with patch("subprocess.run", side_effect=_fake_run):
+            flash._write_qtr_starter_cal("mpremote", "/dev/ttyUSB0")
+
+        snippet = captured["snippet"]
+        self.assertIn("'/qtr.cal'", snippet)
+        # The staged payload is the repr of a JSON document with the
+        # save_calibration schema: 10 pins, 10 mins, 10 maxes, and
+        # every span positive (min < max) — a starter file that fails
+        # load_calibration would be worse than no file.
+        start = snippet.index("f.write(") + len("f.write(")
+        payload_repr = snippet[start:snippet.index("); f.close()")]
+        payload = eval(payload_repr)   # repr of a str literal
+        data = _json.loads(payload)
+        self.assertEqual(data["pins"], list(range(1, 11)))
+        self.assertEqual(len(data["min"]), 10)
+        self.assertEqual(len(data["max"]), 10)
+        for lo, hi in zip(data["min"], data["max"]):
+            self.assertTrue(0 < lo < hi <= 65535, (lo, hi))
+
+    def test_verification_failure_dies(self):
+        def _fake_run(cmd, capture_output=True, text=True, timeout=None):
+            return MagicMock(returncode=0, stdout="garbage\n", stderr="")
+
+        with patch("subprocess.run", side_effect=_fake_run):
+            try:
+                flash._write_qtr_starter_cal("mpremote", "/p")
+            except flash.FlashError as e:
+                self.assertIn("starter QTR calibration", str(e))
+            else:
+                self.fail("must die on unverified write")
+
+
 class NameWriteSnippetTests(unittest.TestCase):
     """The mpremote ``exec`` snippet must embed the name in a form that
     ``openbricks._read_hub_name`` will accept back (bytes via set_blob)."""

{openbricks-2.6.2 → openbricks-2.7.0}/tests/test_run.py

@@ -339,13 +339,13 @@ class RunFlowTests(unittest.TestCase):
 
         self.assertEqual(rc, 0)
         joined = b"".join(fake.writes)
-        # The SOURCE crossed the link, targeting the run slot's
-        # source path, and no sibling delete was composed. The
-        # button's /program.* is never touched.
+        # The SOURCE crossed the link, targeting the BUTTON slot's
+        # source path (run = upload-then-run since 2.7.0, so a failed
+        # run stays button-rerunnable), and no sibling delete was
+        # composed on the source path.
         self.assertIn(b"hello from hub", joined)
-        self.assertIn(b"'/run.py'", joined)
-        self.assertNotIn(b"'/program.py'", joined)
-        self.assertNotIn(b"'/program.mpy'", joined)
+        self.assertIn(b"'/program.py'", joined)
+        self.assertNotIn(b"'/run.py'", joined)
         self.assertNotIn(b"os.remove", joined)
         self.assertIn("predates precompiled", err.getvalue())
         self.assertIn("1.91.1", err.getvalue())
@@ -367,10 +367,10 @@ class RunFlowTests(unittest.TestCase):
         self.assertNotIn("===", out.getvalue())
 
         joined = b"".join(fake.writes)
-        # Confirm the staging writes the RUN slot and calls
-        # run_program on it — never the button's /program.*.
-        self.assertIn(b"'/run.mpy'", joined)
-        self.assertNotIn(b"'/program.py'", joined)
+        # Confirm the staging writes the BUTTON slot (run =
+        # upload-then-run since 2.7.0) and calls run_program on it.
+        self.assertIn(b"'/program.mpy'", joined)
+        self.assertNotIn(b"'/run.mpy'", joined)
         self.assertIn(b"launcher.run_program", joined)
         # Confirm the control-byte sequence of raw-paste mode.
         self.assertIn(b"\x03\x03", joined)      # Ctrl-C interrupt
@@ -522,11 +522,13 @@ class InlineCommandTests(unittest.TestCase):
         self.assertIn(b"M\\x06", joined)   # .mpy header inside the
         self.assertNotIn(b"print('hello')", joined)  # staged repr
         self.assertIn(b"launcher.run_program", joined)
-        # One-shot runs stage to their OWN slot (1.97.0) — the
-        # BUTTON's /program.mpy must never appear in a run session.
-        self.assertIn(b"'/run.mpy'", joined)
-        self.assertNotIn(b"'/program.mpy'", joined)
-        self.assertNotIn(b"os.remove('/program.py')", joined)
+        # run stages to the BUTTON slot (2.7.0: upload-then-run, so
+        # a failed run stays rerunnable by start press) — the .mpy
+        # staging removes a stale source sibling so the launcher's
+        # source-wins resolution can't run old code.
+        self.assertIn(b"'/program.mpy'", joined)
+        self.assertNotIn(b"'/run.mpy'", joined)
+        self.assertIn(b"os.remove('/program.py')", joined)
 
 
     def test_connect_failure_propagates_as_run_error(self):
@@ -857,7 +859,7 @@ class HostInterruptForwardingTests(unittest.TestCase):
             return None
 
         async def _stub_pick(blink, l, *slot_pair):
-            return run_mod._RUN_TARGET_PATH, False, None
+            return run_mod._TARGET_PATH, False, None
 
         patches = [
             ("_enter_raw_repl", _raw_repl),