---
id: historical-backups-stage1
title: Diseño histórico Backups Etapa 1
category: backups
version: 1.0
status: historical
updated_at: 2026-07-14
---

# 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:

```text
/srv/esp-platform/backups/tmp
```

Flow:

1. Create temporary capture session.
2. Read flash blocks through Web Serial.
3. Upload each block to the backend.
4. Verify received size.
5. Calculate SHA-256 in the backend.
6. Show a summary.
7. 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:

```text
/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:

```text
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:

```text
/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.