From 50de29acfb02eb836da6f6dec3007639cb0e85b5 Mon Sep 17 00:00:00 2001 From: b14ckyy Date: Sat, 11 Apr 2026 15:54:44 +0200 Subject: [PATCH 1/4] docs: add Backup and Restore documentation for Configurator auto-backup feature - Add new docs/Backup and Restore.md covering automatic backup/restore during firmware flash, migration preview, file locations and formats - Update Installation.md: reference auto-backup in Backup/Restore section - Update Configuration.md: replace outdated GUI backup warning - Update Cli.md: note that Configurator now handles backup automatically Related: iNavFlight/inav-configurator#2603 --- docs/Backup and Restore.md | 107 +++++++++++++++++++++++++++++++++++++ docs/Cli.md | 2 + docs/Configuration.md | 2 +- docs/Installation.md | 6 ++- 4 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 docs/Backup and Restore.md diff --git a/docs/Backup and Restore.md b/docs/Backup and Restore.md new file mode 100644 index 00000000000..9206abafa03 --- /dev/null +++ b/docs/Backup and Restore.md @@ -0,0 +1,107 @@ +# Backup and Restore + +INAV Configurator can automatically back up your configuration before flashing firmware and offer to restore it afterwards. When upgrading across major versions (e.g. 7.x → 8.x → 9.x), settings are automatically migrated to the new firmware format. + +For manual CLI-based backup and restore, see the [CLI documentation](Cli.md#backup-via-cli). + +## Automatic Backup & Restore During Firmware Flash + +### What happens automatically + +1. **Before flashing** (with Full Chip Erase enabled): Your current CLI configuration (`diff all`) is automatically captured and saved to the backup directory. +2. **After flashing**: Depending on the situation, the Configurator offers to restore your settings: + +| Scenario | Behavior | +|----------|----------| +| **Patch update** (e.g. 8.0.0 → 8.0.1) | Auto-restore offered immediately | +| **Minor update** (e.g. 8.0.0 → 8.1.0) | Auto-restore offered immediately | +| **Major upgrade** (e.g. 7.x → 8.x) with migration profile available | Migration preview shown — confirm to restore with converted settings | +| **Major upgrade** without migration profile | Warning shown — restore still possible but some settings may fail | +| **Major downgrade** (e.g. 9.x → 7.x) | Auto-restore blocked — manual restore only (settings may be incompatible) | +| **Local firmware file** (loaded from disk) | No auto-restore offered — backup is still saved | +| **Flash without Full Chip Erase** | Backup taken, no restore offered | + +### Migration Preview + +When updating across major versions (e.g. 7.x → 9.x), the Configurator shows a **migration preview overlay** before restoring. This lists: + +- **Removed settings** — settings that no longer exist in the new firmware (will be skipped) +- **Renamed settings** — settings whose name changed (automatically converted) +- **Renamed commands** — CLI commands that were renamed (automatically converted) +- **Value replacements** — setting values that changed meaning (automatically converted) +- **Setting remappings** — numeric IDs that were renumbered (automatically converted) +- **Warnings** — settings whose semantics changed and require manual review + +You can review all changes before confirming or cancelling the restore. + +Multi-step migrations are handled automatically. For example, a 7.x → 9.x upgrade applies migration profiles in sequence (7→8, then 8→9). + +## Manual Backup & Restore + +The Firmware Flasher tab provides three buttons: + +- **Backup Config** — saves your current CLI configuration to a file (opens save dialog) +- **Restore Config** — loads a backup file and restores it to your flight controller + - If the backup is from a different major version, the migration preview is shown first + - If no migration profile exists for the version gap, a warning is shown but you can still proceed +- **Open Backups Folder** — opens the backup directory in your file manager + +For CLI-based backup and restore procedures, see [Backup via CLI](Cli.md#backup-via-cli) and [Restore via CLI](Cli.md#restore-via-cli). + +## Backup File Location + +Backups are stored in your OS-specific application data directory: + +| OS | Path | +|----|------| +| **Windows** | `%APPDATA%/inav-configurator/backups/` | +| **macOS** | `~/Library/Application Support/inav-configurator/backups/` | +| **Linux** | `~/.config/inav-configurator/backups/` | + +Use the **Open Backups Folder** button in the Firmware Flasher tab to open this directory. + +## Backup File Naming + +| Type | Format | +|------|--------| +| Auto-backups | `UPDATE_inav_backup_{version}_{board}_{YYYY-MM-DD_HHMMSS}.txt` | +| Manual backups | `inav_backup_{version}_{board}_{YYYY-MM-DD_HHMMSS}.txt` | + +Auto-backups are pruned automatically — only the 10 most recent are kept. Files you rename are never pruned. + +## Backup File Format + +Backup files are plain-text CLI dumps with a metadata header: + +``` +# INAV Backup +# Version: 8.0.0 +# Board: SPEEDYBEEF405V4 +# Date: 2026-04-11T10:30:00.000Z +# Craft: MyQuad +# +# INAV/SPEEDYBEEF405V4 8.0.0 Apr 1 2026 / 12:00:00 (abc1234) +# GCC-13.2.1 +# ... +set gyro_main_lpf_hz = 110 +set acc_hardware = AUTO +... +``` + +You can open and edit these files with any text editor. + +## Restore Error Handling + +If errors occur during restore (e.g. unknown settings, invalid values): + +- An error dialog shows the affected lines +- You can choose: + - **Save anyway** — saves the successfully applied settings and reboots + - **Abort** — discards all changes and exits CLI mode + +## Tips + +- **Always flash with Full Chip Erase** when upgrading to a new version. This ensures clean defaults and triggers automatic backup and restore. +- **Review migration previews carefully** — especially the warnings section, which highlights settings whose meaning may have changed. +- **Keep manual backups** before major upgrades. While auto-backup handles this, having an extra copy in a known location gives peace of mind. +- **Use `diff` over `dump`** for backups. The `diff` format only stores settings that differ from defaults, which makes restoring safer across versions. The auto-backup feature already uses `diff all`. diff --git a/docs/Cli.md b/docs/Cli.md index d949937a61b..d27029ee1b5 100644 --- a/docs/Cli.md +++ b/docs/Cli.md @@ -22,6 +22,8 @@ See the other documentation sections for details of the cli commands and setting ## Backup via CLI +> **Note:** The INAV Configurator now performs automatic backups before flashing and can restore settings afterwards, including migration across major versions. See [Backup and Restore](Backup%20and%20Restore.md) for details. The CLI method below remains available for manual backup. + Disconnect main power, connect to cli via USB/FTDI. dump using cli diff --git a/docs/Configuration.md b/docs/Configuration.md index 1ccea15d110..f48de1a10d6 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -10,7 +10,7 @@ See the Serial section for more information and see the Board specific sections The GUI cannot currently configure all aspects of the system, the CLI must be used to enable or configure some features and settings. -__Due to ongoing development, the fact that the GUI cannot yet backup all your settings and automatic chrome updates of the GUI app it is highly advisable to backup your settings (using the CLI) so that when a new version of the configurator or firmware is released you can re-apply your settings.__ +__The INAV Configurator now (versions after 9.0.x) automatically backs up your settings before flashing firmware and can restore them afterwards (when Full Chip Erase is enabled), including automatic migration across major versions. For details, see [Backup and Restore](Backup%20and%20Restore.md). You can also manually backup and restore settings using the [CLI](Cli.md#backup-via-cli).__ ## GUI diff --git a/docs/Installation.md b/docs/Installation.md index 38e9470fd81..140f47bd6c9 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -27,4 +27,8 @@ When upgrading be sure to backup / dump your existing settings. Some firmware r ## Backup/Restore process -See the CLI section of the docs for details on how to backup and restore your configuration via the CLI. +The INAV Configurator (after version 9.0.x) automatically backs up your configuration before flashing and offers to restore it afterwards (when Full Chip Erase is enabled) — including automatic settings migration when upgrading across major versions. + +For details on automatic and manual backup/restore, see [Backup and Restore](Backup%20and%20Restore.md). + +For CLI-based backup and restore, see the [CLI documentation](Cli.md#backup-via-cli). From 959aa7848c99864a5457067820885a00e051ea95 Mon Sep 17 00:00:00 2001 From: b14ckyy Date: Sat, 11 Apr 2026 16:00:46 +0200 Subject: [PATCH 2/4] docs: add Backup/Restore architecture reference for migration profiles Developer-facing documentation covering migration engine internals, migration profile schema, and instructions for creating new profiles when major INAV versions are released. Related: iNavFlight/inav-configurator#2603 --- .../Backup Restore Architecture.md | 251 ++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 docs/development/Backup Restore Architecture.md diff --git a/docs/development/Backup Restore Architecture.md b/docs/development/Backup Restore Architecture.md new file mode 100644 index 00000000000..9dd971230c6 --- /dev/null +++ b/docs/development/Backup Restore Architecture.md @@ -0,0 +1,251 @@ +# Backup, Restore & Settings Migration — Architecture + +> **Note:** This document describes the internals of the INAV Configurator's backup/restore and settings migration system. It is intended for Configurator developers, not end users. For user-facing documentation, see the [INAV docs](https://github.com/iNavFlight/inav/blob/master/docs/Backup%20and%20Restore.md). + +## Architecture Overview + +``` +User → Firmware Flasher Tab → STM32.connect(onCliReady) → CLI mode + ↓ + BackupRestore.captureCliDiffAll() + ↓ + Save to file, prune old backups + ↓ + STM32 flash (DFU or serial) + ↓ + onFlashComplete() callback + ↓ + Version check → Migration check → UI overlay + ↓ + User confirms → Poll for FC reconnect + ↓ + BackupRestore.performRestore() or performRestoreWithMigration() + ↓ + saveAndReboot() or abortRestore() +``` + +## Files + +| File | Purpose | +|------|---------| +| `js/backup_restore.js` | Core backup/restore module — CLI protocol, file I/O, auto-backup | +| `js/migration/migration_handler.js` | Version migration engine — profile chaining, line transformation | +| `js/migration/7_to_8.json` | Migration profile: INAV 7.x → 8.0 | +| `js/migration/8_to_9.json` | Migration profile: INAV 8.0 → 9.0 | +| `tabs/firmware_flasher.js` | Flash integration — auto-backup trigger, restore UI, version gating | +| `tabs/firmware_flasher.html` | Overlays and buttons for backup/restore/migration UI | +| `src/css/tabs/firmware_flasher.css` | Overlay styles | +| `js/protocols/stm32.js` | STM32 flash protocol — `onCliReady` callback, DFU timeout fix | +| `js/main/main.js` | Electron main process — IPC handlers for file operations | +| `js/main/preload.js` | IPC bridge — exposes backup API to renderer | +| `locale/en/messages.json` | All i18n translation keys | + +## Adding a New Migration Profile + +When a new major INAV version is released (e.g. 9.x → 10.x), create a migration profile: + +### Step 1: Create the JSON profile + +Create `js/migration/9_to_10.json`: + +```json +{ + "fromVersion": "9", + "toVersion": "10", + "description": "INAV 9.x → 10.0 migration profile", + + "commandRenames": { + "old_command_name": "new_command_name" + }, + + "settingRenames": { + "old_setting_name": "new_setting_name" + }, + + "valueReplacements": { + "setting_name": { + "OLD_VALUE": "NEW_VALUE" + } + }, + + "removed": [ + "deleted_setting_1", + "deleted_setting_2" + ], + + "settingPatternMappings": [ + { + "pattern": "^regex_matching_setting_names$", + "valueMap": { "old_numeric_id": "new_numeric_id" }, + "description": "Human-readable description of remapping" + } + ], + + "warnings": [ + "Human-readable warning about settings whose semantics changed and need manual review." + ] +} +``` + +### Step 2: Register the profile + +In `js/migration/migration_handler.js`, add the import and append to the array: + +```javascript +import profile_9_to_10 from './9_to_10.json'; + +const MIGRATION_PROFILES = [ + profile_7_to_8, + profile_8_to_9, + profile_9_to_10, // ← add here +]; +``` + +The migration engine automatically chains profiles. A 7.x → 10.x upgrade will apply all three profiles in sequence (7→8, 8→9, 9→10). + +### How to determine what goes into a migration profile + +Compare CLI settings between the old and new firmware version: + +1. **Removed settings**: Run `diff all` on old and new firmware with default settings. Settings present in old but not in new → add to `removed` +2. **Renamed settings**: Check INAV release notes and source code for renamed settings → add to `settingRenames` +3. **Renamed commands**: Check for CLI command name changes (e.g. `profile` → `control_profile`) → add to `commandRenames` +4. **Value replacements**: Check for enum value name changes → add to `valueReplacements` +5. **Pattern mappings**: Check for bulk ID renumbering (OSD elements, etc.) → add to `settingPatternMappings` +6. **Warnings**: Check for settings where the meaning/units changed but name stayed the same → add to `warnings` + +Key INAV source files to check: +- `src/main/fc/settings.yaml` — all CLI settings definitions +- `src/main/fc/cli.c` — CLI command implementations +- Release notes on GitHub + +## Migration Profile Schema Reference + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `fromVersion` | `string` | Yes | Source major version number (e.g. `"9"`) | +| `toVersion` | `string` | Yes | Target major version number (e.g. `"10"`) | +| `description` | `string` | Yes | Human-readable description | +| `commandRenames` | `object` | Yes | Maps old CLI command names to new names. Applied to any token in the command line. E.g. `"profile" → "control_profile"` transforms `profile 2` to `control_profile 2` | +| `settingRenames` | `object` | Yes | Maps old `set` setting names to new names. Only applies to `set = ` lines | +| `valueReplacements` | `object` | Yes | Maps setting names to value replacement objects `{ "oldval": "newval" }`. Only modifies the value portion after `=` | +| `removed` | `string[]` | Yes | List of setting names to remove entirely. Lines with `set = ...` matching these are dropped | +| `settingPatternMappings` | `array` | Yes | Array of pattern-based value remappings for settings matching a regex. Each entry has `pattern` (regex), `valueMap` (object), `description` (string) | +| `warnings` | `string[]` | Yes | Warning messages about semantic changes requiring manual review. Displayed in migration preview overlay | + +## Existing Migration Profile Details + +### 7_to_8.json (INAV 7.x → 8.0) + +| Category | Changes | +|----------|---------| +| **Command renames** | `profile` → `control_profile` | +| **Value replacements** | `gps_provider`: `UBLOX7` → `UBLOX` | +| **Removed settings** (18) | `control_deadband`, `cpu_underclock`, `disarm_kill_switch`, `dji_workarounds`, `fw_iterm_limit_stick_position`, `gyro_anti_aliasing_lpf_type`, `gyro_hardware_lpf`, `gyro_main_lpf_type`, `gyro_use_dyn_lpf`, `inav_use_gps_no_baro`, `inav_use_gps_velned`, `ledstrip_visual_beeper`, `max_throttle`, `nav_auto_climb_rate`, `nav_manual_climb_rate`, `osd_stats_min_voltage_unit`, `pidsum_limit`, `pidsum_limit_yaw` | +| **Pattern mappings** | `osd_custom_element_N_type`: IDs remapped 4→9, 5→16, 6→7, 7→10 | +| **Warnings** | `nav_fw_wp_tracking_accuracy` semantics changed: was arbitrary tracking response, now distance in meters | + +### 8_to_9.json (INAV 8.0 → 9.0) + +| Category | Changes | +|----------|---------| +| **Command renames** | `controlrate_profile` → `use_control_profile` | +| **Setting renames** | `mixer_pid_profile_linking` → `mixer_control_profile_linking`, `osd_pan_servo_pwm2centideg` → `osd_pan_servo_range_decadegrees` | +| **Value replacements** | None | +| **Removed settings** | None | +| **Pattern mappings** | None | +| **Warnings** | Position estimator defaults changed (`w_z_baro_v`, `inav_w_z_gps_p`, `inav_w_z_gps_v`). `ahrs_acc_ignore_rate` default changed 20→15 | + +## Migration Engine Internals + +### Profile chaining + +`buildMigrationChain(fromVersion, toVersion)` selects all profiles where `profileFrom >= fromMajor` and `profileTo <= toMajor`, sorted by `fromVersion`. A 7.x → 9.x migration applies both 7→8 and 8→9 profiles in sequence. + +### Line processing + +Each non-comment, non-empty line passes through every profile in the chain. For each profile, transformations are applied in this order: + +1. Command renames (any token in the line) +2. Removed settings (line dropped if `set ` matches) +3. Setting renames (`set ` replacement) +4. Value replacements (value after `=` replaced) +5. Setting pattern mappings (regex-matched settings with value remapping) + +### Missing profile detection + +`hasMissingProfiles()` returns `true` when the number of profiles in the chain is fewer than the number of major version steps. The UI shows a warning but still allows restore — some settings may fail. + +## Edge Cases Handled + +1. **Stale FC version after flash**: Real FC version is queried via `MSP_FC_VERSION` after connect, not the cached value +2. **DFU mode (no MSP)**: `FC.CONFIG` null checks prevent crashes when connected in DFU mode +3. **DFU timeout**: UI unlock and progress label update on timeout (no permanent lock) +4. **Local firmware files**: `localFirmwareLoaded` flag prevents stale dropdown version from triggering wrong migration +5. **Backup pruning with mixed versions**: Sort by timestamp portion, not full filename +6. **Multi-step migration**: 7.x → 9.x automatically chains 7→8 + 8→9 profiles +7. **Missing migration profiles**: Warning shown but restore allowed — graceful degradation +8. **Version detection from backup**: Parsed from backup header (`# Version: X.Y.Z`), not from FC state + +## i18n Keys + +All backup/restore/migration translation keys in `locale/en/messages.json`: + +### Backup status +| Key | Text | +|-----|------| +| `backupRestoreStatusEnteringCli` | Entering CLI | +| `backupRestoreStatusReadingConfig` | Reading configuration via CLI | +| `backupRestoreStatusSavingFile` | Saving backup file... | +| `backupRestoreStatusExitingCli` | Exiting CLI mode | +| `backupRestoreBackupSaved` | Backup saved $1 | +| `backupRestoreAutoBackupSaved` | Auto-backup saved to $1 | +| `backupRestoreBackupComplete` | Backup complete | +| `backupRestoreBackupCancelled` | Backup cancelled | +| `backupRestoreBackupFailed` | Backup failed | + +### Restore status +| Key | Text | +|-----|------| +| `backupRestoreStatusConnecting` | Connecting to flight controller | +| `backupRestoreStatusRestoringConfig` | Restoring configuration | +| `backupRestoreStatusRestoringProgress` | Restoring... $1 / $2 | +| `backupRestoreStatusSaving` | Saving configuration | +| `backupRestoreRestoreComplete` | Configuration restored. Flight controller is rebooting. | +| `backupRestoreRestoreCancelled` | Restore cancelled. | +| `backupRestoreRestoreFailed` | Restore failed. | + +### Auto-restore UI +| Key | Text | +|-----|------| +| `backupRestoreAutoRestoreConfirm` | Restore confirmation prompt | +| `backupRestoreAutoRestoreWaiting` | Waiting for FC to reboot after flash | +| `backupRestoreAutoRestoreYes` | Yes, restore settings | +| `backupRestoreAutoRestoreNo` | No, keep current settings | +| `backupRestoreAutoRestoreWaitingPort` | Waiting for port $1 to reconnect | +| `backupRestoreDowngradeNoAutoRestore` | Major downgrade warning | +| `backupRestoreFlashCompleteBackupSaved` | Backup saved (local firmware, no restore offer) | +| `backupRestoreMigrationApplied` | Migration applied: $1 → $2 ($3 changes) | +| `backupRestoreMigrationWarningsHeader` | Migration Warnings: | + +### Migration preview +| Key | Text | +|-----|------| +| `migrationPreviewTitle` | Settings Migration Required | +| `migrationPreviewSubtitle` | Conversion explanation | +| `migrationPreviewRemovedHeader` | Removed Settings: | +| `migrationPreviewRenamedSettingsHeader` | Renamed Settings: | +| `migrationPreviewRenamedCommandsHeader` | Renamed Commands: | +| `migrationPreviewValueReplacementsHeader` | Value Replacements: | +| `migrationPreviewSettingRemappingsHeader` | Setting Remappings: | +| `migrationPreviewContinue` | Continue with migration | +| `migrationPreviewCancel` | Cancel restore | +| `migrationMissingProfileWarning` | Missing profile warning | + +### Error messages +| Key | Text | +|-----|------| +| `backupRestoreErrorTitle` | Restore Errors Detected | +| `backupRestoreErrorText` | Error explanation | +| `backupRestoreErrorAbort` | Abort | +| `backupRestoreErrorSave` | Save anyway | From ea2c1f12c9e2c5aed4b8461d04650e4e4bb0b925 Mon Sep 17 00:00:00 2001 From: b14ckyy Date: Sat, 11 Apr 2026 16:04:00 +0200 Subject: [PATCH 3/4] docs: add migration profile reminder to release checklist Reference Backup Restore Architecture doc in pre-release checklist and breaking changes branch usage section to ensure migration profiles are created when major versions introduce settings changes. --- docs/development/release-create.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/development/release-create.md b/docs/development/release-create.md index 16dccb6292d..f1ba7cf2369 100644 --- a/docs/development/release-create.md +++ b/docs/development/release-create.md @@ -109,6 +109,7 @@ Version numbers are set in: - [ ] Release notes drafted - [ ] Breaking changes documented - [ ] New features documented +- [ ] **Configurator migration profile created** for major version bumps (see [Backup Restore Architecture](Backup%20Restore%20Architecture.md#adding-a-new-migration-profile)) ## Release Workflow @@ -492,6 +493,7 @@ gh api repos/iNavFlight/inav-configurator/git/refs -f ref="refs/heads/maintenanc - **Changes maintaining backward compatibility** → PR to maintenance-X.x (e.g., maintenance-9.x) - **Breaking changes** (MSP protocol, settings structure) → PR to maintenance-(X+1).x (e.g., maintenance-10.x) + - When breaking changes affect CLI settings (renames, removals, value changes), a **Configurator migration profile** must be created. See [Backup Restore Architecture](Backup%20Restore%20Architecture.md#adding-a-new-migration-profile) - **Master** → NOT a PR target (receives merges only) Lower version branches are periodically merged into higher version branches (e.g., maintenance-9.x → master → maintenance-10.x). From 392d21b2c3efaec22bd846fba1667346ea0d645c Mon Sep 17 00:00:00 2001 From: b14ckyy Date: Sat, 11 Apr 2026 16:14:35 +0200 Subject: [PATCH 4/4] clearer wording for backup and restore doc --- docs/Backup and Restore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Backup and Restore.md b/docs/Backup and Restore.md index 9206abafa03..771b129762d 100644 --- a/docs/Backup and Restore.md +++ b/docs/Backup and Restore.md @@ -8,8 +8,8 @@ For manual CLI-based backup and restore, see the [CLI documentation](Cli.md#back ### What happens automatically -1. **Before flashing** (with Full Chip Erase enabled): Your current CLI configuration (`diff all`) is automatically captured and saved to the backup directory. -2. **After flashing**: Depending on the situation, the Configurator offers to restore your settings: +1. **Before flashing** (with or without Full Chip Erase enabled): Your current CLI configuration (`diff all`) is automatically captured and saved to the backup directory. +2. **After flashing**: Depending on the situation, the Configurator offers to restore your settings if Full Chip Erase was enabled: | Scenario | Behavior | |----------|----------|