ADR-001 - Backups, Firmware Fingerprint and Progress Semantics
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.
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.
Información técnica del documento
- Ruta lógica
- adr/ADR-001-backup-fingerprint-and-progress.md
- Commit Git
a83cef9e1ee0c5b0b22662fe3493139d77c23570- SHA-256
3c93960e28367a0132b9904d98e42f414d71b2a2bb82f36e90ef87154aec53f1- Regeneración
scripts/build-documentation.sh