PicoCalc MicroPython

A MicroPython firmware and script collection for the Clockwork Pi PicoCalc handheld device, powered by the Raspberry Pi Pico 2W. Features:

• 320x320 LCD display with flicker-free rendering
• Membrane keyboard with VT100 terminal
• Categorized, arrow-key navigable app menu (auto-hides libraries)
• Games (Tetris, Snake), 4-instrument Synthesizer, Strudel live-coding music, WiFi Manager, local LLM client (Ollama)
• SSH client with ECDH-SHA2-NISTP256, AES-128-CTR encryption, interactive VT100 terminal
• Development dashboard with file manager, editor, diff, REPL, eject
• SD card script auto-discovery

Quick Start

• YouTube PicoCalc 2.0 Demo: https://youtu.be/gf3ittEwFJ8

1. Flash the Firmware

1. Power off the PicoCalc and unplug USB.
2. Hold BOOTSEL on the Pico 2W, then connect USB.
3. A drive named RP2350 appears.
4. Copy MicroPython/firmware/picocalc_micropython_pico2w.uf2 to that drive.
5. The device reboots automatically.

2. Deploy Files to the Device

Option A: Dashboard (Recommended)

The easiest way -- a local web UI that handles everything:

python3 MicroPython/tools/dashboard.py

This opens a browser dashboard where you can:

• Deploy All -- pushes boot files, modules, and scripts in one click
• Browse device files, view diffs, push individual files
• Drag-and-drop .py files to upload
• Side-by-side diff -- click a modified file to see device vs local changes color-coded
• New script -- create scripts from a starter template with one click
• REPL -- run Python on the device from the browser (30s timeout per command)
• Eject -- safely disconnect with on-device countdown, then unplug USB

First run will prompt to install mpremote if needed. Requires Python 3.7+.

Adding new files: Scripts in modules/ and sd/py_scripts/ are auto-discovered by the dashboard. Root-level files (like boot.py) must be added to FILE_MAP in dashboard.py to appear.

Option B: AI-Assisted Development (Vibe Coding)

Let your AI coding assistant talk directly to the PicoCalc -- write code, push it, test on device, iterate, all from the AI conversation.

MCP Server (Recommended)

MCP gives AI tools native access to the device with no dashboard running. Install from PyPI:

pip install picocalc-mcp

Then add to your .mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "picocalc": {
      "command": "picocalc-mcp"
    }
  }
}

Or run directly from the repo: "args": ["/path/to/PicoCalc/mcp/mcp_server.py"]

Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible tool. Full setup guide: MCP_README.md

See it in action: MCP & Dashboard Demo

Claude Code Skills (Optional)

For Claude Code users, the code-skills repo provides PicoCalc-specific skills that teach the AI how to write correct apps, use the hardware APIs, review code, and handle device operations. The MCP server gives the AI hands to interact with the device; the skills give it the knowledge to build for it.

# With skill-deployer installed, just paste a URL:
"install this skill https://github.com/LofiFren/code-skills/tree/main/skills/picocalc-app"

Dashboard REST API (Legacy)

If you already have the dashboard running, AI tools can also use its HTTP endpoints:

curl -s http://localhost:8265/api/device                          # Device status
curl -s -X POST http://localhost:8265/api/exec -H 'Content-Type: application/json' \
  -d '{"code": "print(1+1)"}'                                     # Run Python on device
curl -s -X POST http://localhost:8265/api/push -H 'Content-Type: application/json' \
  -d '{"file": "sd/py_scripts/my_app.py"}'                        # Push file to device
curl -s "http://localhost:8265/api/diff?file=sd/py_scripts/synth.py"  # Diff local vs device
curl -s -X POST http://localhost:8265/api/eject                   # Safe disconnect

All endpoints: /api/device, /api/exec, /api/push, /api/pull, /api/files, /api/diff, /api/local/tree, /api/eject, /api/reset, /api/cleanup

Option C: Manual

Use Thonny, mpremote, or rshell to copy files to the Pico's internal flash.

Copy these to the Pico root (/):

MicroPython/boot.py       --> /boot.py
MicroPython/main.py       --> /main.py
MicroPython/modules/      --> /modules/     (entire directory)

