4. Protocols & Data

Protocols & Data

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

Trail Mate’s communication stack is easy to misread as “it supports many protocols, so everything should interoperate automatically”. That is not how the project is designed. The real goal is to make it clear which capabilities come from upstream protocol interoperability, which capabilities are project-specific field extensions, and which code paths exist in the repository but should not yet be described as complete public promises.

The Main Rule First

Trail Mate is currently a single-protocol runtime.

The active protocol role is selected by AppConfig::mesh_protocol. At startup, ProtocolFactory instantiates the corresponding adapter. The active roles currently documented for users are not only Meshtastic and MeshCore, but also device-side LXMF mode and RNode Bridge.

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

But this does not mean Trail Mate already implements every Meshtastic application-layer feature. The project documentation already calls out unfinished areas such as:

• native WAYPOINT_APP interoperability
• STORE_FORWARD_APP
• TRACEROUTE_APP

So when discussing Meshtastic in Trail Mate, it helps to distinguish what is already a dependable interoperability path from what still exists as a documented gap.

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

LXMF as device-side Reticulum mode

LXMF in Trail Mate is not a future placeholder. It is already present as a device-side protocol mode in the repository and related design notes. It runs on top of an RNode-compatible raw LoRa carrier, but the device itself owns the Reticulum/LXMF identity, announce behavior, path handling, and message logic.

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 Bridge as external-host bridge mode

RNode Bridge is not the same thing as LXMF.

In RNode Bridge mode, the Trail Mate device behaves more like a USB CDC RNode KISS 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

So RNode Bridge is a bridge and modem role, not a local on-device chat protocol mode. It belongs in the Reticulum family, but it is operationally different from LXMF.

How Data Flows

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

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

The receive side follows the same pattern. Radio tasks hand raw packets directly to the active adapter rather than sending them through an automatic protocol detector first. That keeps boundaries clearer and reduces the chance of mixed-protocol misclassification. In RNode Bridge, the destination is not primarily the local chat UI but the external Reticulum host side.

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 LXMF adapter	protocol interoperability	the primary device communication path, but semantics differ by protocol
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 Bridge	USB CDC RNode KISS modem path	interoperability plus bridge role	lets an external Reticulum host use the device as a modem
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 coordination features. They are not the same path as Meshtastic native WAYPOINT_APP. Current documentation already makes this distinction: Team waypoint and assembly-point capability exists, while native Meshtastic waypoint interoperability is still incomplete.

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.

Another distinction matters here too: HostLink and RNode Bridge are not the same path. HostLink is Trail Mate’s own structured desktop exchange layer. RNode Bridge is an RNode/KISS modem path for external Reticulum hosts.

Explicitly Not Supported Or Still Incomplete

Several points are worth stating directly:

• Trail Mate does not auto-detect and switch between protocols at runtime.
• RNode Bridge should not be described as another name for device-side LXMF.
• LXMF should not be described as a future-only placeholder.
• Meshtastic native waypoint interoperability is still incomplete.
• Meshtastic store-and-forward and traceroute support are still incomplete.
• 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. Meshtastic, MeshCore, and LXMF are device-side protocol modes, while RNode Bridge is an external-host bridge role
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’s own field-coordination extensions

Good Future Splits

This page will eventually work even better when split into narrower subpages, such as:

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

For now, the goal is simply to pin down the main boundaries before other discussions start from the wrong assumptions.