ESP Platform Operations

Service commands:

sudo systemctl status esp-platform-backend
sudo systemctl restart esp-platform-backend
sudo journalctl -u esp-platform-backend -f

Nginx commands:

sudo nginx -t
sudo systemctl reload nginx

PostgreSQL check:

sudo -u postgres psql -d esp_platform -c 'select count(*) from firmware;'

Firmware storage:

/srv/esp-platform/firmware

The .bin files are stored in the filesystem. They are not stored as PostgreSQL BLOBs.

Temporary Flasher Access For Web Serial

For Phase 2 testing without HTTPS, open a local SSH tunnel from the Mac:

ssh -N -L 18888:127.0.0.1:88 codex@192.168.1.62

Then use Chrome or Edge at:

http://localhost:18888/flasher

Direct HTTP access by IP address is useful for viewing the page, but browsers can block Web Serial there because it is not a secure context.

Firmware Artifact Library

Firmware binaries are stored as independent artifacts in:

/srv/esp-platform/artifacts

Operational rules:

Uploading a .bin calculates SHA-256 first and reuses an existing artifact when the checksum already exists.
firmware records describe catalog entries.
firmware_segment records link firmwares to artifacts and preserve offsets for multipart packages.
firmware_part is no longer part of the active schema; it was removed after migration to firmware_segment.
Deleting a firmware deletes only its record and segment relations.
Physical artifact files are deleted only by orphan cleanup after no firmware segment references them.
The admin page exposes Clean orphan artifacts for explicit cleanup.
The clone action creates a new firmware record sharing the same artifacts as the source; deleting the source does not affect the clone.

Validation command:

cd /opt/esp-platform/repo
scripts/validate-artifact-library.sh

Backups Stage 1

Open:

https://iot.aeizoon.com/backups

Stage 1 operations are read-only and browser-local:

Read complete flash downloads a full flash .bin and metadata JSON.
Read partitions parses the ESP-IDF partition table and downloads selected regions.

Backups may contain sensitive data. Do not publish or share them casually. Stage 1 does not store backups on the backend and does not create restore packages.

Later stages remain disabled until separately approved:

Create backup package;
Restore backup package;
Import firmware from connected ESP32.

Backups Storage and Operations

Backups are stored outside public web roots:

/srv/esp-platform/backups

The backend service has explicit systemd write access to:

/srv/esp-platform/backups

Useful checks:

sudo systemctl status esp-platform-backend
sudo journalctl -u esp-platform-backend -f
sudo -u postgres psql -d esp_platform -c 'select id, name, status, validation_status, source_mac, size_bytes from device_backup order by captured_at desc;'
sudo -u postgres psql -d esp_platform -c 'select event_type, backup_id, session_id, occurred_at from backup_audit_log order by occurred_at desc limit 20;'
sudo find /srv/esp-platform/backups -maxdepth 3 -type f -ls

Backups can contain credentials and private state. Do not copy, publish or expose files from /srv/esp-platform/backups without explicit approval.

Current implemented backup actions:

Create complete device backup to local computer.
Create complete device backup to ESP Platform server storage.
Analyze flash layout.
Download selected regions.
Create backup ZIP package from a saved server backup.
Download/delete generated ZIP package.
Delete saved server backup after confirmation.

Not implemented yet:

Restore backup package.
Import firmware from connected ESP32.

Backup Fingerprints

Backups expose two hashes:

Device Backup SHA-256: full flash image, including NVS and device state.
Firmware Fingerprint SHA-256: reusable firmware regions only.

The fingerprint excludes NVS, OTA data, coredump and regions classified as sensitive/device-state/diagnostic. It is the preferred value for comparing whether two devices run the same firmware while allowing NVS to change.

The backup list shows repository match count. A match means a fingerprint region SHA-256 exactly matches an artifact already present in the firmware artifact repository.

Restore Backup Package

Use https://iot.aeizoon.com/backups and the Restore backup package panel.

Operational rules:

Validate a saved backup or uploaded esp-platform-backup.zip before connecting restore intent.
Connect the target ESP32 and review compatibility.
Keep baudrate at 115200 unless deliberately testing advanced speeds.
Leave Create safety backup before restore enabled for devices with unknown or valuable state.
Use complete restore only when overwriting the full device is intended.
Use selective restore for app/filesystem repair when NVS must be preserved.
Never select NVS by default; select it only after accepting the identity/credential warning.
Type RESTORE only after reviewing summary and target device.
If cancellation happens during writing, treat the target as potentially incomplete and recover with complete restore.
Review backup_restore_session and backup_audit_log after validation runs.

Restore does not convert a backup into firmware. Firmware import remains a separate future function.