Copy SD card scripts:

MicroPython/sd/py_scripts/*.py  --> SD card /py_scripts/

Do NOT copy these to the device (they run on your computer, not the PicoCalc):

tools/             <-- Dashboard web UI (runs on your computer)
picocalcdisplay/   <-- C source, compiled into firmware
vtterminal/        <-- C source, compiled into firmware
firmware/          <-- UF2 images and Dockerfile

3. Prepare the SD Card

1. Format an SD card as FAT32 (4GB-32GB recommended).
2. Create a py_scripts folder on the SD card.
3. Copy all .py files from MicroPython/sd/py_scripts/ into that folder.
4. Insert the SD card into the PicoCalc.

Or use the Dashboard -- click Deploy Scripts to push all scripts to the SD card over USB.

4. Boot

Power cycle the PicoCalc. The boot splash shows initialization progress, then the main menu appears with arrow-key navigation.

Repository Structure

MicroPython/
|-- boot.py                  --> Copy to device /
|-- main.py                  --> Copy to device / (launches menu)
|-- boot_thonny.py           --> Deploy as /boot.py for Thonny users
|-- boot_dev.py              --> Deploy as /boot.py for dev mode (REPL only)
|-- cleanup.py               --> (Optional) one-time cleanup, or use dashboard Cleanup button
|-- modules/                 --> Copy to device /modules/
|   |-- picocalc.py              Hardware abstraction (display + keyboard)
|   |-- vt.py                    VT100 terminal emulator
|   |-- py_run.py                Categorized app menu (auto-hides libraries)
|   |-- enhanced_sd.py           SD card initialization
|   |-- picocalc_system.py       System utilities
|   |-- sdcard.py                SD card driver
|   |-- checksd.py               SD card verification
|   |-- pye.py                   Built-in text editor
|   |-- colorer.py               Terminal color support
|   |-- default_style.py         Syntax highlighting styles
|   |-- highlighter.py           Code syntax highlighting
|   |-- flush.py                 Module cache flushing
|   \-- mkdir.py                 Directory creation utility
|-- sd/py_scripts/           --> Copy contents to SD card /py_scripts/
|   |-- tetris.py                Tetris with sound effects
|   |-- snake.py                 Snake with high scores
|   |-- synth.py                 4-instrument synthesizer with piano keyboard
|   |-- strudel.py               Strudel mini-notation parser + sequencer (library)
|   |-- strudel_live.py          Live-coding music UI (color themes, playhead)
|   |-- strudel_demo.py          Interactive tutorial: learn the mini-notation
|   |-- ProxiScan.py             BLE proximity scanner & fox hunt tool
|   |-- WiFiManager.py           WiFi scanning & connection manager
|   |-- picocalc_ollama.py       Local LLM client (Ollama)
|   |-- brad.py                  WiFi utility library
|   |-- demo.py                  Visual display showcase (grayscale, animation)
|   \-- editor.py                On-device file browser + code editor
|-- sd/samples/              --> Copy to SD card /samples/ (Strudel drum kit)
|   \-- bd/sd/hh/cp.raw          8-bit PCM one-shots for the picosampler engine
|-- firmware/                    Prebuilt UF2 firmware images
|   |-- picocalc_micropython_pico2w.uf2   (v1.25.0, stable)
|   |-- picocalc_v127_pico2w.uf2          (v1.27.0, patched)
|   |-- picocalc_v128_pico2w.uf2          (v1.28.0, native USB + audio engine)
|   |-- Dockerfile                         Build for v1.25.0
|   |-- Dockerfile.v127                    Build for v1.27.0 + USB fix
|   |-- Dockerfile.v128                    Build for v1.28.0 (no USB patch)
|   \-- USB_REGRESSION_FIX.md              RP2350 USB bug report
|-- micropython.cmake            Top-level build config for C modules
|-- picocalcdisplay/             C display driver (compiled into firmware)
|   |-- picocalcdisplay.c
|   |-- picocalcdisplay.h
|   |-- font6x8e500.h
|   \-- micropython.cmake
|-- vtterminal/                  C terminal emulator (compiled into firmware)
|   |-- vtterminal.c
|   |-- vtterminal.h
|   |-- font6x8.h
|   \-- micropython.cmake
|-- picosampler/                 C audio engine (DMA-PWM sampler, compiled in)
|   |-- picosampler.c                8-voice 8-bit PCM mixer, stereo PWM out
|   |-- micropython.cmake
|   |-- make_samples.sh              wav -> 8-bit PCM converter (ffmpeg)
|   \-- generate_drums.py            synthesize a starter drum kit (no deps)
|-- tools/                       Development tools
|   |-- dashboard.py                 Web UI server (run this!)
|   |-- bottle.py                    Vendored web framework (zero install)
|   \-- static/
|       |-- index.html               Dashboard frontend
|       \-- vendor/                  CodeMirror editor (vendored, offline)
mcp/                                 MCP server for AI assistants
|-- mcp_server.py                    MCP server (pip install picocalc-mcp or run directly)
\-- MCP_README.md                    Full setup guide

Applications

Strudel Support

This is a small reimplementation of Strudel's pattern idea that runs natively in MicroPython + C -- not a full port. There is no JavaScript engine and not the full Strudel/TidalCycles function library; it's a focused subset. Sounds are samples only (the bundled bd/sd/hh/cp kit, plus any 8-bit pcm_u8 .raw you drop in /sd/samples/ -- the sample name is the file name).

Mini-notation supported

Effects supported (per layer, after \|): lpf hpf res gain a d s r dur -- see Strudel Effects below.

Not supported (by design, for now): the JavaScript API and method chains; synth/oscillator voices (note/n); pitch / speed / accelerate; pan; time/character effects (delay, room/reverb, crush, coarse, shape); transform functions (rev, jux, every, sometimes, off, degrade, ...); per-event (rather than per-layer) effects; and sample banks beyond what you place in /sd/samples/.

Strudel Effects

The picosampler audio engine does real per-voice DSP in C: a resonant 2-stage state-variable filter (highpass -> lowpass) and an ADSR amplitude envelope, all mixed in float for full output resolution. Add effects to a pattern line after a | bar (they apply to every sound on that line):

bd*4 , hh*8 | lpf 600 res 150     # dark, squelchy lowpass
~ sd ~ sd   | hpf 1200            # thin, highpassed snare
bd ~        | a 3 r 180 dur 90    # shaped attack/release

SSH Client Notes

The SSH client supports modern OpenSSH 10.x servers (which dropped legacy DH key exchange) via ECDH-SHA2-NISTP256, with automatic fallback to diffie-hellman-group14 for older servers. Key exchange completes in ~1.3 seconds on the RP2350.

Required files:

• sd/py_scripts/ssh_client.py -- the SSH client application
• sd/py_scripts/secure_creds.py -- PIN-based credential encryption library
• sd/wifi.json -- WiFi credentials (created by WiFiManager)

Auto-created on first use:

• /sd/ssh_profiles.json -- saved connection profiles (passwords encrypted)
• /sd/ssh_known_hosts.json -- trusted host key fingerprints

Usage:

• Connect: Select a saved profile or create a new connection (host, port, user, password)
• Net Info: Press I on the menu to see this device's own IP, gateway, SSID, and MAC -- plus the ready-to-copy ssh -p 2222 user@<ip> command for SSHing back in
• Edit profiles: Press E on a saved connection to update host/port/credentials
• Disconnect: Press ESC-ESC to exit the terminal session
• Ctrl+C: Works for interrupting remote commands. For high-output programs like top, you may need to press Ctrl+C rapidly a few times since the keyboard is polled between SSH packets
• Host keys: First connection uses Trust-On-First-Use (TOFU) -- you confirm the fingerprint once, and it's saved
• Passwords: Always encrypted at rest with a 4-8 digit PIN via AES-128-CBC. You will be prompted to set a PIN on first save

SSH Server Notes

Run SSH Server to log in to the PicoCalc from another machine and get a live MicroPython REPL over the network. Reuses the SSH client's transport/crypto and adds the server side: an ECDSA-nistp256 host key, key-exchange signing, and password + publickey authentication.

Connect from your computer:

ssh -p 2222 <user>@<pico-ip>      # password auth
ssh -i ~/.ssh/id_ecdsa -p 2222 <user>@<pico-ip>   # public-key auth

The app's status screen shows the exact command (with the device IP) and the host-key fingerprint. Default port is 2222.

Files (on the SD card):

• sd/py_scripts/ssh_server.py -- the SSH server application
• /sd/ssh_host_ecdsa.json -- ECDSA host key (auto-generated on first run)
• /sd/ssh_server.json -- username + salted password hash (set on first run)
• /sd/authorized_keys -- optional OpenSSH-format public keys (one per line) for key auth

Notes:

• Single session at a time; the handshake takes ~1-2 s on the RP2350.
• Requires WiFi (run WiFiManager first). Press ESC on the status screen to stop the server.
• Supported client public keys: ecdsa-sha2-nistp256 and ssh-rsa/rsa-sha2-256. Ed25519 client keys are not yet supported -- use an ECDSA/RSA key or password auth.
• The session is a self-contained REPL (eval/exec with output streamed to your terminal); exit() or Ctrl-D disconnects.

Menu Controls

The main menu groups apps by category (Music, Games, Network, Tools...) with one-line descriptions, and auto-hides library/helper files. Apps opt in to a category with a header comment: # picocalc-app: Name | Category | description.

Building Firmware from Source

The prebuilt UF2 files in firmware/ are ready to flash -- building from source is not required. Only do this if you want to modify the C display/terminal drivers or experiment with different MicroPython versions.

Requires: Docker Desktop.

Option A: Standard Build (v1.25.0 -- recommended)

Stable, known-good USB. Used by the prebuilt picocalc_micropython_pico2w.uf2.

# 1. Build the Docker image (one-time, ~5 min)
docker build -t picocalc-build MicroPython/firmware/

# 2. Compile firmware with PicoCalc C modules (~3 min)
docker run --rm \
  -v $(pwd)/MicroPython:/picocalc \
  -v $(pwd)/MicroPython/firmware:/out \
  picocalc-build \
  bash -c "make BOARD=RPI_PICO2_W USER_C_MODULES=/picocalc/micropython.cmake -j\$(nproc) && \
           cp build-RPI_PICO2_W/firmware.uf2 /out/picocalc_micropython_pico2w.uf2"

Option B: Patched v1.27.0 Build

Newer MicroPython with BLE pairing APIs enabled. Includes a two-line patch for the RP2350 USB regression (see firmware/USB_REGRESSION_FIX.md).

# 1. Build the Docker image (one-time, ~5 min)
docker build -t picocalc-v127 -f MicroPython/firmware/Dockerfile.v127 MicroPython/firmware/

# 2. Compile firmware (~3 min)
docker run --rm \
  -v $(pwd)/MicroPython:/picocalc \
  -v $(pwd)/MicroPython/firmware:/out \
  picocalc-v127 \
  bash -c "make BOARD=RPI_PICO2_W USER_C_MODULES=/picocalc/micropython.cmake -j\$(nproc) && \
           cp build-RPI_PICO2_W/firmware.uf2 /out/picocalc_v127_pico2w.uf2"

Option C: v1.28.0 Build (native USB -- recommended for Pico 2W)

MicroPython v1.28.0 fixes the RP2350 USB-CDC regression upstream, so no USB patch is needed -- USB enumerates natively. This build keeps the BLE pairing APIs. Recommended if the patched v1.27 build fails to enumerate on your USB host (see issue #11).

# 1. Build the Docker image (one-time, ~5 min)
docker build -t picocalc-v128 -f MicroPython/firmware/Dockerfile.v128 MicroPython/firmware/

# 2. Compile firmware (~3 min)
docker run --rm \
  -v $(pwd)/MicroPython:/picocalc \
  -v $(pwd)/MicroPython/firmware:/out \
  picocalc-v128 \
  bash -c "make BOARD=RPI_PICO2_W USER_C_MODULES=/picocalc/micropython.cmake -j\$(nproc) && \
           cp build-RPI_PICO2_W/firmware.uf2 /out/picocalc_v128_pico2w.uf2"

Firmware Files

Hardware

Troubleshooting

"no module named 'picocalc'" after flashing new firmware:

• The C source directories (picocalcdisplay/, vtterminal/) may be on the device filesystem, shadowing the C modules compiled into firmware. Delete them from the device -- they should only exist in the repo, not on the Pico.
• Ensure /modules/ directory with picocalc.py is on the device.

Boot doesn't auto-run:

• Verify boot.py is at the root of the Pico filesystem (/boot.py).
• Check that /modules/ contains all .py files.

SD card not mounting:

• Format as FAT32. Ensure card is seated firmly.
• The boot sequence includes a stabilization delay for cold starts.

Display blank but REPL responds:

• The display runs on Core 1. If the firmware is old, update to the latest UF2.

USB REPL not connecting (no serial port appears):

• Firmware must be built with BOARD=RPI_PICO2_W. Default RPI_PICO is the wrong chip.
• MicroPython v1.26.0 and v1.27.0 have a USB-CDC regression on RP2350 (#18990); the prebuilt v1.27.0 carries a manual --wrap=dcd_event_handler patch, but that workaround is marginal on some USB host controllers (see issue #11). v1.28.0 fixes the regression natively -- if v1.27 fails to enumerate, use picocalc_v128_pico2w.uf2. The v1.25.0-preview firmware also has no regression.
• Check with ls /dev/tty.usbmodem* (macOS) or ls /dev/ttyACM* (Linux).

Thonny shows KeyboardInterrupt traceback on connect:

• This is normal! Thonny sends Ctrl+C to interrupt main.py's menu loop. You'll see a traceback followed by >>>. This means Thonny connected successfully.

Thonny shows "Unexpected read during raw paste":

• Deploy boot_thonny.py as /boot.py on the device (meaning rename boot_thonny.py as boot.py). This skips os.dupterm() which conflicts with Thonny's raw paste protocol. The PicoCalc screen and keyboard still work for apps and the menu -- only REPL output moves to Thonny's shell panel instead of the device screen.
• To switch back to standard boot: deploy boot.py as /boot.py.
• The dashboard and mpremote work with the standard boot.py and don't need the Thonny variant.

What's New in v3.1

• Strudel on PicoCalc -- a focused subset of Strudel/TidalCycles pattern music ported to the handheld (not the full engine -- see Strudel Support for exactly what's covered):
  • picosampler native C audio engine -- a DMA-paced PWM sampler that mixes up to 8 voices of 8-bit PCM streamed from the SD card on both audio channels, so the device plays real sampled drums instead of pulse-wave beeps. Compiled into the v1.28 firmware as a third C module.
  • Per-voice DSP -- a resonant 2-stage filter (lowpass/highpass) and an ADSR envelope, all fixed-point so the audio interrupt never touches the FPU. Drive it from the mini-notation with a per-layer effect tail: bd*4 , hh*8 | lpf 600 res 150 r 40 (see Strudel Effects).
  • Mini-notation sequencer (strudel.py) -- parses a Strudel subset (bd sd hh*2, [bd sd], <bd cp>, euclid bd(3,8), comma-stacked layers, // and # comments) and schedules it in real time.
  • Live-coding UI (strudel_live.py) -- edit patterns on the device and hear them update at the next cycle (like Strudel's Ctrl-Enter); sweeping playhead, event timeline, and 5 real color themes -- SonicPink, Dracula, Monokai, Nord, Terminal.
  • Strudel Basics (strudel_demo.py) -- an interactive 11-lesson color tutorial that teaches the mini-notation and effects with live audio and a rhythm timeline.
• Real color from the 4-bit display -- the GS4 framebuffer drives a 16-entry hardware color LUT, so apps can show true color (not just grayscale) by reprogramming the palette with picocalcdisplay.setLUT -- no extra framebuffer RAM. Themes become instant palette swaps.
• Categorized app menu -- py_run.py now groups apps into sections with one-line descriptions and auto-hides library/helper files (no more stray modules in the list). Apps opt in via a # picocalc-app: Name | Category | description header.
• Removed Remote Claude -- the on-device Anthropic-API chat app (picocalc_claude.py) has been retired.

What's New in v3.0

• MCP Server -- AI coding assistants (Claude Code, Claude Desktop, Cursor) can talk directly to the PicoCalc over USB via the Model Context Protocol -- run code, read/push files, check status, no dashboard needed
• SSH Server (two-way SSH) -- SSH into the PicoCalc for a MicroPython REPL over WiFi, alongside the existing SSH client. ECDSA-nistp256 host key, ECDH key exchange, password + public-key auth (ssh -p 2222 user@pico-ip)
• Remote Claude -- chat with Claude over WiFi straight from the device: streaming replies from the Anthropic API, multi-turn context, claude-opus-4-8 default, and a choice of API-key or Max/Pro OAuth auth with the credential PIN-encrypted on the SD card
• Synth 4.0 -- ground-up rewrite with 4 instruments (Piano, Organ, Strings, Synth), QWERTY piano keyboard, ADSR envelope, arpeggiator, 16-step sequencer, LFO, presets, stereo harmonic enrichment
• Dashboard eject button -- sends 7-second countdown to device screen, then reboots to menu for safe USB unplug
• Dashboard side-by-side diff -- click a modified file to see device vs local changes color-coded in a split view
• Dashboard new script -- "+" button creates scripts from a starter template, opens in editor
• Smart file clicks -- modified files auto-show diff, clean files open in editor
• Adaptive polling -- 1.5s when disconnected for fast reconnection, 5s when connected
• Firmware v1.28.0 (native USB) -- recommended build for Pico 2W; v1.28.0 fixes the RP2350 USB-CDC regression upstream so no patch is needed (firmware/Dockerfile.v128). The patched v1.27.0 build remains available as an alternative.
• USB regression fixed -- discovered and root-caused the MicroPython RP2350 USB-CDC bug affecting v1.26.0/v1.27.0 (#18990); v1.28.0 resolves it natively
• SD cold-start hardening -- enhanced_sd.initsd() retries the mount with backoff and validates capacity, so a slow card on first boot no longer comes up as internal flash
• App UI polish pass -- reviewed every bundled app: fixed the SSH header bar, on-screen ProxiScan antenna calibration (no more blind REPL prompts), editor long-name truncation, synth SET-page footer overlap, math-app centering, and removed leftover debug output
• Audio quality -- anti-click retrigger, soft duty ceiling, per-instrument stereo overtones, frequency-scaled decay
• Removed PicoBLE -- old BLE file transfer removed (dashboard handles file transfer over USB)

What's New in v2.0

• Development Dashboard -- local web UI (python3 MicroPython/tools/dashboard.py) with FTP-style dual-pane file manager, in-browser editor, REPL, drag-and-drop deploy, file diff, and macOS junk cleanup
• Flicker-free display -- beginDraw() blocks Core 1 during screen clear to prevent white flash artifacts
• Firmware build pipeline -- Dockerfile pinned to known-good MicroPython v1.25.0 for USB stability on RP2350
• Boot/main split -- USB REPL available immediately after boot; Thonny and mpremote can connect without issues
• WiFiManager rewrite -- full VT100 terminal UI with arrow-key navigation, color-coded signal bars, channel congestion analysis, real-time signal monitor
• On-device code editor -- browse, create, edit, and delete scripts directly on the PicoCalc, no computer needed
• Demo app -- visual display showcase with grayscale palette, animated boxes, scrolling gradient
• Thonny support -- boot_thonny.py variant for Thonny users (skips dupterm)
• Dashboard code editor -- Python syntax highlighting and PicoCalc-aware linting (vendored CodeMirror, works offline)
• Codebase cleanup -- consolidated ProxiScan variants, removed legacy scripts and archive directory

Credits

Built on PicoCalc-micropython-driver by zenodante (LCD driver, keyboard logic, original 1.0 UF2 image).

License

MIT License

Contact

• Issues: GitHub Issues
• IG: @lofifren
• YT: @lofifren
• YouTube PicoCalc 2.0 Demo: https://youtu.be/gf3ittEwFJ8
• YouTube MCP & Dashboard: https://youtu.be/iEJeBd9a6NE
• Playlist: PicoCalc Playlist