Reference documentation for developers, contributors and curious users.
For end-user setup see the README.
- LVGL UI rewrite (v3.0.0) — the entire UI was rebuilt on LVGL 9: a modern widget tree replaces the hand-painted frames, every view redrawn with anti-aliased Montserrat fonts, and the PAX painter retired. The Settings tab was reorganised — the old Network category is split into separate WiFi and Bluetooth tiles, Path hash size moved under Radio, and Role moved under Identity. A new 6-digit BLE pairing code (fixed NimBLE passkey, persisted to NVS) lives under Bluetooth. The Home screen is now a 4×3 grid with new WiFi, Bluetooth and Toolbox shortcut tiles. See UI / UX.
- Toolbox (v2.7.0) — a Settings tile launching LoRa diagnostic tools.
Packet Log: a live hex / dissector view of every RX and TX frame, with
pause, scroll, a per-frame detail view, and an
Eexport of the capture ring to/sd/meshcore/log/pkt_<unix>.csv. Coverage Test: ping discovered repeaters 3x with an upstream MeshCore TRACE, colour-code reachability, and log every GPS-stamped attempt (+ uplink/downlink SNR) to one CSV per session. See Toolbox and UI / UX. - Carto-only map styles (v2.7.0) — the Settings "Style" picker now cycles
only the styles in a one-line
MAP_PROFILES_ENABLED[]list (Carto by default, matching the tileset shipped on SD); one line re-enables CyclOSM / OpenTopo / Ripple. See Maps. - Screensaver + robustness (v2.6.0) — the screensaver also blanks the keyboard backlight and wakes on any key; plus a batch of receive-path fixes (1-byte sender-hash collisions, a duty-cycle accounting race, node-table eviction). See the changelog.
- Notification sounds — drop your own WAVs on
/sd/meshcore/sounds/{1..4}.wav, pick one per event (DM / Channel / Error / Boot) in Settings → Sounds. Volume + on/off per event, all NVS-persisted. - PA1010D GPS auto-fill — one-press scan from
Settings → Region & Location → Auto-fill from GPS, reads NMEA over
the QWIIC bus, commits
lat_e6/lon_e6to NVS with source tagGPS_SRC_PA1010D. - BLE companion radio (toggle in Settings) — pair with the iPhone MeshCore app to use the badge as its radio. Pair UI + SMP passkey toast wired; lat/lon write path is preview (see GPS sources).
- Refactor hygiene — handle_nav / handle_key split per view, field registry replaces parallel save + builder tables, lora_rx_task split per packet type. Net: same code size, much less duplication, adding a settings field or packet type is now a localised edit.
The docs are grouped into four folders.
- Blueprint — design rationale and how to program in this project (read first)
- Architecture (rules) — the enforced layers, forbidden includes, wire boundary
- Module overview — the modules and how they interact
- Components — the component map, dependency graph, constants
- Getting started — first run: set your Owner + Advert name, then get on the air
- Build / Deploy — IDF env, badgelink upload, launcher dependency, partition layout
- Map tiles via MOBAC — download map tiles onto the SD card without Docker
- Contributing — the contributor checklist and code rules
- Releases — the fixed release format and how to cut a release
- MeshCore protocol — packet types, encryption, ADVERT/DM/Channel/PATH formats
- Settings / NVS — every persistent key, default, range, the regulatory tables
- C6 radio —
lora_rpc, RSSI/SNR patches, supported frequencies - Firmware versions — the radio/lora/launcher forks vs upstream
- SD card layout —
/sd/meshcore/structure, encryption, self heal
- UI / UX — views, key bindings, the edit-mode state machine, the QR overlay, the Toolbox
- Maps — the slippy map: tile cache, the Carto-only style picker, the rendering pipeline
- Toolbox — the Packet Log and Coverage Test (TRACE-based reachability + the wire gotchas)
- GPS sources — the four input paths (manual, PA1010D, USB-CDC companion, BLE companion)
- Sounds — WAV format, recommended free sources, the upload recipe
- Screenshots — every view, full set
- Changelog — what changed per version