feat: add config backup and restore with schema versioning

Add export/import of the full device configuration as a versioned JSON
file via the web UI. Backup downloads from GET /api/backup (secrets
optional via checkbox); restore uploads to POST /api/restore, applies
recognized settings leniently, and reboots.

- config_backup module serializes/deserializes config via ArduinoJson,
  gated by CONFIG_SCHEMA_VERSION with a migrate() hook for future
  non-additive schema changes
- Lenient restore: recognized fields applied (clamped via setters),
  unknown ignored, absent left at current values; cross-version restore
  proceeds with a mismatch warning
- Secrets (WiFi/MQTT passwords, HA token) omitted unless requested and
  never erased by a no-secrets restore
- Backup and Restore card on the System settings page
- Docs: configuration guide and API reference

Author: chvvkumar

config.h

@@ -23,6 +23,11 @@ enum LogSeverity {
 // SYSTEM CONFIGURATION
 // =============================================================================
 
+// Config backup/restore schema version. Bump when fields are added, renamed,
+// removed, or change meaning. See config_backup.cpp migrate() for the
+// non-additive migration hook.
+#define CONFIG_SCHEMA_VERSION 1
+
 // Memory allocation sizes
 // NOTE: These values automatically control PPA hardware accelerator buffer sizes:
 //   - PPA source buffer = FULL_IMAGE_BUFFER_SIZE

config_backup.cpp

@@ -0,0 +1,24 @@
+#pragma once
+#include <Arduino.h>
+
+// Config backup/restore module. Single owner of the mapping between
+// ConfigStorage state and the versioned JSON backup document.
+namespace ConfigBackup {
+  struct RestoreResult {
+    bool ok = false;
+    String error;
+    int fileVersion = 0;
+    int applied = 0;
+    int skipped = 0;
+    bool versionMismatch = false;
+    bool secretsIncluded = false;
+  };
+
+  // Serialize the full device configuration to JSON. When includeSecrets is
+  // false the wifiPassword, mqttPassword, and haAccessToken keys are omitted.
+  String exportJson(bool includeSecrets);
+
+  // Parse a backup document and apply recognized fields through ConfigStorage
+  // setters, then saveConfig(). Does not reboot; the caller handles that.
+  RestoreResult importJson(const String& body);
+}

config_backup.h

@@ -10,6 +10,7 @@ Complete guide to configuring the ESP32-P4 AllSky Display firmware, covering bot
 - [Web UI Configuration](#web-ui-configuration)
 - [MQTT Configuration](#mqtt-configuration)
 - [Multi-Image Setup](#multi-image-setup)
+- [Backup and Restore](#backup-and-restore)
 - [Serial Commands Reference](#serial-commands-reference)
 - [Advanced Configuration](#advanced-configuration)
 
@@ -650,6 +651,57 @@ mkdir -p "${OUTPUT_DIR}"
 
 ---
 
+## Backup and Restore
+
+Export the full device configuration to a file, then restore that file onto a device that has been wiped or reset. The backup captures runtime settings stored in NVS: device name, WiFi, MQTT, Home Assistant, image sources and transforms, display settings, and system thresholds. Compile-time settings are not part of a backup.
+
+### Where the Controls Live
+
+The controls are on the System settings page, in the "Backup and Restore" card.
+
+1. Navigate to `http://allskyesp32.lan:8080/system`
+2. Find the "Backup and Restore" card
+
+The card contains a "Download backup" button, an "Include passwords and tokens" checkbox, a file picker, and a "Restore and reboot" button.
+
+### Download a Backup
+
+1. Decide whether to include secrets. The "Include passwords and tokens" checkbox controls whether the WiFi password, MQTT password, and Home Assistant access token are written to the file.
+2. Select "Download backup". The browser saves a `.json` file named after the device.
+
+Warning: when "Include passwords and tokens" is checked, the secrets are stored in plaintext in the downloaded file. There is no encryption. Store the file in a protected location. When the checkbox is unchecked, the secret keys are omitted from the file, and other identifiers such as the WiFi SSID and MQTT username are still written.
+
+### Restore and Reboot
+
+1. Select the file picker and choose a `.json` backup file.
+2. Select "Restore and reboot" and confirm the prompt.
+3. The device applies the recognized settings, saves them to NVS, and reboots. After the reboot, the device runs with the restored settings.
+
+A restore that fails to parse the file does not reboot the device.
+
+### Version Behavior
+
+The backup file carries a schema version. Restore is lenient and best-effort:
+
+- Recognized fields are applied.
+- Unknown fields are ignored.
+- Fields absent from the file keep their current value on the device.
+- A backup made on a different schema version still restores. The restore proceeds and reports a version mismatch warning.
+- A no-secrets backup does not erase existing credentials. Secret fields are applied only when present and non-empty, so restoring a file saved without secrets leaves the current WiFi password, MQTT password, and Home Assistant token in place.
+
+### Wipe Then Restore Sequence
+
+After a factory reset the web UI is not reachable until WiFi is configured, because a factory reset clears WiFi credentials. Use this order:
+
+1. Factory reset the device.
+2. Complete WiFi setup through the captive portal so the device joins your network and the web UI becomes reachable.
+3. Open the System settings page and restore the backup file.
+4. The device reboots with the restored configuration.
+
+If the backup includes secrets, the restored WiFi credentials take effect after the reboot. If the backup excludes secrets, the WiFi credentials entered during setup are retained.
+
+---
+
 ## Serial Commands Reference
 
 Connect via Serial Monitor at 9600 baud to access these commands:

docs/03_configuration.md

@@ -835,6 +835,59 @@ bool isRunning();
 bool isOTAInProgress() const;
 ```
 
+### REST API Endpoints
+
+#### GET /api/backup
+
+Returns the device configuration as a JSON file attachment.
+
+Query parameters:
+
+| Parameter | Values | Description |
+|-----------|--------|-------------|
+| `secrets` | `0` or `1` | `1` includes passwords and tokens (WiFi password, MQTT password, Home Assistant access token). `0` omits them. |
+
+Response: the configuration document with `Content-Type: application/json` and a `Content-Disposition: attachment` header. The filename is derived from the device name.
+
+Example:
+
+```bash
+# Download a backup with secrets included
+curl -OJ "http://allskyesp32.lan:8080/api/backup?secrets=1"
+
+# Download a backup without secrets
+curl -OJ "http://allskyesp32.lan:8080/api/backup?secrets=0"
+```
+
+#### POST /api/restore
+
+Applies a backup file, saves the configuration, and reboots on success.
+
+Request body: the raw backup file text (the JSON document returned by `GET /api/backup`). The body is read from the `plain` argument.
+
+Behavior: the handler parses the body, applies every recognized field through the matching `ConfigStorage` setters, saves the configuration, then reboots the device. Unknown fields are ignored. Absent fields keep their current value. Secret fields are applied only when present and non-empty, so a no-secrets backup does not erase existing credentials.
+
+Response JSON fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | Result of the restore. |
+| `message` | string | Human-readable detail. |
+| `applied` | number | Count of recognized fields applied. |
+| `skipped` | number | Count of unknown fields ignored. |
+| `fileVersion` | number | Schema version read from the file. Absent value is treated as 0. |
+| `versionMismatch` | boolean | `true` when `fileVersion` differs from the firmware schema version. The restore still proceeds. |
+
+Errors: an empty or unparseable body returns HTTP 400 and does not reboot. A successful restore reboots after sending the response.
+
+Example:
+
+```bash
+# Restore a previously downloaded backup
+curl -X POST "http://allskyesp32.lan:8080/api/restore" \
+  --data-binary @allsky-config-backup.json
+```
+
 ---
 
 ## ConfigStorage

docs/developer/api_reference.md

@@ -64,6 +64,8 @@ bool WebConfig::begin(int port) {
         server->on("/api/update-image-duration", HTTP_POST, [this]() { handleUpdateImageDuration(); });
         server->on("/api/restart", HTTP_POST, [this]() { handleRestart(); });
         server->on("/api/factory-reset", HTTP_POST, [this]() { handleFactoryReset(); });
+        server->on("/api/backup", HTTP_GET, [this]() { handleBackup(); });
+        server->on("/api/restore", HTTP_POST, [this]() { handleRestore(); });
         server->on("/api/set-log-severity", HTTP_POST, [this]() { handleSetLogSeverity(); });
         server->on("/api/clear-crash-logs", HTTP_POST, [this]() { handleClearCrashLogs(); });
         server->on("/api/force-brightness-update", HTTP_POST, [this]() { handleForceBrightnessUpdate(); });

web_config.cpp

@@ -68,6 +68,8 @@ class WebConfig {
     void handleUpdateImageDuration();
     void handleRestart();
     void handleFactoryReset();
+    void handleBackup();
+    void handleRestore();
     void handleSetLogSeverity();
     void handleClearCrashLogs();
     void handleForceBrightnessUpdate();

web_config.h

@@ -12,6 +12,7 @@
 #include "ha_discovery.h"
 #include "logging.h"
 #include "image_presets.h"
+#include "config_backup.h"
 #include <Update.h>
 #include <driver/jpeg_encode.h>  // ESP32-P4 hardware JPEG encoder (screenshot endpoint)
 
@@ -1105,6 +1106,62 @@ void WebConfig::handleFactoryReset() {
     ESP.restart();
 }
 
+void WebConfig::handleBackup() {
+    bool includeSecrets = server->hasArg("secrets") && server->arg("secrets") == "1";
+    LOG_INFO_F("[WebAPI] Configuration backup requested (secrets: %s)\n", includeSecrets ? "included" : "omitted");
+
+    String body = ConfigBackup::exportJson(includeSecrets);
+    server->sendHeader("Content-Disposition", "attachment; filename=\"allsky-config.json\"");
+    sendResponse(200, "application/json", body);
+}
+
+void WebConfig::handleRestore() {
+    if (!server->hasArg("plain") || server->arg("plain").length() == 0) {
+        LOG_WARNING("[WebAPI] Configuration restore called with empty body");
+        sendResponse(400, "application/json", "{\"status\":\"error\",\"message\":\"Request body is empty. Upload a backup file.\"}");
+        return;
+    }
+
+    LOG_INFO("[WebAPI] Configuration restore request received");
+    ConfigBackup::RestoreResult r = ConfigBackup::importJson(server->arg("plain"));
+
+    // Build the human-readable message, noting cross-version restores.
+    String message;
+    if (r.ok) {
+        message = "Configuration restored. Device restarting now...";
+        if (r.versionMismatch) {
+            message = "Configuration restored from a different schema version (file v" + String(r.fileVersion) +
+                      "); applied best-effort. Device restarting now...";
+        }
+    } else {
+        message = r.error;
+    }
+
+    String json = "{";
+    json += "\"status\":\"" + String(r.ok ? "success" : "error") + "\",";
+    json += "\"message\":\"" + escapeJson(message) + "\",";
+    json += "\"applied\":" + String(r.applied) + ",";
+    json += "\"skipped\":" + String(r.skipped) + ",";
+    json += "\"fileVersion\":" + String(r.fileVersion) + ",";
+    json += "\"versionMismatch\":" + String(r.versionMismatch ? "true" : "false");
+    json += "}";
+
+    if (!r.ok) {
+        LOG_WARNING_F("[WebAPI] Configuration restore failed: %s\n", r.error.c_str());
+        sendResponse(400, "application/json", json);
+        return;
+    }
+
+    LOG_INFO_F("[WebAPI] Configuration restore applied (applied: %d, skipped: %d) - rebooting\n", r.applied, r.skipped);
+    sendResponse(200, "application/json", json);
+
+    displayManager.debugPrint("Configuration restored...", COLOR_YELLOW);
+
+    delay(500);
+    crashLogger.saveBeforeReboot();
+    ESP.restart();
+}
+
 void WebConfig::handleSetLogSeverity() {
     if (!server->hasArg("severity")) {
         sendResponse(400, "application/json", "{\"status\":\"error\",\"message\":\"Missing severity parameter\"}");

web_config_api.cpp

@@ -583,6 +583,47 @@ String WebConfig::generateAdvancedPage() {
             "</script>";
     html += "</div>";
 
+    // Backup and Restore Section
+    html += "<div class='card' style='margin-top:1.5rem'><h2>💾 Backup and Restore</h2>";
+    html += "<p style='color:#94a3b8;margin-bottom:1rem'>Download the full device configuration to a JSON file, or restore a previously saved file. Restoring replaces the current configuration and reboots the device.</p>";
+    html += "<div style='background:rgba(245,158,11,0.1);border:1px solid #f59e0b;border-radius:8px;padding:1rem;margin-bottom:1rem'>";
+    html += "<p style='color:#f59e0b;margin:0;font-size:0.9rem'><i class='fas fa-exclamation-triangle' style='margin-right:8px'></i>If <strong>Include passwords and tokens</strong> is checked, the backup file stores the WiFi password, MQTT password, and Home Assistant token in plaintext.</p>";
+    html += "</div>";
+    html += "<div class='form-group'><label><input type='checkbox' id='backupSecrets'> Include passwords and tokens</label></div>";
+    html += "<div style='display:flex;gap:0.75rem;flex-wrap:wrap;margin-bottom:1.5rem'>";
+    html += "<button type='button' class='btn btn-primary' onclick='downloadBackup()'>⬇️ Download backup</button></div>";
+    html += "<div class='form-group'><label for='restoreFile'>Restore from file</label>";
+    html += "<input type='file' id='restoreFile' accept='.json,application/json' class='form-control'></div>";
+    html += "<div style='display:flex;gap:0.75rem;flex-wrap:wrap;margin-bottom:0.75rem'>";
+    html += "<button type='button' class='btn btn-primary' onclick='restoreBackup()'>♻️ Restore and reboot</button></div>";
+    html += "<div id='backupStatus' style='color:#94a3b8'></div>";
+    html += "<script>"
+            "function downloadBackup(){"
+            "var s=document.getElementById('backupSecrets').checked?'1':'0';"
+            "window.location='/api/backup?secrets='+s;"
+            "}"
+            "function restoreBackup(){"
+            "var st=document.getElementById('backupStatus');"
+            "var fi=document.getElementById('restoreFile');"
+            "if(!fi.files||!fi.files.length){st.textContent='Select a backup file first.';return;}"
+            "if(!confirm('Restore this configuration? The current settings will be replaced and the device will reboot.'))return;"
+            "var rd=new FileReader();"
+            "rd.onload=function(){"
+            "st.textContent='Restoring...';"
+            "fetch('/api/restore',{method:'POST',body:rd.result}).then(function(r){"
+            "return r.json().then(function(j){return {ok:r.ok,body:j};});}).then(function(res){"
+            "var msg=(res.body&&res.body.message)?res.body.message:('HTTP '+(res.body&&res.body.status?res.body.status:'error'));"
+            "if(res.body&&res.body.versionMismatch){msg+=' (backup schema version differs from this firmware; recognized fields were applied on a best-effort basis)';}"
+            "st.textContent=msg;"
+            "if(res.ok){st.textContent=msg+' Device is rebooting...';}"
+            "}).catch(function(e){st.textContent='Restore failed: '+e.message;});"
+            "};"
+            "rd.onerror=function(){st.textContent='Could not read the selected file.';};"
+            "rd.readAsText(fi.files[0]);"
+            "}"
+            "</script>";
+    html += "</div>";
+
     html += "</div></div>";
     return html;
 }