4. Protocols & Data

Protocols & Data

Language: English. Chinese version: 4. Protocols & Data (中文)

Trail Mate protocols serve the identity, contacts, messaging, and TAK awareness of a decentralized-phone-like device; they are not a protocol feature contest. The MCU feature set is frozen: Meshtastic, MeshCore, and Reticulum are the three selectable paths. No fourth product protocol is planned, and adapters may not redefine anonymity, offline operation, or position authorization.

The Main Rule First

Trail Mate is currently a single-protocol runtime.

AppConfig::mesh_protocol selects Meshtastic, MeshCore, or Reticulum, and ProtocolFactory creates the corresponding adapter. Reticulum may enable several SD-configured interfaces inside one runtime; that is multi-interface Reticulum, not automatic multi-protocol operation.

The UI talks to the common IMeshAdapter interface. The runtime does not inspect raw packets and decide on the fly which protocol they must belong to. It also does not keep multiple live protocol stacks running side by side and auto-switch between them.

That rule matters because many “why does this not line up” problems come from assuming Trail Mate behaves like an automatic multi-protocol mesh.

The Main Protocol Roles In Scope

Meshtastic

Meshtastic is one of Trail Mate’s clearest and most mature interoperability paths. Based on the current repository and documentation, it already covers several practical capabilities:

• text messaging
• basic public-mesh interoperability
• NodeInfo-related paths
• BLE connectivity to Meshtastic companion apps
• position-related compatibility paths

Trail Mate intentionally does not claim every Meshtastic application-layer feature. The following are outside the current MCU product promise rather than roadmap items waiting for a major implementation:

• native WAYPOINT_APP interoperability
• STORE_FORWARD_APP
• TRACEROUTE_APP

These boundaries distinguish the established interoperability path from unsupported upstream features.

MeshCore

MeshCore is another real path in Trail Mate, not just a placeholder. Its role is not “Meshtastic backup mode”, but a lighter and more selectively adaptable communication path that fits certain hardware directions better.

According to the current multi-protocol documentation, the clearest dependable MeshCore loop today is text communication over the RAW_CUSTOM route. More complete semantics such as richer encrypted or authenticated flows are still not something that should be overstated as fully done.

At the same time, the repository already contains MeshCore discovery, contact, and BLE-related integration paths. So the accurate wording is not “MeshCore is only stubbed”. It is “MeshCore is a real integration direction, but the strongest stable promise today is still the minimal closed loop”.

Reticulum with device-side LXMF

Reticulum is the product protocol name used by Settings and the runtime. The device owns its identity and handles announces, paths, LXMF, links, resources, and the supported propagation behavior. Interfaces and propagation policy load from /trailmate/reticulum/config.json on the SD card. LXMF is the messaging and delivery layer, not another protocol selector option.

According to docs/RETICULUM_LXMF_RUNTIME_ALIGNMENT_PLAN.md, the existing LxmfAdapter already goes beyond simple single-packet text experiments. The current baseline includes behavior such as:

• announce validation and caching
• path request initiation and path-response handling
• announce cache replay
• HEADER_2 multi-hop forwarding
• reverse-path proof relay
• local link session handling
• link request relay
• resource advertise, request, hashmap, part, and proof flow
• propagation offer and get request handling

This means the main question on the Reticulum path is no longer “is there any real implementation at all”. It is how to keep the transport, link, resource, and service lifecycle clean enough to remain maintainable.

At the same time, this should not be described as complete parity with every desktop Python Reticulum or LXMF behavior.

RNode/KISS as an external-host capability

The repository contains a USB CDC RNode/KISS service, but the current settings UI has no separate RNode Bridge protocol option.

When the external-host RNode/KISS HostLink runtime is explicitly enabled, Trail Mate provides a USB CDC modem. Its job is to:

• expose the LoRa carrier
• present a bridge and modem path to an external Reticulum host
• let the external host control identity, announce handling, path logic, and higher-level message behavior

RNode/KISS is a modem capability in an explicitly enabled external-host HostLink runtime. It is not ordinary Reticulum mode or an LXMF alias. Legacy persisted RNode values are accepted for migration and normalize to Reticulum.

How Data Flows

At a structural level, the communication path can be simplified like this:

UI / UseCase
    ↓
IMeshAdapter
    ↓
Meshtastic / MeshCore / Reticulum Adapter
    ↓
LoRa Radio / BLE / USB KISS / related bridge path

The receive side follows the same pattern: radio tasks hand packets to the active adapter instead of an automatic protocol detector. External-host RNode/KISS is a separately enabled HostLink runtime and is outside this normal product-protocol selection chain.

Native Protocol Capability vs Project Extension

This table exists to reduce the most common misunderstandings.

