vicliu
e466060fbd
* draft * Adjust IME candidate scrolling and space behavior * Remove IME buffer label and update remaining counter * Align Meshtastic handling and stabilize chat UI - Align Meshtastic send/receive flow: add routing ACK decoding/log mapping, ack timeouts, channel tracking, and richer RX/TX diagnostics. - Persist and manage PKI peer keys; add PKI backoff on NO_CHANNEL/UNKNOWN_PUBKEY and fall back to PSK when needed. - Improve chat UI state handling: safer app switching with exit callbacks, active app clearing on menu return, and safer chat container cleanup. - Fix Contacts → Compose parent selection to avoid UI tree mismatch; add broadcast compose support and refine action button behavior. - Add UI debug logging for screen/parent validity and child counts to diagnose black-screen/stacking issues. - Apply timezone offset helpers for display-time formatting and reuse in screenshot timestamps. * Add changelog entry and time helpers
# 🗺️ Trail Mate
A low-power, offline-first handheld device for outdoor navigation and communication
📋 Project Overview
Outdoor activities often take place in environments where cellular networks are unreliable or completely unavailable.
In these scenarios, users still need to share short text messages, understand their relative positions, and stay oriented—without relying on smartphones or complex infrastructure.
Trail-mate is a low-power, offline-first handheld device built on ESP32-class hardware, designed to address these challenges.
It focuses on two essential needs in off-grid outdoor scenarios:
- Simple, reliable self-positioning, using North-Up GPS mapping without visual complexity
- Direct text-based communication over LoRa, allowing users to send free-text messages into a Meshtastic mesh network without relying on a smartphone
Trail-mate prioritizes stability, efficiency, and interoperability over visual effects or feature richness, making it suitable for long-duration outdoor use on constrained hardware.
✨ Key Features
🧭 GPS Mapping (Performance-First)
- Fixed North-Up map orientation (no rotation)
- Fully offline map support
- Discrete zoom levels optimized for embedded systems
- Simple breadcrumb trail recording for path awareness
- Predictable memory usage and low power consumption
📡 LoRa Chat (Meshtastic-Compatible)
- Text messaging over LoRa
- Compatible with Meshtastic public networks
- Broadcast-based communication (no central infrastructure)
- Designed for high latency, low bandwidth, and packet loss
- Minimal protocol implementation for ESP32 efficiency
✅ Implemented Features
🧭 GPS Map Navigation
- Offline Map Display - Fully offline north-up map rendering without network connection
- GPS Positioning - GPS location tracking and coordinate display
- Map Zooming - Discrete zoom levels optimized for embedded devices
- Motion Detection - Intelligent power-saving strategy that adjusts GPS sampling based on motion state
📝 Text Chat Communication
- Meshtastic Compatible - Complete LoRa Mesh network protocol stack implementation
- Real-time Text Messages - Point-to-point and broadcast messaging with Chinese support
- Message History - Local message storage and history viewing
- Unishox2 Decompression Support - Support for receiving compressed text messages to save bandwidth
- Route Acknowledgment - Message delivery status tracking and error handling
👥 Contact Management
- Node Discovery - Automatic discovery of other devices in the Meshtastic network
- Contact List - Management and status display of known nodes
- Node Information - Display of device ID, short name, hardware model, etc.
- Online Status - Real-time display of node online/offline status
⚙️ System Settings
- Screen Settings - Brightness adjustment and sleep timeout configuration
- GPS Parameters - Positioning collection interval and motion detection sensitivity adjustment
- System Information - Device status, battery information, version information display
💾 USB Mass Storage
- USB Mass Storage - Device mounts as USB drive to computer
- File Management - Direct file management on device storage from computer
🔌 System Management
- Graceful Shutdown - Safe system shutdown process
- Low Power Management - Automatic screen sleep and intelligent GPS adjustment
- Status Monitoring - System runtime status and resource usage monitoring
🚀 Planned Features
🔗 Meshtastic Protocol Compatibility Enhancement
- GPS Position Sharing (
meshtastic_PortNum_POSITION_APP,meshtastic_Position) - Implement team member position sharing for enhanced outdoor collaboration safety - Waypoint Management (
meshtastic_PortNum_WAYPOINT_APP,meshtastic_Waypoint) - Support for points of interest (POI), campsite locations, and hazard markers to improve navigation experience - Store-and-Forward Mechanism (
meshtastic_PortNum_STORE_FORWARD_APP) - Implement offline message storage and forwarding in unstable network outdoor environments - Network Diagnostics Tool (
meshtastic_PortNum_TRACEROUTE_APP,meshtastic_TraceRoute) - Provide route tracing and connection quality assessment capabilities - Meshcore Network Compatibility - Support connection to Meshcore LoRa Mesh networks for cross-protocol interoperability
🧭 GPS Navigation Enhancement
- Real-time Position Display - Display current position markers and coordinate information on the map in real-time
- Track Recording Feature - Basic path recording and track display functionality
- Advanced Track Recording - Complete breadcrumb trail recording with track playback, saving, and navigation capabilities
📝 Chat Feature Enhancement
- Unishox2 Compression - Send compressed text message functionality to save bandwidth
🔌 System Feature Enhancement
- Language Switching - Chinese/English interface switching functionality
- Firmware Updates - Firmware upgrade capability via USB or wireless methods
💡 Design Philosophy
Trail-mate is not a smartphone replacement, and it does not attempt to hide the realities of off-grid communication.
Instead, it focuses on:
- ✅ Honest representation of uncertainty
- ✅ Deterministic system behavior
- ✅ Long-term reliability on constrained hardware
💬 Built for environments where simplicity and robustness matter more than polish.
📱 Planned Supported Devices
Trail-mate is planned to initially support the following ESP32-based handheld devices. These platforms feature built-in keyboards, allowing users to send free-text messages directly over a LoRa mesh network without relying on a smartphone, which is a key design goal of the project.
They also offer mature LoRa communication capabilities, input methods, and active community ecosystems, making them well suited for offline communication and positioning use cases:
- LILYGO T-Deck Plus
- LILYGO T-Deck Pro
- LILYGO T-LoRa-Pager
- M5Stack Cardputer
The project is designed to remain as hardware-agnostic as possible. Core logic—including GPS handling, LoRa protocols, map rendering, and chat functionality—is decoupled from specific hardware implementations to allow future expansion to additional ESP32-class platforms, while remaining compatible with networks built using Meshtastic.
🌐 Languages
📝 Changelog
See CHANGELOG.md for release notes and planned work.
📄 License
This project is licensed under the MIT License.
You are free to use, modify, and distribute this project,
with the understanding that it is provided "as is", without warranty.
See the LICENSE file for details.
🤝 Contributing
All code in Trail Mate is 100% generated by AI under human guidance. This project is also a long-term experiment in how humans and AI can collaborate to build real, working engineering systems.
Here, contribution is not defined by how much code you write.
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 drivers, anglers, and other outdoor participants
- People who use the device in no-network, low-power, and harsh environments
- People who may not write code, but have a clear sense of what is useful and what is not
Their ideas, frustrations, and judgments are the starting point of this system’s evolution.
What counts as a contribution?
-
🧭 Real usage scenarios and problem descriptions
Where were you? What went wrong? What felt unreasonable?
-
🧠 Intuitive judgments about feature trade-offs
What information mattered? What became noise?
-
🧪 Failure cases and boundary feedback
When did the system stop being trustworthy?
-
🔑 Token resources that enable AI-driven generation, validation, and iteration
Even if you never submit code directly, your judgment can still be transformed by AI into runnable, verifiable system behavior.
How do we collaborate?
- Humans (especially outdoor users) are responsible for: deciding what is worth existing
- AI is responsible for: turning those decisions into consistent, working implementations
Pull Requests are still welcome, but they are neither the only nor the most important form of contribution. Trail Mate values judgment and problem quality in real environments more than lines of code.
If a feature has no value outdoors, it should not exist.
🙏 Acknowledgements
During the development of Trail Mate, the project has received practical support from the community and hardware vendors.
Special thanks to LILYGO for providing development boards for this project. Their open hardware ecosystem and stable ESP32 product line have made it possible to iterate on real devices and validate key design assumptions throughout development.
This support significantly lowered the barrier for prototyping and allowed Trail Mate to receive feedback from real-world usage at an early stage.
If other hardware vendors share the design philosophy of this project and are interested in exploring the potential of their devices in outdoor, offline scenarios, feel free to get in touch. When feasible, I will make a best effort to adapt Trail Mate to supported devices and provide feedback and improvement suggestions based on real-world use.
Built with ❤️ for the outdoor community