4.1 Reticulum, LXMF and RNode Bridge

Reticulum on Trail Mate

Language: 中文版：4.1 Reticulum, LXMF and RNode Bridge (中文)

Trail Mate can operate as a self-contained Reticulum terminal. The device owns its identity, discovers peers, sends and receives LXMF, maintains paths and contacts, and connects those capabilities to Contacts, Chat, Network, Team, and call UI. It does not need a phone or an external computer to turn raw LoRa packets into a usable Reticulum experience.

This page describes the current product: what works, how it is configured, and where the deliberate device boundaries are.

The short version

Select Reticulum under Settings > Network > Protocol to start the device-side Reticulum/LXMF runtime.

• Reticulum is the active network protocol.
• LXMF is the messaging and delivery layer used for direct chat, shared-destination chat, and some Trail Mate application data.
• LoRa, Wi-Fi TCP Client, and Auto are carrier interfaces available to the same Reticulum runtime. They are not separate chat protocols.
• RNode/KISS is a USB modem capability for an external Reticulum host. It is not a normal protocol option alongside Reticulum in the current settings UI.

Old persisted LXMF or RNode protocol values are accepted for compatibility and normalized to Reticulum. Those names may therefore remain in source or history, while the product and current documentation use Reticulum.

What the device supports

Identity and discovery

When Reticulum is enabled, Trail Mate creates and persists a local identity. Settings > Network shows:

• Identity Hash: the local Reticulum identity hash.
• LXMF Address: the local LXMF delivery destination to share with someone who needs to message this device.

Both are 16-byte hashes displayed as 32 hexadecimal characters. A line wrap on a small screen is not part of the address.

The runtime sends and validates announces, requests paths, accepts path responses, and projects verified peers into Nearby and Network. Anonymous Peer keeps the local identity and outbound communication available but suppresses local delivery/propagation announces and ordinary path-discovery responses, making the device harder to discover automatically.

Direct chat, contacts, and groups

Reticulum integrates with the normal Contacts and Chat apps:

• Nearby contains peers learned through announces and path traffic.
• Contacts contains peers saved by the user.
• Groups contains locally configured LXMF shared destinations.
• Ignored contains peers hidden from normal lists.

The peer's LXMF announce display name is preferred, followed by a local remark and then a short-hash fallback. Press a in Contacts to add a 32-character LXMF Address or a MeshChat-style lxmf@... address manually.

Groups are not discovered from the network. Every participant must know the same shared destination. Firmware ships with no built-in Reticulum groups; groups created on the device are stored in /trailmate/reticulum/groups.tsv on the SD card.

LXMF delivery

This is not a one-packet text demo. The supported device runtime includes:

• announce validation, caching, and replay;
• path requests, path responses, and multi-hop HEADER_2 forwarding;
• packet proofs and reverse-path proof relay;
• local link sessions, link-request relay, and link identify;
• direct LXMF delivery and shared-destination group messages;
• resource advertise, request, hashmap, part, and proof flows;
• propagation offers, synchronization, and message acceptance;
• integration with the local message store, peer directory, and UI.

Users do not select packet, link, or resource delivery manually. The runtime applies the supported delivery behavior from the known path, payload, and peer state.

Team data

Trail Mate position and real-time track data can travel as Reticulum/LXMF appdata. It uses Trail Mate Team keys and application formats. Another Trail Mate with the same Team keys can consume it; a generic LXMF client will normally only see application data it does not understand.

Reticulum Groups and Trail Mate Teams are different concepts. Groups are shared-destination text conversations. Team is Trail Mate's encrypted collaboration domain, and Team position traffic is not presented as though it had been sent to a Reticulum group.

Audio calls

Pager-class targets with a supported microphone, speaker, and audio codec can place Reticulum audio calls. Call Protocol in Settings > Network selects the supported Sideband or MeshChat-compatible wire profile.

Calls are Wi-Fi-interface only. Real-time audio is never placed on LoRa. During a call, the device prioritizes the active link, call control, Codec2, and the audio path while pausing or deferring MQTT, BLE updates, GPS collection, downloads, OTA, public discovery, periodic announces, LoRa polling, and non-urgent SD writes. Incoming calls can wake the device into the answer/decline overlay.

Reticulum network configuration comes from the SD card

The authoritative Reticulum interface and LXMF propagation-client configuration is:

/trailmate/reticulum/config.json

Create it as trailmate/reticulum/config.json relative to the SD-card root. Do not use Settings as the normal interface-configuration source. Legacy bearer/gateway settings are consulted only to build factory defaults when neither an SD configuration nor a cached last-known-good copy exists.

