ESP Platform Backups - Stage 1 UX Review and Stage 2 Package Base

Date: 2026-07-12

Backups now supports read-only capture from the browser with two destinations:

Download to this computer.
Save in ESP Platform.

Restore and firmware import are still intentionally not implemented.

Navigation

Main navigation:

Firmware
Flasher
Diagnostics
Backups

Backups sections:

Create complete device backup
Analyze flash layout
Create backup package
Restore backup package (not implemented)
Import firmware from connected ESP32 (not implemented)

Analyze flash layout

The UI reads the ESP-IDF partition table from 0x8000 with size 0x1000 and adds conventional readable regions:

bootloader at 0x1000, size 0x7000.
partition-table at 0x8000, size 0x1000.

The partition table shows:

Select
Name
Type
Subtype
Offset
Size
Description
Classification
Flags

Descriptions and classifications:

| Region | Description | Classification | | --- | --- | --- | | bootloader | Device boot code. | Reusable | | partition-table | Flash layout definition. | Reusable | | nvs | Persistent configuration, credentials, tokens and device state. | Sensitive | | otadata | OTA partition selection and boot state. | Device state | | app0/app1/factory | Application image. | Reusable | | spiffs/littlefs/fat | Filesystem and resources. May contain credentials or private configuration. | Reusable with warning | | coredump | Last severe crash diagnostic data. | Diagnostic |

Safe defaults exclude:

NVS
OTA data
coredump
NVS keys

Sensitive or diagnostic regions can be selected manually after an explicit warning.

Create complete device backup

The complete device backup reads from offset 0x0 for the detected flash size.

Download to this computer

The browser downloads:

ESP32_<MAC>_full_<UTC timestamp>.bin
ESP32_<MAC>_full_<UTC timestamp>.metadata.json

The metadata includes chip, revision, MAC, flash ID, flash size, SHA-256, size, build and warnings.

Save in ESP Platform

The browser reads flash in blocks and uploads those blocks to the backend. The backend stores temporary data under:

/srv/esp-platform/backups/tmp

Flow:

Create temporary capture session.
Read flash blocks through Web Serial.
Upload each block to the backend.
Verify received size.
Calculate SHA-256 in the backend.
Show a summary.
User chooses Save backup or Discard.

If discarded, no backup record is created and temporary files are deleted.

If saved, the backup is stored under:

/srv/esp-platform/backups/device-backup-<capture-session-id>

The backup is recorded as DEVICE_DUMP, CAPTURED, UNVERIFIED and CONNECTED_DEVICE.

Backend model

Backup data is independent from firmware data.

Tables:

device_backup
backup_artifact
backup_region
backup_capture_session
backup_audit_log

Backups are not converted into firmware automatically.

Create backup package

Stage 2 package creation is implemented for saved server backups.

The ZIP contains:

manifest.json
full-flash.bin
checksums.sha256

If separate region files do not exist, regions/ is not invented.

The ZIP can be:

created from the saved backup row;
downloaded;
deleted without deleting the backup;
regenerated.

Restore remains disabled.

Cancellation

The Cancel operation button is available during:

complete flash read;
selected region read;
upload to backend.

Behavior:

cancellation is requested immediately;
no new flash reads are started;
active upload fetch is aborted when possible;
incomplete results are discarded;
partial server sessions are discarded;
the UI shows Operation cancelled — no valid backup was created.

Technical limitation: the current esptool-js readFlash call may not abort in the middle of a block already requested from the chip. ESP Platform reads in 64 KiB blocks so cancellation stops at the next block boundary when immediate abort is not available.

Security

Server backups are stored outside public web routes:

/srv/esp-platform/backups

Files may include credentials, certificates, MQTT tokens, SSIDs, NVS, filesystem data and device-specific state. They must not be published automatically.

The current MVP does not yet include a full authentication/authorization layer, so access control is inherited from the internal ESP Platform deployment boundary. Audit rows are recorded for capture session creation, verification, discard, backup creation, package creation, package deletion and backup deletion.

Validation status

Backend validation completed on 2026-07-12:

Created a temporary capture session.
Uploaded a chunk.
Verified size and SHA-256.
Saved a temporary backup record.
Created a ZIP package.
Verified ZIP contains manifest.json, full-flash.bin and checksums.sha256.
Deleted the temporary backup and confirmed filesystem cleanup.
Created and discarded a partial session and confirmed no partial file or backup record remained.

Physical validation still required:

Create a real complete ESP32 capture and save it in ESP Platform.
Cancel a real capture and confirm no partial data remains.
Download a local complete capture.
Verify real flash size and SHA-256.
Select NVS manually and confirm warning.
Save and discard a real temporary session.
Create and open a ZIP from a real backup.
Confirm the ESP32 is not modified by read operations.