JakubandClaude Opus 5.5
002f478231
One .vpk file per region in /vmap (header, sorted index of tiles and
points, then the data), read in place with the index in PSRAM; loose
{dz}/{x}/{y}.vt/.vp files still work. osm_vector.py writes packs
(--pack/--name), reads OSM PBF extracts for a box (--pbf/--bbox, via
pyosmium) and picks label languages (--lang). Map tools > Vector regions
lists the packs on the card: show one on the map, delete it. No
on-device download: packs are made with the tool.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Host-side tools
Helper scripts that run on your computer, not on the device.
| Tool | Purpose |
|---|---|
screenshot.py |
capture the device display over USB serial and save it as a PNG |
trail_export.py |
capture a GPX track from the device over USB serial |
gpx-downloader/index.html |
the same GPX capture in a browser, via Web Serial |
bdf2gfx.py |
convert a BDF bitmap font to an Adafruit-GFX header |
Python dependencies are managed with uv — run the
scripts with uv run tools/<script>.py from the repository root.
Tip
The hosted Solo Tools Web App does both screenshots and GPX export with nothing to install, and is the easiest option for most people. The scripts here are the offline equivalents.
Important
USB serial is suspended while a BLE connection is active, so disconnect the companion app from BLE before using any of these. If the app is connected over USB, disconnect it too — the raw stream would otherwise disrupt its frame protocol.
Display screenshot
All solo firmware environments are built with -D ENABLE_SCREENSHOT, so no
special build is needed. On other environments (repeater, room server, the
non-solo companion builds) add the flag yourself:
PLATFORMIO_BUILD_FLAGS="-D ENABLE_SCREENSHOT" pio run -e <env> -t upload
Usage:
-
Connect the device over USB, with no companion app attached
-
Run the tool:
uv run tools/screenshot.pyOptions:
--port PORT— serial port to use (default: auto-detect)--scale SCALE— upscale factor for the output image (1 = none; default: 1)
-
Press S in the tool's interactive menu to capture
-
The PNG lands in
tools/pngs/with a timestamped filename
How it works:
- The tool sends
CMD_GET_SCREENSHOT(66) to the device - The device replies with
RESP_CODE_SCREENSHOT(29) carrying the framebuffer - The framebuffer arrives in chunks (a 128 × 64 display is 1024 bytes, split across several frames), which the tool reassembles into a PNG
GPX trail export
-
Connect the device over USB, with no companion app attached
-
Start the listener:
uv run tools/trail_export.pyOptions:
--port PORT— serial port to use (default: auto-detect)--out OUT— output file (default: a timestamped file intools/gpx/)
-
On the device: Tools › Trail › Hold Enter › Export (live) or Export (saved)
-
The script captures the GPX 1.1 XML stream and writes it to disk
Font conversion
uv run tools/bdf2gfx.py <font.bdf> <first_hex> <last_hex> <VarPrefix> > out.h
Emits a contiguous glyph table over the given codepoint range, with empty
placeholders for codepoints the BDF does not define, so the renderer can index
by cp - first. This is how src/helpers/ui/MiscFixedFont.h
— the unified 6×9 Latin/Greek/Cyrillic display font — was generated from
6x9.bdf.