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 a Meshtastic mesh network 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
🧭 GPS Map (Performance-First)
- Fixed North-Up map orientation (no rotation)
- Fully offline map support
- Discrete zoom levels optimized for embedded systems
- Simple breadcrumb trails for path awareness
- Predictable memory usage and low power consumption
📡 LoRa Chat (Meshtastic Compatible)
- LoRa-based text messaging
- Chinese text support
- Compatible with the Meshtastic public mesh
- Broadcast-based communication (no central infrastructure)
- Designed for high latency, low bandwidth, and packet-loss environments
- Minimal protocol implementation optimized for ESP32-class devices
💡 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-based networks.
🌐 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
- Offline map rendering with fixed north-up orientation
- GPS positioning and coordinate display
- Discrete zoom levels optimized for embedded systems
- Motion-aware power saving, dynamically adjusting GPS sampling frequency
📝 Text Messaging
- Meshtastic-compatible LoRa mesh protocol stack
- Real-time text messaging, including Chinese support
- Message history stored locally
- Unishox2 decompression for receiving compressed messages
- Routing confirmation and delivery status tracking
👥 Contacts
- Node discovery within the Meshtastic network
- Contact list with status indicators
- Node metadata (device ID, short name, hardware model)
- Online/offline status tracking
⚙️ System Settings
- Display controls (brightness, sleep timeout)
- GPS parameters (sampling interval, motion sensitivity)
- System information (battery, version, device status)
💾 USB Mass Storage
- USB Mass Storage mode
- Direct file management from a connected computer
🔌 System Management
- Graceful shutdown
- Low-power management
- Runtime state monitoring
🚀 Planned Features
🔗 Enhanced Meshtastic Compatibility
- Position sharing (
POSITION_APP) for team awareness - Waypoint management (
WAYPOINT_APP) for POIs, camps, hazards - Store-and-forward messaging for unstable networks
- Network diagnostics (
TRACEROUTE_APP) - Meshcore network compatibility
🧭 GPS Enhancements
- Real-time position markers
- Basic track recording
- Advanced breadcrumb trail recording and playback
📝 Messaging Enhancements
- Unishox2 compression for outgoing messages
🔌 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.
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.
Built with care for the outdoor community ❤️