At startup the device begins with defaults, loads a valid last-known-good copy from NVS if present, and then reads the SD file when the card becomes available. A valid SD configuration becomes active and refreshes the NVS cache. A missing card/file leaves the cached copy active. An invalid SD file never replaces the current valid snapshot; status reports Invalid Reticulum config with a reason.

The SD card is probed every five seconds until its first check. An explicit reload can reread the file, but reload is deferred while an audio call owns the realtime resource lease. Powering down, editing the card, reinserting it, and booting is the least ambiguous workflow.

Complete example

config.json is UTF-8 JSON. Comments and trailing commas are invalid:

{
  "schema": "trail-mate.reticulum",
  "version": 1,
  "interfaces": [
    { "id": "integrated-lora", "type": "IntegratedLoRaInterface", "enabled": true },
    {
      "id": "local-wifi",
      "type": "AutoInterface",
      "enabled": true,
      "group_id": "reticulum",
      "discovery_scope": "link",
      "discovery_port": 29716,
      "data_port": 42671
    },
    {
      "id": "primary-tcp",
      "type": "TCPClientInterface",
      "enabled": true,
      "target_host": "reticulum.example.net",
      "target_port": 4242
    },
    {
      "id": "backup-tcp",
      "type": "TCPClientInterface",
      "enabled": false,
      "target_host": "backup.example.net",
      "target_port": 4242
    }
  ],
  "lxmf": {
    "propagation": {
      "enabled": true,
      "service_enabled": false,
      "delivery_method": "auto",
      "propagation_node": "auto",
      "sync_on_start": true,
      "sync_interval_seconds": 900,
      "max_messages_per_sync": 32
    }
  }
}

Replace the example hostname with a real Reticulum TCP server. Remove an unused interface or set enabled to false, but at least one interface must remain enabled.

Parser and file requirements

• Maximum file size: 2048 bytes.
• Maximum JSON nesting: five levels; maximum structural tokens: 128.
• Maximum JSON string length: 128 bytes.
• schema must equal trail-mate.reticulum; numeric version must be 1.
• interfaces must contain 1–6 entries with at least one enabled.
• Every id is required, unique, and at most 23 characters.
• Case-sensitive types are IntegratedLoRaInterface, AutoInterface, and TCPClientInterface only.

Interface rules

IntegratedLoRaInterface uses the integrated RNode-compatible raw LoRa radio; only one is allowed. Frequency, BW, SF, CR, and TX power remain part of the device's Reticulum LoRa radio configuration. Direct LoRa peers need matching, legal radio parameters.

AutoInterface provides IPv6 link-scope discovery and per-peer UDP; only one is allowed. group_id defaults to reticulum, must be non-empty, and is limited to 31 characters. discovery_scope only accepts link. Discovery port defaults to 29716 and must be 1–65534; data port defaults to 42671 and must be 1–65535.

TCPClientInterface connects to a Reticulum TCP server/gateway with TCPInterface HDLC framing; up to three are allowed. target_host is required and limited to 63 characters. target_port defaults to 4242 and must be 1–65535. This is not MQTT or HTTP.

T-Display-P4 uses the C6 companion's single TCP transport, so it uses only the first enabled TCP Client and does not expose IPv6 AutoInterface through the companion.

Unknown destinations and announces may fan out over ready interfaces. Learned paths, links, proofs, resources, calls, and Nomad requests remain bound to the ingress or learned-path interface.

LXMF propagation fields

• enabled: enable the propagation client; default true.
• service_enabled: announce and accept traffic as a propagation service; default false and not required for normal clients.
• delivery_method: direct, propagated, or auto.
• propagation_node: auto or exactly 32 hexadecimal destination-hash characters.
• sync_on_start: synchronize after startup.
• sync_interval_seconds: 60–86400.
• max_messages_per_sync: 1–64.

auto prefers an existing direct link, then opportunistic delivery with a usable ratchet, then a discovered propagation node, and finally a direct link when no propagation node is available. Automatic node selection prefers active, fresh, lower-hop propagation nodes.

Keep service_enabled false unless you intentionally want this battery device to act as a propagation service and accept the additional traffic.

Frequent configuration errors

• using /reticulum/config.json instead of /trailmate/reticulum/config.json;
• accidentally creating config.json.txt on Windows;
• misspelling schema, version, or a case-sensitive interface type;
• comments, trailing commas, or a file over 2 KB;
• duplicate interface ids or all interfaces disabled;
• multiple integrated LoRa/Auto entries or more than three TCP Clients;
• an AutoInterface scope other than link;
• a propagation node that is neither auto nor a 32-character hexadecimal hash.

Public IP Reticulum traffic can be noisy. Trail Mate prioritizes direct/group chat, active links, proofs, path responses, and Team traffic while sampling or deferring public discovery, logs, and non-urgent SD writes. Network is a bounded device view, not a live mirror of an entire public network.

