4.1.1 Reticulum Settings

Reticulum Discovery, Gateways and IFAC

This page describes Trail Mate 1.0.0. Reticulum network and LXMF settings use the network block in the SD working configuration (TMSET7). See 3.7 SD-Editable Working Configuration (TMS) for the file format, source schema and migration from older separate JSON configuration. Hardware interoperability remains a separate check from native test coverage.

Device setup

1. Connect Wi-Fi and open Settings > Reticulum. Choose a bearer that permits Wi-Fi; select TCP Entry to edit one of the three bootstrap/manual endpoints.
2. Keep at least one reachable TCP entry. Native discovery learns additional public endpoints over an existing Reticulum connection. It does not obtain Internet access on its own.
3. Use Geocaching without changing the chat protocol. To use Reticulum chat and its Contacts projection, select Reticulum under Settings > Profile.
4. Leave the device connected. A discovered endpoint becomes the persisted fallback after 60 seconds of stable connection. A restart can restore that endpoint from SD.

The factory TCP entries are bootstrap seeds, not a guarantee of availability. If all seeds and the saved endpoint are unreachable, edit a TCP entry to a reachable server. There is currently no HTTPS directory download or periodic scraping of directory.rns.recipes; that directory can help an operator find a bootstrap address manually.

Settings reference

Item	Use
Bearer	Select the permitted Reticulum carrier policy. TCP requires a policy that permits Wi-Fi.
Display Name, Identity Hash, LXMF Address	Read-only runtime identity information; shown when the Reticulum chat adapter is active.
TCP Entry	Select manual TCP entry 1, 2 or 3 before editing its host and port.
Gateway Host, Gateway Port	Configure the selected entry. Clearing its host removes it and shifts later entries forward.
Restore Reticulum TCP defaults	Replace manual TCP entries with the factory bootstrap seeds while preserving other interface settings.
Auto Wi-Fi	Set the Reticulum automatic Wi-Fi connection preference.
Anonymous Peer	Suppress public discovery announcements and ordinary discovery responses while retaining outbound communication.
Location Requests	Control the existing Reticulum location-request preference; this does not change the chat protocol.

Controls depend on device Wi-Fi capability. The chat protocol remains in Settings > Profile; changing a TCP entry does not switch chat or Contacts to Reticulum. TCP fields configure manual entries, not the temporary automatically discovered pool. IFAC has no device form fields yet: use the TMS procedure below.

Automatic discovery and maintenance

Reticulum preferences have a dedicated Settings > Reticulum category. Configure TCP entries, Auto Wi-Fi, bearer and privacy preferences without switching the selected chat protocol. TCP controls require Wi-Fi support.

Select the chat protocol under Settings > Profile. Meshtastic, MeshCore and Reticulum remain separate choices for chat, Contacts and integrated radio ownership. Editing Reticulum preferences does not change that choice.

Identity and LXMF address fields currently appear when the Reticulum chat adapter is active. Opening Settings does not create a network service to populate those fields.

The implementation retains three editable TCP entries and selects one TCP uplink at a time. Failed endpoints back off independently. Verified native discovery announcements can supply up to four additional candidates sharing one slot; they do not replace manual settings. Repeated announcements and candidate changes preserve failure history.

Factory public entries now serve as bootstrap connections. After one remains stable for 60 seconds, idle maintenance can try one verified public discovered candidate. A previously stable candidate takes priority as soon as it is restored from SD. Active calls, messages, resources and recent custom requests defer the handoff; switching retires the old interface's idle links and routes. An unsuccessful trial falls back with cooldown and does not repeatedly interrupt a healthy connection. Custom manual hosts and IFAC interfaces stay under the user's control. A healthy discovered connection is retained. This is reliability-based selection, not a claim to find the lowest-latency gateway.

Automatic candidates must be public endpoints. Private, loopback, link-local, CGNAT and reserved IPv4 addresses, and local-only hostnames, are rejected even when restoring an old cache. A peer's 192.168.x.x advertisement cannot become this device's public gateway. Explicit manual LAN entries still work.

One discovered endpoint that remained connected for 60 seconds is saved to a bounded SD cache. Eligible candidates with fewer consecutive connection failures are tried first; the saved endpoint wins ties within the discovery pool. A stable connection clears the failure score after 60 seconds. Cooldown expiry and repeated announcements do not clear it. Healthy connections stay in place, with one TCP uplink and no background latency probes. Other discovered candidates are temporary. An explicitly empty TCP list or a bearer policy that disallows Wi-Fi prevents automatic TCP admission. Native discovery needs a reachable Reticulum peer; it cannot bootstrap connectivity from an entirely disconnected device.

