3.5 Configuration Guide

Configuration Guide

Language: English. Chinese version: 3.5 Configuration Guide (中文)

Settings must preserve Trail Mate's four product boundaries: anonymous operation, decentralization, offline operation, and TAK. Public discovery, contact position, Team position, and local tracks are distinct concerns and must not be treated as one unbounded sharing switch.

Three Boundaries To Keep In Mind

First, many settings are constrained by hardware reality rather than UI choice. GPS presence, SD support, RAM budget, and input method all affect whether some pages and options even appear.

Second, Trail Mate is currently a single-protocol runtime. Protocol selects the protocol role that is actually active. It is not a secondary compatibility checkbox. If the protocol is wrong, the rest of the wireless settings will not put you into the network you expect.

Third, region and carrier parameters are not cosmetic. Region, MC Region Preset, TX Power, and BW/SF/CR affect both interoperability and legal limits. If these are wrong, the result is often not “reduced performance” but “cannot receive, cannot transmit, or no longer belongs to the same network”.

Recommended First-Time Order

For first setup, a stable order is:

1. confirm the hardware target and decide which protocol path you actually want
2. set Protocol and then Region or MC Region Preset
3. set identity and channel-related values
4. review TX Power, Hop Limit, and transmit-related options
5. confirm GPS, maps, and track settings
6. only then tune brightness, BLE, NMEA output, or debug options

How The Settings Are Grouped

The current shared settings page groups configuration into GPS, Map, Chat, Network, System, and Advanced. That is not arbitrary naming. It roughly matches the internal config model, the runtime apply logic, and where maintainers will find the corresponding code paths.

The categories are not truly independent, though:

• the Protocol setting under Chat changes which wireless parameters under Network actually matter
• GPS sampling strategy affects map behavior, track recording, and battery life
• BLE, brightness, and timeout under System still change real field usability

Chat: Identity, Protocol, and Channel

User Name and Short Name

These settings affect how other people see you first, and how the local UI displays you second. Short Name is better suited to constrained screens, contact lists, and map markers. User Name is more appropriate for fuller identity display. In field use, short and stable names are usually more useful than descriptive ones.

Protocol

Protocol selects the active product protocol. The current selector contains Meshtastic, MeshCore, and Reticulum. LXMF is the messaging layer inside Reticulum; RNode/KISS is an external-host runtime capability, not another selector option. Once Reticulum is selected, interfaces and propagation are configured from /trailmate/reticulum/config.json on the SD card.

Changing the protocol has immediate consequences:

• the system instantiates a different adapter rather than mixing protocols
• the set of meaningful settings changes
• saved history may remain, but current over-the-air behavior follows only the currently selected protocol

In Reticulum, the device owns its identity and handles announces, paths, LXMF, and the supported link/resource/propagation behavior. It acts as a USB modem only when the external-host HostLink/RNode KISS runtime is explicitly enabled; that is not normal Reticulum configuration.

Region and MC Region Preset

These settings matter because they define the actual radio boundary, not just a label.

On the Meshtastic path, Region is not cosmetic. In the current implementation it can also constrain transmit power, and changing region may automatically clamp TX Power down to that region’s allowed maximum. That is intentional behavior, not a bug.

On the MeshCore path, MC Region Preset acts more like a reusable bundle of frequency, bandwidth, spread factor, and coding rate. If you are not deliberately doing coordinated radio experiments, using the preset is safer than hand-entering carrier values.

One of the most common failure modes is a device that boots, shows UI, and seems alive, but is in a different region or preset than the network around it.

Channel and Channel Key / PSK

Channel is a logical communication domain selector, not just a UI label. Channel Key / PSK is the corresponding key entry for the currently active protocol path. In both Meshtastic and MeshCore, channel mismatch or key mismatch means you are no longer in the same effective communication domain, even if the hardware is otherwise healthy.

For first validation, do not change protocol and channel at the same time if you can avoid it. First align the protocol, then region, then channel and key. That makes failures easier to isolate.

Encryption and privacy-related options

The UI currently exposes privacy-related options such as OFF, PSK, PKI, and PKI toggles. The careful interpretation is that these are the entry points for privacy and encryption behavior in the selected protocol path, not a guarantee that every protocol already has equally mature encrypted interoperability across every mode.

For users, the practical advice is to treat them as settings that must remain consistent with the selected protocol path. For developers and maintainers, changing them means checking the protocol adapter behavior as well, not only whether the value saves correctly.

Reset actions

Actions such as Reset Mesh Profiles, Reset Node DB, and Clear Message DB are cleanup tools, not optimization buttons.

• use Reset Mesh Profiles after heavy protocol, region, or carrier experiments
• use Reset Node DB when node or contact state looks polluted by stale data
• use Clear Message DB when you need to remove old conversations from current debugging

