Merge pull request #1096 from shorepine/claude/sweet-kepler-b77fdb

OLED: diffed partial updates + background I2C flush task (no more ~300ms display stalls)

Author: bwhitman

AMY_AGENTS.md

@@ -93,6 +93,89 @@ def loop():
 
 ---
 
+## Repeating patterns that must stay tight: put them in `sequencer.AMYSequence`, not `loop()`
+
+Notes sent from `loop()` fire only when Python gets there — anything slow in `loop()`
+(display writes, file/World access, heavy math) pushes them late and the groove flams.
+An `AMYSequence` event lives **inside the audio engine** and repeats sample-accurately no
+matter what Python is doing. Prefer it for any fixed, repeating pattern (drum grooves,
+arps, ostinatos); keep `loop()` for UI, knobs, and evolving the pattern.
+
+`sequencer.AMYSequence(length, divider)` is a looping grid of `length` slots, each
+`1/divider` of a whole note (so `AMYSequence(32, 32)` = one 4/4 bar of 32nd-note slots).
+`seq.add(position, amy.send, synth=…, note=…, vel=…)` schedules a repeating note; it
+returns an event with `.update(position, amy.send, …)` to change it and `.remove()` to
+delete it.
+
+### Example — four-on-the-floor kick + 8th hats that keep time no matter what loop() does
+
+```python
+import amy, sequencer
+
+sequencer.tempo(120)
+amy.send(synth=10, patch=384, num_voices=6, synth_flags=3)   # TR-808 GM kit
+
+seq = sequencer.AMYSequence(32, 32)          # one 4/4 bar, 32nd-note grid
+for pos in (0, 8, 16, 24):
+    seq.add(pos, amy.send, synth=10, note=36, vel=1)         # kick on every beat
+for pos in range(0, 32, 4):
+    seq.add(pos, amy.send, synth=10, note=42, vel=0.3)       # 8th-note closed hats
+
+def loop():
+    pass     # free for UI/display/knobs -- the pattern plays itself
+```
+
+> Source of truth: `tulip/shared/py/sequencer.py` (`AMYSequence`) and
+> `tulip/shared/py/drums.py` (`app.drum_seq.add(position=…, func=amy.send, synth=…,
+> note=…, vel=…)` — the drum machine app schedules every switch this way).
+
+---
+
+## The OLED display: draw via `amyboard.display`, refresh with `.show()` — redraws are diffed, but update on musical boundaries, not every `loop()`
+
+`amyboard.display` is a 128×128 grayscale framebuffer: `.text(s, x, y, col)`,
+`.fill(col)`, `.fill_rect(x, y, w, h, col)`, `.rect`, `.line`, `.pixel`, plus
+`.message(s, row=n)` (one text line with background, includes the refresh). `col` is
+0–255. Text rows are 8px tall; `message()` rows are 12px. All methods are safe no-ops
+when no display is attached, and draw to the on-screen panel in the web simulator.
+
+`display.show()` is cheap: the driver diffs against what the panel already shows and
+transfers **only the rows that changed**, and the transfer itself runs on a background
+firmware task — `show()` queues it and returns in ~1ms instead of blocking Python for
+the 100–200ms a full-screen I2C push takes on the wire. The clear-everything-and-redraw
+idiom is fine, and a `show()` where nothing changed costs ~nothing. Still: refresh when
+the *content* changes (once per bar/beat, on a knob turn), not unconditionally every
+`loop()` call — redrawing in Python isn't free — and put must-stay-tight patterns in
+`AMYSequence` (section above).
+
+### Example — kit name + bar counter, updated once per bar
+
+```python
+import amy, amyboard, sequencer
+
+sequencer.tempo(120)
+amy.send(synth=10, patch=384, num_voices=6, synth_flags=3)
+d = amyboard.display
+step = -1
+
+def loop():
+    global step
+    step += 1
+    if step % 8 == 0:
+        amy.send(synth=10, note=36, vel=1)       # (better: AMYSequence, see above)
+    if step % 32 == 0:                           # once per bar, content changed
+        d.fill(0)
+        d.text("TR-808", 0, 0, 255)
+        d.text("bar %d" % (step // 32), 0, 16, 255)
+        d.show()
+```
+
+> Source of truth: the `Display` class in `tulip/shared/amyboard-py/amyboard.py`;
+> shadow-diff partial updates in `tulip/shared/py/ssd1327.py` / `sh1107.py`;
+> `tulip/amyboardweb/sketches/house_generator.py` (bar-boundary display updates).
+
+---
+
 ## MIDI-controlled parameters: map the CC inside AMY (`midi_cc` / `ic`), don't poll in `loop()`
 
 When the user asks for a synth parameter (resonance, filter cutoff, amp, pan,

tulip/amyboard/amyboard_support.c

@@ -1,5 +1,6 @@
 #include <stdio.h>
 #include <inttypes.h>
+#include <string.h>
 #include "amy.h"
 
 // Stuff just for amyboard -- cv in/out direct , i2c in/out
@@ -8,6 +9,7 @@
 #include "sdkconfig.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
+#include "freertos/message_buffer.h"
 #include "esp_chip_info.h"
 #include "esp_flash.h"
 #include "esp_system.h"
@@ -79,6 +81,76 @@ void i2c_check_for_data() {
 
 
 
+// ---------------------------------------------------------------------------
+// Background I2C write queue.  The OLED framebuffer flush takes ~200ms of bus
+// time at 400kHz; done synchronously from MicroPython it froze Python (and
+// starved the CV tasks' port mutex) for that long.  Python instead enqueues
+// each transaction here and returns immediately; this low-priority task plays
+// them out in order on I2C_NUM_0.  The legacy IDF driver's per-port mutex
+// serializes us against machine.I2C and the CV read/write hooks, and because
+// Python chunks large payloads into small transactions, those users interleave
+// between chunks instead of timing out.  Single producer (the MicroPython
+// task) / single consumer (this task), which is all a MessageBuffer allows.
+
+#define I2C_BG_QUEUE_BYTES 16384      // > one full 8KB OLED frame incl. overhead
+#define I2C_BG_MAX_PAYLOAD 1024       // per-transaction cap (Python sends ~256B)
+#define I2C_BG_TASK_STACK_SIZE 4096
+#define I2C_BG_TASK_PRIORITY (ESP_TASK_PRIO_MIN + 1)  // same as cv_read_task
+#define I2C_BG_TASK_COREID (0)                        // MicroPython runs on core 1
+
+static MessageBufferHandle_t i2c_bg_mb = NULL;
+static volatile uint32_t i2c_bg_errors_count = 0;
+static volatile uint8_t i2c_bg_in_flight = 0;
+
+static void i2c_bg_task(void *pvParameter) {
+    static uint8_t msg[I2C_BG_MAX_PAYLOAD + 1];  // [addr][payload...]
+    for(;;) {
+        size_t n = xMessageBufferReceive(i2c_bg_mb, msg, sizeof(msg), portMAX_DELAY);
+        if(n < 2) continue;
+        i2c_bg_in_flight = 1;
+        esp_err_t ret = i2c_master_write_to_device(I2C_NUM_0, msg[0], msg + 1, n - 1, pdMS_TO_TICKS(100));
+        i2c_bg_in_flight = 0;
+        if(ret != ESP_OK) i2c_bg_errors_count++;
+    }
+}
+
+// Enqueue one I2C write transaction. Returns 0 on success, 1 if it had to be
+// dropped (queue stayed full / payload too big) -- the failure also bumps
+// i2c_bg_errors() so Python can schedule a full panel resync.
+uint8_t amyboard_i2c_bg_write(uint8_t addr, const uint8_t *buf, uint32_t len) {
+    // Only ever called from the MicroPython task (single producer).
+    static uint8_t msg[I2C_BG_MAX_PAYLOAD + 1];
+    if(len == 0 || len > I2C_BG_MAX_PAYLOAD) {
+        i2c_bg_errors_count++;
+        return 1;
+    }
+    if(i2c_bg_mb == NULL) {
+        i2c_bg_mb = xMessageBufferCreate(I2C_BG_QUEUE_BYTES);
+        xTaskCreatePinnedToCore(i2c_bg_task, "i2c_bg", I2C_BG_TASK_STACK_SIZE / sizeof(StackType_t),
+                                NULL, I2C_BG_TASK_PRIORITY, NULL, I2C_BG_TASK_COREID);
+    }
+    msg[0] = addr;
+    memcpy(msg + 1, buf, len);
+    // Blocking here is backpressure: it only happens when more than a whole
+    // queued frame is outstanding, and it bounds how far Python can run ahead.
+    if(xMessageBufferSend(i2c_bg_mb, msg, len + 1, pdMS_TO_TICKS(500)) != len + 1) {
+        i2c_bg_errors_count++;
+        return 1;
+    }
+    return 0;
+}
+
+// Bytes still queued (plus any transaction currently on the wire); 0 == idle.
+uint32_t amyboard_i2c_bg_pending(void) {
+    if(i2c_bg_mb == NULL) return 0;
+    uint32_t queued = I2C_BG_QUEUE_BYTES - (uint32_t)xMessageBufferSpacesAvailable(i2c_bg_mb);
+    return queued + i2c_bg_in_flight;
+}
+
+uint32_t amyboard_i2c_bg_errors(void) {
+    return i2c_bg_errors_count;
+}
+
 #define ADS1015_REGISTER_CONFIG (0x01)
 #define ADS1015_CQUE_DISABLE (0x0003)
 

tulip/amyboardweb/sketches/drum_machine.py

@@ -1,7 +1,7 @@
 # AMYboard Sketch
-# DESCRIPTION: Gamma9001 drum machine: three drum channels at once -- a main kit that rotates through all six banks, TR-909 hats, and a tabla/shaker percussion layer.
+# DESCRIPTION: Gamma9001 drum machine: three drum channels at once -- a main kit that rotates through all six banks, TR-909 hats, and a tabla/shaker percussion layer. The OLED shows the current kit, section position and beat.
 # Top-level code runs once at boot. loop() is called every 32nd note.
-import amy, sequencer
+import amy, amyboard, sequencer
 import random
 
 sequencer.tempo(118)
@@ -22,6 +22,20 @@
 
 amy.send(reverb="0.2,0.5,0.1")
 
+# --- OLED display: kit name, section position, beat. Safe no-ops with no
+# display attached; draws to the panel in the simulator. show() only sends
+# the rows that changed, in the background, so per-beat updates are cheap.
+d = amyboard.display
+
+def draw_kit():
+    d.fill_rect(0, 16, 128, 8, 0)
+    d.text(KITS[kit_idx][1], 0, 16, 255)
+
+d.fill(0)
+d.text("DRUM MACHINE", 0, 0, 255)
+draw_kit()
+d.show()
+
 # GM drum note numbers
 KICK, SNARE, CLAP, RIM = 36, 38, 39, 37
 CHAT, OHAT, CRASH, RIDE = 42, 46, 49, 51
@@ -54,6 +68,7 @@ def loop():
         kit_idx = (kit_idx + 1) % len(KITS)
         amy.send(synth=10, patch=KITS[kit_idx][0], num_voices=6, synth_flags=3)
         amy.send(synth=10, note=CRASH, vel=0.7)  # announce the new kit
+        draw_kit()
 
     # --- Main kit (synth 10) ---
     kicks = kick_synco if bar % 4 == 3 else kick_pattern
@@ -85,3 +100,17 @@ def loop():
         amy.send(synth=12, note=TRIANGLE, vel=0.3)
     if bar == 0 and bar_step == 12:
         amy.send(synth=12, note=COWBELL, vel=0.5)
+
+    # --- Display: bar dots + beat blocks, refreshed once per beat ---
+    if bar_step % 8 == 0:
+        beat = bar_step // 8
+        if beat == 0:  # new bar: move the section-position dot
+            for b in range(BARS_PER_SECTION):
+                x = 4 + b * 15
+                d.fill_rect(x, 32, 11, 8, 255 if b == bar else 0)
+                d.rect(x, 32, 11, 8, 255)
+        for b in range(4):
+            x = 4 + b * 32
+            d.fill_rect(x, 52, 22, 12, 255 if b == beat else 0)
+            d.rect(x, 52, 22, 12, 255)
+        d.show()

tulip/shared/amyboard-py/amyboard.py

@@ -13,6 +13,46 @@ def web():
     return (tulip.board()=="AMYBOARD_WEB")
 
 
+class _BGWriteI2C:
+    """i2c-shaped adapter that enqueues writes on the firmware's background
+    I2C task (tulip.i2c_bg_write) instead of blocking Python on the bus, so a
+    display refresh returns immediately and the bytes clock out at 400kHz in
+    the background.  Payloads are chunked so the CV tasks' small transactions
+    on the same port interleave between chunks instead of timing out.
+
+    writevto() assumes bufs[0] is a one-byte OLED control prefix that must be
+    repeated on each chunk (true of the ssd1327/sh1107 drivers' write_data);
+    the panel's address pointer carries across transactions, so consecutive
+    chunks land contiguously on the glass."""
+    _CHUNK = 256
+
+    def writeto(self, addr, buf):
+        tulip.i2c_bg_write(addr, buf)
+
+    def writevto(self, addr, bufs):
+        bufs = list(bufs)
+        prefix = bytes(bufs[0])
+        data = bufs[1] if len(bufs) == 2 else b''.join(bytes(b) for b in bufs[1:])
+        step = self._CHUNK - len(prefix)
+        if len(data) <= step:
+            tulip.i2c_bg_write(addr, prefix + bytes(data))
+            return
+        mv = memoryview(data)
+        for off in range(0, len(data), step):
+            tulip.i2c_bg_write(addr, prefix + bytes(mv[off:off + step]))
+
+
+def _i2c_bg_available():
+    return hasattr(tulip, 'i2c_bg_write')
+
+
+def _i2c_bg_drain(max_ms=500):
+    """Wait (briefly, bounded) for the background I2C queue to empty."""
+    while tulip.i2c_bg_pending() and max_ms > 0:
+        time.sleep_ms(5)
+        max_ms -= 5
+
+
 class Display:
     """Unified display interface for ssd1327, sh1107, and web framebuffer.
 
@@ -29,12 +69,18 @@ def __init__(self, rotate=0):
         self._fb = None        # framebuf used for drawing
         self._buf = None       # raw byte buffer backing the framebuf
         self._is_web = web()
+        self._bg = False       # panel writes routed through the background I2C task
+        self._last_bg_err = 0
 
         if self._is_web:
             import framebuf
             self._buf = bytearray(self.WIDTH * self.HEIGHT // 2)
             self._fb = framebuf.FrameBuffer(self._buf, self.WIDTH, self.HEIGHT, framebuf.GS4_HMSB)
         else:
+            if _i2c_bg_available():
+                # a previous Display instance may still have queued panel
+                # writes; let them finish before probing/re-initing
+                _i2c_bg_drain()
             # Try ssd1327 first, then sh1107.  rotate only applies to the sh1107
             # (the panel is square, so WIDTH/HEIGHT are unchanged by rotation).
             try:
@@ -50,6 +96,14 @@ def __init__(self, rotate=0):
                     self._fb = hw  # sh1107 *is* a FrameBuffer subclass
                 except Exception:
                     pass  # no physical display
+            if self._hw is not None and _i2c_bg_available():
+                # Probe + init above ran synchronously (so a missing panel
+                # raises and we fall through).  From here on, route panel
+                # writes through the background queue: show() then returns
+                # immediately instead of blocking on the I2C transfer.
+                self._hw.i2c = _BGWriteI2C()
+                self._bg = True
+                self._last_bg_err = tulip.i2c_bg_errors()
 
     @property
     def buffer(self):
@@ -115,14 +169,28 @@ def message(self, message, row=0, inverse=False):
 
     # -- refresh --
 
-    def show(self):
-        """Push the framebuffer to the display hardware (or web bridge)."""
+    def show(self, full=False):
+        """Push the framebuffer to the display hardware (or web bridge).
+
+        Both hardware drivers diff against what the panel already shows and
+        transfer only the changed portion, and on firmware with the
+        background I2C task the transfer itself happens off the Python
+        thread — show() just queues it and returns.  Pass full=True to force
+        the entire framebuffer out.
+        """
         if self._fb is None:
             return
         if self._is_web:
             tulip.framebuf_web_update(self._buf)
         elif self._hw is not None:
-            self._hw.show()
+            if self._bg:
+                err = tulip.i2c_bg_errors()
+                if err != self._last_bg_err:
+                    # a queued write failed, so the panel may no longer match
+                    # the driver's shadow -- resync everything this refresh
+                    self._last_bg_err = err
+                    self._hw._shadow_valid = False
+            self._hw.show(full)
 
     # convenience alias so old code calling display_refresh() on a Display works
     refresh = show

tulip/shared/modtulip.c

@@ -632,6 +632,33 @@ STATIC mp_obj_t tulip_amyboard_send(size_t n_args, const mp_obj_t *args) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(tulip_amyboard_send_obj, 1, 1, tulip_amyboard_send);
 
+#ifdef ESP_PLATFORM
+// Background I2C write queue (amyboard_support.c): the OLED drivers enqueue
+// their transactions here so display refreshes don't block Python while the
+// bytes clock out at 400kHz.
+extern uint8_t amyboard_i2c_bg_write(uint8_t addr, const uint8_t *buf, uint32_t len);
+extern uint32_t amyboard_i2c_bg_pending(void);
+extern uint32_t amyboard_i2c_bg_errors(void);
+
+STATIC mp_obj_t tulip_i2c_bg_write(mp_obj_t addr_obj, mp_obj_t buf_obj) {
+    mp_buffer_info_t bufinfo;
+    mp_get_buffer_raise(buf_obj, &bufinfo, MP_BUFFER_READ);
+    amyboard_i2c_bg_write((uint8_t)mp_obj_get_int(addr_obj), (const uint8_t *)bufinfo.buf, (uint32_t)bufinfo.len);
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_2(tulip_i2c_bg_write_obj, tulip_i2c_bg_write);
+
+STATIC mp_obj_t tulip_i2c_bg_pending(void) {
+    return mp_obj_new_int(amyboard_i2c_bg_pending());
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(tulip_i2c_bg_pending_obj, tulip_i2c_bg_pending);
+
+STATIC mp_obj_t tulip_i2c_bg_errors(void) {
+    return mp_obj_new_int(amyboard_i2c_bg_errors());
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(tulip_i2c_bg_errors_obj, tulip_i2c_bg_errors);
+#endif // ESP_PLATFORM
+
 
 
 
@@ -1705,6 +1732,11 @@ STATIC const mp_rom_map_elem_t tulip_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_amyboard_start), MP_ROM_PTR(&tulip_amyboard_start_obj) },
     { MP_ROM_QSTR(MP_QSTR_amyboard_set_midi_out), MP_ROM_PTR(&tulip_amyboard_set_midi_out_obj) },
     { MP_ROM_QSTR(MP_QSTR_bootloader_mode), MP_ROM_PTR(&tulip_bootloader_mode_obj) },
+#ifdef ESP_PLATFORM
+    { MP_ROM_QSTR(MP_QSTR_i2c_bg_write), MP_ROM_PTR(&tulip_i2c_bg_write_obj) },
+    { MP_ROM_QSTR(MP_QSTR_i2c_bg_pending), MP_ROM_PTR(&tulip_i2c_bg_pending_obj) },
+    { MP_ROM_QSTR(MP_QSTR_i2c_bg_errors), MP_ROM_PTR(&tulip_i2c_bg_errors_obj) },
+#endif
 #else
     #ifndef AMYBOARD_WEB
     { MP_ROM_QSTR(MP_QSTR_display_clock), MP_ROM_PTR(&tulip_display_clock_obj) },