---
id: historical-operations
title: Operación acumulada histórica
category: operations
version: 1.0
status: historical
updated_at: 2026-07-14
---

# ESP Platform Operations

Service commands:

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

Nginx commands:

```bash
sudo nginx -t
sudo systemctl reload nginx
```

PostgreSQL check:

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

Firmware storage:

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

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

Then use Chrome or Edge at:

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

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

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

The backend service has explicit systemd write access to:

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

Useful checks:

```bash
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.