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