trail-mate

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

💡 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

English ← You are here
中文

📝 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.

Built with ❤️ for the outdoor community

README.md Unescape Escape

📋 Project Overview