Adds pico-explorer/ as a parallel CircuitPython firmware target alongside the 52Pi
Kit in pico-cp/. Same engine, same program-string grammar, same programs.json, same
live-sync protocol. Read-only on the device (no on-device beat editing); the web
editor's Live sync mirrors all edits in real time and the Explorer emits its own
play/stop/bpm/sel deltas back.
Hardware (Pimoroni Explorer PIM744):
- RP2350B + 2.8" ST7789V 320x240 LCD (8-bit parallel; CircuitPython's official
board definition pre-builds the BusDisplay so we just use board.DISPLAY).
- 6 user buttons - A/B/C on the left of the screen, X/Y/Z on the right.
- Piezo speaker on GP12 (PWM) with amp enable on GP13.
- I2C QwSTEMMA on GP20/21 - reserved, unused by the firmware.
- No touchscreen, no joystick, no RGB LED. Run state shows on a tiny on-screen dot.
Buttons:
- A = play/stop. B = tap tempo. C = menu.
- X = prev track (hold-repeat). Z = next track (hold-repeat).
- Y = tempo -1 (hold-repeat; -5 after 1.5s).
- X+Z chord = tempo +1 (mirrors Y).
- In a menu: X/Z move the row cursor, Y decrements, A cycles/increments/selects,
B = back, C = close.
Files added:
- pico-explorer/{boot.py, code.py, app.py, programs.json, README.md}.
app.py = 1444 lines (~73KB source -> 29.8KB compiled .mpy).
- info-explorer.html.
Files touched:
- pico-cp/app.py: bump to 0.0.23. Version-query (SysEx 0x02 -> 0x03) reply now
includes the device id as "K;<version>" (backward-compat: editor parses
"contains ';'?" - old firmware sent bare version, treated as K).
- editor.html + editor-beta.html: _parseDeviceReply() splits id;version, FW_PATHS
maps id to .py/.mpy URL pair, so Update firmware now pushes the right binary.
- build.sh + deploy.sh: precompile pico-explorer/app.py -> dist/explorer-app.mpy,
zip pm_x1_circuitpy.zip alongside pm_k1_circuitpy.zip, ship
pico-explorer-app.{py,mpy} next to pico-cp-app.{py,mpy}.
- docs/livesync-protocol.md: new section 7 - per-device emit/apply matrix.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Push to 0.0.14 stalls at ~150 chunks with the MIDI badge going gray (=device silent for
>1s). It's an occasional slow flash flush on the device side — the file buffer fills,
flush takes several seconds, the editor's 4s timeout cuts it off too early.
- Editor: bump per-chunk ACK timeout 4s -> 10s; progress log every 25 chunks now with
elapsed seconds so you can see it advancing through a slow chunk.
- Device 0.0.14: flush per chunk (small, predictable per-chunk cost instead of
infrequent multi-second bursts) + gc.collect() every 50 chunks to keep the heap
fresh during a long push.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Push advanced to ~150/506 chunks then stalled intermittently. With Device audio on, the
heartbeat (0xFE every 250ms + a clock SysEx every ~3s) shares the MIDI link with the
firmware chunks and intermittently costs a chunk its ACK. Pause the heartbeat for the
duration of _pushFirmware and resume after.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Trace showed the push reaching "pushing" then stalling. Two causes: (1) _send went to
ALL MIDI outputs incl. "Midi Through Port-0" (a loopback that just echoes back); (2) the
512-char chunks overran the Pico's USB-MIDI receive buffer, so the device never saw the
end of a chunk's SysEx and never ACKed.
- _send now targets only the device port (name match pico/circuitpython/usb_midi; falls
back to all outputs if none match) - no loopback echo.
- Firmware chunks 512 -> 64 base64 chars (a SysEx that fits the RX buffer); log progress
every 50 chunks + a "committing" line so the console shows it advancing.
Editor-only; hard-reload to pick it up (no firmware change).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
User reports the updater does nothing with no visible error. Every code path shows a
dialog, so it's bailing before/at one of them (likely browser dialog-suppression making
confirm() return false, a stale/cached editor, or an uncaught throw). Log each step so a
console trace pinpoints where it stops.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The single-file app grew to ~57KB; CircuitPython compiling it at boot fragments the
RP2040 heap so badly that the fonts can't get a contiguous block (161KB free, yet a
~16KB alloc fails). Fix: precompile to app.mpy (Adafruit mpy-cross for CP 10.2.1, emits
CircuitPython mpy v6) so the device loads bytecode without compiling -> no fragmentation.
- build.sh precompiles pico-cp/app.py -> dist/app.mpy via tools/mpy-cross (gitignored
binary); the bundle ships app.mpy (NOT app.py); serves pico-cp-app.mpy + pico-cp-app.py
(the .py only for the editor's version regex + as readable reference).
- Loader (code.py) imports app.mpy and rolls back app.bak as .mpy.
- One-click updater now pushes the .mpy: editor base64-encodes it and sends it over the
existing flow-controlled chunked transport (512-char = mult-of-4 chunks); the device
base64-decodes each chunk to /app.new and verifies the CircuitPython .mpy header
(magic 'C', v6, >=4KB) before the A/B install. Version still read from the served .py.
Verified: mpy-cross emits magic 'C'/v6; build produces a 21.8KB app.mpy; editing-logic
harness + scene render still pass; and a simulated push (base64 -> 57 chunks -> a2b_base64)
reassembles the .mpy byte-exact and passes the device's header check.
One-time recovery: delete app.py from the drive, copy app.mpy + code.py from the new zip.
After that, updates are one-click again (and can't brick: header check + A/B rollback).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The standard editor defaults (Styles / Practice / Song) are baked into app.py as
BUILTIN_SETLISTS (ASCII-fied — emoji/accents would break the 7-bit push + the fonts),
so they update with firmware and the user can't change or delete them. User playlists
live separately in programs.json and are merged after the built-ins.
Device:
- Set-list model: self.setlists = built-ins + user lists (deduped by normalized title,
so a baked built-in always wins). load()/goto() work within the current list.
- Navigation: a set-list "tab" (small, above the title) shows playlist + position,
muted for built-in / cyan for user; TAP it to switch playlists. Joystick L/R = item.
- SysEx 0x10 (push) writes programs.json -> rebuild user lists; built-ins untouched.
- Shipped programs.json is now empty ({"setlists":[]}) — built-ins come from firmware.
Editor:
- "Save to device" now syncs only YOUR set lists (filters out the built-in seeds) in the
new {setlists:[...]} format; warns if you have none. Load-from-device imports both the
new multi-list and old flat formats.
Verified in the harness: 3 read-only built-ins, set-list switching, user-list merge +
dedup of a pushed "styles", and the ramp engine on a built-in track (80->84->88, +4/4 bars).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
APP_VERSION -> 0.0.6. Device firmware + editor change in lockstep — one-time manual
copy of 0.0.6 needed (the broken single-shot updater can't deliver it).
Update transport (fixes the failed/bricking updates):
- Editor now pushes app.py in 512-byte flow-controlled chunks: begin(0x21,len) ->
data(0x22)* -> commit(0x23), waiting for each ACK before the next. A single ~38KB
SysEx overran the device's USB-MIDI input buffer and arrived corrupt.
- Device writes chunks straight to /app.new, and on commit verifies length + no NUL +
App().run()/APP_VERSION present before the A/B install; rejects (NAK) otherwise and
keeps the working build. All errors caught -> never bricks.
Run/stop indicator moved off the screen onto the RGB LED (per feedback that recoloring
the whole background is wrong — it forces a full-screen SPI repaint and fringes the
anti-aliased text):
- Dim GREEN when stopped ("on"), dim RED while playing; the beat pulse flashes brighter
and now decays back to the running base instead of to black. Background is static black.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The editor that ships on the device opens via file://, whose null origin can't
fetch() anything — so "Update firmware" died at the download-the-latest step
(CORS-blocked) before the USB-MIDI push. Now _firmwareSource() tries the site
(same-origin on the https editor; absolute URL when online) and, failing that,
lets the user pick app.py — mirroring the programs.json download/drag fallback.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Split the CircuitPython firmware into a tiny stable loader (code.py) + the application (app.py,
carries APP_VERSION). The editor's ⋯ → "⬆ Update firmware" queries the device version (SysEx 0x02
-> 0x03 reply), fetches the latest app from the site (/pico-cp-app.py), shows device-vs-latest, and
pushes the new app.py over USB-MIDI (SysEx 0x20). The device installs it to a trial slot (old build
kept as app.bak), reboots, and the loader AUTO-ROLLS-BACK to app.bak if the new build fails to start;
a build that runs cleanly ~5s is confirmed (clears /trial). No BOOTSEL, no dragging; Chromium/Firefox.
app.py forced to pure ASCII so it pushes raw (no base64); SysEx buffer raised to 60KB.
build.sh/deploy.sh: bundle code.py+app.py and serve /pico-cp-app.py. Docs updated.
Verified in CPython: version reply, update install+reboot+ACK, rollback file dance; editor loads clean
with the updater wired.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Firmware (pico-cp/): the Pico now owns its filesystem by default (boot.py), so it can save the
practice log and write editor-pushed set lists; the drive is read-only to the computer, which also
protects the firmware. Hold button A at power-on for editor mode (drive writable; universal drag).
- Replaced the on-screen touch buttons with an on-device PRACTICE LOG (time · BPM · duration ·
track), newest-first, persisted to /history.json next to programs.json. Plays < 5s aren't logged;
tap a row twice to delete it. Real timestamps once the editor syncs the clock.
- USB-MIDI SysEx receiver: clock-set (0x01 -> RTC) and program-push (0x10 -> write programs.json,
reload, ACK/NAK). disable autoreload so our own writes never self-restart.
- Fixed swing: the parser was discarding the 's' flag, so /2s never swung. Now the scheduler uses a
per-step duration with long-short (2:1, SWING_RATIO 2/3) pairs on even subdivisions, matching the
web engine. Verified: ride:4/2s -> 266/133ms vs straight 200/200.
Editor (editor.html): requestMIDIAccess({sysex:true}); Save to device now pushes programs.json as
SysEx to the device (+ clock sync), waits for ACK, shows "Saved ✓", and falls back to downloading the
file (drag onto the drive in editor mode) when no device answers. Heartbeat also keeps the clock synced.
Web MIDI works in Chromium AND Firefox; the drag fallback covers any browser/OS incl. Safari.
Docs (pico-cp/README, info-kit, README) updated for the two modes, push programming, and the log.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The editor's 'Device audio' now sends a MIDI Active-Sensing heartbeat (0xFE, every 250ms)
to the device while on. The firmware reads usb_midi.ports[0]; while it hears the heartbeat
(<1s) it shows a green 'MIDI' badge top-right and silences the buzzer (the computer plays);
~1s after it stops, it reverts to the buzzer and hides the badge. Manual MUTE_BUZZER still
works. Verified headless: host detected -> MIDI shown + buzzer duty 0; timeout -> reverts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
User reported no computer audio + 'no device being controlled'. Add visibility to
diagnose: the button now shows the connected MIDI input's name (or 'no device'), the
toggle alert lists detected inputs, and the button pulses green on each Note-On
received — so it's clear whether the device is seen and whether notes are arriving.
Also call ensureAudio() in the message handler as a guard.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Firmware (pico-cp/code.py): on every click, send a USB-MIDI note-on per firing lane —
GM drum note by voice (SOUND_GM), velocity by level (accent/normal/ghost) — via the
default-enabled usb_midi.ports[1]. Polyphonic, so the computer plays the full groove.
New CONFIG: MIDI_ENABLED (default on), MUTE_BUZZER (silence the buzzer when using
computer audio).
Editor (editor.html): a '🎹 Device audio' toggle uses the Web MIDI API
(requestMIDIAccess) to voice incoming notes through the existing synth — Note-On ->
GM_NUM[note] / velocity-to-gain -> playInstrument(). The device is the clock; the
browser is the sound module, locked in sync. Chrome/Edge.
Verified: firmware emits the right notes (kick+hat on beat 1 of four-on-the-floor,
snare's rest skipped); editor loads clean with the toggle + handlers present. Docs
(info-kit, both READMEs) updated. The on-device buzzer/screen still work standalone.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add to the editor's set-list ⋯ menu:
- 📟 Save to device — writes the active set list as programs.json (the same file the
PM_K-1 firmware reads). Uses the File System Access API to write straight onto the
CIRCUITPY drive (Chrome/Edge); falls back to a download to drag on. Reuses
setupToPatch() per item -> {title, programs:[{name, prog}]}.
- 📥 Load from device — reads a programs.json back into a new set list (patchToSetup
per item; reuses the existing import path).
Bundle the built editor.html into pm_k1_circuitpy.zip so the drive carries its own
offline programmer. info-kit + pico-cp/README document the workflow.
Verified: editor loads with no console errors; both menu buttons + all four functions
present; zip contains editor.html. (FSA save needs a real user gesture to test on-device.)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Editor: per-lane gain knob (drag/scroll/double-click, dB, applied at schedule
time — no stutter); program box now decodes base64 set-list codes + lints
(clear ✓/✗ message). When embedded it posts its program to the parent.
Landing (Concepts) rebuilt to the spec: description first, the EDITOR open by
default in a live viewport, a summary pane per form factor (click loads it into
the viewport), and a program I/O box that shows the current program decoded (not
base64), accepts plain text OR a base64 set-list code, lints it, loads it into
the viewport, and copies it. Viewport auto-sizes + reflects the device's posted
program. Engine codec inlined for decode/lint.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Remove the VCSL sample kit entirely (editor 351K → 141K). All voices are
synthesized; the friendly GM names now alias to the punchier 808/909 renders
(KIT_ALIAS). build.sh drops the @BUILD:samples inlining; assets/samples.json gone.
- Conventions (backward-compatible): GM note-number aliases (36=kick…), '-'/'_'
rest aliases in step patterns, Euclidean (k,n[,rot]) shorthand.
- Per-lane gain in dB (@<db> in the grammar) applied as a velocity multiplier at
schedule time — no stutter; threaded through every host's buildMeters + the
editor's lanes (knob UI comes in Phase B).
- 15/15 engine round-trip tests pass; pages console-clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Shared header/footer/chrome (src/header.html, src/footer.html, src/chrome.js)
now on every page: editor (header above its app toolbar), player, teacher,
stage, micro, showcase, embed. chrome.js defers to DOMContentLoaded so the
footer version stamps regardless of placement. Player's fullscreen toggle
relocated out of the header to a floating control.
- Open = Info: each form-factor page is self-contained — a more-detailed
description (.about) + an expandable "Spec & BOM" (<details class="spec">,
hidden in embed). info-*.html retired; build/deploy/README updated.
Next: teacher-style dimensioned front + top/side views + loading panels for
Stage, Micro and Showcase.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Concepts is now the landing (/): index.html is the form-factor gallery with the
LIVE widget embedded in every box (editor/teacher/stage/micro/showcase/initial),
on the shared header/footer. concepts.html retired; every "Concepts" link → /.
- New shared chrome partials src/header.html, src/footer.html, src/chrome.js
(assembled by build.sh) + .site-foot / details.spec styles in base.css. Applied
to the landing + showcase this pass.
- Showcase redesign per spec: the pendulum bar IS the display — each lane's
subdivisions/accents ride along the rod as moving RGB light (all meters combined);
transparent outside the body (no black window); a printed tempo scale on the
vertical axis with a draggable weight to set tempo; start is an external button
(the real unit starts when lifted from its holder).
Next pass: roll the shared header/footer onto the remaining pages (incl. the editor
header-above-toolbar), merge Open=Info into one page per form factor with the
expandable Info & BOM, and add teacher-style dimensioned views to Stage/Micro/Showcase.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sync: the visual playhead now advances on a latency-compensated clock
(currentTime − outputLatency||baseLatency) so the on-screen pulse lands when the
click is HEARD, not when it's queued — previously the visual could lead the audio
by the output buffer / Bluetooth latency (up to ~a subdivision). Applied to
editor, player, teacher, and the new pages; also bound the visual queue (vq trim).
No data races: single-threaded; only the rAF draw touches vqPtr/currentStep, and
each vq entry carries the exact scheduled time of its sound.
stage.html — foot-pedal stompbox: two heavy footswitches (Tap=tempo / hold=start-
stop, Next=item / hold=prev), 1/4" expression-pedal input → tempo sweep, big
floor-readable RGB beat light + angled TFT, analog instrument pass-through.
showcase.html — pyramid display piece: an RGB-light pendulum easing to each beat
plus per-lane segment rows showing subdivisions/accents/mutes (canvas).
Both: dual USB-C (data+power and power-thru) to daisy-chain off one source.
Wired into embed.js (stage, showcase variants), build.sh, deploy.sh, the
concepts gallery + landing cards, info-stage.html (~$52) + info-showcase.html
(~$39) with BOMs, and the README.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The site now opens on a proper front door: a hero (logo + tagline + pitch),
an "Open the Editor →" CTA, and form-factor cards (Editor, Stage, Micro, Embed)
linking out to each page + info. The PE-1 editor app moves from index.html to
editor.html; every "Editor"/"Open" link, the embed.js editor variant, and the
editor's own brand-logo (now → /) are repointed. build.sh + deploy.sh build and
publish both index.html (landing) and editor.html (app).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
