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:
1. Validate a saved backup or uploaded "esp-platform-backup.zip" before connecting restore intent.
2. Connect the target ESP32 and review compatibility.
3. Keep baudrate at "115200" unless deliberately testing advanced speeds.
4. Leave "Create safety backup before restore" enabled for devices with unknown or valuable state.
5. Use complete restore only when overwriting the full device is intended.
6. Use selective restore for app/filesystem repair when NVS must be preserved.
7. Never select NVS by default; select it only after accepting the identity/credential warning.
8. Type "RESTORE" only after reviewing summary and target device.
9. If cancellation happens during writing, treat the target as potentially incomplete and recover with complete restore.
10. 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.