Capability	Main mechanism	Type	Note
Text messaging	active Meshtastic, MeshCore, or Reticulum adapter	protocol interoperability	Reticulum text uses LXMF delivery
Contact and node discovery	Meshtastic NodeInfo, MeshCore discovery, LXMF announce and peer recall	protocol interoperability	discovery mechanics differ across protocols
Reticulum/LXMF delivery	announce, path, link, resource, and propagation runtime	protocol interoperability	this is now a real implemented path, not just a future placeholder
RNode/KISS	USB CDC modem in an explicitly enabled external-host HostLink runtime	advanced bridge capability	not a settings product protocol
Basic position sharing	Meshtastic location paths plus internal node-position updates	mostly interoperability	should be described according to the actually implemented path, not as a blanket claim
Team formation	ESP-NOW pairing and TeamKey exchange	project extension	not a native Meshtastic or MeshCore team mechanism
Team position, waypoints, and tracks	custom TEAM_*_APP ports	project extension	for small-team coordination; not the same thing as native Meshtastic waypoint interoperability
Team management	TEAM_MGMT_APP	project extension	includes team-state and key-management flow
HostLink / PC Link	USB CDC-ACM plus HostLink frame	project extension	desktop-device exchange layer, separate from air protocol semantics

Why Team Is Not Just Another Chat Channel

One of the easiest mistakes is to treat Team as “ordinary chat with a special page”. That is not the current design.

Team’s purpose is to keep a temporary action unit able to answer three practical questions: are we still together, what happens next, and is anybody in trouble. That is why Team data includes more than text:

• member positions
• waypoints and assembly points
• track snapshots
• lifecycle events
• visibility and anomaly events

This is also why Team uses its own ports and its own encryption semantics rather than simply reusing ordinary chat payload structure.

Team Formation vs Team Runtime

The project currently separates team formation from team runtime:

• during nearby pairing, ESP-NOW is used to exchange TeamKey and related membership information
• after team formation, runtime team traffic moves to LoRa

This split exists because local secure team formation and long-range low-power runtime communication are different problems.

Which Path Handles Positions and Waypoints

This is another common source of confusion because many things “look like location data” from the outside.

Device’s own position

The device’s own GPS fix first enters the local GPS and map chain. That powers the map page, status pages, and track recording.

Node positions

When Meshtastic or Team position messages enter the system, Trail Mate updates node-position state so that contacts and map views can show other people. The goal is to make location usable across the UI rather than trapping it in one protocol-specific page.

Team waypoints and assembly points

These are Trail Mate’s own TAK features, not the Meshtastic native WAYPOINT_APP path. Team waypoints and assembly points exist; native Meshtastic waypoint interoperability is outside the current MCU product promise rather than a major feature waiting to be added.

The Role Of HostLink / PC Link

HostLink is not a minor extra protocol. It is a major desktop-device data path inside Trail Mate. Over USB CDC-ACM it provides structured binary frames for:

• message and event viewing on the host
• GPS snapshot retrieval
• reading and setting some configuration
• forwarding Team-related app-data
• desktop-side troubleshooting and data collection

If Trail Mate is understood only as an offline chat device, the value of HostLink is easy to underestimate. It is actually the device-to-desktop protocol bridge.

HostLink is the external-host runtime mechanism, but Trail Mate's structured host data protocol and its RNode/KISS modem codec remain different wire protocols and are not interchangeable.

Explicitly Not Supported Or Bounded

Several points are worth stating directly:

• Trail Mate does not auto-detect and switch between protocols at runtime.
• RNode/KISS HostLink capability should not be presented as a product protocol in Settings.
• LXMF should not be described as a future-only placeholder.
• Meshtastic native waypoint interoperability is not supported; Team waypoints are not disguised as upstream waypoints.
• Meshtastic store-and-forward and traceroute are not listed as future MCU feature additions.
• MeshCore’s clearest stable loop is still text communication, not blanket parity with all protocol features.
• Reticulum and LXMF should not be described as complete desktop parity.

The Most Important Conclusions For Users

If you only keep a few points in mind, keep these:

1. only one protocol role runs at a time
2. The product protocols are Meshtastic, MeshCore, and Reticulum; LXMF is its messaging layer and RNode/KISS is an external-host capability
3. ordinary chat, Team coordination, HostLink, and RNode Bridge are all real data paths, but they are not the same path
4. some features are upstream interoperability, while others are Trail Mate product semantics for anonymous, offline, TAK operation

Documentation That Can Be Split Further

This page can be split into narrower explanations of existing behavior, such as:

• Meshtastic interoperability boundaries
• MeshCore interoperability boundaries
• Reticulum, LXMF, and RNode Bridge
• Team data model and ports
• HostLink protocol details

These are documentation splits, not an MCU feature-expansion plan. Protocol maintenance improves correctness, stability, and explainability without adding product domains.