ADR-001 - Backups, Firmware Fingerprint and Progress Semantics
Date: 2026-07-14
Status
Accepted.
Context
ESP Platform backups can capture a complete ESP32 flash image. A complete device dump is useful for restoration, but it includes mutable and sensitive state such as NVS, OTA metadata and coredump. Therefore, the SHA-256 of a complete dump can change even when the installed firmware has not changed.
The UI also performs flash operations in chunks. A single progress bar tied to the current chunk is misleading because it reaches 100% and then restarts for the next chunk.
Decision
ESP Platform keeps two separate hashes for backups:
- Device Backup SHA-256: SHA-256 of the full captured flash image.
- Firmware Fingerprint SHA-256: SHA-256 over reusable firmware regions only, concatenated in flash offset order.
The firmware fingerprint excludes by default:
- NVS;
- OTA data;
- coredump;
- NVS keys;
- regions classified as Sensitive, Device state or Diagnostic.
The firmware fingerprint includes by default:
- bootloader;
- partition table;
- application partitions;
- reusable filesystem partitions, with warning that filesystems can still contain private data.
Backup UI progress uses two bars:
- Total progress: the full operation, monotonic and never reset during one operation.
- Current step: the active block, region, upload chunk or segment.
Consequences
A full backup can differ because NVS changed while the firmware fingerprint still matches. This allows ESP Platform to detect exact firmware equivalence even when device-specific state changes.
Restore and Import are intentionally outside this ADR's implementation scope. The same progress model must be reused when those features are implemented.
Validation
Physical validation on 2026-07-14 confirmed the decision. A complete 4 MB local dump was read through Web Serial over HTTPS, with monotonic total progress and per-block current-step progress. The resulting local dump had SHA-256 "a9ea663ba7afc32f90e73bf25d4e535aeeb182e9285ec5e7c974e4cc67d58600" and exact size "4,194,304" bytes.
The persisted server backup has Device Backup SHA-256 "ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a". The difference is accepted because mutable NVS/device state can change independently of reusable firmware. The persisted Firmware Fingerprint SHA-256 is "4ee0ccd14c1d85ed814cfe8067e6834bec7081a1bf5005768a087cd2e8e6283f", with fingerprint size "4,096,000" bytes.
A real "app0" partition read was also validated: offset "0x10000", size "1,310,720" bytes, SHA-256 "d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948". Manual device validation confirmed that the ESP32 resets and boots normally after read-only operations.
This ADR is therefore validated for Backups Stage 1 and the approved Backups Stage 2 package/fingerprint base. Restore and Import remain separate future decisions and are not implemented by this ADR.