In troubleshooting, collect logs before resetting state when possible. Resetting too early often destroys the evidence you actually needed.

Network: Carrier and Transmit Behavior

Presets and modem profiles

On the Meshtastic path, Use Preset and Modem Preset decide whether you rely on predefined radio parameter combinations such as LongFast, LongSlow, or ShortFast.

For first-time use and real interoperability, presets are safer because they give the whole team a predictable shared parameter set. Hand-editing BW/SF/CR is better reserved for protocol debugging, radio experiments, or board bring-up.

Manual BW / SF / CR

These directly control the carrier modulation behavior. Once changed, the main impact is not UI behavior. It is whether you are still on the same air interface as the devices around you.

These settings should usually be changed only when:

• the whole team moves together to a new known parameter set
• you are explicitly running a controlled experiment
• you are doing board bring-up or protocol debugging

Trying random values “for more range” usually produces disconnection faster than improvement.

TX Power

Higher power is not automatically better on a constrained device:

• it increases current draw and battery pressure
• it is bounded by region and board capability
• it can hide root causes by making people assume power alone can solve link design problems

Trail Mate already generates power choices dynamically based on board capability and region. If different devices expose different power ranges, or power drops after a region change, that is expected.

Hop Limit

On the Meshtastic path, Hop Limit changes multi-hop propagation range. A larger value does not just mean “possibly farther”. It also means more airtime and more network noise. For small-team field use, the right value is the one that preserves usable propagation, not the one that maximizes theoretical spread.

TX Enabled

This is one of the highest-value checks in troubleshooting. When disabled, the device may still receive but will not transmit normally.

If the symptom is “I can receive but not send”, check protocol, region, channel, and then TX Enabled before assuming the radio hardware is broken.

Duty cycle and channel utilization controls

Settings such as Duty Cycle Limit, Channel Utilization, and Override Duty Cycle govern airtime policy. They are not simple “performance boost” toggles.

For field coordination, stable long-duration behavior matters more than short bursts of traffic, and legal compliance matters too. These are not good candidates for casual trial-and-error.

Channel Slot, Freq Offset, and Override Freq

These are advanced radio-tuning settings:

• Channel Slot selects a slot or auto-slot behavior
• Freq Offset helps compensate for small offset needs or experiments
• Override Freq sets a direct working frequency

The common pattern is that once these are wrong, the system does not become “slightly worse”. It simply stops lining up with the intended network.

MeshCore-specific settings

MeshCore exposes a wider set of dedicated carrier settings such as MC Frequency, MC Bandwidth, MC Spread Factor, MC Coding Rate, MC TX Power, MC Repeat, MC RX Delay Base, MC Airtime Factor, MC Flood Max, MC Multi ACKs, MC Channel Slot, MC Channel Name, and MC Channel Key.

Their importance is not that MeshCore has “more knobs”. It is that the MeshCore path is intentionally more tunable and more selective about device capability. That makes it useful for developers and advanced users, but not ideal as the first thing a new user should tune by intuition.

Reticulum SD configuration

The authoritative Reticulum configuration is /trailmate/reticulum/config.json on the SD card. It defines Integrated LoRa, AutoInterface, TCP Client, and the LXMF propagation client. See 4.1 Reticulum, LXMF and RNode Bridge for the complete JSON example, limits, load order, and error behavior.

Reticulum contacts do not belong in config.json. They are stored in the unified binary /mesh/peers.bin, which must not be edited manually; the current release has no supported contact TSV/JSON importer. Add a contact through Contacts > Add or save a discovered peer from Nearby. A destination hash without identity hash and public keys remains Address pending until a genuine announce/path response completes the identity.

For users, this means two practical things:

• config.json selects Reticulum interfaces and propagation policy; frequency, BW, SF, CR, and TX power configure the integrated LoRa radio
• legacy bearer/gateway values in Settings only construct defaults when neither SD configuration nor NVS last-known-good exists; they are not the normal configuration source
• these modes should not be understood through Meshtastic-style channel and PSK thinking

The device UI hides some fields accordingly because the semantics are different.

GPS: Fix Strategy, Sampling, and External Output

Location Mode

The current GPS modes include High Accuracy, Power Save, and Fix Only.

• High Accuracy is for real movement and continuous awareness
• Power Save is for reducing ongoing GNSS cost
• Fix Only is closer to “confirm a fix exists” than to full tracking behavior

Because boards, antennas, and power conditions differ, the same mode will not behave identically on every target.

Satellite systems

Combinations of GPS, BDS, GAL, and GLO influence initial lock behavior, satellite search range, and resource usage. For first use, the default multi-constellation setting is usually the safer choice unless you already know you need to constrain it for a specific device or region.

Position strategy and update interval

These settings define whether the positioning path favors continuous awareness or power-saving behavior.

