mirror of
https://github.com/MarekZegare4/MeshCore-Solo.git
synced 2026-08-08 05:06:11 +00:00
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>
93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
# 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](https://docs.astral.sh/uv/) — run the
|
||
scripts with `uv run tools/<script>.py` from the repository root.
|
||
|
||
> [!TIP]
|
||
> The hosted [Solo Tools Web App](https://marekzegare4.github.io/Solo-tools/)
|
||
> 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:
|
||
|
||
```sh
|
||
PLATFORMIO_BUILD_FLAGS="-D ENABLE_SCREENSHOT" pio run -e <env> -t upload
|
||
```
|
||
|
||
**Usage:**
|
||
|
||
1. Connect the device over USB, with no companion app attached
|
||
2. Run the tool:
|
||
|
||
```sh
|
||
uv run tools/screenshot.py
|
||
```
|
||
|
||
Options:
|
||
- `--port PORT` — serial port to use (default: auto-detect)
|
||
- `--scale SCALE` — upscale factor for the output image (1 = none; default: 1)
|
||
|
||
3. Press **S** in the tool's interactive menu to capture
|
||
4. 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
|
||
|
||
1. Connect the device over USB, with no companion app attached
|
||
2. Start the listener:
|
||
|
||
```sh
|
||
uv run tools/trail_export.py
|
||
```
|
||
|
||
Options:
|
||
- `--port PORT` — serial port to use (default: auto-detect)
|
||
- `--out OUT` — output file (default: a timestamped file in `tools/gpx/`)
|
||
|
||
3. On the device: **Tools › Trail › Hold Enter › Export (live)** or
|
||
**Export (saved)**
|
||
4. The script captures the GPX 1.1 XML stream and writes it to disk
|
||
|
||
---
|
||
|
||
## Font conversion
|
||
|
||
```sh
|
||
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`](../src/helpers/ui/MiscFixedFont.h)
|
||
— the unified 6×9 Latin/Greek/Cyrillic display font — was generated from
|
||
`6x9.bdf`.
|