Merge pull request #162 from chvvkumar/Dev

Add device configuration backup and restore functionality

Author: chvvkumar

.gitignore

@@ -160,8 +160,10 @@ coverage.xml
 # Claude Code local settings
 .claude/
 
-# Implementation plans (local development only)
+# Superpowers specs and implementation plans (local development only)
+docs/superpowers/
 docs/plans/
+docs/specs/
 
 # AI conversation context documentation
 CONVERSATION_CONTEXT.md

build_info.h

@@ -9,8 +9,8 @@
 #define BUILD_TIME __TIME__
 
 // Git information (updated by compile script)
-#define GIT_COMMIT_HASH "8845feb"
-#define GIT_COMMIT_FULL "8845feb8cfedc9e828d4ac05d499daeab1c3773e"
-#define GIT_BRANCH "feat/solar-lunar-display"
+#define GIT_COMMIT_HASH "1f1abd5"
+#define GIT_COMMIT_FULL "1f1abd5bdb01707a96e570f90a548c52461d36c0"
+#define GIT_BRANCH "snd"
 
 #endif // BUILD_INFO_H

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