Network and Nomad/Micron pages

When Reticulum is active, the main menu includes Network, which provides:

• Reticulum runtime status;
• a latest-100 projection of the SD-backed announce directory;
• search by display name, destination hash, identity hash, or aspect;
• a small-screen Nomad/Micron page browser.

Enter an address such as <destination>:/page/index.mu. Pages are read first from /trailmate/reticulum/pages/<destination>/... on the SD card. On an ESP target, a cache miss can start a bounded link-based request; a successful response is cached before rendering. An unavailable runtime, timeout, retryable failure, or terminal failure remains visible instead of silently falling back to unrelated content.

This is deliberately not a complete NomadNet browser. It reliably renders small static Micron pages with common headings, colors, text styles, dividers, bounded tables, links, and local anchors. Form controls are display-only. Scripts, images, attachments, file resources, dynamic partials, desktop-grade tables, and unbounded pages are outside the device boundary.

Current primary limits are:

• 4096 bytes of page body;
• 32 clickable links and 32 local anchors per page;
• 180 rendered rows and 520 page-created objects;
• six table cells per row.

The renderer shows truncation and unsupported-feature notices when a page exceeds those limits instead of quietly producing misleading output.

SD-backed state

The SD card is the source of truth for the Reticulum directory:

/trailmate/reticulum/announces.tsv
/trailmate/reticulum/lxmf_addresses.tsv
/trailmate/reticulum/groups.tsv
/trailmate/reticulum/pages/

• announces.tsv stores verified announce records.
• lxmf_addresses.tsv stores the address book built from valid delivery announce and path information.
• groups.tsv stores user-configured shared destinations.
• pages/ stores the Nomad/Micron page cache.

Directory updates use bounded reads and temporary-file replacement. Non-urgent writes caused by public discovery are deferred toward screen-off maintenance windows so they do not contend with the UI, maps, and other SD users. Without an SD card, discovery persistence, the durable address book, groups, and the page cache cannot provide the full product behavior; firmware does not substitute hidden built-in groups.

What RNode/KISS means here

The repository still contains a USB CDC RNode/KISS service. When the corresponding external-host HostLink runtime is enabled, a computer can use the device radio as an RNode-compatible modem and run identity, routing, LXMF, and applications on the host.

The important boundaries are:

• the current protocol selector contains Meshtastic, MeshCore, and Reticulum, not a separate RNode Bridge option;
• legacy RNode settings are compatibility input and normalize to Reticulum;
• the USB RNode/KISS service is an external-host/HostLink runtime, not evidence that ordinary Reticulum mode hands its device-side stack to a computer;
• Trail Mate's own HostLink data protocol is not the RNode/KISS protocol.

Normal users should select Reticulum for the self-contained device experience. USB KISS matters only when using a compatible external Reticulum host and the corresponding firmware/runtime entry point.

The compatibility claim

The accurate claim is that Trail Mate implements a stable Reticulum/LXMF product subset suited to its hardware and UI, protected by fixed vectors, runtime-state contracts, and product tests.

It is not accurate to claim that the device is equivalent to Python RNS, a complete NomadNet installation, a public router, a propagation server, or every extension supported by desktop clients. The conformance fixtures stabilize Trail Mate's implemented subset; they are not certification of the entire upstream protocol surface.

First-use checklist

1. Select Reticulum on two devices.
2. Enable only IntegratedLoRaInterface in /trailmate/reticulum/config.json for the first LoRa test, then match frequency, BW, SF, CR, and TX power.
3. Disable Anonymous Peer and wait for both devices to appear under Contacts > Nearby or Network.
4. Inspect the peer, confirm its LXMF Address, and send a short message.
5. Add a Wi-Fi TCP Client only after basic communication is understood; avoid debugging every carrier at once.
6. For group chat, configure the same shared destination on every participant.
7. For calls, confirm supported audio hardware, a connected Wi-Fi Reticulum interface, and a known peer identity/path.

Troubleshooting order

When a message cannot be delivered, check:

1. Protocol is Reticulum.
2. /trailmate/reticulum/config.json loaded successfully and contains at least one enabled, ready interface.
3. LoRa parameters match, or the TCP Client is connected.
4. The destination's LXMF Address, identity public keys, and path are known.
5. Anonymous Peer is not preventing both sides from learning each other through announces.
6. Group participants use the same shared destination.
7. The SD card and directory files are available.
8. A Network page request reports cache miss, active loading, retryable failure, or terminal failure as expected.

See also 3.5 Configuration Guide, 4. Protocols & Data, 13. FAQ, 14. Troubleshooting, and 15. Logging and Debugging.