3.6 Settings Backup and Restore

Settings Backup and Restore

Backup Settings creates a portable settings snapshot on the SD card. Restore Settings imports it on a compatible ESP device. It is for moving a known working configuration or protecting it before maintenance; it is not a copy of every SD-card file or database.

Location, availability, and security

• Requires an ESP target with a usable SD card.
• Current document: /trailmate/settings-backup.json.
• Backup first writes /trailmate/settings-backup.tmp, then replaces the completed document.
• The document is schema version 2. It contains radio keys, MQTT and Wi-Fi credentials, and Reticulum destination hashes; keep it private.

Restore checks the document magic, schema version, and main configuration object before applying it. Version 1 documents remain importable. Missing v2 fields in a v1 document leave the current value unchanged.

Storage model and restore semantics

Owner	Active storage	Snapshot behavior
AppConfig	Preferences / NVS	Exports and restores persisted application settings.
settings_store	Preferences / NVS	Exports every supported logical preference and its presence state.
Reticulum groups	SD /trailmate/reticulum/groups.tsv	Embeds groups in the snapshot and restores them through the group owner.

Normal settings remain in NVS: a missing SD card must not prevent boot. SD is the portable snapshot medium and the owner of Reticulum groups. During restore, the group owner completes its physical SD write before NVS preferences and AppConfig are committed. A group-file failure therefore leaves those NVS owners untouched. This is failure ordering, not a global NVS/SD transaction.

For each supported settings_store key, v2 records whether the source had an explicit value. present: true restores it; present: false clears the target-side override so it uses the same code-defined default. V1 did not have this marker, so omitted V1 preferences are non-destructive on import.

Complete version 2 inventory

Feature visibility is board- and protocol-dependent, but every item below is included when supported by the device.

Area	Settings backed up and restored
Chat policy and identity	Relay; default hop limit; broadcast and squad acknowledgements; maximum retries and channels; user/node name; short name; selected protocol.
Primary / secondary channels	Enabled, uplink, downlink, has module settings, position precision, mute state; Meshtastic channel names, IDs, key lengths, and keys.
Meshtastic radio	Region, preset mode, modem preset, bandwidth, SF, CR, TX power, hop limit, TX enabled, duty override, channel number, frequency offset/override, relay, MQTT-ignore and config_ok_to_mqtt policies.
Meshtastic MQTT	Enabled, uplink, downlink, host, port, root topic, username, password.
MeshCore radio	Region preset, frequency, bandwidth, SF, CR, TX power, TX enabled, repeat, RX delay, airtime factor, flood max, multi-ACK, send/forward profiles, selected channel slot.
MeshCore channels and MQTT	Every supported channel slot's enabled state, name, and key; active legacy name/key mirror; MQTT enabled, uplink, downlink, host, port, root, username, password.
Reticulum	Frequency override, bandwidth, SF, CR, TX power, TX enabled, LoRa and Wi-Fi gateway controls, Wi-Fi auto-connect, anonymous peer, gateway host/port, interface policy, and Allow location requests.
Reticulum groups	Every configured slot's enabled state, display name, and destination hash. Restore writes /trailmate/reticulum/groups.tsv and waits for success.
GPS	Enabled, initial baud/probe timeout, receiver/RXM/GNSS/NMEA policies, update interval, mode, satellite mask, strategy, altitude reference, coordinate format, motion idle timeout/sensor, external NMEA rate and sentence mask.
Maps, tracks, network, privacy, route	Coordinate system, map source, contour overlay, track enabled/interval/format, duty cycle, channel utilization, privacy encryption mode, route enabled/path.
APRS / iGate	Enabled, iGate callsign/SSID, TOCALL, path, minimum TX interval, dedupe window, symbol table/code, position interval, self beacon enabled/callsign.
Display and feedback preferences	screen_timeout, screen_brightness, speaker_volume, vibration_enabled, display_locale, enabled_imes.
Wi-Fi preferences	wifi_enabled, active wifi_ssid/wifi_password, wifi_profile_count, and wifi_ssid_0 … wifi_ssid_9 with wifi_password_0 … wifi_password_9.
Time, alert, diagnostic, and gauge preferences	timezone_offset, timezone_profile, timezone_tzdef; chat_message_alerts, chat_contact_alerts, chat_auto_reply_enabled, chat_auto_reply_text; adv_debug; gauge_design_mah, gauge_full_mah.

Explicit exclusions

Not included	Reason
Message history/database	User data; manage it separately with the message DB actions.
Node, peer, contact, discovery, and APRS node-map databases	Runtime/user data, not portable Settings.
Offline map tiles, map packages, and recorded tracks	SD content/data; copy separately when migrating cards.
Debug logs	Diagnostic evidence, not Settings.
Complete /trailmate/reticulum/config.json	Separate Reticulum interface/propagation configuration. The snapshot includes AppConfig Reticulum options and groups, but does not replace this file.
Runtime-only state	BLE is forced off by the ESP configuration backend; live links, uptime, GPS fix, scan results, and UI session state are not settings.

Recommended workflow

1. Verify a writable SD card is ready.
2. Configure protocol, radio, Wi-Fi/MQTT, location, display, and groups.
3. Use Maintenance → Backup Settings and keep the JSON private.
4. On the target, install compatible firmware, insert the card, and use Maintenance → Restore Settings.
5. Verify protocol, radio region/channel, Wi-Fi/MQTT, location, and group list before field use.

For failures, check SD readiness and file integrity first. See 14. Troubleshooting and 4.1 Reticulum, LXMF and RNode Bridge.