{"id":43500488,"url":"https://github.com/vicliu624/trail-mate","last_synced_at":"2026-04-22T16:01:07.320Z","repository":{"id":333664701,"uuid":"1136847791","full_name":"vicliu624/trail-mate","owner":"vicliu624","description":"Trail Mate is an offline‑first handheld system for GPS navigation, LoRa communication, and real‑time team situational awareness in no‑network environments.","archived":false,"fork":false,"pushed_at":"2026-04-16T07:21:30.000Z","size":30600,"stargazers_count":193,"open_issues_count":4,"forks_count":21,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-04-16T09:38:42.594Z","etag":null,"topics":["gps-tracker","meshcore","meshtastic","outdoor","tak"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vicliu624.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":"COPYRIGHT","agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T13:24:38.000Z","updated_at":"2026-04-16T08:00:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"89bb6a51-82e0-4fed-b8d2-7cf97ba086a1","html_url":"https://github.com/vicliu624/trail-mate","commit_stats":null,"previous_names":["vicliu624/trail-mate"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/vicliu624/trail-mate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicliu624%2Ftrail-mate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicliu624%2Ftrail-mate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicliu624%2Ftrail-mate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicliu624%2Ftrail-mate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vicliu624","download_url":"https://codeload.github.com/vicliu624/trail-mate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicliu624%2Ftrail-mate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32010978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gps-tracker","meshcore","meshtastic","outdoor","tak"],"created_at":"2026-02-03T11:20:09.886Z","updated_at":"2026-04-19T15:06:34.419Z","avatar_url":"https://github.com/vicliu624.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🗺️ Trail Mate\n\n![trail mate page](docs/images/ChatGPTImage.png)\n\n\u003e A low-power, offline-first handheld device for outdoor navigation and communication\n\n[English](README.md) | [中文](README_CN.md) | [Join Discord](https://discord.gg/87PVMVUP)\n\n---\n\n## 📋 Overview\n\n![logo](docs/images/logo_big.png)\n\nOutdoor activities often take place in environments where cellular networks are unreliable or completely unavailable.\nIn 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.\n\n**Trail Mate** is a low-power, offline-first handheld device project built on ESP32-class hardware, designed specifically to address these constraints.\n\nIt focuses on two core needs in offline outdoor scenarios:\n\n* **Simple and reliable self-positioning**, using a fixed north-up GPS map to avoid unnecessary visual complexity\n* **Direct LoRa text communication**, allowing users to send free-form messages to Meshtastic or MeshCore mesh networks **without relying on a smartphone**\n\nTrail 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.\n\n---\n\n## ✨ Core Features\n\n### 🧭 Main Menu Overview\n\n![main menu](docs/images/main.png)\n\nThe main menu provides quick access to GPS, LoRa chat, tracker, and system utilities,\ndesigned for fast navigation on a physical keyboard without deep menu nesting.\n\n\n### 🧭 GPS Map (Performance-First)\n\n| Layer Menu | OSM Base Map |\n| --- | --- |\n| ![map menu](docs/images/map_menu.png) | ![map osm](docs/images/map_osm.png) |\n\n| Terrain Base Map | Satellite Base Map |\n| --- | --- |\n| ![map terrain](docs/images/map_terrain.png) | ![map satellite](docs/images/map_satellite.png) |\n\n* Fixed **North-Up** map orientation (no rotation)\n* Fully **offline** map rendering from SD card tiles\n* Three switchable base layers: **OSM / Terrain / Satellite**\n* Optional contour overlay for terrain shape awareness\n* Real-time position marker for the current GPS fix\n* Discrete zoom levels optimized for embedded systems\n* Simple breadcrumb trails for path awareness\n* Fast in-page layer switching via map layer menu (no page restart)\n\nExpected SD card tile layout:\n\n```text\n/maps/base/osm/{z}/{x}/{y}.png\n/maps/base/terrain/{z}/{x}/{y}.png\n/maps/base/satellite/{z}/{x}/{y}.jpg\n/maps/contour/major-500/{z}/{x}/{y}.png\n/maps/contour/major-200/{z}/{x}/{y}.png\n/maps/contour/major-100/{z}/{x}/{y}.png\n/maps/contour/major-50/{z}/{x}/{y}.png\n/maps/contour/major-25/{z}/{x}/{y}.png\n```\n\n### 🛰️ GNSS Sky Plot\n\n![skyplot](docs/images/SkyPlot.png)\n\n* Real-time sky plot of visible satellites (azimuth/elevation)\n* SNR status and constellation coloring (GPS/GLONASS/Galileo/BeiDou)\n* Clear indication of satellites used in the current fix\n* Summary of USE/HDOP/FIX for fast diagnostics\n\n### 📶 Energy Sweep (Sub-GHz Scan)\n\n![sub-ghz scan](docs/images/subGScan.png)\n\nEnergy Sweep provides a fast Sub-GHz occupancy view for channel planning in the field.\n\n* Real-time RSSI sweep bars across the configured Sub-GHz band\n* Cursor readout for exact frequency, RSSI, and noise floor\n* Best-channel recommendation with cleanliness/SNR hint\n* `STOP/SCAN` control for pause/resume\n* `AUTO` applies the current best channel and moves cursor to the recommended frequency\n* Sweep range follows the currently configured region (Meshtastic region or MeshCore region preset)\n\n### 📡 LoRa Chat (Meshtastic + MeshCore Compatible)\n\n![message compose page](docs/images/screenshot_20260118_200651.png)\n\n![messages](docs/images/messages.png)\n\nMessages view shows recent conversations and history for quick review.\n\n* LoRa-based text messaging\n* Chinese text support\n* Compatible with the **Meshtastic public mesh** (LongFast/PSK)\n* Compatible with **MeshCore networks** (native MeshCore packet path)\n* Bluetooth connectivity to Meshtastic / MeshCore companion apps\n* Broadcast-based communication (no central infrastructure)\n* Designed for high latency, low bandwidth, and packet-loss environments\n* Minimal protocol implementation optimized for ESP32-class devices\n\n### 📷 SSTV Receiver (Slow-Scan TV)\n\n![sstv page](docs/images/sstv_page.jpg)\n\n![sstv result](docs/images/sstv_image_result.jpg)\n\n* Receive SSTV audio and decode to images on-device\n* Real-time decode progress and image preview\n* Designed for low-power, embedded decoding\n\n### 👥 Contacts\n\n![contacts](docs/images/contacts.png)\n\nContacts shows discovered nodes, recent activity, and quick actions\nto jump into direct or team conversations.\n\n### 💻 Data Exchange (PC Link)\n\n![data exchange](docs/images/data_exchange.png)\n\nPC Link connects the device to a host computer and exposes a structured HostLink stream\nfor real-time APRS/iGate integration, diagnostics, and data capture.\n\n* Live forwarding of LoRa messages, team updates, and GPS snapshots\n* APRS-oriented metadata for external gateways and dashboards\n* USB CDC-ACM transport with deterministic framing\n\n### 🤝 Team Mode (ESP-NOW Pairing + LoRa Ops)\n\n![team join](docs/images/team_join.png)\n\n![team map](docs/images/team_map.png)\n\nTeam mode is designed for small groups that are physically together.\nPairing happens over ESP-NOW at close range to exchange a team key,\nthen all team operations run over LoRa.\n\n* Create a team (leader) or join a nearby team (member)\n* Secure key distribution and team ID establishment during pairing\n* Team chat (text/location) and shared status updates\n* Member list with leader/member roles and counts\n* Team waypoint / assembly-point sharing\n* Team map view with latest member positions and track snapshots\n\n### 🧭 Track Recording \u0026 Route Following\n\n![tracker](docs/images/tracker.png)\n\n![tracker](docs/images/tracker1.png)\n\n* Track recording and storage (record/route modes)\n* Track list browsing and route focus\n* KML route overlay support\n* GPX tracks exportable via USB Mass Storage\n\n### 🎙️ Walkie Talkie\n\n![walkie talkie](docs/images/walkie_talkie.png)\n\n* FSK + Codec2 voice walkie talkie\n* Half-duplex PTT (press to talk / release to listen)\n* Jitter buffering and fixed playback cadence for stability\n\n---\n## 💡 Design Philosophy\n\nTrail Mate is **not** a smartphone replacement, and it does not attempt to hide the real limitations of offline communication.\n\nInstead, it focuses on:\n\n* ✅ Honest representation of uncertainty\n* ✅ Deterministic and predictable system behavior\n* ✅ Long-term reliability on constrained hardware\n\n\u003e 💬 **Designed for environments where simplicity and robustness matter more than visual refinement.**\n\n---\n\n## 📱 Planned Supported Devices\n\nTrail Mate's long-term goal is not simply to support as many boards as possible. The priority is to support the kinds of devices that actually make sense for off-grid outdoor communication. This section describes the **hardware direction**, not a promise that every device listed here is already fully supported in the current release.\n\nCurrent priority device categories include:\n\n- **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\n- **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\n- **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\n\nWhen evaluating hardware, the project currently prioritizes:\n\n- Reliable LoRa / Sub-GHz radio capability, or at least a clear path to integrate it cleanly\n- A device that can handle basic input, viewing, and configuration on its own rather than depending heavily on a phone\n- Reasonable power, battery, and field portability characteristics\n- A stable enough ecosystem, documentation base, or supply chain to justify long-term maintenance\n\nThe project still aims to stay as **hardware-agnostic** as practical. Protocol logic, storage, and UI/business behavior are kept as decoupled as possible from board-specific code so future ESP32- and nRF52-class targets can continue to reuse Meshtastic / MeshCore-related capabilities instead of forking into separate applications per board.\n\n---\n\n## 🧩 Current Device Support \u0026 Development Status\n\nThe table below describes the **real build targets that exist in the repository today**, not the broader long-term hardware direction.\n\n| Device / Target | Build Target | Stack | Current Status |\n| --- | --- | --- | --- |\n| **LILYGO T-LoRa-Pager (SX1262)** | `tlora_pager_sx1262` | PlatformIO / Arduino | Current default environment and still the most complete day-to-day validation target |\n| **LILYGO T-Deck** | `tdeck` | PlatformIO / Arduino | Primary validation target; keyboard, chat, maps, and shared UI paths are actively used |\n| **GAT562 Mesh EVB Pro** | `gat562_mesh_evb_pro` | PlatformIO / Arduino (nRF52) | Resource-constrained target focused on monochrome UI, Meshtastic, BLE, and persistence paths; some features are intentionally trimmed to fit RAM limits |\n| **LILYGO T-LoRa-Pager (SX1280)** | `tlora_pager_sx1280` | PlatformIO / Arduino | Integrated Pager RF variant for alternate hardware versions |\n| **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 |\n| **LILYGO T-Watch S3** | `lilygo_twatch_s3` | PlatformIO / Arduino | Experimental target used more for system and UI validation than for full feature coverage |\n| **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 |\n| **LILYGO T-Display P4** | `TRAIL_MATE_IDF_TARGET=t_display_p4` | ESP-IDF | Early integrated target used to validate the shared IDF shell and large-screen path |\n\n### How To Choose A Target Today\n\n- If you want the most stable daily development path right now, start with **`tlora_pager_sx1262`** or **`tdeck`**\n- If you are debugging a resource-constrained monochrome target or Meshtastic / BLE behavior, start with **`gat562_mesh_evb_pro`**\n- If you are working on the newer large-screen ESP-IDF path, start with **`tab5`**\n- **`tdeck_pro_*`**, **`lilygo_twatch_s3`**, and **`t_display_p4`** are better treated as bring-up, layout, or device-adaptation targets than as the highest-maturity feature-validation path\n- “The repository has a build target” does not mean every page or capability is equally mature on that device; some features are enabled or hidden dynamically based on capabilities, RAM budget, and input hardware\n- GitHub Actions currently keeps building the main path through **`tlora_pager_sx1262`**, **`tdeck`**, and **`lilygo_twatch_s3`**\n\n---\n\n## 🛠️ Build Methods\n\nTrail Mate currently uses two main toolchain paths: **PlatformIO** and **ESP-IDF**. The commands below are intended to be run from the **repository root**.\n\n### PlatformIO\n\nPlatformIO covers both the ESP32 Arduino targets and the current nRF52 Arduino target. The root [platformio.ini](platformio.ini) keeps only shared configuration, while the actual target environments live under `variants/*/envs/*.ini`.\n\nCommon build commands:\n\n```bash\n# Primary targets\nplatformio run -e tlora_pager_sx1262\nplatformio run -e tdeck\n\n# nRF52 / resource-constrained target\nplatformio run -e gat562_mesh_evb_pro\n\n# Other integrated targets\nplatformio run -e tlora_pager_sx1280\nplatformio run -e tdeck_pro_a7682e\nplatformio run -e tdeck_pro_pcm512a\nplatformio run -e lilygo_twatch_s3\n```\n\nIf you want more verbose diagnostics, the repository also provides these debug environments:\n\n```bash\nplatformio run -e tlora_pager_sx1262_debug\nplatformio run -e tlora_pager_sx1280_debug\nplatformio run -e tdeck_debug\nplatformio run -e lilygo_twatch_s3_debug\n```\n\nGeneric upload form:\n\n```bash\nplatformio run -e \u003cenv\u003e --target upload\n```\n\nIf you need to select the serial port explicitly, add `--upload-port COMx`. For example:\n\n```bash\nplatformio run -e tlora_pager_sx1262 --target upload --upload-port COM6\n```\n\nNotes:\n\n- Running `platformio run` with no explicit environment uses the root default environment, currently **`tlora_pager_sx1262`**\n- If you only want to sanity-check whether a target still builds, start with **`tlora_pager_sx1262`**, **`tdeck`**, or **`gat562_mesh_evb_pro`**\n- For very tight-RAM targets such as GAT562, prefer release-like or low-log validation instead of enabling excessive debug output by default\n\n### ESP-IDF\n\nESP-IDF is currently used mainly for the newer shared-shell path. The officially wired targets right now are `tab5` and `t_display_p4`. The repository root already contains the top-level `CMakeLists.txt`, so you can invoke `idf.py` directly from the root directory.\n\n`tab5` example:\n\n```bash\nidf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 reconfigure build\nidf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 -p COM6 flash\nidf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 monitor\n```\n\n`t_display_p4` example:\n\n```bash\nidf.py -B build.t_display_p4 -DTRAIL_MATE_IDF_TARGET=t_display_p4 reconfigure build\nidf.py -B build.t_display_p4 -DTRAIL_MATE_IDF_TARGET=t_display_p4 build\n```\n\n### Notes\n\n- ESP-IDF generated `sdkconfig` state now lives inside the selected build directory such as `build.tab5` or `build.t_display_p4`, so different targets do not fight over stale config output anymore\n- For **Tab5**, prefer running `monitor` separately after flashing; chaining `flash monitor` can leave ESP32-P4 in ROM download mode after auto-reset\n- VS Code already provides **`IDF Tab5: Reconfigure`**, **`IDF Tab5: Build`**, **`IDF Tab5: Flash`**, and **`IDF Tab5: Monitor`** tasks via `tools/vscode/run_idf_task.ps1`\n- 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\n\n---\n\n## 🌐 Languages\n\n* [English](README.md) ← You are here\n* [中文](README_CN.md)\n\n---\n\n## 📝 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and planned updates.\n\n---\n\n## 📄 License\n\nThis project is licensed under the **GNU Affero General Public License v3.0 (AGPLv3)**.\n\nThe license is intended to ensure that:\n\n* Source code remains available when the project is modified, deployed, or offered as a network service\n* The core system cannot be incorporated into closed-source or proprietary products without authorization\n\n### Commercial Licensing\n\nA separate **commercial license** may be provided for the following use cases:\n\n* Commercial or closed-source products\n* Hardware vendors integrating or pre-installing the firmware\n* Commercial applications unable or unwilling to comply with AGPLv3\n\nFor such use cases, please contact the project author to discuss licensing terms.\nPublication of this repository does **not** grant any default commercial rights.\n\nSee the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🔐 Project Scope\n\nThis repository contains the **core system implementation** of the Trail Mate project, including but not limited to:\n\n* Device-side firmware\n* Offline navigation and GPS processing logic\n* LoRa-based communication protocols and mesh behavior\n* System interaction and state management for constrained hardware\n\nThis project **does not include**:\n\n* Commercial desktop software\n* Mobile applications (iOS / Android)\n* Commercial services or platform products\n\nAny surrounding tools or services may follow different licensing strategies and are outside the scope of this repository.\n\n---\n\n## 🤝 Contributing\n\nAll code in Trail Mate is **100% generated by AI under human guidance**.\nThe project itself is a long-term experiment in **human–AI collaboration for real engineering systems**.\n\nHere, **contribution does not equal writing code**.\n\n### Contribution \u0026 Copyright\n\nUnless explicitly stated otherwise, all contributions to this repository are released under the **AGPLv3 license**.\n\nThe project is currently author-driven and does not accept contributions that alter core architecture or licensing terms.\nFor commercial collaboration or deep involvement, please contact the author directly.\n\n### Who Are the Most Important Contributors?\n\n**The most important contributors are people who actually spend time outdoors.**\n\nWe especially welcome:\n\n* Hikers, campers, cyclists, off-road travelers, anglers\n* Users operating in **no-network, low-power, harsh environments**\n* People who may **not write code**, but have strong intuition about what is useful and what is not\n\nTheir judgments, frustrations, and decisions are the starting point for this system’s evolution.\n\n### What Can Contributions Be?\n\n* 🧭 **Real-world usage scenarios and problem descriptions**\n\n  \u003e In what environment? What went wrong? What behavior felt unreliable?\n* 🧠 **Intuitive judgments about feature trade-offs**\n\n  \u003e What information matters? What becomes noise?\n* 🧪 **Failure cases and boundary feedback**\n\n  \u003e When does the system stop being trustworthy?\n* 🔑 **Token resources** to support AI generation, verification, and iteration\n\nEven if you **never submit code**, your judgment can still be transformed — through AI — into **executable, verifiable system behavior**.\n\n### How Do We Collaborate?\n\n* Humans (especially outdoor users) decide:\n  **what deserves to exist**\n* AI translates those decisions into:\n  **consistent, runnable implementations**\n\nPull Requests are welcome, but they are neither the only nor the most important form of contribution.\nTrail Mate values **judgment quality and real-world feedback** over lines of code.\n\n\u003e If a feature has no value outdoors, it should not exist.\n\n---\n\n## ✅ Implemented Features\n\n### 🧭 GPS Navigation \u0026 Tracks\n\n- Offline map rendering (north-up, no rotation)\n- Runtime base layer switching: OSM / Terrain / Satellite\n- Contour overlay toggle in map layer menu\n- SD tile layout support for OSM/Terrain PNG and Satellite JPG\n- Real-time position marker and coordinate display\n- Discrete zoom levels and low-power tuning\n- Track recording and route modes (record/route list)\n- KML route overlays and focus\n- GPX tracks exportable via USB Mass Storage\n\n### 📝 LoRa Messaging (Meshtastic + MeshCore Compatible)\n\n- LoRa text messaging with Chinese support\n- Meshtastic public mesh compatibility (LongFast/PSK)\n- MeshCore network compatibility (native MeshCore packet path)\n- Bluetooth connectivity to Meshtastic / MeshCore companion apps\n- Message history and conversation list\n- Routing confirmations and reliability diagnostics\n- Unishox2 decompression for incoming messages\n\n### 🤝 Team Mode (ESP-NOW Pairing + LoRa Ops)\n\n- Close-range ESP-NOW pairing with key distribution and team ID setup\n- Member list and leader/member roles\n- Team chat (text/location)\n- Team map view with member position updates\n- Team waypoint / assembly-point sharing\n- Team track and status rebroadcast\n\n### 📷 SSTV Receiver (Slow-Scan TV)\n\n- SSTV audio reception and on-device image decoding\n- Real-time decode progress and image preview\n- Lightweight pipeline for low-power hardware\n\n### 👥 Contacts\n\n- Node discovery and contacts list\n- Node metadata (ID/short name/device info)\n- Online/offline status and recent activity\n- Quick jump to direct or team conversations\n\n### 💻 Data Exchange (PC Link / HostLink)\n\n- USB CDC-ACM transport\n- HostLink frames/events/config support\n- Live forwarding of LoRa/team/GPS data\n- APRS/iGate-oriented metadata output\n\n### 🎙️ Walkie Talkie\n\n- FSK + Codec2 voice walkie talkie\n- Half-duplex PTT (press to talk / release to listen)\n- Jitter buffering and fixed playback cadence\n\n### ⚙️ System Settings \u0026 Status\n\n- Display/sleep controls and basic settings\n- GPS and network-related configuration\n- Status bar icons and system notifications\n- Screenshot capture (ALT double-press, saved to SD /screen)\n\n### 💾 USB Mass Storage\n\n- Device mounts as a USB drive\n- Direct management of exported tracks and files\n\n### 🔌 System Management\n\n- Graceful shutdown\n- Low-power management\n- Runtime status monitoring\n\n### 📻 Trail-mate Relay Edition (GAT562 Mesh EVB Pro)\n\n- A dedicated firmware path exists for `GAT562 Mesh EVB Pro`, positioned as a **relay device inside the Trail-mate system**, not as a normal handheld endpoint\n- The relay edition already covers Meshtastic-compatible LoRa RX/TX, Text / NodeInfo / Position handling, and the corresponding persistence paths\n- It already supports BLE interaction with the Meshtastic app for message, node-information, and configuration-related synchronization\n- Relay-side parameters can already be updated remotely and persisted\n- The monochrome UI is usable for time, GPS, radio status, and runtime diagnostics, which fits field deployment and maintenance for relay use\n\n---\n## 🚀 Planned Features\n\n### 🔗 Enhanced Meshtastic Compatibility\n\n* [x] **Position sharing** (`POSITION_APP`) for team awareness (see Team Mode)\n* [ ] **Native Meshtastic waypoint interoperability** (`WAYPOINT_APP`, `meshtastic_Waypoint`) for POIs, camps, and hazards; Trail-mate team waypoints / assembly points already exist, but protocol-level interoperability with native Meshtastic waypoints is still missing\n* [ ] **Store-and-forward messaging** for unstable networks\n* [ ] **Network diagnostics** (`TRACEROUTE_APP`)\n* [x] **Meshcore network compatibility** (selectable adapter)\n\n### 🧭 GPS Enhancements\n\n* [x] Real-time position markers (see GPS Map / Team Mode)\n* [x] **Track export** (GPX via USB Mass Storage)\n* [ ] **Track playback \u0026 stats** (replay, distance/elevation summaries)\n\n### 📝 Messaging Enhancements\n\n* [ ] **Unishox2 compression** for outgoing messages\n* [ ] **Reticulum support** for interoperable offline messaging experiments\n\n### 🔌 System Enhancements\n\n* [ ] Language switching (EN / ZH)\n* [ ] Firmware updates via USB or wireless\n\n### 📻 Trail-mate Relay Edition Integration\n\n* [ ] **Remote relay-parameter management from regular devices** - the `GAT562 Mesh EVB Pro` relay firmware already supports remote parameter updates and persistence on the relay side, but normal Trail-mate handheld devices do not yet expose the matching entry point, interaction flow, or management page\n\n---\n## 🙏 Acknowledgements\n\nTrail Mate has benefited from real support from the community and hardware vendors.\n\nSpecial thanks to **LILYGO** for providing development hardware.\nTheir open hardware ecosystem and stable ESP32 product line have enabled continuous iteration and validation in real devices.\n\nSpecial thanks to **Shenzhen GAT-IOT Technology Co., Ltd.** (https://github.com/gat-iot) for providing hardware support to this project.\nThe 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.\n\nThese contributions lowered the barrier to prototyping and allowed Trail Mate to receive real-world feedback much earlier.\n\nIf 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.\nWhen feasible, I am happy to adapt the software to additional devices and provide feedback based on real usage.\n\n\nSpecial thanks to **dawsonjon** (https://github.com/dawsonjon) for the open-source **PicoSSTV** project:\nhttps://github.com/dawsonjon/PicoSSTV. Our SSTV receiver borrows from its decoding approach.\nFor algorithm details, see: https://101-things.readthedocs.io/en/latest/sstv_decoder.html\n\n---\n\n**Built with care for the outdoor community ❤️**\n\n# NOTICE\n\n## About This Project\n\n**Trail-mate** is an offline-first field communication and situational-awareness system built around low-power radio devices (LoRa and compatible sub-GHz radios).\nThe project focuses on reliable human-to-human coordination in environments where cellular networks are unavailable, unstable, or undesirable.\n\nThis repository is an actively developed engineering project, not an abandoned code drop and not a code archive.\n\nIf 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.\n\n---\n\n## Author\n\n**Vic Liu**\n\nThe system architecture, protocols, firmware design, and reference implementations are primarily maintained by the original author.\n\n---\n\n## Contact\n\n* Email: **[vicliu@outlook.com](mailto:vicliu@outlook.com)**\n* Discord: **[Trail Mate Discord](https://discord.gg/87PVMVUP)**\n* WeChat: **vicliu890624**\n\nYou may contact me for:\n\n* Hardware adaptation or porting\n* Protocol clarification\n* Integration into existing radio systems\n* Commercial licensing discussions\n* Collaboration or joint development\n* Field deployment guidance\n* Bug reports that are difficult to describe via Issues\n\nDiscord or WeChat is preferred for real-time technical discussion.\nEmail is preferred for formal or long-form communication.\n\n---\n\n## For Organizations / Companies\n\nIf your organization is testing or evaluating this repository internally:\n\nYou are welcome to reach out even if you are only in the research or feasibility stage.\nEarly technical discussion usually saves significant engineering time.\n\nCustomization, hardware adaptation guidance, and technical consulting are available.\n\n---\n\n## Licensing Reminder\n\nThis project is open-source and distributed under the terms specified in the LICENSE file.\n\nIf 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.\n\nIf you are unsure, please contact the author before deployment.\n\n---\n\n## Intent\n\nThe goal of Trail-mate is to enable practical, human-centered, off-grid communication and coordination.\nConstructive feedback, real-world testing reports, and implementation experiences are especially appreciated.\n\nYou are not required to open Issues before contacting the author directly.\n\nThank you for taking the time to examine and use this project.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicliu624%2Ftrail-mate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicliu624%2Ftrail-mate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicliu624%2Ftrail-mate/lists"}