JakubandClaude Opus 5
fe02fda897
README had drifted from the firmware in several places: - Supported Devices listed only the three nRF52 boards; Heltec V3/V4 were missing entirely, as was any mention that ESP32-S3 flashes differently. Flashing is now split per MCU, with the merged-vs-app-only .bin trap spelled out — that one costs an afternoon to diagnose from a dark screen. - It advertised a Lemon/Default font switch that was retired in v1.23; there is one unified misc-fixed 6x9 font now and no font setting at all. - tools/README claimed ENABLE_SCREENSHOT had to be added by hand, directly contradicting README's "no special build flags required". The envs have carried the flag for a while; rewrote the file to cover all four tools. - "S key for screenshot" described screenshot.py's menu, not the device — screenshots are driven entirely from the host via CMD_GET_SCREENSHOT. Structurally, general notes (factory reset on migration, BLE-over-USB priority) sat at the tail of the ESP32 subsection and read as ESP32-specific; they're now placed where they apply. Heltec wiring moved out of Supported Devices into its own section so the device table stays scannable, and the Solo Tools heading is no longer a link (it was generating a garbage anchor). New docs/solo_features/external_keyboard.md covers CardKB and the wired joystick: shortcut table, Full vs Compact, and the pin assignment. The pins are marked as verified on real V4 hardware only — V3 inherits them from Heltec's documented pin-compatibility and hasn't been checked on a board. FEATURES.md (roadmap + code audit, developer-only) moves to docs/development/roadmap.md; nothing referenced it by path. Adds Building from source / Releasing / Repository layout, since the release flow was only discoverable by reading the workflow. Co-Authored-By: Claude Opus 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.