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
• Arrow-key navigable menu system
• Games (Tetris, Snake), 4-instrument Synthesizer, BLE Keyboard, WiFi Manager, LLM client
• 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                Menu system with arrow-key navigation
|   |-- 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
|   |-- ProxiScan.py             BLE proximity scanner & fox hunt tool
|   |-- WiFiManager.py           WiFi scanning & connection manager
|   |-- picocalc_ollama.py       Local LLM client (Ollama)
|   |-- picocalc_claude.py       Remote Claude client (Anthropic API)
|   |-- brad.py                  WiFi utility library
|   |-- demo.py                  Visual display showcase (grayscale, animation)
|   \-- editor.py                On-device file browser + code editor
|-- 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)
|   |-- 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
|-- 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

App	Description
Tetris	Classic Tetris with 7 pieces, ghost piece, sound effects, level progression
Snake	Snake with high score tracking, speed levels, sound
Synth	4-instrument synthesizer (Piano, Organ, Strings, Synth) with QWERTY piano keyboard, ADSR envelope, arpeggiator, 16-step sequencer, LFO effects, presets
ProxiScan	BLE proximity scanner, fox hunt tool with compass, signal tracking, competition timer, waypoints, antenna calibration
WiFiManager	WiFi scanner with VT100 UI, signal bars, channel analysis, signal monitor
SSH Client	Secure shell client -- ECDH-SHA2-NISTP256 key exchange, AES-128-CTR + HMAC-SHA2-256 encryption, RSA host key verification (TOFU), saved connection profiles with PIN-encrypted passwords, interactive VT100 terminal (53x40)
SSH Server	SSH into the PicoCalc for a MicroPython REPL -- ECDH-SHA2-NISTP256 key exchange, ECDSA-nistp256 host key, AES-128-CTR + HMAC-SHA2-256, password (salted-hash) and public-key (authorized_keys) auth
Ollama Client	Chat with local LLMs over WiFi via Ollama
Remote Claude	Chat with Claude (Anthropic API) over WiFi -- streaming replies, multi-turn, API-key or Max/Pro OAuth auth, PIN-encrypted credential. Default model claude-opus-4-8
Demo	Visual display showcase: grayscale palette, bouncing boxes, scrolling gradient, device info
Editor	On-device file browser and code editor -- browse, create, edit, delete scripts without a computer

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.

Remote Claude Notes

Remote Claude talks directly to the Anthropic Messages API (api.anthropic.com) over HTTPS and streams the reply token-by-token. Multi-turn conversation. First-run setup includes a model picker -- Opus 4.8 (default, most capable), Sonnet 4.6 (balanced), Haiku 4.5 (fastest/cheapest), or any model id you type -- and you can switch any time with /model. Requires WiFi (run WiFiManager first) and firmware with ssl/mbedtls (the v1.27/v1.28 builds include it).

Two ways to authenticate (chosen on first run):

Mode	Header	When to use
API key (recommended)	x-api-key	Static credential, pay-as-you-go. Get one at console.anthropic.com. Best default for a handheld -- paste once, no expiry.
Max/Pro OAuth (experimental)	Authorization: Bearer + anthropic-beta: oauth-2025-04-20	Use your Claude.ai subscription instead of API credits. Tokens are short-lived -- generate on your computer and re-paste via /auth when it stops working.

Why API key is the default: the OAuth token expires and needs a refresh flow that's awkward on a headless device, whereas an API key is a static credential you paste once.

Getting a Max/Pro OAuth token (the setup screen also prints these steps):

brew install anthropics/tap/ant        # or use Claude Code (logs in the same way)
ant auth login                         # sign in with your Claude subscription
ant auth print-credentials --access-token   # copy the sk-ant-oat... value

Paste that token into the OAuth setup. It expires after a while -- refresh it the same way and re-enter via /auth.

The app is Claude-themed throughout: it opens with an orange sunburst intro on black (a temporary palette swap to true Claude clay #D97757), and the chat carries the same theme -- an orange Claude> label, light-orange prompt, and dim command hints -- restoring the default palette on exit.

Files (on the SD card):

• sd/py_scripts/picocalc_claude.py -- the app
• /sd/claude.json -- auth mode + credential (PIN-encrypted via secure_creds when a PIN is set) + model

In-chat commands: /models pick from a menu, /model <id> set a specific model, /reset clear history, /auth re-enter credentials, /help, /quit.

---

Menu Controls

The main menu uses arrow-key navigation:

Key	Action
Up/Down	Navigate script list
Enter	Run selected script
ESC	Exit to REPL
R	Reload script list
F	Flush module cache
M	Show memory/storage info
T	File management tools

---

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

File	MicroPython	Notes
picocalc_micropython_pico2w.uf2	v1.25.0-preview	Stable default, all apps work
picocalc_v127_pico2w.uf2	v1.27.0 (patched)	BLE pairing APIs, manual USB wrap (marginal on some hosts)
picocalc_v128_pico2w.uf2	v1.28.0	Native USB (no patch), BLE pairing APIs -- recommended
Dockerfile	v1.25.0-preview	Standard build
Dockerfile.v127	v1.27.0 + patches	USB fix + BLE security enabled
Dockerfile.v128	v1.28.0 + BLE patch	Native USB, BLE security enabled
USB_REGRESSION_FIX.md	--	Bug analysis and patch details

---

Hardware

Component	Details
Display	320x320 ILI9488 LCD, SPI1, 4-bit grayscale
Keyboard	Membrane keypad, I2C MCU at 0x1F
SD Card	SPI0, FAT32, mounted at /sd
Audio	PWM stereo, GPIO 27 (right) + GPIO 28 (left)
WiFi/BLE	CYW43 via Pico 2W
MCU	RP2350 (Raspberry Pi Pico 2W)

---

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.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