4.1 Reticulum, LXMF and RNode Bridge

Reticulum on Trail Mate

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

Trail Mate operates as a self-contained Reticulum terminal. Reticulum serves decentralized identity, anonymous control, offline communication, and TAK awareness; it is a network path and may not redefine product position-authorization boundaries. The device owns identity, contacts, and paths, exchanges LXMF, and integrates with Contacts, Chat, Network, Team, and calls without a phone or cloud dependency.

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.

Contact persistence

Current firmware no longer uses the legacy /trailmate/reticulum/lxmf_addresses.tsv described by older development notes. Reticulum contacts share the unified peer directory with other protocols:

/mesh/peers.bin

peers.bin is a firmware-owned binary database, not a user configuration file. It contains a format magic, version, record count, CRC, and fixed-layout peer records, with a maximum file budget of 768 KiB. A Reticulum peer record can contain:

• LXMF delivery destination and Reticulum identity hashes;
• encryption and signing public keys;
• an optional ratchet public key and timestamp;
• display name, source, and first/last-seen times;
• favorite, ignored, and trusted user flags.

Reticulum can persist up to 1024 peer records, while the recent Contacts projection is bounded to 100. When persistence capacity is exceeded, the oldest Reticulum record is evicted. Writes go through /mesh/peers.tmp before replacing /mesh/peers.bin; do not modify either file while the device is running.

Add a contact on the device

1. Select Reticulum and open Contacts.
2. Press a or use Add.
3. Enter a plain 32-hex-character LXMF destination hash or lxmf@.... Spaces, colons, hyphens, and underscores are ignored.
4. If a verified announce/path response has already supplied the identity hash and encryption/signing public keys, the device marks the peer as a favorite/contact and synchronously persists it to /mesh/peers.bin.
5. With only a destination hash, Trail Mate can create a local contact projection but reports Address pending. A complete durable peer record is created only after a genuine LXMF delivery announce or path response supplies the verifiable identity and public keys.

Adding a discovered Reticulum peer from Nearby is the most reliable workflow because that record normally already contains the complete identity material.

Can contacts be added by editing the SD card on a computer?

The current release has no supported Reticulum contact TSV/JSON import file. Do not edit /mesh/peers.bin; creating the legacy lxmf_addresses.tsv will not import contacts into the current ESP runtime.

For offline bulk provisioning, first discover peers through announce/path traffic and save them on the device, or wait for a dedicated contact-import format with field validation and atomic import. Generating or modifying peers.bin directly bypasses CRC, version, identity-consistency, and public-key checks and can make the complete peer directory unreadable.

Contacts, Chat, and Network operations

Shortcuts apply only to the page currently in focus. The same key can mean different things on different pages: S searches in Contacts but composes a message inside a conversation. Devices without a physical keyboard expose equivalent actions through touch controls, the rotary encoder, direction controls, and on-screen buttons.

Contacts

Action	Key or entry	Result
Search	S or /	Filter the current list by contact name
Add an LXMF address	A	Open address entry; Reticulum mode only
Show/hide filters	F	Toggle Contacts, Nearby, Groups, and Ignored filters
Open selected item	Enter	Open the contact action menu or selected filter
Help	H	Show shortcuts for the current page
Back/close	Back	Close a dialog or return to the previous page

Use direction controls or the rotary encoder to move focus. Select a contact and press Enter; depending on peer state, the menu may offer Chat, Ping, Call, Info, Add/Edit/Delete, or Ignore/Unignore. Not every action is available for every peer.

There are two ways to add a contact:

1. Recommended: open Nearby, select a peer already discovered through an announce/path, press Enter, then choose Add. Such a record normally has the verified identity and public keys needed for durable storage.
2. Manual: press A in Contacts, enter a 32-character destination hash or an lxmf@... address, and confirm. If identity and keys have not been discovered, the contact temporarily reports Address pending while the device waits for trustworthy announce/path data.

To remove, hide, or restore a peer, select it, press Enter, and choose Delete, Ignore, or Unignore. The Ignored filter is where hidden peers can be recovered.

Chat list and conversation

On the Chat conversation list:

Action	Key	Result
Search conversations	S or /	Search contact/conversation names, not message bodies
Action menu	Enter or Space	Show actions for the selected conversation
Open chat	C	Enter the selected conversation
Peer information	I	Open information for the selected peer
Ping	P	Ping a Reticulum peer when supported
Delete	D	Delete the selected conversation after confirmation
Show/hide filters	F	Toggle the conversation filter pane

Inside a conversation:

Action	Key	Result
Compose or reply	S	Open the message editor; S no longer means search here
Scroll messages	Up / Down or rotary	Move through messages
Page history	Prev / Next	Load older/newer messages
Jump to edge	Home / End	Jump to the top/bottom
Map	M	Show or hide the conversation location map
Map layer	L	Cycle the map layer
Help	H	Show shortcuts for the current page
Back	Back or Esc	Return to the conversation list

Groups

Open the Groups filter in Contacts and select the Add row. Enter a group name and the shared 32-character destination used by every member, then save. Groups are not discovered through announces; every member must be provisioned with exactly the same shared destination. Group configuration is stored in /trailmate/reticulum/groups.tsv.

Network nodes and page browsing

Action	Key	Result
Search announces	S or /	Match display name, destination, identity, aspect, and address data
Refresh	R	Refresh Network content
Node list	A or C	Open Nodes
Favourites	F	Open Favourites
Immersive browser	I	Show/hide the immersive page browser
Open or lock page	Enter	Open a link; lock scrolling when the page viewport has focus
Unlock or return	Back	Unlock page scrolling first, then navigate back
Help	H	Show shortcuts for the current page

With page scrolling locked, use the rotary encoder or Up/Down to scroll and Prev/Next to page. In the side-by-side layout, Right moves from the directory into the browser and Left returns to the directory.

Starting and answering a Reticulum call

Select a call-capable peer in Contacts or Chat, press Enter to open its action menu, then choose Call. If no path exists yet, the UI requests one; when it reports Path requested, wait for discovery and try again. Use the on-screen Answer or Decline actions for an incoming call and the hang-up control during a call. Call appears only when the device, active interface, and peer state support it.

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/groups.tsv
/trailmate/reticulum/pages/
/mesh/peers.bin

• announces.tsv stores verified announce records.
• /mesh/peers.bin is the unified binary peer directory containing Reticulum contacts, discovery records, identity keys, and user flags; it is not manually editable.
• 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.