liu weikai# 🗺️ Trail Mate
A low-power, offline-first handheld device for outdoor navigation and communication
📋 Overview
Outdoor activities often take place in environments where cellular networks are unreliable or completely unavailable. In these conditions, people still need to exchange short text messages, understand relative positions, and maintain basic orientation — without depending entirely on smartphones or complex infrastructure.
Trail Mate is a low-power, offline-first handheld device project built on ESP32-class hardware, designed specifically to address these constraints.
It focuses on two core needs in offline outdoor scenarios:
- Simple and reliable self-positioning, using a fixed north-up GPS map to avoid unnecessary visual complexity
- Direct LoRa text communication, allowing users to send free-form messages to Meshtastic or MeshCore mesh networks without relying on a smartphone
Trail Mate prioritizes stability, efficiency, and interoperability over feature density or visual polish, making it suitable for long-term use on constrained hardware in real outdoor environments.
✨ Core Features
🧭 Main Menu Overview
The main menu provides quick access to GPS, LoRa chat, tracker, and system utilities, designed for fast navigation on a physical keyboard without deep menu nesting.
🧭 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 card tiles
- 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)
Expected SD card tile layout:
/maps/osm/{z}/{x}/{y}.png
/maps/terrain/{z}/{x}/{y}.png
/maps/satellite/{z}/{x}/{y}.jpg
/maps/contour/major-500/{z}/{x}/{y}.png
/maps/contour/major-200/{z}/{x}/{y}.png
/maps/contour/major-100/{z}/{x}/{y}.png
/maps/contour/major-50/{z}/{x}/{y}.png
/maps/contour/major-25/{z}/{x}/{y}.png
🛰️ 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
📶 Energy Sweep (Sub-GHz Scan)
Energy Sweep provides a fast Sub-GHz occupancy view for channel planning in the field.
- Real-time RSSI sweep bars across the configured Sub-GHz band
- Cursor readout for exact frequency, RSSI, and noise floor
- Best-channel recommendation with cleanliness/SNR hint
STOP/SCANcontrol for pause/resumeAUTOapplies the current best channel and moves cursor to the recommended frequency- Sweep range follows the currently configured region (Meshtastic region or MeshCore region preset)
📡 LoRa Chat (Meshtastic + MeshCore Compatible)
Messages view shows recent conversations and history for quick review.
- LoRa-based text messaging
- Chinese text support
- Compatible with the Meshtastic public mesh (LongFast/PSK)
- Compatible with MeshCore networks (native MeshCore packet path)
- Bluetooth connectivity to Meshtastic / MeshCore companion apps
- Broadcast-based communication (no central infrastructure)
- Designed for high latency, low bandwidth, and packet-loss environments
- Minimal protocol implementation optimized for ESP32-class devices
📷 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 shows discovered nodes, recent activity, and quick actions to jump into direct or team conversations.
💻 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
🤝 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
- Track recording and storage (record/route modes)
- Track list browsing and route focus
- KML route overlay support
- 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
💡 Design Philosophy
Trail Mate is not a smartphone replacement, and it does not attempt to hide the real limitations of offline communication.
Instead, it focuses on:
- ✅ Honest representation of uncertainty
- ✅ Deterministic and predictable system behavior
- ✅ Long-term reliability on constrained hardware
💬 Designed for environments where simplicity and robustness matter more than visual refinement.
📱 Planned Supported Devices
Trail Mate is designed to prioritize ESP32-based handheld devices with built-in physical keyboards, allowing users to send free-form text messages directly over LoRa mesh networks without relying on a smartphone — a key design goal of this project.
These platforms are relatively mature in terms of LoRa capability, input methods, and community ecosystem, making them suitable foundations for offline communication and navigation terminals:
- LILYGO T-Deck Plus
- LILYGO T-Deck Pro
- LILYGO T-LoRa-Pager
- M5Stack Cardputer
The project aims to remain as hardware-agnostic as possible. Core logic — including GPS processing, LoRa protocols, map rendering, and chat functionality — is decoupled from specific hardware implementations, allowing future expansion to additional ESP32-class platforms while maintaining compatibility with Meshtastic and MeshCore networks.
🧩 Current Device Support & Development Status
As of March 12, 2026, the repository contains both mature PlatformIO targets and active ESP-IDF bring-up targets.
| Device / Target | Build Path | Current Status |
|---|---|---|
| LILYGO T-LoRa-Pager (SX1262) | PlatformIO tlora_pager_sx1262 |
Primary supported target; shared UI/runtime path is active |
| LILYGO T-LoRa-Pager (SX1280) | PlatformIO tlora_pager_sx1280 |
Supported build target; follows the same shared shell structure |
| LILYGO T-Deck | PlatformIO tdeck |
Primary supported target; shared menu/chat/map path is active |
| M5Stack Tab5 | ESP-IDF TRAIL_MATE_IDF_TARGET=tab5 |
Active bring-up target; shared shell is running and hardware integration is in progress |
| LilyGO T-Display P4 | ESP-IDF TRAIL_MATE_IDF_TARGET=t_display_p4 |
Early target shell wired into the common IDF app root |
| LILYGO T-Watch S3 | PlatformIO lilygo_twatch_s3 |
Experimental / secondary target; not the main focus of current feature validation |
Progress Snapshot
- The repository now uses one shared UI/page/runtime structure across PlatformIO and ESP-IDF instead of maintaining separate page implementations per app layer.
- PlatformIO targets currently provide the most complete end-to-end experience for Pager and T-Deck.
- ESP-IDF support has moved from a temporary skeleton to the shared startup/menu/status shell, with Tab5 as the main active hardware bring-up target.
- Capability-gated pages are now enabled or hidden per platform/runtime, rather than duplicated as separate implementations.
- Device-specific layout/profile work is still ongoing, so feature maturity can vary by target even when the page exists in the shared menu.
What This Means in Practice
- If you want the most stable daily development path today, start with
tlora_pager_sx1262ortdeck. - If you are working on the new large-screen ESP-IDF path, use
tab5. - “Planned supported devices” above describes the long-term hardware direction; the table in this section describes the actual repository targets that are wired today.
🛠️ Build Methods
Trail Mate currently supports two build flows: PlatformIO for Arduino-based targets and ESP-IDF for the newer shared IDF shell targets.
PlatformIO
Use PlatformIO for Pager / T-Deck / T-Watch build targets:
platformio run -e tlora_pager_sx1262
platformio run -e tlora_pager_sx1280
platformio run -e tdeck
platformio run -e lilygo_twatch_s3
To build and upload:
platformio run -e tdeck --target upload
platformio run -e tlora_pager_sx1262 --target upload
ESP-IDF
Use the shared apps/esp_idf shell with an explicit target selector:
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
For the t_display_p4 target:
idf.py -B build.t_display_p4 -DTRAIL_MATE_IDF_TARGET=t_display_p4 reconfigure build
Notes
- ESP-IDF generated
sdkconfigstate now lives inside the selected build directory such asbuild.tab5orbuild.t_display_p4. - For Tab5, prefer running
monitorseparately after flashing; chainedflash monitorcan leave ESP32-P4 in ROM download mode after auto-reset. - VS Code tasks for the IDF workflow are available through
tools/vscode/run_idf_task.ps1.
🌐 Languages
📝 Changelog
See CHANGELOG.md for version history and planned updates.
📄 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 the core system implementation of the Trail Mate project, including but not limited to:
- Device-side firmware
- Offline navigation and GPS processing logic
- LoRa-based communication protocols and mesh behavior
- System interaction and state management for constrained hardware
This project does not include:
- 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
All code in Trail Mate is 100% generated by AI under human guidance. The project itself is a long-term experiment in human–AI collaboration for real engineering systems.
Here, contribution does not equal writing code.
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.
Who Are the Most Important Contributors?
The most important contributors are people who actually spend time outdoors.
We especially welcome:
- Hikers, campers, cyclists, off-road travelers, anglers
- Users operating in no-network, low-power, harsh environments
- People who may not write code, but have strong intuition about what is useful and what is not
Their judgments, frustrations, and decisions are the starting point for this system’s evolution.
What Can Contributions Be?
-
🧭 Real-world usage scenarios and problem descriptions
In what environment? What went wrong? What behavior felt unreliable?
-
🧠 Intuitive judgments about feature trade-offs
What information matters? What becomes noise?
-
🧪 Failure cases and boundary feedback
When does the system stop being trustworthy?
-
🔑 Token resources to support AI generation, verification, and iteration
Even if you never submit code, your judgment can still be transformed — through AI — into executable, verifiable system behavior.
How Do We Collaborate?
- Humans (especially outdoor users) decide: what deserves to exist
- AI translates those decisions into: consistent, runnable implementations
Pull Requests are welcome, but they are neither the only nor the most important form of contribution. Trail Mate values judgment quality and real-world feedback over lines of code.
If a feature has no value outdoors, it should not exist.
✅ Implemented Features
🧭 GPS Navigation & Tracks
- Offline map rendering (north-up, no rotation)
- Runtime base layer switching: OSM / Terrain / Satellite
- Contour overlay toggle in map layer menu
- SD tile layout support for OSM/Terrain PNG and Satellite JPG
- Real-time position marker and coordinate display
- Discrete zoom levels and low-power tuning
- Track recording and route modes (record/route list)
- KML route overlays and focus
- GPX tracks exportable via USB Mass Storage
📝 LoRa Messaging (Meshtastic + MeshCore Compatible)
- LoRa text messaging with Chinese support
- Meshtastic public mesh compatibility (LongFast/PSK)
- MeshCore network compatibility (native MeshCore packet path)
- Bluetooth connectivity to Meshtastic / MeshCore companion apps
- Message history and conversation list
- Routing confirmations and reliability diagnostics
- Unishox2 decompression for incoming messages
📷 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
🤝 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)
- Receive SSTV audio and decode to images on-device
- Real-time decode progress and image preview
- Designed for low-power, embedded decoding
👥 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
🚀 Planned Features
🔗 Enhanced Meshtastic Compatibility
- Position sharing (
POSITION_APP) for team awareness (see Team Mode) - Native Meshtastic waypoint interoperability (
WAYPOINT_APP,meshtastic_Waypoint) for POIs, camps, and hazards - Store-and-forward messaging for unstable networks
- Network diagnostics (
TRACEROUTE_APP) - Meshcore network compatibility (selectable adapter)
🧭 GPS Enhancements
- Real-time position markers (see GPS Map / Team Mode)
- Track export (GPX via USB Mass Storage)
- Track playback & stats (replay, distance/elevation summaries)
📝 Messaging Enhancements
- Unishox2 compression for outgoing messages
- Reticulum support for interoperable offline messaging experiments
🔌 System Enhancements
- Language switching (EN / ZH)
- Firmware updates via USB or wireless
🙏 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 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 offline-first field communication and situational-awareness system built around low-power radio devices (LoRa and compatible sub-GHz radios). The project focuses on reliable human-to-human coordination in environments where cellular networks are unavailable, unstable, or undesirable.
This repository is an actively developed engineering project, not an abandoned code drop and not a code archive.
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, protocols, firmware design, and reference implementations are primarily maintained by the original author.
Contact
- Email: vicliu@outlook.com
- WeChat: vicliu890624
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
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
The goal of Trail-mate is to enable practical, human-centered, off-grid communication and coordination. Constructive feedback, real-world testing reports, and implementation experiences are especially appreciated.
You are not required to open Issues before contacting the author directly.
Thank you for taking the time to examine and use this project.