🗺️ Trail Mate
Your identity belongs to you. Keep private records local. Choose what to share.
Trail Mate is a privacy-focused handheld for decentralized communication and offline navigation. It reduces the personal information a platform needs to hold: no real-name, phone or email account is required for the Web tools, and device-held keys prove authorship. Contacts, conversations and unshared tracks remain on hardware and storage you control.
Communicate over compatible Meshtastic, MeshCore or Reticulum/LXMF networks, carry offline maps and record your journey locally. Choose independent gateways and directories, and publish only the trails or Geocaches you select. A service can help you communicate without becoming the owner of your identity and complete private history. Features depend on the board; the project includes ESP32, nRF52 and Linux implementations.
English | Documentation | Releases | Join Discord
1.1.0 adds installable Cardputer Zero and T-Display-CM0 Linux packages, online
map creation and radio/storage reliability improvements. Get the board-specific
files and release notes.
Linux users should follow the Debian installation guide;
supported microcontrollers also have a browser installer.
Check the device support table below before choosing an image or package.
The device is your account
Connect a supported Trail Mate device over USB to prove your author identity in
the browser. There is no website account or password to register. This avoids
requiring a platform profile with your real name, phone number or email. The device
holds its identity and signs publications; the browser provides convenient
editing, maps, file handling, and access to Reticulum through the computer's
network. These author operations do not require changing the device's selected
chat protocol or routing Internet traffic through its LoRa radio.
| Part of the system | What it does |
| --- | --- |
| Firmware | Owns identity, records local tracks, reads offline maps, communicates in the field, and signs authorized maintenance operations. |
| Web | Edits device configuration through Web Serial, maintains Geocaching publications, and imports, edits, browses and shares KML trails. |
| Trail Mate Center | Prepares offline map regions, provides a desktop dashboard, and handles HostLink data, replay, export and propagation tools. |
| Reticulum services | Independently operated gateways and directories carry requests and index signed shared content. They can run on different nodes. |
Browsing shared content does not require the author's device. Creating, updating
or archiving under your device identity requires its authorization. Browser USB
access requires a browser that implements Web Serial and a secure origin, such
as the HTTPS site or localhost. Browser support differs; the page reports
availability before asking you to choose a serial port.
Ownership and privacy
Your identity and private local records do not have to live in one platform's
account database. You decide which caches and tracks to publish, keep portable
files, and can use independently operated directories. Author signatures allow
receivers to check who created a publication without trusting the directory to
invent that identity. A single operator is not required to control the entire
system or collect every user's complete activity history.
Public sharing is still public. A directory or recipient can store and
analyse the routes, coordinates, timestamps, author identity and metadata you
publish. Repeated use of one public author identity can link those publications.
Gateways can observe connection metadata, and external map providers can see
map requests. Archiving changes the current published state; it cannot erase
copies already received by others. Decentralization gives users choices and
reduces dependence on one operator; it does not make published location data
secret or prevent every form of behavioural analysis.
The 1.1.0 build and installation record and
physical Linux-device acceptance
separate release contents from hardware-support claims. The earlier
1.0.1 delivery record remains available for that release.
⚙️ Engineering Snapshot
- Platforms: ESP32 and nRF52 firmware, Linux device applications, and a Linux simulator
- Networking: Meshtastic · MeshCore · Reticulum/LXMF, with support depending on the target
- Hardware: keyboard handhelds, touch navigation terminals, and low-power message devices
- Toolchains: PlatformIO / Arduino · ESP-IDF · CMake for Linux
- Validation: multi-target CI builds, native regression tests, LVGL integration tests, architecture boundary checks, stack and runtime-budget checks, and OTA-size validation
- Releases: automated firmware packaging, ARM64/ARMHF Linux device packages, web-flasher images for selected targets, nRF52 UF2 images, and tagged-release debug symbols
- Core capabilities: GNSS · offline maps · LoRa messaging · local storage · on-device team awareness
- License: AGPL-3.0
Capabilities vary with memory, peripherals, input hardware, and port maturity. The simplified nRF52 targets currently provide Meshtastic / MeshCore messaging rather than the full feature set. See the device table below for current status.
Engineering evidence: CI and release workflow · shared protocol tests · repository architecture · version history.
🚀 Try Trail Mate
Plan and follow a route offline
Prepare a region in Trail Mate Center, then put its TMAP files and resources on
the SD card. Include the area's routing graph and POI search data as well as
the map styles you want to see. OSM, terrain and satellite views, numeric terrain
data and contour overlays each use the data included in those packages.
On a supported PSRAM-capable device, open Tracker → Menu → Nav → New.
Start from your current GNSS position or a place you find in the offline search,
choose a destination, and calculate a walking route on the device. Save it as a
.tmroute plan for another day, or open its preview and start following it in Map.
Calculating and following the plan do not need an Internet connection.
Map shows progress, remaining distance, geometric turn hints, deviation and
arrival. Manual or automatic replanning can calculate a new path from your
current position; cancellation or a failed attempt keeps the saved plan intact.
Live guidance is presented while Map is open. The graph must cover the requested
trip, and route calculation has an explicit memory/search budget. A raster-only
map cannot supply a path by itself.
You can also bring your own KML routes, record local tracks, inspect elevation
profiles and route images, search for places, save waypoints, and see team
members or radio contacts on the map. The offline navigation guide
explains installation and controls. Wio L2 navigation, presentation and touch
interaction have been accepted on hardware; other targets retain their own
validation status.
Widgets and music for everyday use
Pager, T-Deck and Wio L2 share an adaptive app grid. The widget screen beside it
shows one widget at a time: mesh status, GNSS, recent activity, Agenda, Music,
Quick controls, and Compass when the device has a magnetometer. P4 keeps the
same idea in a larger layout, with pages in its right-hand dashboard.
On T-Deck and Wio L2, swipe right from the main menu to open the widget screen and
left to return; swipe up/down to change widgets. On Pager, press V to switch
between the main menu and widgets. W/A/S/D and the wheel select app icons;
inside widgets, W/S or the wheel changes widgets, A/D selects a control and
Enter or a wheel press activates it. H opens contextual Help. The footer keeps
the V shortcut visible, and V also works with launcher Help open. P4's right-hand
dashboard uses horizontal paging for additional widgets.
Put MP3 files under /Music on the SD card; subfolders are scanned too.
Music opens Now Playing when a session is active, or the library when idle.
Browse songs, artists, albums and folders, create your own playlists, and use
repeat-all, repeat-one or shuffle. Track information includes the available ID3
fields, album art and embedded lyrics; matching .lrc files can sit beside a
song. Chinese titles and lyrics use the same installed content font as Chat.
The Music widget offers transport controls, and Quick controls provides Wi-Fi,
LoRa, GPS, volume and brightness through the existing device services. Only the
visible widget retains its view resources. Playback uses a bounded PSRAM PCM
buffer and pauses when voice or intercom takes the audio output. Audio hardware
and playback quality still depend on the target; the support table applies.
Actual native LVGL previews with sample metadata, artwork and simulated service
state. The Music and widgets guide
includes file placement and keyboard controls.
Browser device configuration
The website provides direct
Device management, Tracks and Geocaching links on every page. The
highlighted link identifies the current tool. Tool links and the home logo keep
your selected interface language; Flash opens firmware installation.
GitHub and Wiki are in Resources. The same tool links remain visible on
narrow screens, with task cards on the homepage.
Current homepage and tool navigation, captured in English from the rebuilt
Web sources. Device connection and publication still require the appropriate
hardware, permissions and reachable directory.
Open the Device page, connect
the device and choose its USB port. The page verifies the author and configuration
snapshot before allowing edits. Settings are grouped by purpose and searchable;
enumerations, percentages, durations, frequencies, masks and collections use
appropriate controls with explanations rather than unexplained numeric fields.
Review the changed values before saving. The page reads back the device result
and supports configuration backup/restore and explicit identity maintenance.
Identity backups are sensitive: normal author operations use device-side signing
and do not require exposing the private key in the browser.
Keep the device's SD card installed for configuration exchange and stored-content
maintenance. Device author proof itself is independent of the card; a successful
identity check does not imply that its file storage is available.
Current English browser configuration controls with simulated-device data. The screenshot
illustrates readable percentage input, not a physical-device acceptance result.
Decentralized Geocaching
Create and publish signed caches over Reticulum, browse independently operated directories, and download cache details for offline maps. The live web map queries the network directly, so new publications do not require a website update. Publishers keep their own identities; the protocol supports independent directory operators rather than requiring one central service.
The browser also maintains your own caches. Connect USB, open your device drafts,
edit the cache, review the publication and authorize its signature. The browser
publishes through the computer's Reticulum connection, verifies the directory
receipt and confirms the result on the device. Updates keep the cache identity;
archive operations publish a new state. Pending confirmation remains visible
and can be continued instead of silently starting a second publication.
Actual Web maintenance page from a native Reticulum directory check with a
simulated USB author. Sample cache data is shown; this is not a real-Wio result.
The firmware browses caches through a reused single card. The card emphasizes
distance and an approximate administrative area; details retain coordinates and
the full cache description. Only the current item is hydrated.
Production LVGL page rendered with synthetic cache and administrative-area data;
this capture demonstrates the interface, not geographic accuracy on hardware.
Decentralized KML trail sharing
Firmware Tracker uses the same card interaction for recordings and KML routes.
Previous/next navigation reuses the widgets; the current file's start position
feeds the shared approximate-area and distance presentation. Route geometry,
elevation and images are opened through the existing preview when needed.
The card uses the full content width. Menu in the bottom bar selects
Tracks, Routes or Nav on supported navigation targets. Contacts,
Chat, Settings, Extensions and Network use the same bottom-menu components;
Contacts and Chat expose their radio status through Menu → Info.
Tracks and Nav provide View, New and Current submenus instead of
separate creation commands in the root menu. An active recording retains a direct
Stop recording action.
Actual Wio native LVGL preview from CI with sample KML and simulated GPS. The
preview has no TMAP administrative data, so its region remains unknown. This is
not a physical-device capture.
Current production LVGL native render: flat action rows, a light focus state,
content-sized height and a compact title-bar close button. X/x closes the current
frame-based Map/Tracker dialogs on keyboard devices; touch uses the same close
control. Other legacy dialogs have not all been migrated.
The Tracks workspace combines
your own trail library, shared-trail discovery, and trail details and
maintenance. Import KML/KMZ or supported device recordings, keep drafts in the
browser, and use the connected device as the publication author.
- Browse independently hosted directories and query the visible map extent.
Pan or zoom the map to explore another area; automatic search can follow map
movement. Administrative filtering uses the catalog supplied by the directory.
The public directory supplies a global catalog with 251 country/region parents
and 4,596 administrative units. Selection stops after two levels. Region names
use available source translations for the 11 Web languages and otherwise fall
back to the base name; boundaries are approximate discovery geometry.
- Open a trail by its publication ID, copy that ID or a version link, and inspect
verified author/version information before downloading it. A publication ID
identifies the shared object; a KML Placemark ID identifies an item inside a
file and is not a global directory address.
- Maintain geometry, segments, waypoints, supported KML metadata and attachments;
inspect elevation and timed records; and keep portable local backups. Source
files are retained rather than quietly replaced by an unrelated format.
- Publish, update and archive using device signatures. Successive updates keep
the object ID and link to the previous signed version. Archiving preserves the
published history rather than pretending to delete every remote copy.
- Save shared content for offline use and install supported signed packages on
a connected device. Hardware storage and the supported package capabilities
determine which resources can be used on that device.
Current English Web page querying the public WSS/Reticulum track directory.
The selected Austria boundary is verified; this query returned no shared trails.
This capture uses no USB author and does not claim a completed publication test.
The same built Web page selects Austria and then Vorarlberg through the public
directory, verifies the supplied boundary and queries that administrative area.
The global catalog stops after two levels. This capture uses no USB author;
the capture itself does not establish firmware or publication acceptance.
Current English browser workspace with sample KML data, showing elevation
inspection and the time filter for recorded points. The example supplies its
own elevations and timestamps; it does not imply automatic terrain data.
The release record records deployment and acceptance
separately from these browser captures.
Configure network access under Settings > Reticulum without changing the chat protocol. Manually configured TCP interfaces support IFAC through the SD configuration; RNode/LoRa and AutoInterface IFAC are still pending. See the Reticulum settings guide and Geocaching developer guide.
- Choose a device from the support table below. T-LoRa-Pager SX1262 and T-Deck are the primary validation targets.
- Install a matching image from Releases, or use the website and web flasher for supported targets. For source builds, see Build Methods.
- Prepare for offline use with the Wiki: configure the selected protocol and radio region, and prepare maps and local storage for your device.
Review the responsible-use and safety guidance before field use.
🧩 Current Device Support & Development Status
The table below records the real build targets currently present in the repository and their maturity.
| Device / Target | Build Target | Stack | Current Status |
| --- | --- | --- | --- |
| LILYGO T-LoRa-Pager (SX1262) | tlora_pager_sx1262 | PlatformIO / Arduino | Current default environment and still the most complete day-to-day validation target |
| LILYGO T-Deck | tdeck | PlatformIO / Arduino | Primary validation target; keyboard, chat, maps, and shared UI paths are actively used |
| Seeed Wio Tracker L2 Pro (touchscreen) | wio_tracker_l2 | PlatformIO / Arduino (ESP32-S3) | Offline navigation, current menus and touch interaction accepted on hardware; CI and native LVGL coverage. ES8311 audio is supported; see the target contract. |
| GAT562 Mesh EVB Pro | gat562_mesh_evb_pro | PlatformIO / Arduino (nRF52) | Simplified nRF52 firmware target with monochrome UI, Meshtastic / MeshCore LoRa paths, and persistent on-device radio settings |
| LILYGO T-Echo-Lite-KeyShield | t-echo-lite | PlatformIO / Arduino (nRF52) | Simplified nRF52 firmware target with 192x176 e-paper UI, 4x5 physical keypad input, Meshtastic / MeshCore LoRa paths, and local device settings |
| LILYGO T-LoRa-Pager (LR1121) | tlora_pager_lr1121 | PlatformIO / Arduino | Supported Pager RF variant with LR1121 RF switch and TCXO bring-up |
| LILYGO T-Deck Pro | tdeck_pro_a7682e / tdeck_pro_pcm512a | PlatformIO / Arduino | Separate environments exist, but this line is still in active bring-up / adaptation work |
| LILYGO T-Watch S3 | lilygo_twatch_s3 | PlatformIO / Arduino | Experimental target used more for system and UI validation than for full feature coverage |
| M5Stack Tab5 | TRAIL_MATE_IDF_TARGET=tab5 | ESP-IDF | Main large-screen IDF bring-up target; the shared shell runs and hardware-specific work is still being filled in |
| LILYGO T-Display P4 TFT | TRAIL_MATE_IDF_TARGET=t_display_p4_tft | ESP-IDF | TFT / HI8561 port with shared UI and dashboard; display, touch and sliders verified on the test unit. External keyboard input remains under hardware diagnosis. |
| LILYGO T-Display P4 AMOLED | TRAIL_MATE_IDF_TARGET=t_display_p4_amoled | ESP-IDF | Explicit AMOLED / RM69A10 + GT9895 bring-up target for the shared IDF shell |
Linux release targets include the Cardputer Zero ARM64 device app
and T-Display-CM0 Raspbian ARMHF app, with
installation and native ABI details.
Their paired LoRa messaging and Zero framebuffer/keyboard paths have
separate physical acceptance.
The Linux simulator remains a development target.
How To Choose A Target Today
- If you want the most stable daily development path right now, start with
tlora_pager_sx1262 or tdeck
- If you are debugging a resource-constrained simplified nRF52 target, start with
gat562_mesh_evb_pro or t-echo-lite
- If you are working on the newer large-screen ESP-IDF path, start with
tab5
tdeck_pro_*, lilygo_twatch_s3, t_display_p4_tft, and t_display_p4_amoled are better treated as bring-up, layout, or device-adaptation targets than as the highest-maturity feature-validation path- A build target establishes that the device is present in the repository; the table's status column records page and capability maturity. Features may be enabled or hidden dynamically according to capabilities, RAM budget, and input hardware
- GitHub Actions builds
wio_tracker_l2, tlora_pager_sx1262, tlora_pager_lr1121, tdeck, lilygo_twatch_s3, gat562_mesh_evb_pro, and the nRF52 wrapper target t-echo-lite, plus the ESP-IDF P4 TFT, P4 AMOLED, and C6 companion targets; GAT562 and T-Echo-Lite release artifacts include UF2 files for manual flashing, verified with the nRF52840 UF2 family ID 0xADA52840
🏗️ Shared Architecture & Protocol Interoperability
Trail Mate carries shared messaging, storage, navigation, and UI/business capabilities across device families. The repository separates reusable modules, platform adapters, board definitions, and application shells, with responsibilities documented in the architecture specification.
Meshtastic, MeshCore, and Reticulum/LXMF are selectable network paths within that product model. A device runs one explicit product protocol path at a time; this does not imply automatic bridging between the three networks or complete upstream feature parity. On-device TAK means Trail Mate's own team-awareness capabilities; ATAK, WinTAK, and CoT interoperability are outside the current claim.
Maintaining this shared product involves protocol compatibility, different radio and display drivers, constrained RAM and task stacks, storage ownership, UI behavior, and release images across targets. The CI workflow makes these concerns visible through build matrices and targeted regression and contract checks.
🔒 Security & Reliability
Trail Mate handles input from radio, network, Bluetooth, serial, USB, and removable storage. Protocol parsing, identity and key handling, persistence, and shared hardware access are security-sensitive boundaries.
The repository includes tests for control-frame authentication and corruption rejection, media-frame integrity, duplicate and malformed shard rejection, and voice-inbox persistence. CI also checks storage transactions, bounded map delivery, ESP stack hygiene, Wi-Fi access policy, and Reticulum runtime budgets. These checks provide specific regression evidence, not a claim of a completed security audit.
See SECURITY.md to report a suspected vulnerability privately.
📋 Why Trail Mate Exists
On a walk, the useful things are straightforward: see where you are, find a
route, keep a record and stay in touch with your group. Trail Mate puts those
tools on a device with its own controls, local maps and a radio. Installed map
data remains useful when Internet access is unavailable; communication uses
the protocol and links you configure.
The person carrying the device should keep control of its identity and data.
The device holds its author key. Maps, recordings, messages and contacts have
local storage. Public discovery, direct contacts, Team position and personal
tracks have separate sharing rules, so joining a network does not have to mean
handing one service your complete activity history.
When a larger screen helps, use the browser or Center to edit settings, prepare
maps or work on a trail. The device can authorize a specific publication while
the computer handles its network connection. Independent directories index
signed content, and recipients can verify the author's signature. Publishing
still makes that chosen content public; the privacy section above explains what
others can retain.
Portable files, device-held identity and independently operated services give
people alternatives when a provider changes or disappears. That is the reason
for bringing offline navigation, Meshtastic, MeshCore, Reticulum and team tools
together: keep a useful field companion in the user's hands.
Connection is a capability people can hold. Trail Mate keeps that capability in the hands of each user.
🧭 Product Position
Trail Mate is organized around four defining capabilities:
- Anonymous operation: device identity exists independently of cloud accounts and phone numbers. The system reduces unnecessary public discovery, identity linkage, and location exposure. Anonymous operation has explicit technical limits, and the user still applies security judgment to the surrounding environment.
- Decentralized communication: Meshtastic, MeshCore, and Reticulum provide three selectable product network paths. Identity and contacts can exist independently of any single platform, messages can travel through the network selected by the user, and the loss of one path cannot claim ownership of the whole system. The device runs one explicit protocol path at a time, keeping network membership and behavior understandable.
- Offline operation: input, viewing, configuration, maps, contacts, messages, and tracks can be handled on the device. Phone and desktop tools provide optional extensions while control remains at the edge.
- TAK capability: the device provides member, position, waypoint, track, status, and team-message awareness. Trail Mate's current TAK claim covers its own on-device team-awareness capability. ATAK, WinTAK, and CoT interoperability sit outside the present claim.
The system models public discovery position, contact position, Team position, and local tracks as four distinct data relationships. Users should be able to confirm the shared content, its recipients, and the network path used.
⚖️ Responsible Use, Legal Compliance, and Scope
Trail Mate is an assistance system for hiking, camping, trail running, and
other outdoor activities. Its purpose is to help people share positions,
coordinate with a group, maintain safety contact, and seek assistance when
normal connectivity is limited or unavailable.
Trail Mate is not intended to serve anyone who harms, controls, surveils,
harasses, or stalks others, or who engages in any other unlawful activity.
Use this device and its software only for lawful, legitimate purposes that
respect the rights, safety, and privacy of others.
The product boundary is deliberate: Trail Mate focuses on helping people stay
in contact and obtain assistance during outdoor activities. It is not a
general-purpose radio experimentation platform or a complete communication
protocol terminal. Features unrelated to outdoor activity, safety
coordination, or assistance—and especially features aimed primarily at radio
operation, network administration, or other non-outdoor uses—are outside the
scope of this project.
Legal compliance
Before using Trail Mate, understand and comply with every applicable law,
regulation, and local requirement where it is used. This includes, but is not
limited to:
- Radio-spectrum rules, including permitted frequencies, transmit power,
transmission duration, and duty-cycle limits
- Radio-equipment approval, licensing, registration, or amateur-radio operator
requirements
- Rules set by countries, regions, parks, protected areas, campsites, and
event organizers
- Privacy, personal-data, location-data, and communication-content protections
- Restrictions governing emergency, public-safety, and other protected
communications
Requirements vary substantially by country and region. A feature being
technically capable of operating does not mean it is lawful to use in a given
location. Each user is responsible for ensuring that their device
configuration, frequency plan, transmit power, and operating practice comply
with local requirements.
Do not use Trail Mate, derivative devices, software, or networks for illegal
activity. This includes unauthorized interception, tracking, or location of
people; privacy violations; harassment; fraud; regulatory evasion;
interference with lawful radio communications; or assisting anyone in harming
others.
Meshtastic and MeshCore interoperability
Trail Mate integrates selected Meshtastic and MeshCore protocol capabilities
so that outdoor users can establish the necessary interoperability with people
running their official firmware. The intended use is outdoor coordination,
safety contact, and seeking or offering assistance when conventional network
coverage is absent or unreliable.
Trail Mate does not aim to implement every Meshtastic or MeshCore feature, nor
to replace their official firmware, clients, or ecosystems. It implements only
the capabilities that fit Trail Mate's purpose of outdoor assistance,
coordination, and safety contact.
Features without a direct relationship to outdoor activities and safety
communication—particularly those focused on radio experimentation, network
administration, general-purpose communication extensions, or other
non-outdoor uses—are not planned for implementation. This is a product-scope
decision, not a judgment on Meshtastic, MeshCore, their communities, or their
respective feature directions.
Meshtastic and MeshCore names, software, protocols, and related materials
belong to their respective owners and communities. Compatibility or
interoperability with those projects does not imply their endorsement,
approval, or official support of Trail Mate.
Safety notice
Trail Mate can support outdoor activities, but it cannot replace thorough trip
planning, route preparation, weather assessment, navigation skills, first-aid
knowledge, group coordination, or professional rescue equipment.
In remote, high-risk, extreme-weather, or otherwise unreliable communication
environments, do not treat Trail Mate as your only life-safety measure. Choose
appropriate additional equipment for the activity, such as maps and a compass,
backup power, first-aid supplies, a whistle, satellite communications, or a
personal locator beacon, and share your itinerary with a reliable contact
before departure.
🔒 Frozen Embedded-Firmware Boundary
The major feature set of Trail Mate's current embedded firmware is now defined. Its future scope consists of the existing feature domains, the three Meshtastic/MeshCore/Reticulum product protocols, and the four core capabilities of anonymous operation, decentralization, offline operation, and TAK. This boundary applies specifically to the embedded firmware product surface. Trail Mate as a whole also includes the Linux version and other edge-device forms.
Ongoing work focuses on bug fixes, reliability and security, protocol interoperability correctness, resource efficiency, carrying the existing product on suitable hardware, test tooling, and documentation. New board ports carry the established capabilities onto suitable devices.
✨ Core Features
🧭 Main Menu Overview
The main menu provides quick access to maps, chat, Tracker, Music and utilities.
Pager, T-Deck and Wio L2 use the same grid with a column count that adapts to the
available width. Pager uses W/A/S/D or the wheel to select an app, V to switch
between apps and widgets, and H for Help. Touch devices expose the same pages
through their controls and gestures.
Current native Pager preview with simulated service state. The footer keeps
the V shortcut visible; this image demonstrates the interface rather than a
physical-device test.
🧭 GPS Map (Performance-First)
| Layer Menu | OSM Base Map |
| --- | --- |
| | |
| Terrain Base Map | Satellite Base Map |
| --- | --- |
| | |
- Fixed North-Up map orientation (no rotation)
- Fully offline map rendering from SD-hosted TMAP packages
- Three switchable base layers: OSM / Terrain / Satellite
- Optional contour overlay for terrain shape awareness
- Real-time position marker for the current GPS fix
- Discrete zoom levels optimized for embedded systems
- Simple breadcrumb trails for path awareness
- Fast in-page layer switching via map layer menu (no page restart)
The current bottom bar keeps zoom at the left and Pos, Help, conditional
Team, and Menu at the right. Menu opens upward: Map Layer selects OSM,
Terrain or Satellite directly; Search opens the existing place picker;
Navigation, Tracks and Contours open dedicated management dialogs.
Load/unload and contour visibility are managed inside those dialogs. Team has a
separate quick menu and appears only while joined to a valid team.
| Navigation management | Touch-accessible Help |
| --- | --- |
| | |
The Menu, Navigation and Help images are production LVGL native renders
with sample map/GPS data from the candidate before the saved-route replan/Finish
controls were added. Follow the workflow below for the current controls. The
base-layer images illustrate existing map display. Native renders are not physical-device
acceptance captures. Each layer displays only the coverage and zoom levels
contained in its installed packages.
On supported PSRAM-capable ESP targets, create a foot route through Tracker →
Menu → Nav → New. Use the current GNSS fix as the origin, or select both endpoints
with the existing POI search. Calculate from an installed routing graph, then save
and preview a self-contained .tmroute file. Load the saved plan and open Map
for indexed viewport rendering, progress/remaining distance and geometric turn
hints. Map's Navigation dialog offers manual/automatic replanning, cancel/retry,
reload and a fixed Stop/Finish action. A replacement is opened before activation;
a failed or cancelled replan preserves the previous saved route. Confirmed
arrival ends the active session. Unloading does not delete its file.
Following runs while Map is open and resumes the saved active path on reentry.
Geometry cues have no street-name or intersection semantics. Routing coverage
depends on the installed package's graph, independently of its raster coverage.
The released TMAP SDK 0.2.0 is pinned by commit and source hash. See the
native navigation implementation and resource evidence
for the Center London 20.779 km replay, fixed reader/screen budgets, failure
behavior and the distinction between host measurements and physical-device
acceptance. A few KiB of free RAM cannot run the complete planner.
Node inspection from the map
Select a discovered node directly on the map to inspect its protocol, last-seen state, zoom level, coordinates, and surrounding offline-map context without leaving the situational view.
Recommended TMAP package layout on the SD card:
/maps/tmap/osm/<region>-osm-z<min>-<max>.tmap
/maps/tmap/terrain/<region>-terrain-z<min>-<max>.tmap
/maps/tmap/satellite/<region>-satellite-z<min>-<max>.tmap
/routes/navigation/*.tmroute # saved calculated plans
/trailmate/packs/fonts/<resource-id>/ # required generated map fonts
Copy the packages and their generated font resources from Center. POIs, names and
search indexes are carried by the OSM TMAP; detailed Center packages can also
contain their routing graph and digital elevation. The current TMAP workflow does not
require the former per-tile PNG/JSON export. The reader also discovers flat
/maps/tmap/*.tmap packages and supported routing locations described in the
guide. See TMAP maps and terrain
for export, installation and font details.
🛰️ GNSS Sky Plot
- Real-time sky plot of visible satellites (azimuth/elevation)
- SNR status and constellation coloring (GPS/GLONASS/Galileo/BeiDou)
- Clear indication of satellites used in the current fix
- Summary of USE/HDOP/FIX for fast diagnostics
📡 Protocol Probe (LoRa Profile Discovery)
Protocol Probe finds complete LoRa air profiles carrying real Trail Mate
protocol traffic. It is not an RSSI spectrum analyser and never calls a quiet
frequency a usable protocol channel.
- Starts with the active profile and finite protocol-derived candidates instead of a generic 25 kHz frequency grid
- MeshCore uses Discover and a valid response/ACK for active confirmation
- Meshtastic passively discovers a target node, then uses a keyed unicast
want_ack check when available
- Reticulum records only self-consistent public Announce or control Path Request traffic; it remains passive and does not claim confirmation in this temporary tuning flow
- Lists only
OBSERVED and CONFIRMED profiles, with evidence counts but no business-packet labels
- Lets the user apply a selected observed/confirmed profile only after explicit confirmation
See the Protocol Probe specification for the
evidence model and protocol-specific boundaries.
📡 Decentralized Messaging (Meshtastic / MeshCore / Reticulum)
| Conversation | Reticulum Peer |
| --- | --- |
| | |
Messages view shows recent conversations and history for quick review.
- Three selectable product protocols: Meshtastic, MeshCore, and Reticulum
- Reticulum mode uses an on-device Reticulum/LXMF runtime and can carry traffic over configured LoRa, AutoInterface, or TCP gateway interfaces
- Reticulum peer details expose the display name, LXMF address, and identity hash needed to verify and manage decentralized identities
- Chinese text support
- Compatible with the Meshtastic public mesh (LongFast/PSK)
- Compatible with MeshCore networks (native MeshCore packet path)
- Standalone operation with on-device controls and optional USB tools; Meshtastic / MeshCore companion-app connections are outside the supported product workflow
- Designed for high latency, low bandwidth, and packet-loss environments
- Contacts, conversations and messages persist on-device. Reticulum networking uses the SD working configuration; the firmware manages its binary peer directory.
For the Reticulum SD-card format, file locations, contact import, and on-device operations, see the Reticulum Mode User Guide.
☁️ Mesh MQTT (Meshtastic / MeshCore)
Trail Mate can bridge both Meshtastic and MeshCore traffic through a configurable MQTT broker when Internet or gateway connectivity is available. Each protocol has independent enable, uplink, downlink, host, port, root-topic, and credential settings. Meshtastic ships with its ecosystem defaults; MeshCore ships disabled with the public test.mosquitto.org:1883 test broker and meshcore root as editable starter values. The public broker is intended for evaluation only—field and production deployments should use a private or self-hosted broker.
🌐 Nomad Network
| Micron Page Rendering | Engine & Link Semantics |
| --- | --- |
| | |
| Offline Form State | Compatibility Diagnostics |
| --- | --- |
| | |
Nomad Network renders Reticulum Micron pages directly on the device. The embedded browser supports navigable links, constrained layout primitives, forms, cached/offline-ready state, and visible compatibility diagnostics for unsupported or unknown Micron constructs. It keeps small information services reachable over Reticulum without depending on a conventional web browser or the public Internet.
📷 SSTV Receiver (Slow-Scan TV)
- Receive SSTV audio and decode to images on-device
- Real-time decode progress and image preview
- Designed for low-power, embedded decoding
👥 Contacts
Contacts is a persistent on-device communication directory. It combines discovered and user-maintained contacts, recent activity, and protocol identities, with quick access to direct messaging, calls, ping, or team actions when supported by the active protocol and hardware.
On keyboard-equipped interfaces, press S to search contacts. Save a discovered
peer from Nearby or use Contacts > Add. A Reticulum destination entered without
verified identity keys remains Address pending until a valid announce or path
response supplies them. The firmware owns /mesh/peers.bin; current firmware
does not import contacts from a hand-edited TSV/JSON file. See the
Reticulum guide
for the supported workflow.
💻 Data Exchange (PC Link)
PC Link connects the device to a host computer and exposes a structured HostLink stream
for real-time APRS/iGate integration, diagnostics, and data capture.
- Live forwarding of LoRa messages, team updates, and GPS snapshots
- APRS-oriented metadata for external gateways and dashboards
- USB CDC-ACM transport with deterministic framing
🖥️ Trail Mate Center
Trail Mate Center is the desktop-side control center for Trail Mate and Meshtastic-compatible field devices connected through USB HostLink. Its Avalonia interface combines live maps, nodes, teams, event streams, messaging, device configuration, replay, protocol inspection, and data export in one application.
It also prepares offline OSM, terrain, satellite, and contour-map regions for removable media; can build a buffered cache around imported KML routes; and provides a propagation workbench for coverage, interference, relay placement, calibration, and result export. Trail Mate Center is maintained as a separate desktop repository and does not contain the embedded firmware.
| Offline map preparation | Desktop propagation workbench |
| --- | --- |
| | |
Existing actual screenshots from the Center repository. These illustrate the
desktop workflow; Center has its own release cycle and is not assigned the
firmware's 1.0.0 version. Screenshot provenance is recorded with the assets.
🤝 TAK / Team Mode (ESP-NOW Pairing + LoRa Ops)
Team mode is designed for small groups that are physically together.
Pairing happens over ESP-NOW at close range to exchange a team key,
then all team operations run over LoRa.
- Create a team (leader) or join a nearby team (member)
- Secure key distribution and team ID establishment during pairing
- Team chat (text/location) and shared status updates
- Member list with leader/member roles and counts
- Team waypoint / assembly-point sharing
- Team map view with latest member positions and track snapshots
🧭 Track Recording & Route Following
| Step 1 — Elevation & Route Overview | Step 2 — Waypoint Image Preview |
| --- | --- |
| | |
- Track recording and storage (record/route modes)
- Track list browsing and route focus
- KML route overlay support
- Two-stage route preview: inspect the full elevation profile first, then page through georeferenced remote images and their positions along the route
- Route preview progress, saved-image counts, distance, and load state remain visible on the embedded display
- GPX tracks exportable via USB Mass Storage
🎙️ Walkie Talkie
- FSK + Codec2 voice walkie talkie
- Half-duplex PTT (press to talk / release to listen)
- Jitter buffering and fixed playback cadence for stability
💡 Non-Negotiable Design Principles
- Edge ownership: identity, contacts, messages, configuration, maps, and tracks belong first to the person holding the device.
- Explicit data relationships: protocols, contact relationships, and position purposes remain distinct and visible to the user.
- Honest uncertainty: the interface directly presents link failure, stale position, and unknown state, and displays success only after obtaining evidence of success.
- Predictable degradation: when a network, phone, cloud service, or hardware capability is absent, the independently useful parts of the system remain available.
- Long-term reliability on constrained hardware: resource efficiency, determinism, and maintainability take priority over feature accumulation and visual spectacle.
📱 Hardware-Carriage Strategy
Trail Mate's hardware work focuses on devices suited to carrying the established product capabilities. This section describes the hardware-selection direction. The build-target table above records current implementation maturity. New hardware continues to carry the defined product domains.
Current priority device categories include:
- Keyboard-first LoRa handhelds such as
T-LoRa-Pager, T-Deck, T-Deck Pro, and Cardputer-style devices, where users can enter free-form text directly without depending on a phone
- Large-screen touch navigation terminals such as
M5Stack Tab5 and T-Display P4, which are better suited to maps, team situational awareness, and HostLink / companion-computer workflows
- Ultra-low-power / small-screen message terminals such as tighter
nRF52 + SX1262 class devices, where monochrome UI, status viewing, simplified chat, and BLE bridging matter more than feature breadth
When evaluating hardware, the project currently prioritizes:
- Reliable LoRa / Sub-GHz radio capability, or at least a clear path to integrate it cleanly
- A device that can handle basic input, viewing, and configuration independently, with phones serving as optional extensions
- Reasonable power, battery, and field portability characteristics
- A stable enough ecosystem, documentation base, or supply chain to justify long-term maintenance
The project stays as hardware-agnostic as practical. Protocol logic, storage, and UI/business behavior remain decoupled from board-specific code. Embedded and Linux targets share the established Meshtastic, MeshCore, Reticulum, and TAK capabilities and retain one product model.
🛠️ Build Methods
Trail Mate currently uses two main toolchain paths: PlatformIO and ESP-IDF. The commands below are intended to be run from the repository root.
PlatformIO
PlatformIO covers both the ESP32 Arduino targets and the current nRF52 Arduino targets. The root platformio.ini keeps only shared configuration, while the actual target environments live under variants/*/envs/*.ini.
Common build commands:
# Primary targets
platformio run -e tlora_pager_sx1262
platformio run -e tlora_pager_lr1121
platformio run -e tdeck
# nRF52 / simplified targets
platformio run -e gat562_mesh_evb_pro
platformio run -d builds/pio_nrf52 -e t-echo-lite
# Other integrated targets
platformio run -e wio_tracker_l2
platformio run -e tdeck_pro_a7682e
platformio run -e tdeck_pro_pcm512a
platformio run -e lilygo_twatch_s3
If you want more verbose diagnostics, the repository also provides these debug environments:
platformio run -e tlora_pager_sx1262_debug
platformio run -e tdeck_debug
platformio run -e lilygo_twatch_s3_debug
Generic upload form:
platformio run -e <env> --target upload
If you need to select the serial port explicitly, add --upload-port COMx. For example:
platformio run -e tlora_pager_sx1262 --target upload --upload-port COM6
Notes:
- Running
platformio run with no explicit environment uses the root default environment, currently tlora_pager_sx1262
- If you only want to sanity-check whether a target still builds, start with
tlora_pager_sx1262, tdeck, gat562_mesh_evb_pro, or t-echo-lite
- For very tight-RAM nRF52 simplified targets such as GAT562 and T-Echo-Lite-KeyShield, use release-like or low-log validation and enable extra debug output only for a specific diagnostic need
ESP-IDF
ESP-IDF is currently used mainly for the newer shared-shell path. The officially wired targets right now are tab5, t_display_p4_tft, and t_display_p4_amoled. The repository root already contains the top-level CMakeLists.txt, so you can invoke idf.py directly from the root directory.
tab5 example:
idf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 reconfigure build
idf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 -p COM6 flash
idf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 monitor
t_display_p4_tft example:
idf.py -B build.t_display_p4_tft -DTRAIL_MATE_IDF_TARGET=t_display_p4_tft reconfigure build
idf.py -B build.t_display_p4_tft -DTRAIL_MATE_IDF_TARGET=t_display_p4_tft build
t_display_p4_amoled example:
idf.py -B build.t_display_p4_amoled -DTRAIL_MATE_IDF_TARGET=t_display_p4_amoled reconfigure build
idf.py -B build.t_display_p4_amoled -DTRAIL_MATE_IDF_TARGET=t_display_p4_amoled build
Notes
- ESP-IDF generated
sdkconfig state now lives inside the selected build directory such as build.tab5, build.t_display_p4_tft, or build.t_display_p4_amoled, giving every target isolated configuration output
- For Tab5, prefer running
monitor separately after flashing; chaining flash monitor can leave ESP32-P4 in ROM download mode after auto-reset
- VS Code already provides split Tab5, T-Display-P4 TFT, and T-Display-P4 AMOLED
Reconfigure / Build / Flash / Monitor tasks via tools/vscode/run_idf_task.ps1
- If your goal is release validation or routine regression checks, prefer the main PlatformIO path that CI already covers; ESP-IDF targets are still more useful for board bring-up and shared-shell evolution
🌐 Documentation Language
English documentation is maintained in this repository.
📝 Changelog
See CHANGELOG.md for version history. The Roadmap records the established product direction and maintenance boundary.
📄 License
This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
The license is intended to ensure that:
- Source code remains available when the project is modified, deployed, or offered as a network service
- The core system cannot be incorporated into closed-source or proprietary products without authorization
Commercial Licensing
A separate commercial license may be provided for the following use cases:
- Commercial or closed-source products
- Hardware vendors integrating or pre-installing the firmware
- Commercial applications unable or unwilling to comply with AGPLv3
For such use cases, please contact the project author to discuss licensing terms.
Publication of this repository does not grant any default commercial rights.
See the LICENSE file for details.
🔐 Project Scope
This repository contains Trail Mate's open-source edge-device implementations, including:
- Embedded firmware for ESP32-, nRF52-, and related targets
- Linux portable-terminal applications and shared UI/business capabilities
- Offline maps, positioning, tracks, and on-device TAK capabilities
- Meshtastic, MeshCore, and Reticulum/LXMF communication paths and local storage
- HostLink, board integrations, tests, and development tooling
This project does not include:
- Separately distributed commercial desktop software
- Mobile applications (iOS / Android)
- Commercial services or platform products
Any surrounding tools or services may follow different licensing strategies and are outside the scope of this repository.
🤝 Contributing
Trail Mate's embedded product boundary is now defined. Contributions focus on making the existing capabilities more trustworthy, understandable, and usable on real devices.
Contribution & Copyright
Unless explicitly stated otherwise, all contributions to this repository are released under the AGPLv3 license.
The project is currently author-driven and does not accept contributions that alter core architecture or licensing terms.
For commercial collaboration or deep involvement, please contact the author directly.
The most useful contributions include:
- Private vulnerability reports through SECURITY.md
- Reproducible defect reports with device, firmware, protocol, network conditions, and exact steps
- Real test results from off-grid, weak-link, low-power, and harsh environments
- Interoperability verification against upstream Meshtastic, MeshCore, and Reticulum/LXMF implementations
- Measurements of power, memory, storage, concurrency, and long-running behavior
- Reliability, security, hardware-port, test, and documentation improvements that preserve the product boundary
- Specific reports of misleading status, unclear operations, or ambiguous privacy boundaries
Pull Requests remain welcome, but changes to the core architecture, product boundary, or licensing strategy should be discussed with the author first. Even without code, a report that clearly states the conditions, action, expected result, and actual result is valuable.
Every existing Trail Mate promise should be worthy of trust.
✅ Current Capability Index
This section provides a searchable implementation index. The Trail Mate Wiki is the user-documentation source for configuration, keyboard shortcuts, file formats, and operational procedures.
🧭 GPS Navigation & Tracks
- Offline map rendering (north-up, no rotation)
- Runtime base layer switching: OSM / Terrain / Satellite
- Contour visibility through a dedicated Map management dialog
- SD-hosted TMAP packages with independent labels, POIs and place search
- Real-time position marker and coordinate display
- Discrete zoom levels and low-power tuning
- Track recording, route and navigation cards with selected-item hydration
- Foot-route calculation from current/searched origin to a searched destination
- Persistent
.tmroute plans, indexed viewport reads, geometric turn hints,
confirmed off-route replanning and arrival/Stop/Finish while Map is open
- Tracker View/New/Current submenus and Map load/unload management
- KML route overlays and focus
- GPX tracks exportable via USB Mass Storage
📝 Decentralized Messaging (Meshtastic / MeshCore / Reticulum)
- LoRa text messaging with Chinese support
- Meshtastic public mesh compatibility (LongFast/PSK)
- MeshCore network compatibility (native MeshCore packet path)
- On-device Reticulum/LXMF runtime with LoRa, AutoInterface, and TCP gateway interfaces
- SD-backed Reticulum network/LXMF settings and a device-managed persistent contact directory
- Standalone controls and optional USB tooling; no supported Meshtastic / MeshCore companion-app workflow
- Message history and conversation list
- Routing confirmations and reliability diagnostics
- Unishox2 decompression for incoming messages
🤝 TAK / Team Mode (ESP-NOW Pairing + LoRa Ops)
- Close-range ESP-NOW pairing with key distribution and team ID setup
- Member list and leader/member roles
- Team chat (text/location)
- Team map view with member position updates
- Team waypoint / assembly-point sharing
- Team track and status rebroadcast
📷 SSTV Receiver (Slow-Scan TV)
- SSTV audio reception and on-device image decoding
- Real-time decode progress and image preview
- Lightweight pipeline for low-power hardware
👥 Contacts
- Node discovery and contacts list
- Node metadata (ID/short name/device info)
- Online/offline status and recent activity
- Quick jump to direct or team conversations
💻 Data Exchange (PC Link / HostLink)
- USB CDC-ACM transport
- HostLink frames/events/config support
- Live forwarding of LoRa/team/GPS data
- APRS/iGate-oriented metadata output
🎙️ Walkie Talkie
- FSK + Codec2 voice walkie talkie
- Half-duplex PTT (press to talk / release to listen)
- Jitter buffering and fixed playback cadence
⚙️ System Settings & Status
- Display/sleep controls and basic settings
- GPS and network-related configuration
- Status bar icons and system notifications
- Screenshot capture (ALT double-press, saved to SD /screen)
💾 USB Mass Storage
- Device mounts as a USB drive
- Direct management of exported tracks and files
🔌 System Management
- Graceful shutdown
- Low-power management
- Runtime status monitoring
📻 Trail-mate Simplified Edition (nRF52 / GAT562 Mesh EVB Pro / T-Echo-Lite-KeyShield)
- The simplified edition currently supports two nRF52 devices:
GAT562 Mesh EVB Pro and T-Echo-Lite-KeyShield
- It already covers Meshtastic and MeshCore dual-protocol LoRa RX/TX, including Text / NodeInfo / Position handling and the corresponding persistence paths
- Device-side protocol switching and Meshtastic / MeshCore air-parameter editing are available for standalone operation without relying on a phone app
- Device-side parameters can already be edited locally and persisted
- The monochrome UI can be used to view time, GPS, and radio status
🙏 Acknowledgements
Trail Mate has benefited from real support from the community and hardware vendors.
-
Special thanks to LILYGO for providing development hardware.
Their open hardware ecosystem and stable ESP32 product line have enabled continuous iteration and validation in real devices.
-
Special thanks to M5Stack for supporting the Cardputer Zero adaptation with hardware support.
Their support helped validate the Cardputer Zero environment against real device constraints and move Trail Mate's Linux portable-device path forward.
-
Special thanks to Seeed Studio for supporting Trail Mate with development hardware.
Their support helps broaden device compatibility and enables continued development and validation on real hardware.
-
Special thanks to Shenzhen GAT-IOT Technology Co., Ltd. (https://github.com/gat-iot) for providing hardware support to this project.
The real devices they supplied have helped Trail Mate carry out development, debugging, and validation on actual hardware, further advancing the implementation and refinement of related features.
These contributions lowered the barrier to prototyping and allowed Trail Mate to receive real-world feedback much earlier.
If other hardware vendors resonate with the project's design philosophy and wish to explore its potential in offline outdoor scenarios, feel free to get in touch.
When feasible, I am happy to adapt the software to additional devices and provide feedback based on real usage.
Special thanks to dawsonjon (https://github.com/dawsonjon) for the open-source PicoSSTV project:
https://github.com/dawsonjon/PicoSSTV. Our SSTV receiver borrows from its decoding approach.
For algorithm details, see: https://101-things.readthedocs.io/en/latest/sstv_decoder.html
Built with care for the outdoor community ❤️
NOTICE
About This Project
Trail Mate is an edge-first personal communication and situational-awareness system designed for anonymous operation, decentralization, and offline use. It runs on personally held embedded devices and Linux portable terminals, using Meshtastic, MeshCore, Reticulum, and on-device TAK capabilities for communication, position, navigation, and coordination.
Trail Mate makes the Internet an optional connectivity resource and places basic communication directly on personally held devices. Identity, contacts, messages, position, maps, and tracks remain as close as possible to the user, with explicit relationships and choices whenever data is shared.
This repository is an actively developed and maintained engineering project containing practical implementations for evaluation, porting, integration, and deployment.
If you are evaluating, integrating, porting, modifying, or using this codebase in any product, research, deployment, or internal tooling — you are encouraged to contact the author.
Author
Vic Liu
The system architecture, communication protocols, embedded firmware, Linux edge implementation, and reference implementations are primarily maintained by the original author.
Contact
You may contact me for:
- Hardware adaptation or porting
- Protocol clarification
- Integration into existing radio systems
- Commercial licensing discussions
- Collaboration or joint development
- Field deployment guidance
- Bug reports that are difficult to describe via Issues
Discord or WeChat is preferred for real-time technical discussion.
Email is preferred for formal or long-form communication.
For Organizations / Companies
If your organization is testing or evaluating this repository internally:
You are welcome to reach out even if you are only in the research or feasibility stage.
Early technical discussion usually saves significant engineering time.
Customization, hardware adaptation guidance, and technical consulting are available.
Licensing Reminder
This project is open-source and distributed under the terms specified in the LICENSE file.
If you are using the code in a network service, device firmware distribution, or any redistributable system, please ensure that your usage complies with the license requirements.
If you are unsure, please contact the author before deployment.
Intent
Trail Mate aims to reduce the number of centers a person must trust in order to communicate, navigate, and coordinate. It provides autonomy with explicit, verifiable boundaries: the device remains with its user and continues to work when cloud accounts, phone applications, and stable public networks are all absent.
The embedded feature surface is now defined. Defect reports, interoperability testing, field validation, deployment experience, and improvements to reliability, security, resource efficiency, hardware carriage, and documentation clarity are especially welcome.
You are not required to open Issues before contacting the author directly.
Thank you for taking the time to examine and use this project.