Among equally reliable discovered candidates, recent announcements take priority: observations age after 24 hours and become stale after three days. Unused temporary candidates expire after seven days, once their cooldown ends. The installed and last stable endpoints remain available. This uses the device's monotonic clock; SD restoration does not repeatedly refresh the age, but reboot starts a new age interval for the restored endpoint. No additional connection probes or memory buffers are required.

Failed connection attempts back off for 10, 20, 40, 80, 160 and then at most 300 seconds. Losing Wi-Fi or waiting for socket admission does not count as a server failure. The device favors eligible endpoints with fewer consecutive failures and retains a working uplink. Automatic selection does not measure latency or continuously probe servers.

The stable discovered endpoint is stored in /trailmate/reticulum/gateway.a and gateway.b, using bounded records with CRC validation. Preserve these files for restart recovery; they contain no IFAC credentials. Only one stable endpoint is persisted, not the complete temporary discovery pool. Remounting or externally taking over storage invalidates pending storage operations.

TCP IFAC configuration

Use USB Disk mode or power off before editing the SD card. Back up the complete /trailmate/config.tms document. Find the rt.net.interface.N.type record identifying the desired TCP interface, then add or update all three access records before the end marker. Do not create duplicate records. The example index is 2; it is the interface index, not the TCP Entry selector number:

rt.net.interface.2.network_name=str:my-network
rt.net.interface.2.passphrase=str:example-passphrase
rt.net.interface.2.ifac_size=u16:128

Each credential supports up to 63 UTF-8 bytes. The size is in bits, from 8 to 512 in multiples of eight. Keep an empty str: record for name-only or passphrase-only access. Clear both credentials and set the size to zero to restore public access. Missing or duplicate access records are rejected. Existing files without these records remain public.

Match the server's network name, passphrase and IFAC size exactly. Use the TMS escaping rules for special characters, leave external disk mode, and restart the device to load the complete document. A successful TCP connection alone does not establish IFAC compatibility: confirm that protected Reticulum traffic is received and a message obtains a recipient proof. Wrong credentials must not cause a retry as an unprotected public interface.

The TCP adapter authenticates before HDLC transmission and after HDLC reception, including the shared C6 TCP path. Changing credentials closes the old connection and clears its receive queues. Failure to allocate the PSRAM codec disables the interface rather than sending without IFAC. The host suite checks Python Reticulum wire vectors, actual framing functions and TMS round trips; physical-device interoperability is not yet verified.

RNode/LoRa IFAC, AutoInterface IFAC, device input fields and protected discovery candidates are still pending. Configuring IFAC on a non-TCP interface is currently rejected. Issue #89 remains open for the complete interface interoperability work.

Verification and troubleshooting

• If connection attempts time out, check Wi-Fi, DNS, the server's port and the endpoint cooldown. Discovering an endpoint does not prove it is reachable from this device.
• If no new gateways appear, ensure a bootstrap connection exists and its network carries native discovery announcements. Announcements must pass signature, shape and stamp checks. IFAC-protected and encrypted discovery advertisements are not currently admitted. [Reticulum][Discovery] verified host=... means discovery succeeded; bootstrap handoff host=... marks the trial, and gateway connected host=... confirms the selected TCP endpoint. A verified announcement alone does not prove connection or destination reachability.
• If the fallback disappears after restart, check that SD is mounted and writable and that the connection remained stable for 60 seconds. Persistence retries are bounded and writes are paced; a transient connection is not saved immediately.
• If TCP connects but protected messages do not arrive, compare all IFAC fields with the server. Do not clear access credentials as an automatic workaround.
• If a message remains Queued, distinguish waiting for a path/link or propagation upload from a packet awaiting proof. Screen saver now permits queued propagation work and expiry to progress; opening a conversation does not yet recreate an orphaned send task automatically.

The native network suite in tests/reticulum_gateway checks discovery, candidate selection, backoff, aging, bounded persistence, IFAC wire vectors, TCP framing and TMS records. Run python tests/reticulum_gateway/ifac_reference.py --check with Python Reticulum 1.5.4 to verify the reference vectors. These tests do not prove every public gateway is online or physical-device IFAC interoperability.

NAS deployment

See the network configuration reference for storage, migration, editing, discovery validation and retry behavior.

The NAS deployment template also enables Python Reticulum's native discovery, with a minimum stamp value of 16 and two automatically connected interfaces. Its three fixed public peers serve as bootstrap interfaces. This is separate from the ESP device's single-uplink policy. Existing deployments must merge the updated mounted configuration and recreate the services while retaining their data volumes; pulling firmware alone does not update the NAS. See the deployment update instructions.

Opportunistic direct messages show Sent once the transport accepts the packet. Only a verified recipient proof advances them to Delivered. A missing proof does not keep an already submitted message in Queued.

Mesh contains protocol-specific channel and MQTT settings. It is hidden when no items apply to the selected protocol, including Reticulum, and returns when applicable. Protocol selection remains under Settings > Profile > Protocol.