cardputer-puzzles

Install

Plug the Cardputer into this computer over USB‑C and press the button. The whole firmware is written from your browser - no PlatformIO, no esptool, no driver install.

This browser can't talk to serial devices. Use Chrome or Edge on desktop, or flash manually with the commands below. Serial access needs a secure (https) page. Open this site over https.

Desktop Chrome or Edge only (Web Serial). Version -. The write skips the nvs partition and stops far short of the save-file partition, so upgrading keeps your in-progress games. If the device isn't listed in the port picker, hold G0 while plugging it in.

Flash manually instead

Download cardputer-puzzles-vX.Y-merged.bin from the latest release and write it at offset 0x0:

esptool --chip esp32s3 write-flash 0x0 cardputer-puzzles-vX.Y-merged.bin

That single-command form erases the nvs partition in the gap it spans. To keep an existing device's settings, write the two halves around it:

esptool --chip esp32s3 write-flash 0x0 firmware-0x0.bin 0xe000 firmware-0xe000.bin

Both split parts are served from this page (0x0, 0xe000) and are the same bytes as the merged image.

Running an SD-card launcher such as the M5Stack Launcher? Take the -app.bin asset instead. It keeps the device's own partition table, so saved games persist only if that table has a spiffs partition.

The 40 games

Black Box
Bridges
Cube
Dominosa
Fifteen
Filling
Flip
Flood
Galaxies
Guess
Inertia
Keen
Light Up
Loopy
Magnets
Map
Mines
Mosaic
Net
Netslide
Palisade
Pattern
Pearl
Pegs
Range
Rectangles
Same Game
Signpost
Singles
Sixteen
Slant
Solo
Tents
Towers
Train Tracks
Twiddle
Undead
Unequal
Unruly
Untangle

Every game keeps its own board across a power‑off, with preset and custom sizes, an in‑menu rules viewer, and an error path that returns to the menu instead of hanging.

Controls

Every plain key goes to the puzzle, so games that use letters (Map's l, Solo's hex digits) work as they do upstream. Frontend commands live on Ctrl, Tab and `.

`;` `.` `,` `/`	Move cursor (up / down / left / right)
`Enter`	Select - the cursor cell, or a click at the crosshair in pointer mode
`Space`	Select2 / mark (flag, pencil, ...)
digits, letters, `⌫`	Per-game input
`Ctrl`+`Z` / `Y`	Undo / redo
`Ctrl`+`N` / `R`	New game / restart
`Tab`	Menu in a game (size, new, restart, solve, pointer, zoom, pan, rules); help on the game list
`Ctrl`+`P`	Toggle the IMU tilt pointer
`Ctrl`+`Space`	Recenter the tilt pointer on your current hold
`Ctrl`+`L`	Toggle 2× zoom; `Ctrl`+`;.,/` pans
`	Back, to the game list or out of a menu

Drag games - Map, Pegs, Signpost, Guess and Untangle - split the drag across two presses in pointer mode, because the crosshair can't hold a button: Enter picks up, tilt to aim, Enter drops. The key that picked it up is the key that drops it; the other key cancels.

Hardware

Built and tested on the M5Stack Cardputer ADV (ESP32‑S3 Stamp‑S3A, 8 MB flash, no PSRAM, 240×135 display). It should run on the original Cardputer too - same board family and panel, and M5Unified picks the keyboard driver at runtime - but that's untested; the tilt pointer needs the IMU the ADV added, so it stays off there. If you try it, open an issue saying what the Fn keys do.

Build it yourself

git clone --recurse-submodules https://github.com/chongjiazhen/cardputer-puzzles
cd cardputer-puzzles
pio run -e puzzles -t upload

Game logic lives in upstream/, a git submodule pinned unmodified. Only the Cardputer frontend (src/puzzles/, lib/) is original to this project.