AMYboard: phase-lock sketch loop() to the sequencer downbeat

Sketch loop() callbacks fire on the AMY sequencer's absolute tick grid
(every 6 ticks = a 32nd note), the same clock AMYSequence events use --
but a sketch's own step counter starts at 0 whenever the sketch loads,
which is some arbitrary 32nd note inside the bar. Any pattern built on
that counter plays at a constant phase offset from AMY-sequenced
patterns (e.g. dx7_groove_128_bpm's bass/piano/arp vs. its drums).

Two changes in _start_sketch_loop:
- The first loop() call is held until the next bar boundary
  (tick % 192 == 0 at 48 PPQ, 4/4), so existing sketches' counters
  start on the downbeat, in phase with AMYSequence bars.
- If the sketch declares loop(step), it gets the global 32nd-note
  index on the bar-locked grid (step % 32 == 0 is always a downbeat).
  Deriving position from step instead of a local counter also can't
  drift if a callback is ever dropped (mp_sched_schedule queue full).
  Plain loop() still works via a one-time TypeError fallback.

The default sketch template (amyboard.py and both spss.js copies)
now uses loop(step) and documents the grid.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bwhitman

tulip/amyboardweb/static/spss.js

@@ -90,9 +90,11 @@ const CURRENT_ENV_DIR = CURRENT_BASE_DIR;
 // there is no MicroPython. Keep it in sync with amyboard.py's DEFAULT_SKETCH_SOURCE.
 var AMYBOARD_DEFAULT_SKETCH =
   "# AMYboard Sketch\n" +
-  "# Code put here runs first, then loop() is called every 32nd note.\n" +
+  "# Code put here runs first, then loop(step) is called every 32nd note,\n" +
+  "# starting on a bar downbeat. step counts 32nd notes on the sequencer's\n" +
+  "# bar-locked grid, so step % 32 == 0 is always a downbeat.\n" +
   "import amyboard, amy\n\n" +
-  "def loop():\n    pass\n\n" +
+  "def loop(step):\n    pass\n\n" +
   "# Do not edit. Set automatically by the knobs on AMYboard Online.\n" +
   "_auto_generated_knobs = \"\"\"\n\"\"\"\n";
 function _get_default_sketch() {
@@ -5635,7 +5637,7 @@ async function _reset_amyboard_send_and_cleanup() {
     console.log('reset: zP factory_reset sent');
     await sleep_ms(2000);
     // Set JS state to defaults.
-    var defaultSketch = "# AMYboard Sketch\n# Code put here runs first, then loop() is called every 32nd note.\nimport amyboard, amy\n\ndef loop():\n    pass\n\n# Do not edit. Set automatically by the knobs on AMYboard Online.\n_auto_generated_knobs = \"\"\"\n\"\"\"\n";
+    var defaultSketch = "# AMYboard Sketch\n# Code put here runs first, then loop(step) is called every 32nd note,\n# starting on a bar downbeat. step counts 32nd notes on the sequencer's\n# bar-locked grid, so step % 32 == 0 is always a downbeat.\nimport amyboard, amy\n\ndef loop(step):\n    pass\n\n# Do not edit. Set automatically by the knobs on AMYboard Online.\n_auto_generated_knobs = \"\"\"\n\"\"\"\n";
     // SYNC 2: clear the knob log so a later Write doesn't re-emit the old
     // session's knobs (the default sketch has an empty knobs block).
     if (window.knob_log && typeof window.knob_log.clear === 'function') window.knob_log.clear();

tulip/shared/amyboard-py/amyboard.py

@@ -197,10 +197,12 @@ def show(self, full=False):
 
 DEFAULT_SKETCH_SOURCE = """\
 # AMYboard Sketch
-# Code put here runs first, then loop() is called every 32nd note.
+# Code put here runs first, then loop(step) is called every 32nd note,
+# starting on a bar downbeat. step counts 32nd notes on the sequencer's
+# bar-locked grid, so step % 32 == 0 is always a downbeat.
 import amyboard, amy
 
-def loop():
+def loop(step):
     pass
 
 # Do not edit. Set automatically by the knobs on AMYboard Online.
@@ -726,23 +728,53 @@ def run_sketch():
 
 
 def _start_sketch_loop(loop_fn):
-    """Schedule loop_fn via TulipSequence (every 32nd note, ~60ms)."""
+    """Schedule loop_fn via TulipSequence (every 32nd note).
+
+    Sketch loops ride the AMY sequencer's absolute tick count -- the same
+    clock AMYSequence events fire on. The first call is held until a bar
+    boundary (4 beats), so a sketch that keeps its own step counter starts
+    on the downbeat, in phase with any AMY-sequenced patterns. A sketch can
+    instead declare loop(step): step is the global 32nd-note index on that
+    bar-locked grid (step % 32 == 0 is always a downbeat), which stays in
+    phase even if a callback is ever dropped.
+    """
     import sequencer
     global _sketch_seq
-    _loop_running = False
+    ticks_per_step = int((4.0 / 32.0) * sequencer.PPQ)  # one 32nd note
+    ticks_per_bar = 4 * sequencer.PPQ
+    _busy = False
+    _started = False
+    _takes_step = None
 
     def _guarded_loop(tick):
-        nonlocal _loop_running
-        if _loop_running:
+        nonlocal _busy, _started, _takes_step
+        if _busy:
             return
-        _loop_running = True
+        _busy = True
         try:
-            loop_fn()
+            if not _started:
+                if tick % ticks_per_bar:
+                    return  # hold loop() until the next downbeat
+                _started = True
+            step = tick // ticks_per_step
+            if _takes_step is None:
+                # First call decides the signature: prefer loop(step), fall
+                # back to loop() for sketches that don't take an argument.
+                try:
+                    loop_fn(step)
+                    _takes_step = True
+                except TypeError:
+                    _takes_step = False
+                    loop_fn()
+            elif _takes_step:
+                loop_fn(step)
+            else:
+                loop_fn()
         except Exception as e:
             print("sketch.loop() error:")
             sys.print_exception(e)
         finally:
-            _loop_running = False
+            _busy = False
 
     _sketch_seq = sequencer.TulipSequence(32, _guarded_loop)