3.7 SD Editable Working Configuration (TMS)

SD-editable working configuration (TMS)

Trail Mate 1.0.0 stores its working configuration in /trailmate/config.tms. The current document is TMSET7. It is a complete, typed settings file, not a collection of optional overrides. Keep the file the device produced and edit only the values you need.

For routine changes, the device Settings page or the browser Device page is easier: controls explain units and choices, and saving validates the complete result. Direct SD editing remains useful when the normal interface is unavailable.

Which copy is authoritative?

Startup condition	Behavior
A complete, valid SD working file exists	The SD document is authoritative.
No card or no working file	Firmware uses its compatibility startup state; a new complete file can be materialized when writable storage is available.
The file is malformed, incomplete or has an unknown key	Firmware retains it for repair and uses safe code defaults. It does not silently hide the error behind an older NVS copy.
USB Disk mode owns the card	Firmware services do not read or rewrite it concurrently. Host edits are validated at the next restart.

The file covers the settings supported by the board, including the core app, Wi-Fi profiles, Reticulum interfaces/LXMF, BLE preferences and optional cellular settings. Reticulum identity and contact databases are distinct resources.

Edit safely

1. Enter USB Disk mode, or power off before removing the card.
2. Back up the complete working file.
3. Change the intended values in the existing records. Keep their keys, types and canonical order; do not add guessed records or delete disabled slots.
4. Preserve the header, schema version, document kind and final END marker.
5. Eject the host volume cleanly, return storage to the device and restart.
6. If the edit is refused, inspect [AppCfg][SD] logs and repair or restore the file. Do not delete recovery files as a way of making validation succeed.

The record shape is:

TMSET7
schema.version=u16:7
document.kind=enum:working
# complete ordered typed records emitted by this firmware
END

This illustrates the syntax, not a valid minimal configuration. Every required record must appear exactly once. The parser rejects unknown keys, duplicates, missing required records, invalid types and out-of-range values. The file is bounded to 32 KiB and each line uses the firmware's 384-byte scratch.

Wi-Fi, Reticulum and access settings

Use the existing profile/interface records rather than constructing a block from an old example. The browser Device page supports profile and interface maintenance while preserving fields you did not change. Reticulum TCP entries, AutoInterface, LoRa and LXMF settings share this document.

For network behavior and IFAC, see 4.1.1 Reticulum Settings and the network configuration reference. The implementation's current projection is the final authority for record names and board-specific fields; a pre-release dialect can look similar while being incompatible.

The SD file can contain Wi-Fi and interface access credentials. Treat backups as private and avoid posting an unredacted file with a bug report.

Migration and recovery

TMSET2 through TMSET6 are migration inputs. In particular, TMSET6 was a strict pre-release layout without the complete BLE projection and with an older Reticulum/group dialect. Firmware accepts its supported complete legacy layout and writes TMSET7 after validation. Do not change the version number manually on an old document.

Updates validate and canonicalize config.tms.new, record a transaction digest, retain the old generation as config.tms.bak, and promote the new working file. At boot, recovery chooses a validated candidate or backup according to the transaction. These files support recovery; they are not independent settings sources to edit.

The settings projection uses bounded temporary PSRAM on supported ESP boards; the firmware streams records instead of retaining the whole document in RAM.

See the persistence architecture and codec schema for the exact contract. The earlier draft remains at 3.7.1 Legacy TMS6 Record Reference for historical context, not as a current editing template.