• Continuous is for active movement and live map updates
• Motion Wake ties activity more closely to movement state
• Low Power Off is more aggressive and favors power reduction over constant awareness

Update Interval currently offers values like 1s, 2s, 5s, and 10s. Shorter intervals improve map following and track detail but increase power and processing cost. The right value depends on whether the use case is hiking, patrol, vehicle movement, or something else.

Altitude reference and coordinate format

Altitude Reference controls whether altitude is shown relative to mean sea level or ellipsoid. Coordinate Format affects whether coordinates are shown as DD, DMS, or UTM. These settings mostly affect human interpretation, not over-the-air behavior.

The important part is coordination: if route files, map workflow, or external collaborators rely on one coordinate style, the whole team should use it consistently.

NMEA output

NMEA Output and related sentence selection are for external consumers, host tools, or troubleshooting workflows. If you are not feeding a host tool or diagnosing a serial positioning issue, leaving them off is usually the safer choice.

Map: Base Layers, Coordinates, and Tracks

Coordinate system

The map coordinate system options currently include WGS84, GCJ-02, and BD-09. This is not decorative. It changes how location is interpreted against the base map.

If the base map, route data, and coordinate system do not match, the usual result is “the fix exists, but the point looks wrong”. In mainland China scenarios especially, this matters a great deal.

Map Source and contour overlay

Map Source selects among the current base-map families: OSM, Terrain, and Satellite.

• OSM is best for roads, place names, and man-made context
• Terrain is better for landform and relief judgement
• Satellite is better for checking actual surface appearance

Contour Overlay adds contour lines on top of the selected base map. It is especially useful in mountain terrain, but only when the SD-card directory structure and files are prepared correctly.

Track recording

Track handling is not just for remembering where you were. It supports after-action review and route reconstruction.

• Track Recording is the master switch
• Track Interval offers choices such as 1s, 5s, 10s, or Distance
• Track Format includes GPX, CSV, and Binary

GPX is better for interchange, CSV is easy to post-process, and Binary is more device-oriented. If you carry maps and GPS but forget to enable tracks, you lose valuable evidence for later review. If you sample too frequently or choose the wrong format, you increase storage and handling cost instead.

System: Display, Power, BLE, and Device Experience

Display options

Display Language, Screen Timeout, and Screen Brightness are not superficial preferences. They directly affect readability, battery life, and field usability under sunlight, cold, gloves, or night operation.

Speaker, vibration, and BLE

These settings control alert behavior and external connectivity:

• Speaker Volume affects audible feedback
• Vibration affects tactile feedback
• Bluetooth controls whether the BLE interaction path is open

If you depend on phone-side apps, BLE matters. If you want a more self-contained low-exposure field device, you may want to be more conservative with it.

Time zone and battery-gauge parameters

Time Zone affects local time readability. Gauge parameters such as Gauge Design (mAh) and Gauge Full (mAh) are closer to calibration data than to user preference. They should not be changed casually unless you are deliberately adapting or calibrating a specific board.

Power and sleep boundaries

Power behavior is not exposed as one giant unified power page because some of it is board-specific:

• screen timeout and brightness affect UI-side power use
• GPS strategy changes GNSS power behavior
• shutdown and sleep details depend on board implementation

If one board behaves differently from another, check the device page and troubleshooting page before assuming the generic settings page should make them identical.

Advanced: Logs and Debugging

Debug Logs is the clearest high-level troubleshooting toggle. It helps with startup, protocol, and board adaptation issues, but it also means more serial output and more runtime noise.

For normal users it is best enabled only when:

• you are about to capture serial logs for maintainers
• you are debugging startup, communication, or board issues
• you are deliberately validating a protocol or initialization path

What Is Not Exposed As One Global Settings Block

People often ask where “team configuration” lives. The more accurate answer is that many Team values are session state and workflow state rather than stable device-wide settings.

Examples include:

• whether the device is currently in a team
• how the team was formed
• the current TeamKey or key id
• member role and lifecycle state

This is why you will not find one giant “team settings sheet” in the same style as region or brightness. Team is modeled as its own coordination workflow.

The Settings Most Likely To Break A Working Setup

These are the changes most likely to make a healthy device suddenly look wrong:

• changing protocol while peers remain on another protocol
• changing region or preset so the team no longer shares one carrier profile
• disabling transmit and then diagnosing the symptom as a radio failure
• mismatching map coordinate system against the base map or route data
• forgetting to enable tracks or choosing a track format that does not fit the follow-up workflow
• hand-editing BW, SF, CR, or Override Freq without understanding the air interface impact

Information Still Worth Expanding

Two future splits would be especially useful:

• device-specific configuration differences, such as GPS mode support, battery gauge notes, or sleep behavior differences
• protocol-specific configuration boundary pages, including Reticulum SD interface and LXMF propagation configuration