# ESP Platform Documentation Product version: v0.1.0-flasher-backups Associated AEOS version: 0.7.0 Documentation revision: 1 Updated: 17/08/2026 13:42:31 CEST ## Contents - [getting-started-quick-start] Inicio rápido (getting-started) - [getting-started-introduction] Introducción a ESP Platform (getting-started) - [getting-started-requirements] Requisitos y compatibilidad (getting-started) - [user-guide-firmware-management] Gestión de firmware (user-guide) - [flasher-using-flasher] Flasher Web (flasher) - [backups-validation-20260714-progress-fingerprint] Backups Validation - Progress and Firmware Fingerprint (backups) - [backups-overview] Backups y Restore (backups) - [backups-create] Crear un backup de dispositivo (backups) - [historical-backups-stage1] Diseño histórico Backups Etapa 1 (backups) - [backups-package-format] Formato del paquete de backup (backups) - [backups-sensitive] Particiones sensibles (backups) - [backups-restore] Restaurar un backup (backups) - [backups-plan-compare-repository-and-import-device] Technical Plan - Compare with Repository and Import Firmware from Connected ESP32 (backups) - [validation-restore-backup-package] Validación de Restore backup package (backups) - [artifacts-library] Biblioteca de artefactos binarios (artifacts) - [historical-vm-status] Estado histórico de la VM (operations) - [historical-install] Instalación inicial histórica (operations) - [historical-operations] Operación acumulada histórica (operations) - [operations-platform-operations] Operación de la plataforma (operations) - [diagnostics-overview] Diagnostics (diagnostics) - [diagnostics-freepocket-nvs-diagnostics] FreePocket NVS Diagnostics (diagnostics) - [diagnostics-serial-commands] Monitor serie y comandos de desarrollo (diagnostics) - [architecture-overview] Arquitectura del sistema (architecture) - [architecture-components] Componentes del sistema (architecture) - [architecture-esp-platform-architecture-v1-0] Constitución de ESP Platform (architecture) - [architecture-database] Modelo de datos (architecture) - [architecture-filesystem] Rutas y almacenamiento (architecture) - [api-overview] API REST v1 (api) - [development-codex-live-session] Codex Live Session (development) - [development-repository] Desarrollo y releases (development) - [releases-v0-1-0-flasher-backups] ESP Platform v0.1.0 - Flasher and Backups (releases) - [release-documentation-1-0] Portal documental 1.0 (releases) - [reference-troubleshooting] Resolución de problemas (reference) - [reference-terminology] Terminología (reference) - [documentation-home] Documentación de ESP Platform (project) - [validation] ESP Platform Phase 1E Validation (project) - [phases-phase-1-infrastructure] Phase 1 - Infrastructure (phases) - [phases-phase-2-flasher-web] Phase 2 - Flasher Web (phases) - [validation-documentation-portal-20260714] Validación del portal documental 1.0 (validation) - [security-overview] Modelo de seguridad (security) - [security-web-serial] Seguridad de Web Serial (security) - [adr-adr-000-template] ADR-000 - Title (adr) - [adr-adr-001-backup-fingerprint-and-progress] ADR-001 - Backups, Firmware Fingerprint and Progress Semantics (adr) - [adr-002-documentation-source] ADR-002: Fuente documental y exportaciones (adr) --- Document ID: getting-started-quick-start # Inicio rápido ## Requisitos Use Chrome o Edge reciente sobre macOS, Windows o Linux, conecte el ESP32 por USB o adaptador USB-TTL y abra https://iot.aeizoon.com. Web Serial requiere HTTPS y no funciona de forma fiable en navegadores móviles. ## Primer flasheo 1. Abra Firmware y suba un archivo simple o un paquete multiparte. 2. Revise hardware, offsets y parámetros de flash. 3. Abra Flasher, seleccione el firmware y conecte el ESP32. 4. Mantenga 115200 baudios como valor predeterminado. 5. Autorice el puerto serie, inicie la escritura y espere la verificación y el reset. ## Primer backup 1. Abra Backups y conecte el dispositivo. 2. Elija Download to this computer o Save in ESP Platform. 3. Cree el dump completo. 4. Verifique tamaño y SHA-256. 5. Si se guarda en servidor, confirme la ficha y genere el ZIP cuando sea necesario. Los dumps pueden contener credenciales, certificados e identidad del equipo. No deben compartirse como si fueran firmware. --- Document ID: getting-started-introduction # Introducción a ESP Platform ESP Platform es el proyecto técnico independiente para dispositivos ESP32 del ecosistema Casa-Energy. Su primera entrega estable administra firmware, programa dispositivos por USB desde el navegador, inspecciona flash y crea o restaura copias completas. ## Alcance estable La versión actual incluye catálogo de firmware simple, paquetes multiparte, imágenes unificadas, biblioteca de artifacts, Web Serial, borrado y reset, monitor serie, diagnósticos, backups y restore. OTA, Provisioning, Fleet Management, Compare with repository, Import firmware from connected ESP32 y Aeizoon Edge OS no forman parte de esta versión. ## Principios El navegador controla físicamente el ESP32 mediante Web Serial. El backend conserva metadatos en PostgreSQL y archivos binarios fuera del árbol web público. El Markdown en Git documenta el sistema. Las operaciones destructivas requieren una intención explícita y dejan auditoría. ESP Platform tiene repositorio, identidad y ciclo de vida propios. Reutiliza la metodología operativa de Casa-Energy, pero no mezcla su código con Casa-Energy. --- Document ID: getting-started-requirements # Requisitos y compatibilidad ## Navegador y contexto seguro Web Serial está validado mediante HTTPS en iot.aeizoon.com. Chrome y Edge de escritorio son los navegadores admitidos. Safari y Firefox no ofrecen la API Web Serial necesaria. El puerto serie solo aparece después de una acción del usuario. ## Hardware La detección comprueba familia, revisión, MAC, flash ID y tamaño real. La versión se ha validado físicamente con ESP32-D0WD rev 1 y flash de 4 MB. Las familias ESP32-S2, S3, C3, C6 y otras deben tratarse como distintas para restauración. ## Conexión El valor estable es 115200 baudios. Las velocidades superiores son opciones avanzadas y dependen del adaptador, cableado y placa. Para USB-TTL pueden ser necesarios BOOT, EN y control manual del modo de descarga. ## Servidor La aplicación requiere Debian 12, Java 17, PostgreSQL, Nginx, systemd y almacenamiento local con permisos mínimos. No usa Docker. --- Document ID: user-guide-firmware-management # Gestión de firmware Firmware es una ficha distribuible. Artifact es un binario inmutable identificado por SHA-256. Firmware segment relaciona ambos y conserva nombre, orden y offset. ## Firmware simple Un único archivo binario se registra con sus metadatos, tamaño y checksum. Puede descargarse y flashearse en la dirección configurada. Una imagen merged se comporta como firmware simple autónomo y se graba en 0x0. ## Paquete multiparte Un paquete conserva chip, modo, frecuencia, tamaño de flash y segmentos con offsets. Antes de usarlo se validan rangos, solapamientos y archivos. Cada parte puede descargarse o sustituirse desde la ficha. ## Imagen unificada Generar imagen unificada ejecuta esptool merge-bin en el backend. La imagen resultante puede publicarse como una ficha autónoma con trazabilidad descriptiva, descargarse y flashearse en 0x0. No sustituye al paquete multiparte original. ## Clonado, bloqueo y edición Clonar crea una ficha nueva que comparte artifacts por SHA-256. Bloquear impide su selección operativa sin borrar datos. Editar permite cambiar metadatos y segmentos. Sustituir un segmento crea o reutiliza el artifact correspondiente. ## Eliminación segura Eliminar firmware borra la ficha y relaciones. Nunca elimina directamente un artifact compartido. La limpieza física solo elimina artifacts huérfanos mediante una acción controlada. --- Document ID: flasher-using-flasher # Flasher Web ## Flujo Seleccione firmware, conecte el ESP32, autorice el puerto, descargue los binarios y comience la escritura. La interfaz muestra progreso global continuo y progreso parcial de la región o bloque actual. El log técnico conserva detección de chip, flash ID, tamaño, offsets y resultado. ## Parámetros 115200 es la velocidad predeterminada. Flash mode define el bus, Flash frequency expresa MHz y Flash size puede conservar el encabezado o usar el tamaño detectado. Los paquetes multiparte aportan sus propios offsets. Las imágenes merged siempre se escriben desde 0x0. ## Acciones Erase ESP32 borra la flash completa y deja el dispositivo sin firmware. Hardware Reset solicita un pulso por RTS; el mensaje confirma que se solicitó, no garantiza por sí solo el arranque. Serial Monitor libera la sesión de esptool y abre el puerto para observar el boot. ## Cancelación y errores La cancelación detiene nuevos bloques cuando la librería lo permite. Un dispositivo cancelado durante escritura puede no arrancar. Los errores distinguen contexto inseguro, navegador incompatible, permiso denegado, desconexión, descarga fallida, incompatibilidad de tamaño y fallo de escritura. ## Limitaciones Web Serial requiere interacción del usuario y acceso físico. El navegador no puede prometer control RTS/DTR idéntico con todos los adaptadores. Secure Boot, Flash Encryption y eFuses pueden impedir reutilizar imágenes en otro chip. --- Document ID: backups-validation-20260714-progress-fingerprint # Backups Validation - Progress and Firmware Fingerprint Date: 2026-07-14 Status: approved ## Scope This validation closes the Backups Stage 1 UX revision and the Backups Stage 2 package/fingerprint base that were implemented before Restore or Import. It covers read-only operations only. Not included: - Restore backup package - Import firmware from connected ESP32 - OTA - Provisioning - Fleet Management - Edge OS ## Device - Chip: ESP32-D0WD revision 1 - MAC: `2c:bc:bb:75:f2:74` - Flash ID: `16405e` - Flash size: 4 MB / `4,194,304` bytes - Connection: Web Serial over HTTPS - Baudrate: `115200` ## Complete Flash Read Result: passed. - Operation: local complete device backup download - Size: `4,194,304` bytes - SHA-256: `a9ea663ba7afc32f90e73bf25d4e535aeeb182e9285ec5e7c974e4cc67d58600` - UI global progress: monotonic from start to completion - UI partial progress: reset by block with block labels - Final state: `Completed` The SHA-256 differs from the existing server backup SHA-256 `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`. This is expected when mutable NVS/device state changes between captures. The firmware fingerprint exists to compare reusable firmware regions independently from device-specific state. ## Partition Read Result: passed. - Partition: `app0` - Offset: `0x10000` - Size: `1,310,720` bytes / `0x140000` - SHA-256: `d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948` - Matches persisted backup region SHA-256: yes ## Firmware Fingerprint Result: passed. Current persisted backup values: - Device Backup SHA-256: `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a` - Firmware Fingerprint SHA-256: `4ee0ccd14c1d85ed814cfe8067e6834bec7081a1bf5005768a087cd2e8e6283f` - Firmware Fingerprint size: `4,096,000` bytes - Repository matches: `1` Included in the firmware fingerprint: - bootloader - partition table - app partitions - reusable filesystem partitions Excluded by default: - NVS - OTA data - coredump - device-state regions - diagnostic regions - sensitive regions ## Metadata JSON Result: passed. Local single-file capture metadata now exposes top-level: - `sha256` - `sizeBytes` The existing `files[]` array remains present for detailed file-level metadata. ## Device Integrity Result: passed. Manual physical validation confirmed: - ESP32 resets correctly. - Firmware boots normally. - Complete flash read did not modify flash contents. - Partition read/download did not modify flash contents. ## Decision Backups Stage 1 read-only operations and Backups Stage 2 package/fingerprint base remain approved. The project may proceed to planning Compare with repository and Import firmware from connected ESP32. Restore backup package is still explicitly out of scope. --- Document ID: backups-overview # Backups y Restore Un backup conserva el estado de un dispositivo; un firmware distribuye software reutilizable. Nunca se convierten automáticamente uno en otro. ## Captura Create complete device backup lee desde 0x0 hasta el tamaño detectado. Analyze flash layout interpreta la tabla de particiones. Las regiones seleccionadas se descargan con offset y metadata. Todas estas operaciones son de solo lectura. ## Destinos Download to this computer mantiene el dump en el equipo del usuario. Save in ESP Platform transmite bloques al backend, usa un área temporal fuera de rutas públicas y solo crea la ficha tras verificación y confirmación. ## Restore Restore valida paquete, checksums, chip, tamaño, offsets y compatibilidad antes de habilitar escritura. Puede escribir la imagen completa o regiones seleccionadas. Safety backup es recomendado y NVS nunca se selecciona por defecto. Los backups de servidor requieren acceso administrativo y auditoría. Pueden contener información personal y secretos del dispositivo. --- Document ID: backups-create # Crear un backup de dispositivo ## Lectura completa Tras conectar, la aplicación detecta chip, revisión, MAC, flash ID y tamaño real. Lee la flash por bloques, actualiza dos barras de progreso y calcula SHA-256. Un dispositivo de 4 MB debe producir exactamente 4.194.304 bytes. ## Guardado local Se descargan el archivo ESP32_MAC_full_TIMESTAMP.bin y su metadata JSON. El hash del dump identifica el estado completo, incluida configuración cambiante. ## Guardado en servidor El navegador crea una sesión temporal y sube cada bloque leído. El backend comprueba continuidad, tamaño y SHA-256. El usuario puede guardar la ficha o descartar. Descartar y cancelar eliminan temporales y no crean backup válido. ## Fingerprint Device Backup SHA-256 corresponde al dump completo. Firmware Fingerprint usa regiones reutilizables y excluye NVS, OTA data, coredump y clasificaciones sensibles. Dos dispositivos pueden compartir firmware fingerprint aunque su dump completo sea distinto. La cancelación se atiende al límite técnico del bloque actual. Una pérdida de conexión invalida la captura incompleta. Las sesiones tienen expiración y limpieza de temporales abandonados. --- Document ID: historical-backups-stage1 # ESP Platform Backups - Stage 1 UX Review and Stage 2 Package Base Date: 2026-07-12 Backups now supports read-only capture from the browser with two destinations: - Download to this computer. - Save in ESP Platform. Restore and firmware import are still intentionally not implemented. ## Navigation Main navigation: - Firmware - Flasher - Diagnostics - Backups Backups sections: - Create complete device backup - Analyze flash layout - Create backup package - Restore backup package (not implemented) - Import firmware from connected ESP32 (not implemented) ## Analyze flash layout The UI reads the ESP-IDF partition table from `0x8000` with size `0x1000` and adds conventional readable regions: - `bootloader` at `0x1000`, size `0x7000`. - `partition-table` at `0x8000`, size `0x1000`. The partition table shows: - Select - Name - Type - Subtype - Offset - Size - Description - Classification - Flags Descriptions and classifications: | Region | Description | Classification | | --- | --- | --- | | bootloader | Device boot code. | Reusable | | partition-table | Flash layout definition. | Reusable | | nvs | Persistent configuration, credentials, tokens and device state. | Sensitive | | otadata | OTA partition selection and boot state. | Device state | | app0/app1/factory | Application image. | Reusable | | spiffs/littlefs/fat | Filesystem and resources. May contain credentials or private configuration. | Reusable with warning | | coredump | Last severe crash diagnostic data. | Diagnostic | Safe defaults exclude: - NVS - OTA data - coredump - NVS keys Sensitive or diagnostic regions can be selected manually after an explicit warning. ## Create complete device backup The complete device backup reads from offset `0x0` for the detected flash size. ### Download to this computer The browser downloads: - `ESP32__full_.bin` - `ESP32__full_.metadata.json` The metadata includes chip, revision, MAC, flash ID, flash size, SHA-256, size, build and warnings. ### Save in ESP Platform The browser reads flash in blocks and uploads those blocks to the backend. The backend stores temporary data under: ```text /srv/esp-platform/backups/tmp ``` Flow: 1. Create temporary capture session. 2. Read flash blocks through Web Serial. 3. Upload each block to the backend. 4. Verify received size. 5. Calculate SHA-256 in the backend. 6. Show a summary. 7. User chooses `Save backup` or `Discard`. If discarded, no backup record is created and temporary files are deleted. If saved, the backup is stored under: ```text /srv/esp-platform/backups/device-backup- ``` The backup is recorded as `DEVICE_DUMP`, `CAPTURED`, `UNVERIFIED` and `CONNECTED_DEVICE`. ## Backend model Backup data is independent from firmware data. Tables: - `device_backup` - `backup_artifact` - `backup_region` - `backup_capture_session` - `backup_audit_log` Backups are not converted into firmware automatically. ## Create backup package Stage 2 package creation is implemented for saved server backups. The ZIP contains: ```text manifest.json full-flash.bin checksums.sha256 ``` If separate region files do not exist, `regions/` is not invented. The ZIP can be: - created from the saved backup row; - downloaded; - deleted without deleting the backup; - regenerated. Restore remains disabled. ## Cancellation The `Cancel operation` button is available during: - complete flash read; - selected region read; - upload to backend. Behavior: - cancellation is requested immediately; - no new flash reads are started; - active upload fetch is aborted when possible; - incomplete results are discarded; - partial server sessions are discarded; - the UI shows `Operation cancelled — no valid backup was created`. Technical limitation: the current esptool-js `readFlash` call may not abort in the middle of a block already requested from the chip. ESP Platform reads in 64 KiB blocks so cancellation stops at the next block boundary when immediate abort is not available. ## Security Server backups are stored outside public web routes: ```text /srv/esp-platform/backups ``` Files may include credentials, certificates, MQTT tokens, SSIDs, NVS, filesystem data and device-specific state. They must not be published automatically. The current MVP does not yet include a full authentication/authorization layer, so access control is inherited from the internal ESP Platform deployment boundary. Audit rows are recorded for capture session creation, verification, discard, backup creation, package creation, package deletion and backup deletion. ## Validation status Backend validation completed on 2026-07-12: - Created a temporary capture session. - Uploaded a chunk. - Verified size and SHA-256. - Saved a temporary backup record. - Created a ZIP package. - Verified ZIP contains `manifest.json`, `full-flash.bin` and `checksums.sha256`. - Deleted the temporary backup and confirmed filesystem cleanup. - Created and discarded a partial session and confirmed no partial file or backup record remained. Physical validation still required: - Create a real complete ESP32 capture and save it in ESP Platform. - Cancel a real capture and confirm no partial data remains. - Download a local complete capture. - Verify real flash size and SHA-256. - Select NVS manually and confirm warning. - Save and discard a real temporary session. - Create and open a ZIP from a real backup. - Confirm the ESP32 is not modified by read operations. --- Document ID: backups-package-format # Formato del paquete de backup El paquete esp-platform-backup.zip es restaurable y verificable. ## Contenido - manifest.json describe formato, chip, MAC origen, flash ID, tamaño, regiones, offsets, sensibilidad, herramienta y fecha. - full-flash.bin contiene el dump completo cuando fue capturado. - regions contiene únicamente regiones realmente incluidas. - checksums.sha256 protege cada archivo del paquete. No se inventan particiones separadas si no fueron capturadas. El manifiesto indica versión de formato y compatibilidad conocida. ## Validación Antes de restaurar se comprueban estructura ZIP, nombres seguros, presencia de manifiesto, checksums, tamaños, offsets, solapamientos y límites de flash. Un archivo ausente, hash incorrecto o región fuera de rango invalida el paquete antes de conectar una escritura. Los ZIP se almacenan fuera de rutas web públicas y se descargan mediante un endpoint controlado. Eliminar el ZIP no borra automáticamente la ficha ni el dump original. --- Document ID: backups-sensitive # Particiones sensibles ## Clasificación - bootloader y partition-table: reutilizables cuando chip y layout coinciden. - app0 y app1: imágenes de aplicación reutilizables. - SPIFFS o LittleFS: reutilizables con advertencia; pueden contener credenciales. - NVS: sensible y ligada al dispositivo. - OTA data: estado del dispositivo. - coredump: solo diagnóstico. Safe defaults excluye NVS, OTA data y coredump. La selección manual muestra una advertencia explícita. ## NVS NVS puede contener SSID, credenciales Wi-Fi, tokens, certificados, calibración, activación e identidad. Restaurarla en otro ESP32 puede duplicar identidad, producir conflictos o fallar por dependencia de MAC o eFuse. ## Protección de hardware Un dump de flash no contiene eFuses. Secure Boot y Flash Encryption pueden ligar imágenes a una clave o chip. La plataforma muestra indicios cuando puede detectarlos, bloquea familias incompatibles y no promete clonación completa de dispositivos protegidos. --- Document ID: backups-restore # Restaurar un backup ## Preparación Seleccione un backup guardado o suba un ZIP. La plataforma valida el paquete por completo. Después conecte el destino y revise familia, revisión, flash ID, tamaño y reporte de compatibilidad. ## Restore completo Escribe full-flash.bin desde 0x0. Erase flash before restore está activado por defecto. Sobrescribe bootloader, tabla, aplicaciones, filesystem, NVS, OTA data, coredump y configuración. Es obligatorio escribir RESTORE antes de ejecutar. ## Restore selectivo Seleccione regiones concretas. Los valores seguros incluyen bootloader, partition table, aplicación y filesystem. NVS, OTA data, coredump y regiones sensibles quedan excluidas por defecto. No se borra toda la flash. ## Safety backup Create safety backup before restore lee y verifica la flash actual antes de escribir. Se recomienda para equipos con estado útil. No es un rollback automático: si la restauración se cancela, el usuario debe iniciar una recuperación válida. ## Escritura y verificación La interfaz muestra estados Validating, Connecting, Erasing, Writing, Verifying, Resetting y Completed. Cuando es viable, relee las regiones escritas y compara SHA-256. El reset RTS se solicita al final. Cancelar durante escritura marca la sesión incompleta, libera el puerto, registra auditoría y advierte que el dispositivo puede no arrancar. --- Document ID: backups-plan-compare-repository-and-import-device # Technical Plan - Compare with Repository and Import Firmware from Connected ESP32 Date: 2026-07-14 Status: proposed, not implemented ## Scope This plan covers two approved future capabilities: 1. Compare with repository. 2. Import firmware from connected ESP32. Explicitly out of scope: - Restore backup package. - OTA. - Provisioning. - Fleet Management. - Edge OS. ## Existing Model The current implementation already provides the required foundation: - `firmware`: firmware catalog entry. - `firmware_segment`: ordered segment relation for multipart firmware. - `artifact`: binary artifact library identified by SHA-256. - `device_backup`: backup entity separated from firmware. - `backup_region`: detected/read flash regions associated with a backup. - `backup_artifact`: full dump and ZIP artifacts for backups. Important rule: backup and firmware remain different concepts. A backup is a restorable device-state copy and may contain sensitive or device-specific state. Imported firmware is a reusable catalog item and excludes sensitive/device-specific regions by default. ## Part A - Compare with Repository ### Goal Compare a captured backup, local partition read, or connected-device layout against the firmware repository using reusable region hashes, not only full dump hash. The comparison must detect exact reusable-firmware matches even when NVS, OTA data, coredump or other mutable state differs. ### Matching Levels Implement explicit match levels: - `FULL_DUMP_MATCH`: complete backup SHA-256 matches a stored artifact or backup. - `FIRMWARE_FINGERPRINT_MATCH`: reusable-region fingerprint matches a known firmware or backup fingerprint. - `REGION_EXACT_MATCH`: one region SHA-256 matches an artifact. - `SEGMENT_LAYOUT_MATCH`: offsets, sizes and segment names match a firmware layout, even if one or more hashes differ. - `NO_MATCH`: no useful match found. ### Data Model Additions Add a small persistent comparison model only if needed for audit/history. Minimum proposal: - `repository_compare_result` - `id` - `source_type`: `BACKUP`, `CONNECTED_DEVICE`, `LOCAL_REGIONS` - `source_id`: nullable for browser-only previews - `firmware_fingerprint_sha256` - `match_level` - `best_firmware_id` - `best_backup_id` - `matched_region_count` - `total_reusable_region_count` - `created_at` - `result_json` For MVP, comparison can be computed on demand and returned by API without persistence. Persist only if it helps audit and user workflow. ### Backend API Add read-only API endpoints: - `GET /api/v1/backups/{id}/compare-repository` - Computes comparison for a saved backup. - Uses existing `backup_region.sha256` and `firmware_fingerprint_sha256`. - `POST /api/v1/repository/compare-regions` - Accepts a list of regions from the browser or an import preview. - Fields: name, type, subtype, offset, size, classification, sha256. - Returns match summary and per-region matches. Optional later endpoint: - `GET /api/v1/firmware/{id}/fingerprint` - Returns firmware fingerprint computed from its reusable segments. ### Backend Logic Create a service such as `RepositoryCompareService`. Steps: 1. Normalize region names and subtypes. 2. Exclude non-reusable regions by default: - NVS - OTA data - coredump - NVS keys - Sensitive - Device state - Diagnostic 3. Sort reusable regions by `offset_address`. 4. Compare each region SHA-256 against `artifact.checksum_sha256`. 5. Join artifact matches back to `firmware_segment` and `firmware`. 6. Count matches per firmware. 7. Compute or reuse firmware fingerprint for known firmware entries. 8. Return: - best candidate firmware; - matched regions; - missing regions; - differing regions; - sensitive regions ignored; - confidence label. ### Firmware Fingerprints for Repository Entries Current firmware catalog does not yet store a normalized reusable fingerprint. Add one of these approaches: Preferred MVP: - Add nullable columns to `firmware`: - `firmware_fingerprint_sha256` - `firmware_fingerprint_size_bytes` - `firmware_fingerprint_regions_json` - Compute it for multipart firmware by concatenating included segment artifacts in offset order. - For simple/merged firmware, use the whole artifact as a single reusable region at its flash address unless metadata states otherwise. Alternative: - Keep computed values transient and avoid migration until Import proves the format. This is simpler but slower and less inspectable. Recommended: persist fingerprint columns because backups already persist their fingerprint and UI comparison becomes clearer. ### UI Add Compare with repository controls in Backups: - On each saved backup row: `Compare with repository`. - In flash layout/import preview: `Compare selected regions`. Result panel: - Best match. - Match level badge. - Firmware name/version/application/hardware. - Reusable regions matched versus total. - Ignored sensitive regions. - Table: - Region - Offset - Size - SHA-256 - Repository match - Firmware candidates - Classification ### Validation 1. Compare existing backup #2. 2. Confirm `app0` matches the known artifact SHA-256. 3. Confirm firmware fingerprint remains stable when full dump SHA changes due to NVS. 4. Confirm NVS is reported as ignored/sensitive, not as a firmware mismatch. 5. Confirm at least one repository match is displayed. 6. Confirm no write operation is performed on ESP32. ## Part B - Import Firmware from Connected ESP32 ### Goal Read a connected ESP32 and create a reusable firmware catalog entry from selected non-sensitive regions. Default behavior must avoid importing device-specific or private data. ### Import Flow 1. User opens Backups > Import firmware from connected ESP32. 2. Connect ESP32 via Web Serial over HTTPS. 3. Detect chip, revision, MAC, flash ID and flash size. 4. Analyze flash layout. 5. Display regions with classifications. 6. Select safe defaults: - bootloader: included. - partition table: included. - active application: included. - reusable filesystem: included with warning. - NVS: excluded. - OTA data: excluded. - coredump: excluded. 7. Optional advanced selection with explicit warning for sensitive regions. 8. Read selected regions in browser using existing chunked reader and dual progress model. 9. Upload selected regions to backend as a temporary import session. 10. Backend computes SHA-256 for every uploaded region. 11. Backend compares with artifact library and reuses existing artifacts by SHA-256. 12. UI shows import preview. 13. User enters metadata: - name; - version; - application; - hardware compatible; - description; - origin; - tags; - notes. 14. User confirms `Create firmware`. 15. Backend creates `firmware` and `firmware_segment` rows linked to `artifact` rows. 16. Firmware is marked: - source: `CONNECTED_DEVICE`. - status/validation: `UNVERIFIED`. 17. User can edit, download and flash it like other multipart firmware. ### Import Session Model Add temporary model independent from saved backups: - `firmware_import_session` - `id` - `status`: `CREATED`, `UPLOADING`, `READY_FOR_PREVIEW`, `COMPLETED`, `DISCARDED`, `FAILED` - `chip` - `chip_revision` - `source_mac` - `flash_id` - `flash_size_bytes` - `created_at` - `expires_at` - `metadata_json` - `error_message` - `firmware_import_region` - `id` - `session_id` - `name` - `type` - `subtype` - `offset_address` - `size_bytes` - `flags` - `classification` - `included` - `sha256` - `temporary_path` - `artifact_id`, nullable until finalized Use filesystem temporary storage outside public web paths, for example: - `/srv/esp-platform/imports/tmp//` Final artifacts stay in the existing artifact library location managed by `FirmwareService`/artifact storage rules. ### Backend API Add endpoints under `/api/v1/firmware-imports`: - `POST /api/v1/firmware-imports/sessions` - Creates a temporary import session. - `PUT /api/v1/firmware-imports/sessions/{id}/regions/{regionIndex}` - Uploads one selected region. - Includes offset, size, name, subtype, classification and checksum if browser already calculated it. - `POST /api/v1/firmware-imports/sessions/{id}/verify` - Verifies file sizes, SHA-256 and region metadata. - Checks overlaps and flash bounds. - Reuses artifacts by SHA-256 when possible. - `GET /api/v1/firmware-imports/sessions/{id}/preview` - Returns import preview and repository comparison. - `POST /api/v1/firmware-imports/sessions/{id}/complete` - Creates firmware and firmware_segment rows. - Moves or links artifacts. - `POST /api/v1/firmware-imports/sessions/{id}/discard` - Removes temporary files. ### Artifact Rules Follow the already approved artifact-library rules: 1. Every imported region is hashed with SHA-256. 2. If SHA-256 exists in `artifact`, reuse it. 3. If not, store a new artifact. 4. A `firmware_segment` references an `artifact`. 5. Deleting imported firmware must not delete shared artifacts. 6. Artifact physical cleanup remains an orphan-cleanup operation, not part of firmware deletion. ### Segment Naming Recommended names: - `bootloader` - `partition-table` - `app0` - `app1` - `spiffs` - `littlefs` - `filesystem` Preserve original partition names where possible. Store offsets exactly as detected. ### Active App Selection For MVP, include app partitions selected by the user. Do not attempt to infer active OTA boot state from `otadata` unless explicitly needed. Future enhancement: - Read and interpret `otadata` to mark active app, but keep it excluded from imported reusable firmware unless user intentionally includes it. ### Security and Privacy Before importing filesystem or sensitive partitions, show warnings: - NVS may contain SSIDs, passwords, tokens, certificates and device identity. - Filesystem may contain credentials or customer data. - Coredump is diagnostic only. Defaults: - Exclude NVS. - Exclude OTA data. - Exclude coredump. - Include filesystem only with visible warning and clear classification. Backend logs must not print credentials or file contents. ### UI Within Backups > Import firmware from connected ESP32: Sections: 1. Device detection. 2. Flash layout. 3. Region selection. 4. Repository comparison preview. 5. Firmware metadata form. 6. Import confirmation. 7. Result with link to firmware catalog entry. Use existing dual progress: - Global progress: total bytes across all selected regions and uploads. - Partial progress: current region read or current upload. ### Validation 1. Connect known ESP32. 2. Analyze flash layout. 3. Confirm safe defaults exclude NVS, OTA data and coredump. 4. Import bootloader, partition table, app0/app1 and filesystem as selected. 5. Confirm artifacts are created or reused by SHA-256. 6. Confirm firmware row has source `CONNECTED_DEVICE` and validation `UNVERIFIED`. 7. Confirm firmware segments keep offsets and sizes. 8. Confirm imported firmware appears in Firmware list. 9. Confirm it can be selected in Flasher as multipart firmware. 10. Flash imported firmware to another compatible ESP32 only after explicit approval for that physical validation. 11. Confirm deleting imported firmware does not remove shared artifacts. 12. Confirm temporary import session cleanup leaves no orphan files. ## Recommended Implementation Order ### Step 1 - Repository Comparison Backend - Add comparison DTOs. - Add `RepositoryCompareService`. - Add backup comparison endpoint. - Add tests with existing backup regions and artifact matches. ### Step 2 - Repository Comparison UI - Add `Compare with repository` button on saved backup rows. - Add result panel with best match and per-region table. - Validate against backup #2. ### Step 3 - Firmware Fingerprints for Catalog Entries - Add firmware fingerprint columns if approved. - Compute fingerprints for existing firmware records. - Display fingerprint in firmware detail only where useful. ### Step 4 - Import Session Backend - Add import session and import region migrations/entities. - Add temp upload endpoints. - Add verify/preview/discard endpoints. - Add cleanup for expired sessions. ### Step 5 - Import UI Read and Preview - Add Import firmware screen inside Backups. - Reuse connection/layout/read code from Backups Stage 1. - Upload selected regions to import session. - Show repository comparison preview. ### Step 6 - Complete Import - Create firmware metadata form. - Finalize artifacts and segments. - Create firmware entry with source `CONNECTED_DEVICE` and validation `UNVERIFIED`. - Link to Firmware detail page. ### Step 7 - Validation - Run non-destructive import from the known ESP32. - Verify database rows and filesystem artifacts. - Confirm no sensitive regions are imported by default. - Do not flash to another ESP32 until explicit physical validation approval. ## Open Decisions Before Implementation 1. Should firmware catalog entries get persisted fingerprint columns now, or should comparison compute them on demand for MVP? 2. Should `firmware` get explicit `source`, `tags` and `validation_status` columns before Import, or encode them temporarily in description/metadata? Recommended: add columns. 3. Should imported filesystem regions be selected by default? Recommended: yes for known reusable firmware, but with a visible warning; no for unknown/custom devices. 4. Should Import support a complete raw full-flash artifact as advanced option in this phase? Recommended: not in first import MVP; keep full dumps under Backups. --- Document ID: validation-restore-backup-package # Restore Backup Package Date: 2026-07-14 Status: implemented and physically validated ## Scope Restore backup package completes the backup/write cycle for ESP Platform Backups. It supports: - selecting a saved ESP Platform backup; - uploading an `esp-platform-backup.zip` from the computer; - validating the package before restore options are shown; - complete restore from `full-flash.bin` at `0x0`; - selective restore by detected regions; - optional safety backup before writing; - post-write verification by reading written bytes when enabled; - audit of restore result. It does not convert backups into firmware. Backup and firmware remain separate concepts. Out of scope: - Compare with repository; - Import firmware from connected ESP32; - OTA; - Provisioning; - Fleet Management; - Edge OS. ## Backend Validation Endpoints: - `POST /api/v1/backups/{id}/restore/validate` - `POST /api/v1/backups/restore/upload` - `GET /api/v1/backups/restore-sessions/{id}/files/{filename}` - `POST /api/v1/backups/restore-sessions/{id}/complete` The backend validates: - ZIP structure; - `manifest.json` existence; - `checksums.sha256` existence; - SHA-256 checksums; - file sizes; - flash size bounds; - region offsets; - region overlap; - backup format and format version; - sensitive/device-state/diagnostic region metadata. Uploaded ZIPs are extracted into a private temporary path under: ```text /srv/esp-platform/backups/restore-tmp// ``` Files are not placed in a public web path. Downloads are served through authenticated backend routes. ## Restore Session Audit Restore sessions are stored in `backup_restore_session` with: - source type: `SERVER_BACKUP` or `UPLOADED_ZIP`; - package filename; - package SHA-256; - manifest JSON; - source MAC; - target MAC; - chip; - flash size; - restore mode; - selected regions; - result; - error message; - duration; - flasher build. `backup_audit_log` also records validation/upload and final restore events. ## UI Flow Backups > Restore backup package: 1. Select source: - saved ESP Platform backup; - uploaded `esp-platform-backup.zip`. 2. Validate package. 3. Connect target ESP32 through Web Serial over HTTPS. 4. Review compatibility. 5. Choose restore mode: - complete restore; - selective restore. 6. Choose regions for selective restore. 7. Choose options: - erase flash before complete restore; - create safety backup before restore; - verify after restore. 8. Review summary. 9. Type `RESTORE`. 10. Execute restore. 11. Verify and reset. 12. Review final status. ## Safe Defaults Selected by default for selective restore: - bootloader; - partition table; - app partitions; - reusable filesystem partitions. Excluded by default: - NVS; - OTA data; - coredump; - NVS keys; - sensitive regions; - diagnostic regions; - device-state regions. Selecting sensitive/device-state/diagnostic regions requires explicit warning acceptance in the browser. ## NVS Warning NVS may contain: - Wi-Fi SSIDs; - Wi-Fi passwords; - tokens; - certificates; - identifiers; - calibrations; - activations; - configuration tied to device identity. Restoring NVS to another ESP32 can duplicate identity, copy credentials, create network conflicts or fail if data is tied to MAC, eFuse or chip state. ## Secure Boot and Flash Encryption The UI performs best-effort detection through esptool-js chip hooks when available: - Secure Boot; - Flash Encryption / flash crypt config. If detected, the compatibility report shows critical warnings. ESP Platform does not promise complete cloning of protected devices because flash dumps do not contain eFuses. ## Write Behavior Default baudrate remains `115200`. Complete restore: - writes `full-flash.bin` at `0x0`; - offers `Erase flash before restore`, enabled by default; - warns that everything on flash may be overwritten. Selective restore: - writes only selected regions; - does not erase full flash by default; - leaves non-selected regions untouched. Progress states: - Validating; - Connecting; - Reading; - Erasing; - Writing; - Verifying; - Resetting; - Completed; - Cancelled; - Failed. The UI uses: - global progress for the entire operation; - partial progress for the current region/block/segment. ## Cancellation Cancel requests stop new stages and attempt to abort during progress callbacks. esptool-js may finish the active write/read block before cancellation takes effect. If a restore is cancelled during writing, ESP Platform reports: ```text Restore cancelled; device state may be incomplete. ``` No rollback is attempted automatically. ## Software Validation Completed Validated on 2026-07-14: - saved backup restore validation for backup `#2`; - returned 4 MB full-flash package; - detected 8 restore regions; - safe defaults: bootloader, partition-table, app0, app1, spiffs; - controlled backend download returns `4,194,304` bytes; - controlled backend download SHA-256: `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`; - uploaded real `esp-platform-backup-2.zip` validates successfully; - uploaded ZIP download returns the same 4 MB full-flash image; - corrupted checksum ZIP is rejected with HTTP 400 and clear message; - Backups page loads Restore UI without JavaScript console errors; - Restore package validation renders compatibility, warnings and region table. ## Physical Validation Completed Validated on 2026-07-14 with ESP32-D0WD revision 1, MAC `2c:bc:bb:75:f2:74`, Flash ID `16405e`, 4 MB flash, baudrate `115200`. Test A - Complete restore: passed. - Backup source: saved ESP Platform backup `#2`. - Full image size: `4,194,304` bytes. - Full image SHA-256: `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`. - Safety backup was enabled and downloaded before write. - Safety backup SHA-256: `cd3517473707d59c3d915b52a3e16213cadce80d9ffb2b4371958fb7acb51a08`. - Full restore wrote from `0x0` and post-write verification matched the source SHA-256. - RTS hard reset was requested after restore. Test B - Selective `app0` restore: passed. - Selected only `app0`. - Excluded NVS, OTA data and filesystem. - `app0` offset: `0x10000`. - `app0` size: `1,310,720` bytes. - `app0` SHA-256: `d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948`. - NVS SHA-256 before and after remained `83db022f60712229ae24ca0412897611d656ea5c66102d3f87d5eb3014619172`. Test C - Cancel during write: passed. - Cancellation was requested during `Writing`, after erase had completed. - UI reported `Restore cancelled; device state may be incomplete.` - Success was not shown for the cancelled operation. - Serial port was released. - Audit event `RESTORE_CANCELLED` was recorded. - Device was recovered with a complete verified restore. Test D - Incompatibility: passed. - Controlled invalid package was rejected before writing. - Error: `Region bootloader exceeds flash size.; Region bootloader overlaps coredump.` Test E - Corrupt checksum: passed at package-validation boundary. - Controlled ZIP with altered checksum was rejected before writing. - Error: `Checksum mismatch for full-flash.bin.` - Chrome automation could not attach the ZIP through the native file chooser due `Not allowed`; validation was confirmed through the same backend package-validation endpoint. ## Execute Restore Enablement `Execute restore` is intentionally disabled until all of these are true: - ESP32 connected through Web Serial; - restore package validated; - compatibility is not `incompatible`; - confirmation text is exactly `RESTORE`; - no operation is currently busy. Selecting every partition does not disable execution by itself. Sensitive or device-specific regions such as NVS, OTA data and coredump require explicit warning confirmation when selected. ## Closure Restore backup package is approved for MVP Flasher/Backups closure. New features remain frozen except bug fixes. --- Document ID: artifacts-library # Biblioteca de artefactos binarios Un artifact es contenido binario independiente de cualquier firmware. Su identidad es el SHA-256 y puede ser compartido. ## Relación firmware 1 -> N firmware_segment N -> 1 artifact La ficha describe producto y compatibilidad. El segmento describe cómo usar un archivo dentro de esa ficha. El artifact representa los bytes. ## Deduplicación Al subir un archivo se calcula SHA-256 antes de almacenarlo. Si existe, se reutiliza. Clonar firmware crea nuevas relaciones sin copiar bytes. Dos paquetes pueden compartir bootloader o tabla de particiones. ## Sustitución Editar un segmento no muta el artifact. Se crea o reutiliza otro artifact y la relación cambia de forma transaccional. Los demás firmwares continúan apuntando al contenido anterior. ## Eliminación Eliminar firmware borra ficha y segmentos. Nunca borra directamente el archivo compartido. Un artifact sin relaciones queda huérfano. La limpieza explícita verifica de nuevo referencias, elimina el archivo y luego su registro. ## Riesgos evitados Este modelo impide que borrar el original rompa clones, evita duplicación física, conserva checksums, permite trazabilidad y mantiene integridad referencial. --- Document ID: historical-vm-status # ESP Platform VM Status Date: 2026-07-06 ## Proxmox - Host: 192.168.0.155 - Node: proxmox - VMID: 675 - Name: esp-platform - Storage: local-zfs - Bridge: vmbr0 - Network: DHCP, reserved manually in MikroTik - Reserved DHCP IP: 192.168.1.62 - MAC: BC:24:11:8B:A3:E6 - Static IP inside Debian: not configured - CPU: 2 vCPU - RAM: 4096 MB - Disk: 40 GB ## Operating System - Debian GNU/Linux 12 Bookworm - User: codex - sudo: NOPASSWD validated - SSH: enabled - QEMU guest agent: active ## Native Services - PostgreSQL 15 native, listening on localhost - Nginx 1.22 native, listening on port 88 - UFW active - fail2ban active, sshd jail enabled with systemd backend ## Project Paths - Repository: /opt/esp-platform/repo - Firmware storage: /srv/esp-platform/firmware - Configuration: /etc/esp-platform - Logs: /var/log/esp-platform ## DHCP Reservation The IP address `192.168.1.62` is fixed by a manual DHCP reservation in MikroTik for MAC `BC:24:11:8B:A3:E6`. Do not configure a static IP address inside Debian. DHCP reservations are managed manually by the project owner. --- Document ID: historical-install # ESP Platform Installation ESP Platform runs directly inside VM `675 esp-platform`. Runtime baseline: - Debian 12 Bookworm. - PostgreSQL 15 native. - Nginx native on port 88. - Spring Boot backend managed by systemd. - Firmware binaries stored in `/srv/esp-platform/firmware`. - Firmware metadata stored in PostgreSQL database `esp_platform`. Build and install backend: ```bash cd /opt/esp-platform/repo/backend/esp-platform-backend mvn -DskipTests package sudo install -o esp-platform -g esp-platform -m 0755 target/esp-platform-backend-0.1.0-SNAPSHOT.jar /opt/esp-platform/app/esp-platform-backend.jar sudo systemctl restart esp-platform-backend ``` --- Document ID: historical-operations # 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. --- Document ID: operations-platform-operations # Operación de la plataforma ## VM VMID 675, hostname esp-platform, Debian 12, 2 vCPU, 4 GB RAM, disco local-zfs de 40 GB e IP 192.168.1.62 por DHCP reservado. Usuario de trabajo codex con sudo. No configurar IP fija dentro de Debian ni modificar red Proxmox sin autorización. ## Servicios Compruebe esp-platform-backend con systemctl status y logs con journalctl -u esp-platform-backend. Nginx escucha en puerto 88 y NPM publica HTTPS en iot.aeizoon.com. PostgreSQL es nativo y la base es esp_platform. ## Despliegue Compile con Maven desde backend/esp-platform-backend, instale el JAR según la unidad systemd existente, reinicie el servicio y valide health funcional mediante API y páginas. Ejecute nginx -t antes de recargar Nginx. ## Mantenimiento Revise espacio de /srv, artifacts huérfanos, sesiones temporales, backups sensibles, logs y estado de Flyway. Cree snapshot Proxmox solo tras pruebas y commit. La reserva DHCP la administra el propietario en MikroTik. ## Recuperación El repositorio Git recupera código y documentación. PostgreSQL y /srv requieren backup coordinado porque las filas apuntan a archivos. Un snapshot de VM ayuda a volver a un estado coherente, pero no sustituye una política de backup externo. --- Document ID: diagnostics-overview # Diagnostics Diagnostics reúne operaciones de observación y análisis. ## Read flash region Lee offset y tamaño indicados mediante la conexión Web Serial y descarga un binario sin modificar flash. El preset FreePocket NVS usa el layout conocido del dispositivo de diagnóstico, pero no debe aplicarse a layouts desconocidos. ## Tabla de particiones Analyze flash layout lee la ubicación habitual para la familia detectada e interpreta nombre, tipo, subtipo, offset, tamaño y flags. Si no puede interpretarse, use lectura manual con datos conocidos. ## NVS Los scripts analyze-nvs-dump.sh y compare-nvs-dumps.sh usan herramientas de Espressif cuando están disponibles. La comparación debe mostrar namespaces, claves interpretadas y cambios, sin publicar credenciales. ## Monitor serie El monitor permite ver ROM boot, carga de segmentos, aplicación y logs. Requiere detener la sesión de esptool y abrir el puerto al baudrate de la aplicación. ## Fingerprints El SHA del dump completo mide estado exacto. El firmware fingerprint compara regiones reutilizables para reconocer software aunque cambien NVS u OTA data. --- Document ID: diagnostics-freepocket-nvs-diagnostics # FreePocket NVS Diagnostics Date: 2026-07-12 ## Current conclusion The LittleFS preconfiguration test did not change runtime behavior: the ESP32 still boots in AP mode and does not connect to Wi-Fi `Solax`. Do not generate more LittleFS variants by trial and error. The next diagnostic target is the ESP-IDF NVS partition. ## Partition table source FreePocket multipart packages currently use this partition-table artifact: `/srv/esp-platform/artifacts/14/148b959cbff1c38aa8e1d5c0ba9d612c54997b945e56a63f41223eef650653a1.bin` Decode command: ```bash cd /opt/esp-platform/repo scripts/freepocket-nvs-info.sh ``` Decoded partition table: | Label | Type | Subtype | Offset | Size | | --- | --- | --- | --- | --- | | nvs | data | nvs | `0x9000` | `0x5000` / 20480 bytes | | otadata | data | ota | `0xE000` | `0x2000` / 8192 bytes | | app0 | app | ota_0 | `0x10000` | `0x140000` / 1310720 bytes | | app1 | app | ota_1 | `0x150000` | `0x140000` / 1310720 bytes | | spiffs | data | spiffs | `0x290000` | `0x160000` / 1441792 bytes | | coredump | data | coredump | `0x3F0000` | `0x10000` / 65536 bytes | ## NVS read workflow through Flasher Web Use `https://iot.aeizoon.com/flasher` from Chrome or Edge on the Mac. The Mac is only the physical USB/browser endpoint; the project tooling remains on the VM. Use 115200 baud for this ESP32 board because previous validation showed it is stable while 921600 can lose the flash connection. The ESP32 must be connected in bootloader/flashing mode before reading if auto-reset does not work with the USB-TTL wiring. Steps for the first dump: 1. Open `https://iot.aeizoon.com/flasher`. 2. Set baudrate to `115200`. 3. Click `Connect ESP32` and authorize the USB-TTL serial port. 4. Open `Advanced`. 5. Click `FreePocket NVS`. 6. Confirm: - Offset: `0x9000` - Size: `0x5000` - Suggested filename: `freepocket-nvs-before.bin` 7. Click `Read and download .bin`. After configuring the device manually with: - Wi-Fi SSID: `Solax` - Wi-Fi password value is not included - Web user: `admin` - Web password value is not included repeat the read, using suggested filename: `freepocket-nvs-after-solax-admin.bin` The Flasher Web operation uses esptool-js `readFlash` through the current Web Serial connection and is read-only; it does not modify flash bytes. ## Move dumps to the VM From the Mac, after downloading the two files: ```bash scp ~/Downloads/freepocket-nvs-before.bin ~/Downloads/freepocket-nvs-after-solax-admin.bin codex@192.168.1.62:/opt/esp-platform/repo/diagnostics/nvs/ ``` ## Analyze with Espressif tools Official parser installed in the VM: `/opt/esp-platform/tools/esp-idf/components/nvs_flash/nvs_partition_tool/nvs_tool.py` Repo links: - `tools/nvs-diagnostics/nvs_partition_tool` - `tools/nvs-diagnostics/nvs_partition_generator` Espressif documentation states that `nvs_tool.py` parses NVS storage partitions, lists namespaces, entries, blobs/strings, and can run integrity checks. It does not decrypt encrypted NVS partitions. Analyze one dump: ```bash cd /opt/esp-platform/repo scripts/analyze-nvs-dump.sh diagnostics/nvs/freepocket-nvs-before.bin scripts/analyze-nvs-dump.sh diagnostics/nvs/freepocket-nvs-after-solax-admin.bin ``` Compare before/after: ```bash cd /opt/esp-platform/repo scripts/compare-nvs-dumps.sh \ diagnostics/nvs/freepocket-nvs-before.bin \ diagnostics/nvs/freepocket-nvs-after-solax-admin.bin ``` The comparison generates: - `storage_info.txt` - `namespaces.txt` - `written.txt` - `minimal.txt` - `blobs.txt` - `all.json` - `hexdump.txt` - `minimal.diff` - `written.diff` - `blobs.diff` - `changed-ranges.txt` ## Static findings before NVS dump LittleFS/static web content contains form fields and default JSON-like values for: - `WIFI_SSID` - `WIFI_PASSWORD` - `WIFI_isValid` - `WEB_USERNAME` - `WEB_PASSWORD` - `MAINTAIN_CONFIG` - `MQTT_PASSWORD` - `MQTT_SOLAX_ENABLED` - `SOLAX_WIFI_SERIAL_NUMBER` The application binary contains strings related to ESP-IDF NVS and Wi-Fi persistence, including: - `WIFI_STA_DEF` - `WIFI_AP_DEF` - `ap.ssid` - `ap.passwd` - `bssid.set` - `esp_phy_load_cal_data_from_nvs` - NVS error symbols such as `ESP_ERR_NVS_NOT_FOUND`, `ESP_ERR_WIFI_NVS`, `ESP_ERR_NVS_NO_FREE_PAGES` Interpretation: - LittleFS likely provides UI defaults/static configuration material. - Runtime effective Wi-Fi state may be persisted in NVS by ESP-IDF Wi-Fi and/or by FreePocket application namespaces. - The exact source of truth must be determined from before/after NVS dumps, not inferred from strings alone. ## Open questions for the dump analysis When both dumps are available, identify: - NVS namespaces present before and after configuration. - New or changed keys after setting Wi-Fi and web credentials. - Whether Wi-Fi credentials are stored under ESP-IDF Wi-Fi namespaces or FreePocket application namespaces. - Whether values are plain strings, blobs, integers, or structured serialized records. - Whether flags such as Wi-Fi enabled/valid/configured change independently from SSID/password. - Whether NVS integrity check reports valid pages and entries. - Whether NVS encryption is absent or present. ## Do not implement yet Do not modify firmware, generate NVS images, or add automatic NVS provisioning until the before/after NVS format is understood. --- Document ID: diagnostics-serial-commands # Monitor serie y comandos de desarrollo El monitor serie de `/flasher` permite observar el arranque y los logs del dispositivo a la velocidad seleccionada. El valor predeterminado es 115200 baudios. ## Envío de comandos Cuando el monitor está activo, el campo **Serial command** permite transmitir una línea de texto al dispositivo usando la misma conexión Web Serial. El navegador codifica el texto como UTF-8 y añade un salto de línea. La acción solo está habilitada mientras el puerto está abierto en modo monitor. El campo admite como máximo 160 caracteres. ESP Platform no interpreta ni ejecuta el contenido: el firmware conectado decide qué comandos reconoce. Los comandos de AEOS en modo development, como `config get`, `config set`, `config list` y `config reset`, pertenecen al firmware y no constituyen una shell del servidor. ## Seguridad - La función exige HTTPS y permiso Web Serial concedido por el usuario. - No se registran respuestas fuera de la consola visible del navegador. - No deben enviarse secretos; la consola puede quedar visible durante soporte. - Detener el monitor cierra el puerto y deshabilita inmediatamente el envío. - Las compilaciones de producción pueden no incluir consola de comandos. ## Validación El 18 de julio de 2026 se validó la transmisión bidireccional con AEOS 0.3.0 sobre ESP32-D0WDQ6. Se ejecutaron lecturas, cambios tipados, rechazo de un valor fuera de rango y factory reset sin perder la recepción continua del monitor. --- Document ID: architecture-overview # Arquitectura del sistema ESP Platform separa navegador, backend, metadatos y archivos binarios. ## Flujo principal Browser over HTTPS -> Nginx -> Spring Boot -> PostgreSQL metadata Browser Web Serial -> ESP32 connected by USB Spring Boot -> protected filesystem for artifacts and backups El navegador es responsable de la conexión física, lectura y escritura con esptool-js. Spring Boot administra catálogo, validaciones de servidor, artifacts, sesiones, auditoría, documentación y descargas. PostgreSQL conserva relaciones y estado transaccional. El filesystem conserva binarios grandes. ## Límites No se guardan firmware ni dumps como BLOB. Nginx sirve el acceso interno en el puerto 88 y NPM termina HTTPS para el dominio operativo. systemd controla el proceso Java. No hay contenedores. Las SPEC de la Constitución son la arquitectura oficial. Cualquier cambio arquitectónico se propone y aprueba antes de implementarse. --- Document ID: architecture-components # Componentes del sistema ## Frontend HTML server-side, CSS y JavaScript sin framework pesado. esptool-js 0.6.0 controla Web Serial. Las pantallas son Firmware, Flasher, Backups, Diagnostics y Documentación. ## Backend Spring Boot 3.3 sobre Java 17. Los servicios de firmware, backup y documentación encapsulan validaciones y almacenamiento. Los controladores web sirven vistas Thymeleaf y los controladores API exponen REST v1. ## Datos PostgreSQL conserva firmware, segmentos, artifacts, derivados, backups, regiones, sesiones y auditoría. Flyway versiona el esquema. Los binarios viven bajo rutas protegidas en srv. ## Infraestructura Debian 12 en VM Proxmox, 2 vCPU, 4 GB RAM y disco ZFS de 40 GB. systemd inicia el backend. Nginx publica el puerto 88. La IP procede de DHCP con reserva MikroTik; Debian no tiene IP fija. ## Evolución Los límites de servicio y categorías documentales preparan roles Viewer, Operator, Administrator y Developer. La autenticación multiusuario no forma parte de esta versión. --- Document ID: architecture-esp-platform-architecture-v1-0 # ESP Platform ## Constitución del Proyecto **Documento maestro** Versión: 1.0 --- # Introducción Bienvenido a la Constitución de ESP Platform. Este documento constituye la referencia arquitectónica oficial del proyecto. Su finalidad es proporcionar una visión completa del sistema antes de comenzar cualquier implementación, garantizando que todas las decisiones técnicas respeten una arquitectura común y puedan evolucionar sin perder coherencia. La Constitución está formada por veinte especificaciones (SPEC) que describen la filosofía del proyecto, su arquitectura, los estándares de desarrollo y el Roadmap de evolución. Todas las implementaciones realizadas por desarrolladores humanos o agentes de inteligencia artificial deberán respetar las decisiones recogidas en este documento. Cuando sea necesario modificar la arquitectura, dichas modificaciones deberán aprobarse explícitamente y documentarse mediante un ADR (Architecture Decision Record). --- # Cómo utilizar este documento Las SPEC deben leerse en orden. Cada una desarrolla un aspecto concreto de la plataforma y complementa a las anteriores. No constituyen documentos independientes, sino capítulos de una misma arquitectura. --- # Índice ## Arquitectura - SPEC-001 — Filosofía y Visión - SPEC-002 — Arquitectura Global - SPEC-003 — Aeizoon Edge Platform - SPEC-004 — Edge OS - SPEC-005 — Backend Central ## Infraestructura de dispositivos - SPEC-006 — Flasher Web - SPEC-007 — OTA y Rollback - SPEC-008 — Recovery - SPEC-009 — Provisioning y QR - SPEC-010 — Fleet Management ## Plataforma - SPEC-011 — Seguridad - SPEC-012 — Modelo SaaS - SPEC-013 — Modelo de Datos - SPEC-014 — APIs ## Desarrollo - SPEC-015 — Estándares de Desarrollo - SPEC-016 — Estándares UI/UX - SPEC-017 — Convenciones de Nomenclatura - SPEC-018 — Architecture Decision Records (ADR) - SPEC-019 — Normas para Codex - SPEC-020 — Roadmap --- ## Estado del documento Documento: ESP_PLATFORM_ARCHITECTURE_v1.0.md Versión: 1.0 Estado: Aprobado Número de SPEC: 20 Número de ADR: 0 Fecha de creación: julio de 2026 Responsable de arquitectura: Juan Antonio Arquitectura: ESP Platform Estado del proyecto: Fase de implementación. --- # SPEC-001 — Filosofía y Visión de ESP Platform **Documento:** SPEC-001 **Título:** Filosofía y Visión **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- ## 1. Propósito Esta especificación define la filosofía, visión y principios generales de ESP Platform. Su función es dar contexto a Codex y a cualquier desarrollador que participe en el proyecto, evitando que las primeras implementaciones se conviertan en soluciones aisladas sin coherencia futura. ESP Platform debe desarrollarse como una plataforma reutilizable, no como una colección de firmwares independientes. --- ## 2. Visión ESP Platform nace inicialmente para cubrir necesidades propias de domótica, automatización, monitorización y control. Sin embargo, desde el primer día se diseñará con mentalidad de producto profesional, de forma que pueda evolucionar en el futuro hacia: - uso doméstico avanzado; - instalaciones profesionales; - aplicaciones industriales ligeras; - producto comercial; - backend multiinstalación; - posible modelo SaaS. El objetivo inicial no es construir una empresa ni una plataforma completa desde el primer día. El objetivo inmediato es construir una base técnica correcta que permita validar el concepto y crecer sin rehacerlo todo. --- ## 3. Misión La misión de ESP Platform es permitir crear dispositivos basados inicialmente en ESP32 que compartan: - arquitectura común; - sistema de configuración; - sistema de actualización; - modelo de comunicaciones; - backend; - experiencia de usuario; - herramientas de desarrollo; - gestión centralizada futura. Cada nuevo dispositivo deberá aprovechar el trabajo ya realizado en los anteriores. --- ## 4. Qué NO es ESP Platform ESP Platform no es: - un sketch suelto de Arduino; - un firmware único para un ESP32; - una web aislada para flashear dispositivos; - una colección de pruebas; - un simple servidor MQTT; - un backend sin relación con el firmware; - una solución cerrada solo para AZ-TEMP. La web de flasheo, los firmwares, el backend, el OTA y las aplicaciones son piezas de un sistema mayor. --- ## 5. Componentes principales ESP Platform se organizará en los siguientes bloques. ### 5.1 Edge OS Base común que residirá en los dispositivos. Deberá proporcionar servicios reutilizables como: - red; - configuración persistente; - almacenamiento; - OTA; - rollback; - recovery; - MQTT; - Modbus; - web local; - API local; - logs; - diagnóstico; - seguridad; - provisioning. ### 5.2 Aplicaciones Cada aplicación añadirá lógica específica sobre Edge OS. Aplicaciones previstas: #### AZ-TEMP Dispositivo para adquisición de temperaturas. Funciones previstas: - sondas DS18B20; - nombres configurables; - calibración; - MQTT; - Modbus TCP; - API REST; - alarmas futuras. #### AZ-POWER Pasarela para medidores de energía. Funciones previstas: - RS485; - Modbus RTU Master; - lectura de analizadores eléctricos; - publicación MQTT; - integración con backend, Node-RED y Grafana. #### AZ-NFC Dispositivo para identificación y control mediante NFC. Funciones previstas: - lectura de tarjetas; - identificación de usuarios; - control de accesos; - automatización; - integración con backend. #### AZ-IO Módulo de entradas y salidas. Funciones previstas: - entradas digitales; - salidas digitales; - entradas analógicas; - salidas analógicas; - contadores; - integración con automatización. #### AZ-RELAY Módulo de relés y actuadores. Funciones previstas: - control de relés; - contactores; - escenas; - temporizaciones; - maniobras; - control remoto. ### 5.3 Plataforma central Backend previsto en: ```text iot.aeizoon.com ``` Funciones futuras: - inventario de dispositivos; - catálogo de firmwares; - flasher web; - OTA centralizada; - provisioning; - QR de alta; - usuarios; - logs; - fleet management; - API; - posible SaaS. ### 5.4 Herramientas de desarrollo El desarrollo deberá apoyarse en: - Codex CLI; - PlatformIO; - ESP-IDF; - Git; - VM Debian; - systemd; - PostgreSQL; - Nginx. --- ## 6. Principios básicos ### 6.1 Primero validar, después ampliar La plataforma debe crecer por fases. El primer objetivo práctico será validar: 1. VM funcional. 2. Web de flasheo. 3. Subida de un `.bin`. 4. Flasheo de un ESP32 vacío por USB desde navegador. No se deberá implementar el sistema completo antes de validar este flujo básico. ### 6.2 Arquitectura común Toda pieza nueva deberá diseñarse pensando en su reutilización futura. Si una funcionalidad puede servir para varios dispositivos, deberá considerarse parte de la plataforma común. ### 6.3 Configuración separada del firmware La configuración no debe perderse al actualizar firmware. El firmware será reemplazable. La configuración deberá persistir. ### 6.4 OTA segura Las actualizaciones futuras deberán diseñarse con: - doble partición; - rollback; - comprobación de integridad; - recovery. ### 6.5 Web local en dispositivos Los dispositivos deberán tener una web interna para: - configuración; - diagnóstico; - estado; - OTA local; - mantenimiento. ### 6.6 Backend como centro de gestión El backend no debe ser una simple web auxiliar. Debe evolucionar hacia el centro de gestión de la plataforma. ### 6.7 Experiencia de producto Aunque el proyecto nazca para uso propio, la experiencia debe parecer la de un producto cuidado: - instalación sencilla; - interfaz clara; - nombres consistentes; - mensajes comprensibles; - flujos guiados; - posibilidad de QR; - recuperación ante errores. ### 6.8 No sobredimensionar antes del MVP La visión comercial no debe bloquear la validación técnica. Primero debe funcionar el flujo mínimo. Después se ampliará. --- ## 7. Relación con Codex Codex actuará como implementador técnico. Debe recibir esta documentación para entender: - el objetivo global; - las fases; - las restricciones; - el estilo arquitectónico; - lo que debe evitar. Codex no deberá convertir una fase concreta en una solución cerrada que impida el crecimiento futuro. Tampoco deberá intentar construir toda la plataforma de golpe. Debe implementar exactamente la fase solicitada, dejando la estructura preparada para las siguientes. --- ## 8. Criterio de éxito inicial El primer éxito real del proyecto será: ```text Entrar en iot.aeizoon.com o en la IP interna de la VM, subir un firmware .bin, conectar un ESP32 vacío por USB, seleccionar el firmware, flashear el dispositivo desde el navegador y comprobar que arranca. ``` Hasta conseguir ese resultado, todo lo demás es secundario. --- ## 9. Criterio de éxito futuro ESP Platform será considerada madura cuando sea posible crear nuevos dispositivos reutilizando la misma base: ```text Edge OS + aplicación específica + backend común + OTA + provisioning + fleet management ``` El objetivo final es que desarrollar un nuevo producto no implique volver a resolver desde cero: - configuración; - comunicaciones; - OTA; - recuperación; - flasheo; - backend; - UX. --- ## 10. Regla fundamental La documentación debe servir al proyecto. El proyecto no debe quedar bloqueado por la documentación. Esta Constitución existe para dar dirección a Codex y evitar contradicciones, no para retrasar indefinidamente la implementación. --- ## 11. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** Ninguna **Desarrolla:** Visión general del proyecto **Implementación:** No aplica directamente -------------------------------------------------------------------------------- # SPEC-002 — Arquitectura Global de ESP Platform **Documento:** SPEC-002 **Título:** Arquitectura Global **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la arquitectura general de ESP Platform. Mientras la SPEC-001 explica la filosofía del proyecto, esta especificación describe cómo se organiza la plataforma y cómo se relacionan sus componentes. No entra en el detalle interno de cada componente; dicho detalle se desarrolla en las especificaciones posteriores. --- # 2. Objetivo de la arquitectura La arquitectura debe permitir desarrollar múltiples dispositivos reutilizando una infraestructura común. Cada nuevo dispositivo deberá implementar únicamente su lógica específica. Todo aquello que pueda compartirse entre varios dispositivos deberá formar parte de la plataforma. El crecimiento del proyecto deberá producirse mediante la incorporación de nuevos módulos y aplicaciones, evitando duplicar funcionalidades ya existentes. --- # 3. Visión global La plataforma se divide en cinco grandes bloques. ```text ESP Platform │ ┌──────────────┬────────────┴────────────┬──────────────┐ │ │ │ │ │ │ │ │ Desarrollo Plataforma Edge Backend Central Usuario │ │ │ │ │ │ │ │ PlatformIO Edge OS iot.aeizoon.com Navegador ESP-IDF Aplicaciones PostgreSQL App móvil (futuro) Codex CLI Web Local OTA API Git MQTT Fleet QR Modbus Firmware ``` Cada bloque tiene responsabilidades claramente definidas. --- # 4. Componentes de la plataforma La plataforma se compone de cuatro niveles principales. ## Nivel 1 — Desarrollo Conjunto de herramientas utilizadas para crear el software. Incluye: - Codex CLI - PlatformIO - ESP-IDF - Git - Máquina Virtual de desarrollo - Sistema de compilación - Publicación de firmware Estas herramientas no forman parte del producto final, pero sí del ecosistema de desarrollo. --- ## Nivel 2 — Plataforma Edge Corresponde al software residente en cada dispositivo. Está formado por: - Edge OS - Aplicación instalada El dispositivo deberá ser completamente autónomo para realizar sus funciones principales. El backend no deberá ser imprescindible para el funcionamiento normal. --- ## Nivel 3 — Backend Corresponde al servidor central. Inicialmente estará instalado en una VM Debian. Funciones previstas: - gestión de firmware - flasher web - OTA - inventario - dispositivos - usuarios - logs - provisioning - Fleet Management - API --- ## Nivel 4 — Usuario Es la capa de interacción. Inicialmente estará formada por una aplicación web. En el futuro podrán existir aplicaciones móviles utilizando las mismas APIs. --- # 5. Separación de responsabilidades Cada bloque tiene responsabilidades exclusivas. ## Desarrollo Responsable de crear el software. Nunca participa en la ejecución normal del sistema. --- ## Edge Responsable de: - adquisición de datos - control - automatización local - comunicaciones - diagnóstico Debe seguir funcionando aunque el backend esté fuera de servicio. --- ## Backend Responsable de: - administración - inventario - actualizaciones - almacenamiento histórico - configuración global - gestión de usuarios No debe asumir funciones críticas de tiempo real que pertenezcan al Edge. --- ## Usuario Responsable únicamente de interactuar con el sistema. No debe contener lógica de negocio. --- # 6. Principios arquitectónicos La arquitectura de ESP Platform se basa en los siguientes principios. ## 6.1 Independencia Cada componente deberá poder evolucionar con el mínimo impacto sobre los demás. --- ## 6.2 Modularidad Cada módulo tendrá una responsabilidad única. Los módulos se comunicarán mediante interfaces claramente definidas. --- ## 6.3 Escalabilidad La plataforma deberá crecer añadiendo componentes, no modificando los existentes. --- ## 6.4 Reutilización Siempre que una funcionalidad pueda reutilizarse por más de una aplicación deberá incorporarse al núcleo común. --- ## 6.5 Baja dependencia La comunicación entre módulos deberá minimizar el acoplamiento. Las dependencias cruzadas deberán evitarse. --- # 7. Flujo general de funcionamiento El funcionamiento habitual será el siguiente. ```text Usuario │ │ Navegador ▼ Backend │ ├───────────── OTA │ ├───────────── API │ ├───────────── Inventario │ ▼ Dispositivo │ ├──────── MQTT ├──────── Modbus ├──────── API Local ├──────── Web Local └──────── Hardware ``` --- # 8. Flujo de desarrollo El desarrollo de una nueva aplicación seguirá el siguiente proceso. ```text Arquitectura │ ▼ Codex │ ▼ PlatformIO │ ▼ Compilación │ ▼ Firmware (.bin) │ ▼ Repositorio Firmware │ ▼ Flasher Web │ ▼ ESP32 ``` En el futuro: ```text Repositorio Firmware ↓ OTA ↓ Dispositivos en producción ``` --- # 9. Arquitectura del dispositivo Cada dispositivo seguirá siempre el mismo esquema. ```text +--------------------------------------+ | Aplicación | | (AZ-TEMP / POWER / NFC / ...) | +--------------------------------------+ | Edge OS | |--------------------------------------| | Configuración | | MQTT | | Modbus | | OTA | | Recovery | | Logging | | Seguridad | | Web | | API | +--------------------------------------+ | ESP-IDF | +--------------------------------------+ | Hardware | +--------------------------------------+ ``` Esto garantiza que todas las aplicaciones compartan la misma infraestructura. --- # 10. Arquitectura del backend El backend estará formado por módulos independientes. Inicialmente: ```text Frontend Web ↓ API ↓ Servicios ↓ PostgreSQL ↓ Repositorio Firmware ``` Cada módulo deberá poder evolucionar de forma independiente. --- # 11. Arquitectura de comunicaciones Inicialmente coexistirán cuatro canales principales. ### HTTP / HTTPS Administración. ### MQTT Eventos. Telemetría. Mensajería. ### Modbus TCP Integración industrial. ### USB Flasheo inicial. En el futuro podrán añadirse nuevos protocolos sin modificar la arquitectura principal. --- # 12. Escalabilidad prevista La arquitectura debe permitir evolucionar desde: ```text 1 ESP32 ``` hasta: ```text Centenares de dispositivos ``` sin modificar la estructura fundamental del sistema. La escalabilidad deberá obtenerse añadiendo nuevos módulos, nunca rediseñando los existentes. --- # 13. Relación con las siguientes SPEC Esta especificación actúa como mapa general. Las siguientes especificaciones desarrollarán cada componente. - SPEC-003 → Aeizoon Edge Platform - SPEC-004 → Edge OS - SPEC-005 → Backend - SPEC-006 → Flasher Web - SPEC-007 → OTA - SPEC-008 → Recovery - SPEC-009 → Provisioning - SPEC-010 → Fleet Management - ... No deberán redefinir esta arquitectura, sino ampliarla. --- # 14. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 **Desarrolla:** - Arquitectura general de ESP Platform **Implementación:** - Será utilizada como referencia durante todas las fases del desarrollo. -------------------------------------------------------------------------------- # SPEC-003 — Aeizoon Edge Platform **Documento:** SPEC-003 **Título:** Aeizoon Edge Platform (AEP) **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define Aeizoon Edge Platform (AEP), el núcleo conceptual sobre el que se desarrollarán todos los dispositivos de ESP Platform. Su finalidad es evitar que cada nuevo firmware vuelva a implementar servicios comunes y garantizar una arquitectura uniforme en todos los dispositivos. Todas las aplicaciones deberán ejecutarse sobre AEP. --- # 2. Definición Aeizoon Edge Platform (AEP) es la plataforma software residente en cada dispositivo Edge. No es una aplicación. No es un firmware específico. No depende de AZ-TEMP ni de ninguna otra aplicación. AEP proporciona servicios comunes para que cualquier aplicación pueda centrarse exclusivamente en su lógica funcional. Puede entenderse como la infraestructura común de todos los dispositivos. --- # 3. Objetivos AEP debe conseguir que desarrollar un nuevo dispositivo consista únicamente en implementar la lógica específica del producto. Todo lo demás deberá existir previamente dentro de la plataforma. Los principales objetivos son: - reutilización; - modularidad; - mantenimiento sencillo; - evolución controlada; - comportamiento homogéneo; - reducción del tiempo de desarrollo. --- # 4. Responsabilidades AEP será responsable de todos aquellos servicios que puedan ser utilizados por más de una aplicación. Entre ellos: - gestión de red; - configuración; - almacenamiento persistente; - servidor web; - API local; - autenticación; - MQTT; - Modbus TCP; - OTA; - rollback; - recovery; - logging; - diagnóstico; - identificación del dispositivo; - información de versión; - gestión de usuarios locales (si aplica); - monitorización interna. Las aplicaciones no deberán implementar nuevamente estas capacidades. --- # 5. Qué NO pertenece a AEP Las siguientes funciones pertenecen exclusivamente a las aplicaciones. Ejemplos: AZ-TEMP - lectura de temperatura; - calibración de sondas; - alarmas de temperatura. AZ-POWER - lectura de medidores; - interpretación de registros Modbus; - cálculo energético. AZ-NFC - lectura NFC; - gestión de tarjetas; - identificación de usuarios. AZ-IO - lógica de entradas y salidas. AZ-RELAY - control de relés; - temporizaciones; - escenas. AEP únicamente proporciona la infraestructura necesaria para que estas aplicaciones funcionen. --- # 6. Organización interna Conceptualmente AEP estará organizado mediante servicios. ```text Aplicación │ ┌────────────────────┼────────────────────┐ │ │ │ Configuración Comunicaciones Servicios internos │ │ │ MQTT Web Local OTA Modbus API REST Recovery WiFi Logging Seguridad Ethernet Diagnóstico Storage │ ESP-IDF ``` Cada servicio deberá tener una responsabilidad claramente definida. --- # 7. Independencia de servicios Siempre que resulte razonable, los servicios deberán poder evolucionar de forma independiente. Por ejemplo: Una mejora en OTA no debería requerir modificar el módulo MQTT. Una mejora en Modbus no debería afectar al servidor web. Una modificación del sistema de logs no debería alterar la configuración. La independencia constituye un objetivo arquitectónico. --- # 8. Configuración Toda configuración común deberá gestionarse desde AEP. Ejemplos: - nombre del dispositivo; - hostname; - dirección IP; - DHCP; - WiFi; - Ethernet; - MQTT; - Modbus; - certificados; - usuarios; - parámetros OTA. Las aplicaciones únicamente almacenarán configuración propia. Ejemplo: AZ-TEMP almacenará: - nombres de sondas; - calibraciones; - alarmas. No almacenará configuración de red. --- # 9. Almacenamiento AEP será responsable del almacenamiento persistente. La aplicación solicitará: - guardar; - leer; - eliminar; - actualizar. Nunca deberá conocer el mecanismo físico utilizado. Esto permitirá cambiar la implementación en el futuro sin modificar las aplicaciones. --- # 10. Comunicaciones Todas las comunicaciones comunes estarán gestionadas por AEP. Inicialmente: - HTTP - HTTPS (futuro) - MQTT - Modbus TCP - USB - OTA En el futuro podrán añadirse nuevos protocolos. Las aplicaciones accederán a ellos mediante interfaces proporcionadas por AEP. --- # 11. Seguridad Toda la seguridad común pertenecerá a AEP. Entre otras funciones: - autenticación; - autorización; - validación de firmware; - control de acceso a la web; - control de acceso a la API; - gestión de certificados (futuro). Las aplicaciones no implementarán mecanismos de autenticación propios salvo necesidad justificada. --- # 12. Ciclo de vida Todo dispositivo seguirá el mismo ciclo de funcionamiento. ```text Arranque ↓ Inicialización Edge Platform ↓ Carga de configuración ↓ Inicialización de comunicaciones ↓ Inicialización de aplicación ↓ Funcionamiento normal ↓ OTA (cuando proceda) ↓ Reinicio ``` La aplicación nunca deberá inicializar por sí misma los servicios comunes. --- # 13. Evolución futura AEP deberá diseñarse pensando en el crecimiento. Deberá permitir incorporar nuevos servicios sin modificar la arquitectura existente. Ejemplos futuros: - Bluetooth; - Zigbee; - Matter; - CAN Bus; - Modbus RTU; - VPN; - Edge AI; - sincronización horaria avanzada; - almacenamiento histórico. La incorporación de nuevos servicios no deberá requerir modificar las aplicaciones existentes. --- # 14. Beneficios La existencia de AEP aporta las siguientes ventajas. Para el desarrollo: - menos código duplicado; - menor tiempo de desarrollo; - mayor calidad. Para el mantenimiento: - comportamiento homogéneo; - menor riesgo; - actualizaciones comunes. Para el usuario: - misma experiencia; - misma configuración; - mismo mantenimiento. Para el proyecto: - crecimiento ordenado; - evolución sencilla; - mayor reutilización. --- # 15. Relación con las siguientes SPEC Esta especificación define la plataforma Edge desde un punto de vista conceptual. Las siguientes especificaciones desarrollarán sus componentes. SPEC-004 desarrollará Edge OS. SPEC-007 desarrollará OTA. SPEC-008 desarrollará Recovery. SPEC-011 desarrollará Seguridad. Las aplicaciones utilizarán AEP, pero no modificarán su arquitectura. --- # 16. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 **Desarrolla:** - Aeizoon Edge Platform **Implementación:** - Constituirá el núcleo común de todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-004 — Edge OS **Documento:** SPEC-004 **Título:** Edge OS **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define Edge OS, el firmware base sobre el que se ejecutarán todas las aplicaciones de ESP Platform. Mientras que AEP representa el concepto de plataforma Edge, Edge OS constituye su implementación software. Toda aplicación desarrollada para ESP Platform deberá ejecutarse sobre Edge OS. El objetivo es evitar que cada dispositivo implemente nuevamente funcionalidades comunes. --- # 2. Objetivos Edge OS deberá proporcionar una base sólida, estable y reutilizable para todos los dispositivos. Los objetivos principales son: - inicialización uniforme; - servicios comunes; - arquitectura modular; - configuración persistente; - comunicaciones; - actualización segura; - recuperación; - mantenimiento sencillo; - evolución futura. --- # 3. Filosofía Edge OS no debe contener lógica de negocio. Debe proporcionar únicamente infraestructura. Toda funcionalidad específica deberá implementarse en la aplicación correspondiente. Ejemplos: Edge OS sabe: - iniciar WiFi; - publicar MQTT; - responder una API; - actualizar firmware; - guardar configuración. Edge OS no sabe: - qué es una temperatura; - qué es un medidor; - qué es una tarjeta NFC; - qué significa activar un relé. Eso pertenece a las aplicaciones. --- # 4. Organización general Todo firmware seguirá la siguiente estructura conceptual. ```text +------------------------------------------------+ Aplicación -------------------------------------------------- Servicios Edge OS -------------------------------------------------- Configuración Comunicaciones Seguridad Storage OTA Recovery Logging Diagnóstico API Web -------------------------------------------------- ESP-IDF -------------------------------------------------- Hardware +------------------------------------------------+ ``` Esta organización deberá mantenerse en todos los proyectos. --- # 5. Arquitectura modular Edge OS estará dividido en módulos independientes. Inicialmente se prevén los siguientes. ## Core Responsable de: - arranque; - inicialización; - ciclo principal; - coordinación de módulos. --- ## Config Manager Responsable de: - leer configuración; - guardar configuración; - validar parámetros; - migraciones futuras. --- ## Network Manager Responsable de: - WiFi; - Ethernet; - IP; - DHCP; - hostname; - reconexión. --- ## Web Manager Responsable de: - servidor web; - páginas; - autenticación; - recursos estáticos. --- ## API Manager Responsable de: - API REST; - respuestas JSON; - autenticación; - versionado. --- ## MQTT Manager Responsable de: - conexión; - publicación; - suscripciones; - reconexión; - estado. --- ## Modbus Manager Responsable de: - servidor Modbus TCP; - registros; - mapeo; - diagnóstico. --- ## OTA Manager Responsable de: - descarga; - validación; - instalación; - rollback. --- ## Recovery Manager Responsable de: - recuperación; - firmware alternativo; - restauración. --- ## Storage Manager Responsable de: - almacenamiento persistente; - abstracción del soporte físico. --- ## Log Manager Responsable de: - eventos; - errores; - auditoría local. --- ## Diagnostic Manager Responsable de: - estado del dispositivo; - información interna; - estadísticas. --- ## Time Manager Responsable de: - RTC; - NTP; - sincronización. --- # 6. Ciclo de arranque Todos los dispositivos deberán seguir el mismo proceso. ```text Reset ↓ Bootloader ↓ Edge OS ↓ Inicialización Core ↓ Configuración ↓ Red ↓ Servicios ↓ Aplicación ↓ Funcionamiento normal ``` La aplicación nunca deberá alterar este orden. --- # 7. Inicialización de módulos Cada módulo deberá disponer de una función de inicialización propia. Ejemplo conceptual: ```text Config ↓ Storage ↓ Network ↓ Web ↓ API ↓ MQTT ↓ Modbus ↓ OTA ↓ Aplicación ``` Esto facilitará futuras ampliaciones. --- # 8. Comunicación entre módulos Los módulos no deberán acceder directamente a información interna de otros módulos. La comunicación deberá realizarse mediante interfaces públicas. Ejemplo. La aplicación no accederá directamente al WiFi. Solicitará a Network Manager la información necesaria. Del mismo modo: OTA no accederá directamente al almacenamiento. Utilizará Storage Manager. --- # 9. Gestión de errores Todo módulo deberá detectar y comunicar errores. Los errores deberán clasificarse, al menos, en: - información; - advertencia; - error; - error crítico. Siempre que sea posible, el sistema deberá continuar funcionando. Un error en MQTT no deberá impedir el funcionamiento de la aplicación. --- # 10. Configuración Edge OS almacenará toda la configuración común. Ejemplos: - red; - MQTT; - Modbus; - usuarios; - OTA; - hostname; - idioma (futuro); - certificados (futuro). Las aplicaciones únicamente almacenarán parámetros propios. --- # 11. Recursos compartidos Edge OS administrará todos los recursos comunes. Entre ellos: - memoria; - almacenamiento; - red; - reloj; - tareas; - comunicaciones. Las aplicaciones deberán solicitar dichos recursos al núcleo. --- # 12. API interna Todos los servicios ofrecidos por Edge OS deberán exponerse mediante APIs internas claramente definidas. Ejemplos: Storage API MQTT API Network API OTA API Logging API Esto permitirá sustituir implementaciones sin afectar a las aplicaciones. --- # 13. Extensibilidad La incorporación de nuevos módulos no deberá requerir modificar el resto del sistema. Ejemplos futuros: Bluetooth Matter CAN LoRa RS485 VPN Edge AI Cada nuevo módulo deberá seguir la misma filosofía que los existentes. --- # 14. Beneficios Esta arquitectura proporciona: Para el desarrollador: - menos código; - mayor reutilización; - menor tiempo de desarrollo. Para el mantenimiento: - comportamiento uniforme; - menor riesgo; - evolución sencilla. Para el proyecto: - escalabilidad; - independencia entre módulos; - crecimiento ordenado. --- # 15. Relación con las siguientes SPEC Esta especificación define la estructura interna de Edge OS. Las siguientes especificaciones desarrollarán algunos módulos concretos. - SPEC-005 → Backend - SPEC-006 → Flasher Web - SPEC-007 → OTA - SPEC-008 → Recovery - SPEC-011 → Seguridad - SPEC-014 → APIs --- # 16. Consideraciones de implementación Edge OS deberá desarrollarse inicialmente utilizando: - PlatformIO; - ESP-IDF; - arquitectura modular; - Git; - compilación automatizada. La implementación deberá priorizar claridad, modularidad y mantenibilidad sobre la optimización prematura. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 **Desarrolla:** - Arquitectura interna de Edge OS **Implementación:** - Constituirá la base software común de todos los dispositivos desarrollados sobre ESP Platform. -------------------------------------------------------------------------------- # SPEC-005 — Backend Central **Documento:** SPEC-005 **Título:** Backend Central **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el Backend Central de ESP Platform. El Backend constituye el punto único de administración del ecosistema y será el encargado de proporcionar todos los servicios comunes que no deban ejecutarse dentro de los dispositivos Edge. El Backend no sustituye al funcionamiento autónomo de los dispositivos. Su misión consiste en facilitar su gestión. --- # 2. Objetivos El Backend deberá proporcionar una infraestructura centralizada para administrar todos los dispositivos de la plataforma. Sus objetivos principales son: - gestión de firmware; - flasheo inicial; - OTA; - inventario; - administración; - APIs; - autenticación; - Fleet Management; - auditoría; - crecimiento futuro hacia SaaS. --- # 3. Filosofía Los dispositivos deberán ser capaces de funcionar sin el Backend. El Backend añade funcionalidades de administración y gestión, pero no debe convertirse en un punto único de fallo para el funcionamiento normal de los dispositivos. Si el Backend deja de estar disponible: - los dispositivos seguirán ejecutando su lógica; - seguirán respondiendo por su web local; - seguirán respondiendo mediante Modbus TCP; - seguirán publicando MQTT si el broker continúa disponible. --- # 4. Arquitectura general El Backend se organizará mediante servicios independientes. ```text Navegador │ ▼ Frontend Web │ ▼ API REST │ ┌───────────────┼────────────────┐ │ │ │ Firmware Inventario Usuarios │ │ │ OTA Fleet Manager Auditoría │ │ │ └───────────────┼────────────────┘ │ PostgreSQL │ Repositorio Firmware ``` Cada servicio deberá tener responsabilidades claramente definidas. --- # 5. Responsabilidades El Backend será responsable de: - gestionar usuarios; - gestionar dispositivos; - almacenar firmware; - distribuir firmware; - mantener inventario; - registrar auditoría; - proporcionar APIs; - gestionar Provisioning; - gestionar OTA; - administrar Fleet Management. No será responsable del control en tiempo real de los dispositivos. --- # 6. Frontend Web Inicialmente toda la administración se realizará mediante una aplicación web. La web deberá permitir acceder a todas las funcionalidades del sistema. No deberá existir funcionalidad exclusiva de una futura aplicación móvil. Toda funcionalidad importante deberá poder realizarse desde un navegador. --- # 7. API REST Toda la lógica de negocio deberá residir en la API. La interfaz web actuará únicamente como cliente de dicha API. Esto permitirá desarrollar en el futuro: - aplicaciones móviles; - herramientas CLI; - automatizaciones; - integraciones externas. Sin modificar la lógica del Backend. --- # 8. Base de datos Inicialmente se utilizará PostgreSQL. La base de datos almacenará únicamente información persistente. Ejemplos: - usuarios; - dispositivos; - firmware; - versiones; - auditoría; - inventario; - configuraciones globales. Los datos de telemetría histórica podrán almacenarse posteriormente en sistemas especializados si fuese necesario. --- # 9. Repositorio de firmware El Backend mantendrá un repositorio de firmware. Cada firmware deberá almacenarse acompañado de información como: - nombre; - versión; - fecha; - descripción; - aplicación; - hardware compatible; - checksum; - tamaño. El repositorio será utilizado tanto por el Flasher Web como por OTA. --- # 10. Inventario Todo dispositivo registrado en la plataforma deberá disponer de una ficha propia. Inicialmente se prevén los siguientes datos. - identificador único; - nombre; - aplicación instalada; - versión; - hardware; - dirección IP; - MAC; - estado; - última conexión; - propietario; - ubicación (futuro). El inventario será el punto de partida para Fleet Management. --- # 11. Gestión de usuarios El Backend deberá permitir administrar usuarios. Inicialmente: - autenticación; - cambio de contraseña; - perfiles; - permisos. La arquitectura deberá permitir ampliar posteriormente el sistema de roles. --- # 12. Auditoría Toda operación relevante deberá quedar registrada. Ejemplos: - alta de dispositivo; - actualización OTA; - subida de firmware; - creación de usuario; - modificación de configuración; - operaciones administrativas. La auditoría facilitará el mantenimiento y el diagnóstico. --- # 13. Servicios previstos El Backend crecerá mediante módulos. Inicialmente se prevén: Firmware Service Device Service User Service Provisioning Service OTA Service Fleet Service Audit Service API Service Cada servicio deberá poder evolucionar independientemente. --- # 14. Integración con dispositivos Los dispositivos podrán comunicarse con el Backend mediante: - HTTP/HTTPS; - MQTT; - OTA; - Provisioning. La comunicación deberá minimizar el acoplamiento. Los dispositivos no deberán depender de detalles internos del Backend. --- # 15. Integración con el Flasher El Flasher Web utilizará el Backend para: - consultar firmware; - descargar binarios; - registrar instalaciones (futuro); - validar compatibilidades. El Flasher no almacenará información propia. Será un consumidor de los servicios del Backend. --- # 16. Escalabilidad La arquitectura deberá permitir evolucionar desde: ```text Una instalación doméstica ``` hasta: ```text Múltiples instalaciones ↓ Múltiples clientes ↓ Backend multiusuario ↓ SaaS ``` Sin modificar la arquitectura fundamental. --- # 17. Tecnologías iniciales La primera implementación utilizará: - Debian; - PostgreSQL; - Java (Spring Boot); - Nginx; - systemd. No se utilizarán contenedores. La arquitectura deberá seguir los estándares generales del proyecto. --- # 18. Beneficios El Backend proporciona: Para el usuario: - administración centralizada; - inventario; - firmware; - futuras OTA. Para el desarrollador: - APIs comunes; - reutilización; - separación de responsabilidades. Para la plataforma: - crecimiento ordenado; - punto único de administración; - evolución hacia Fleet Management. --- # 19. Relación con las siguientes SPEC Esta especificación define el Backend de forma general. Las siguientes especificaciones desarrollarán componentes concretos. - SPEC-006 → Flasher Web - SPEC-007 → OTA - SPEC-009 → Provisioning - SPEC-010 → Fleet Management - SPEC-011 → Seguridad - SPEC-014 → APIs --- # 20. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 - SPEC-004 **Desarrolla:** - Arquitectura del Backend Central **Implementación:** - Será el núcleo de administración de ESP Platform y el primer componente desplegado durante la Fase 1. -------------------------------------------------------------------------------- # SPEC-006 — Flasher Web **Documento:** SPEC-006 **Título:** Flasher Web **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el Flasher Web de ESP Platform. El Flasher Web constituye la puerta de entrada de todos los dispositivos nuevos a la plataforma. Su objetivo es permitir que un usuario conecte un ESP32 vacío mediante USB y pueda instalar un firmware desde un navegador web sin utilizar herramientas de desarrollo. El Flasher será el primer componente funcional del MVP de ESP Platform. --- # 2. Objetivos El Flasher deberá permitir: - seleccionar un firmware; - comprobar la compatibilidad con el hardware; - conectar con un ESP32 mediante USB; - escribir el firmware; - informar del progreso; - informar del resultado; - servir como base del futuro proceso de Provisioning. La experiencia deberá ser sencilla incluso para usuarios sin conocimientos técnicos. --- # 3. Filosofía El Flasher no es únicamente una utilidad de programación. Forma parte de la experiencia de usuario de ESP Platform. Su diseño deberá transmitir la misma sensación que un producto comercial. El usuario no deberá preocuparse por herramientas como: - esptool; - PlatformIO; - puertos serie; - comandos. Todo ello deberá quedar abstraído por la aplicación. --- # 4. Alcance de la primera versión La versión inicial permitirá exclusivamente: - seleccionar un firmware existente; - conectar un ESP32 mediante USB; - escribir el firmware; - comprobar el resultado. No realizará todavía: - Provisioning; - alta automática; - OTA; - inventario; - autenticación avanzada. Estas funcionalidades se incorporarán posteriormente reutilizando la misma arquitectura. --- # 5. Flujo de funcionamiento El proceso previsto será el siguiente. ```text Usuario ↓ Accede al Flasher ↓ Selecciona modelo de ESP32 ↓ Selecciona firmware ↓ Conecta USB ↓ Permitir acceso al dispositivo ↓ Flashear ↓ Verificación ↓ Resultado ``` El proceso deberá minimizar el número de pasos. --- # 6. Integración con el Backend El Flasher obtendrá toda la información desde el Backend. Entre ella: - catálogo de firmware; - versiones; - descripción; - hardware compatible; - tamaño; - checksum. El Flasher no almacenará información propia. --- # 7. Catálogo de firmware El usuario visualizará un catálogo organizado. Cada firmware mostrará, al menos: - nombre; - aplicación; - versión; - fecha; - descripción; - hardware compatible. En el futuro podrán añadirse: - notas de versión; - cambios; - estabilidad; - canal (estable / beta). --- # 8. Compatibilidad Antes de iniciar el proceso deberá comprobarse que el firmware es compatible con el dispositivo seleccionado. Inicialmente la selección será manual. En el futuro podrá detectarse automáticamente el hardware conectado. --- # 9. Comunicación con el ESP32 La comunicación se realizará mediante Web Serial. No será necesario instalar aplicaciones adicionales. El navegador solicitará autorización al usuario para acceder al dispositivo. La aplicación nunca accederá al puerto serie sin autorización explícita. --- # 10. Proceso de flasheo El proceso completo será: ```text Conectar USB ↓ Abrir puerto ↓ Comprobar comunicación ↓ Borrar Flash (si procede) ↓ Escribir firmware ↓ Verificar escritura ↓ Reiniciar ESP32 ↓ Resultado ``` Cada paso deberá informar claramente del estado. --- # 11. Interfaz de usuario La interfaz deberá priorizar claridad y sencillez. Elementos mínimos: - selección de hardware; - selección de firmware; - botón Conectar; - botón Flashear; - barra de progreso; - estado; - resultado. No deberá mostrar información técnica innecesaria al usuario final. --- # 12. Gestión de errores Los errores deberán mostrarse mediante mensajes comprensibles. Ejemplos: - dispositivo no encontrado; - acceso denegado; - puerto ocupado; - firmware incompatible; - error de escritura; - desconexión del dispositivo. Siempre que sea posible se propondrá una acción correctiva. --- # 13. Evolución futura El Flasher deberá crecer sin modificar su filosofía. Funciones previstas: - Provisioning automático; - asignación de nombre; - lectura de QR; - configuración inicial; - alta en Backend; - actualización de bootloader; - copia de seguridad; - recuperación. --- # 14. Beneficios Para el usuario: - instalación sencilla; - sin herramientas externas; - menor riesgo de error. Para el desarrollador: - proceso uniforme; - integración con Backend; - reutilización del repositorio de firmware. Para la plataforma: - punto único de instalación; - integración con OTA; - integración con Provisioning. --- # 15. Tecnologías previstas Primera versión: - Web Serial API; - JavaScript; - HTML; - CSS; - Backend Spring Boot; - PostgreSQL. No se utilizarán aplicaciones de escritorio. Toda la funcionalidad residirá en la aplicación web. --- # 16. Relación con otras SPEC El Flasher utiliza: - SPEC-002 Arquitectura Global; - SPEC-005 Backend. Será utilizado posteriormente por: - SPEC-007 OTA; - SPEC-009 Provisioning; - SPEC-010 Fleet Management. --- # 17. Objetivo del MVP El MVP de ESP Platform se considerará alcanzado cuando sea posible: ```text Abrir la web ↓ Seleccionar firmware ↓ Conectar un ESP32 vacío ↓ Flashearlo completamente ↓ Comprobar que arranca correctamente ``` Todo el desarrollo inicial del proyecto deberá orientarse a conseguir este resultado lo antes posible. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-005 **Desarrolla:** - Flasher Web **Implementación:** - Constituirá el principal objetivo de la Fase 2 del proyecto y el primer componente funcional visible de ESP Platform. -------------------------------------------------------------------------------- # SPEC-007 — OTA y Rollback **Documento:** SPEC-007 **Título:** OTA y Rollback **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema de actualización OTA (Over The Air) y el mecanismo de Rollback de ESP Platform. El objetivo es permitir actualizar dispositivos de forma remota con el máximo nivel posible de seguridad y minimizar el riesgo de dejar un dispositivo inutilizable. La actualización OTA constituye una capacidad nativa de Edge OS y deberá estar disponible para todas las aplicaciones de la plataforma. --- # 2. Objetivos El sistema OTA deberá permitir: - actualizar firmware sin conexión física; - minimizar el tiempo de indisponibilidad; - verificar la integridad del firmware; - recuperar automáticamente versiones anteriores cuando sea necesario; - mantener la configuración del dispositivo; - reducir al mínimo el riesgo operativo. --- # 3. Filosofía Actualizar un dispositivo nunca deberá convertirse en una operación de riesgo. Toda actualización deberá poder revertirse automáticamente si el nuevo firmware no supera las comprobaciones definidas. El usuario no deberá intervenir en circunstancias normales. --- # 4. Arquitectura general El sistema OTA estará formado por los siguientes elementos. ```text Repositorio Firmware ↓ Backend ↓ OTA Service ↓ Dispositivo ↓ Verificación ↓ Confirmación ↓ Funcionamiento normal ``` El Backend únicamente distribuirá firmware. La decisión de aceptar o rechazar la actualización corresponderá al dispositivo. --- # 5. Particionado Todos los dispositivos deberán utilizar un esquema de particiones compatible con OTA. Conceptualmente: ```text Bootloader ↓ Firmware A ↓ Firmware B ↓ Configuración ↓ Datos ``` La configuración permanecerá separada del firmware. --- # 6. Proceso OTA El flujo general será: ```text Backend detecta nueva versión ↓ Dispositivo consulta ↓ Descarga firmware ↓ Verifica integridad ↓ Escribe partición alternativa ↓ Reinicio ↓ Arranque nuevo firmware ↓ Autocomprobación ↓ Confirmación ↓ Actualización completada ``` --- # 7. Verificación Antes de aceptar un firmware deberán verificarse, al menos: - integridad del fichero; - compatibilidad con el hardware; - versión; - tamaño; - resultado de la escritura. No deberá instalarse un firmware que no supere las validaciones. --- # 8. Confirmación de arranque Tras el primer arranque del nuevo firmware, Edge OS deberá realizar una comprobación de funcionamiento. Entre otras: - arranque correcto; - inicialización de servicios; - estabilidad mínima; - ausencia de errores críticos. Solo entonces se confirmará definitivamente la nueva versión. --- # 9. Rollback automático Si el nuevo firmware no supera las comprobaciones, el sistema deberá volver automáticamente a la versión anterior. Proceso conceptual: ```text Firmware nuevo ↓ Error ↓ Reinicio ↓ Bootloader ↓ Firmware anterior ↓ Funcionamiento normal ``` El usuario no deberá realizar ninguna intervención. --- # 10. Conservación de configuración Las actualizaciones OTA nunca deberán eliminar: - configuración de red; - parámetros MQTT; - configuración Modbus; - usuarios; - nombres de dispositivos; - configuración específica de la aplicación. La configuración constituye un recurso independiente del firmware. --- # 11. Compatibilidad Antes de iniciar una actualización deberán comprobarse: - modelo de hardware; - aplicación instalada; - versión mínima requerida; - espacio disponible. No deberá instalarse un firmware incompatible. --- # 12. Gestión desde el Backend El Backend permitirá: - publicar versiones; - marcar versión estable; - retirar versiones; - consultar estado de despliegue; - conocer versión instalada; - consultar resultado de la actualización. --- # 13. Estrategias futuras La arquitectura deberá permitir incorporar: - actualización por grupos; - actualización progresiva; - canal estable; - canal beta; - canal desarrollo; - actualización programada; - actualización manual; - actualización automática. Estas capacidades no deberán requerir modificar Edge OS. --- # 14. Gestión de errores El sistema deberá detectar, entre otros: - descarga incompleta; - firmware corrupto; - incompatibilidad; - fallo de escritura; - fallo de arranque; - pérdida de alimentación durante la actualización. Siempre que sea posible deberá recuperarse automáticamente. --- # 15. Beneficios Para el usuario: - actualizaciones sencillas; - mayor seguridad; - menor riesgo. Para el administrador: - despliegue remoto; - control de versiones; - seguimiento de dispositivos. Para la plataforma: - evolución continua; - mantenimiento simplificado; - base para Fleet Management. --- # 16. Evolución futura El sistema OTA podrá ampliarse con: - firmas digitales; - cifrado; - firmware diferencial; - despliegues escalonados; - validaciones avanzadas; - políticas por cliente. La arquitectura actual deberá permitir incorporar estas capacidades sin rediseños importantes. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-004 Edge OS; - SPEC-005 Backend. Será utilizada por: - SPEC-008 Recovery; - SPEC-009 Provisioning; - SPEC-010 Fleet Management; - SPEC-011 Seguridad. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 - SPEC-004 - SPEC-005 **Desarrolla:** - Sistema OTA - Rollback automático **Implementación:** - Constituirá el mecanismo oficial de actualización remota de todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-008 — Recovery **Documento:** SPEC-008 **Título:** Recovery **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema Recovery de ESP Platform. Su objetivo es garantizar que un dispositivo pueda recuperarse de situaciones excepcionales sin requerir intervención técnica compleja y minimizando la necesidad de conexión física. Recovery constituye el último nivel de protección del dispositivo. --- # 2. Objetivos El sistema Recovery deberá permitir: - recuperar dispositivos que no puedan iniciar la aplicación correctamente; - restaurar un firmware operativo; - mantener la configuración siempre que sea posible; - facilitar el diagnóstico; - minimizar desplazamientos y mantenimiento presencial. --- # 3. Filosofía OTA evita fallos. Rollback corrige actualizaciones fallidas. Recovery permite recuperar situaciones que no pueden resolverse mediante OTA o Rollback. El objetivo es que un dispositivo resulte extremadamente difícil de dejar inutilizable. --- # 4. Relación con OTA El orden de actuación será siempre: ```text OTA ↓ Rollback ↓ Recovery ``` Recovery únicamente actuará cuando los mecanismos anteriores no puedan resolver el problema. --- # 5. Arquitectura general Recovery estará formado por: ```text Bootloader ↓ Recovery Manager ↓ Diagnóstico ↓ Opciones de recuperación ↓ Reinicio ``` El Recovery deberá formar parte de Edge OS. --- # 6. Situaciones de activación Recovery podrá iniciarse cuando ocurra alguna de las siguientes situaciones: - fallo repetido de arranque; - firmware inválido; - corrupción detectada; - interrupción grave durante una actualización; - solicitud manual del usuario; - orden remota autorizada (futuro). --- # 7. Modos de recuperación Inicialmente se contemplan los siguientes modos. ## Recuperación automática El dispositivo intentará restaurar el funcionamiento sin intervención del usuario. Ejemplos: - volver al firmware anterior; - restaurar parámetros seguros; - reiniciar servicios. --- ## Recuperación manual El usuario podrá iniciar Recovery mediante un procedimiento físico. Inicialmente se prevé: - pulsación prolongada de un botón durante el arranque. La combinación exacta dependerá del hardware. --- ## Recuperación desde la web Si el dispositivo conserva conectividad, podrá accederse a una interfaz Recovery simplificada. Permitirá: - consultar estado; - cargar un firmware; - reiniciar; - consultar diagnóstico. --- # 8. Conservación de configuración Recovery nunca deberá eliminar la configuración del usuario salvo que éste lo solicite expresamente. Se conservarán siempre que sea posible: - parámetros de red; - MQTT; - Modbus; - configuración de aplicación; - nombres; - usuarios. El borrado completo constituirá una acción independiente. --- # 9. Diagnóstico Recovery deberá proporcionar información suficiente para identificar la causa del problema. Ejemplos: - motivo de entrada en Recovery; - firmware activo; - firmware alternativo; - último error; - estado de memoria; - versión instalada. --- # 10. Restauración de firmware Recovery permitirá instalar nuevamente un firmware válido. Las fuentes previstas serán: - OTA (si existe conectividad); - Flasher Web mediante USB; - carga desde la interfaz Recovery (futuro). --- # 11. Factory Reset Recovery podrá ofrecer un modo Factory Reset. Este modo deberá: - restaurar configuración por defecto; - conservar el firmware operativo; - advertir previamente al usuario. El Factory Reset no constituye una actualización de firmware. --- # 12. Seguridad Las funciones Recovery deberán protegerse frente a accesos no autorizados. Especialmente: - reinstalación de firmware; - borrado de configuración; - restauración completa. Las acciones críticas requerirán autenticación cuando sea técnicamente posible. --- # 13. Integración con el Backend En futuras versiones Recovery podrá comunicarse con el Backend para: - informar de fallos; - solicitar firmware; - registrar incidencias; - permitir recuperación remota. La ausencia del Backend no deberá impedir el funcionamiento del Recovery. --- # 14. Integración con el Flasher Cuando Recovery no pueda resolver un problema mediante red, el dispositivo podrá recuperarse utilizando el Flasher Web. El procedimiento será idéntico al utilizado para un dispositivo nuevo. Esto garantiza un único proceso de recuperación física. --- # 15. Beneficios Para el usuario: - mayor tranquilidad; - menor riesgo de pérdida del dispositivo; - recuperación sencilla. Para el administrador: - menos intervenciones presenciales; - menor tiempo de mantenimiento. Para la plataforma: - mayor robustez; - mayor fiabilidad; - menor coste operativo. --- # 16. Evolución futura El sistema Recovery podrá incorporar posteriormente: - consola de diagnóstico; - copia de seguridad de configuración; - restauración desde Backup; - recuperación cifrada; - recuperación remota supervisada. La arquitectura deberá permitir añadir estas funciones sin rediseños importantes. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-004 Edge OS; - SPEC-006 Flasher Web; - SPEC-007 OTA y Rollback. Será utilizada posteriormente por: - SPEC-009 Provisioning; - SPEC-010 Fleet Management; - SPEC-011 Seguridad. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 - SPEC-004 - SPEC-006 - SPEC-007 **Desarrolla:** - Recovery Manager - Estrategia de recuperación **Implementación:** - Constituirá el mecanismo de recuperación de último nivel para todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-009 — Provisioning y QR **Documento:** SPEC-009 **Título:** Provisioning y QR **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema de Provisioning de ESP Platform. Su finalidad es permitir que un dispositivo recién instalado pueda incorporarse a la plataforma de forma sencilla, rápida y segura. El Provisioning constituye el proceso de transición entre un dispositivo recién flasheado y un dispositivo completamente operativo. --- # 2. Objetivos El sistema deberá permitir: - identificar un dispositivo de forma única; - configurar los parámetros mínimos necesarios; - registrar el dispositivo en el Backend; - simplificar al máximo la instalación; - minimizar errores humanos; - servir como base para instalaciones de gran volumen. --- # 3. Filosofía El proceso de alta deberá poder realizarlo un usuario sin conocimientos técnicos. La complejidad deberá recaer sobre la plataforma, nunca sobre el instalador. El objetivo es que poner en marcha un dispositivo resulte tan sencillo como instalar un producto comercial. --- # 4. Flujo general El proceso previsto será: ```text Flasheo ↓ Primer arranque ↓ Modo Provisioning ↓ Configuración inicial ↓ Registro en Backend ↓ Asignación de identidad ↓ Funcionamiento normal ``` Todo dispositivo nuevo deberá seguir este flujo. --- # 5. Identidad del dispositivo Cada dispositivo dispondrá de un identificador único permanente. Este identificador permitirá: - registrar el dispositivo; - identificarlo en el Backend; - asociarlo a un propietario; - localizarlo en Fleet Management. La identidad nunca deberá depender del nombre asignado por el usuario. --- # 6. Código QR Cada dispositivo podrá disponer de un código QR. El QR podrá contener información como: - identificador único; - modelo; - hardware; - versión mínima compatible; - URL de Provisioning. El formato exacto podrá evolucionar sin modificar el proceso general. --- # 7. Primer arranque Tras instalar un firmware por primera vez, el dispositivo iniciará automáticamente el modo Provisioning. Durante este proceso: - generará una configuración temporal; - habilitará la interfaz de configuración; - esperará la configuración inicial. Una vez completado el proceso pasará automáticamente al funcionamiento normal. --- # 8. Configuración inicial Inicialmente podrán configurarse: - nombre del dispositivo; - red; - parámetros MQTT; - parámetros Modbus; - ubicación (opcional); - descripción (opcional). Las aplicaciones podrán añadir parámetros específicos. --- # 9. Registro en el Backend Una vez completada la configuración, el dispositivo podrá registrarse automáticamente. El Backend almacenará: - identificador; - aplicación; - versión; - hardware; - fecha de alta; - propietario; - configuración básica. --- # 10. Repetición del proceso El usuario podrá reiniciar el proceso de Provisioning cuando sea necesario. Ejemplos: - cambio de propietario; - nueva instalación; - sustitución de red; - reconfiguración completa. No será necesario reinstalar el firmware para volver a ejecutar el Provisioning. --- # 11. Integración con el Flasher El Flasher Web podrá iniciar automáticamente el proceso de Provisioning tras finalizar la programación. Esto permitirá reducir el número de pasos necesarios para poner en marcha un dispositivo nuevo. --- # 12. Seguridad El Provisioning deberá impedir altas no autorizadas. La arquitectura deberá permitir incorporar posteriormente: - códigos de activación; - certificados; - tokens temporales; - autenticación mediante usuario. --- # 13. Experiencia de usuario El objetivo será reducir al mínimo la intervención manual. Idealmente: ```text Flashear ↓ Escanear QR ↓ Asignar nombre ↓ Finalizar ``` La experiencia deberá resultar intuitiva y consistente en todos los dispositivos. --- # 14. Beneficios Para el usuario: - instalación rápida; - menos errores; - configuración guiada. Para el administrador: - inventario automático; - dispositivos identificados; - menor tiempo de despliegue. Para la plataforma: - integración con Fleet Management; - integración con OTA; - crecimiento ordenado. --- # 15. Evolución futura El sistema podrá incorporar posteriormente: - configuración masiva; - importación de parámetros; - Provisioning mediante móvil; - Provisioning sin conexión; - plantillas de instalación; - asistentes inteligentes. --- # 16. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-006 Flasher Web; - SPEC-008 Recovery. Será utilizada posteriormente por: - SPEC-010 Fleet Management; - SPEC-011 Seguridad; - SPEC-012 Modelo SaaS. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-005 - SPEC-006 - SPEC-008 **Desarrolla:** - Provisioning - Identidad del dispositivo - QR **Implementación:** - Constituirá el proceso oficial de incorporación de nuevos dispositivos a ESP Platform. -------------------------------------------------------------------------------- # SPEC-010 — Fleet Management **Documento:** SPEC-010 **Título:** Fleet Management **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema Fleet Management de ESP Platform. Fleet Management constituye el conjunto de herramientas destinadas a administrar, supervisar y operar un gran número de dispositivos desde un único punto. Su objetivo es proporcionar una visión global del estado de toda la plataforma. --- # 2. Objetivos Fleet Management deberá permitir: - visualizar todos los dispositivos; - conocer su estado; - organizar dispositivos; - realizar operaciones masivas; - facilitar el mantenimiento; - reducir el tiempo de administración. --- # 3. Filosofía El número de dispositivos administrados no deberá modificar la experiencia del usuario. La plataforma deberá resultar igual de sencilla administrando: - un único dispositivo; - diez dispositivos; - cien dispositivos; - miles de dispositivos. La arquitectura deberá crecer sin modificar la forma de trabajar. --- # 4. Inventario central Fleet Management utilizará el inventario definido en el Backend. Cada dispositivo dispondrá de una ficha completa. Entre otros datos: - identificador; - nombre; - aplicación; - versión; - hardware; - estado; - propietario; - ubicación; - última conexión. --- # 5. Estado de los dispositivos Cada dispositivo podrá encontrarse, al menos, en uno de los siguientes estados. - En línea. - Desconectado. - Provisioning. - Actualizando. - Recovery. - Error. - Desconocido. El estado deberá actualizarse automáticamente siempre que sea posible. --- # 6. Organización Fleet Management permitirá organizar dispositivos mediante diferentes criterios. Ejemplos: - cliente; - ubicación; - edificio; - planta; - zona; - aplicación; - modelo. La arquitectura deberá permitir añadir nuevos criterios sin modificar el sistema. --- # 7. Búsqueda El usuario deberá localizar rápidamente cualquier dispositivo. Inicialmente podrán utilizarse filtros por: - nombre; - identificador; - aplicación; - versión; - hardware; - estado; - propietario. --- # 8. Operaciones masivas Fleet Management deberá permitir ejecutar operaciones sobre múltiples dispositivos. Ejemplos futuros: - actualizar firmware; - reiniciar; - cambiar configuración; - exportar información; - generar informes. Las operaciones deberán minimizar la intervención manual. --- # 9. Monitorización Fleet Management mostrará información general sobre el estado de la plataforma. Ejemplos: - dispositivos conectados; - dispositivos desconectados; - versiones instaladas; - actualizaciones pendientes; - incidencias. La información deberá presentarse de forma clara. --- # 10. Historial Cada dispositivo dispondrá de un historial. Ejemplos: - altas; - Provisioning; - OTA; - Recovery; - cambios de configuración; - incidencias. El historial facilitará el mantenimiento y el diagnóstico. --- # 11. Integración con OTA Fleet Management utilizará OTA para gestionar actualizaciones remotas. Permitirá: - seleccionar dispositivos; - elegir versión; - iniciar despliegues; - consultar resultados. OTA seguirá siendo el responsable de la actualización. Fleet Management únicamente coordinará el proceso. --- # 12. Integración con Recovery Cuando un dispositivo entre en Recovery, Fleet Management podrá reflejar dicha situación. En futuras versiones permitirá iniciar acciones de recuperación remota cuando la arquitectura lo permita. --- # 13. Panel principal La plataforma dispondrá de un panel principal con información resumida. Ejemplos: - número de dispositivos; - dispositivos en línea; - dispositivos con incidencias; - firmware más utilizado; - actualizaciones pendientes. El objetivo es proporcionar una visión global inmediata. --- # 14. Escalabilidad Fleet Management deberá funcionar correctamente independientemente del número de dispositivos. La arquitectura deberá diseñarse pensando en un crecimiento continuo. No deberán existir limitaciones derivadas del diseño inicial. --- # 15. Beneficios Para el usuario: - administración sencilla; - visión global; - menor tiempo de mantenimiento. Para el administrador: - operaciones centralizadas; - control de versiones; - diagnóstico rápido. Para la plataforma: - escalabilidad; - administración profesional; - evolución hacia SaaS. --- # 16. Evolución futura Fleet Management podrá incorporar posteriormente: - mapas; - planos; - dashboards personalizados; - mantenimiento predictivo; - inteligencia artificial; - reglas automáticas; - informes avanzados. La arquitectura deberá permitir estas ampliaciones sin rediseñar el sistema. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-007 OTA; - SPEC-008 Recovery; - SPEC-009 Provisioning. Será utilizada posteriormente por: - SPEC-011 Seguridad; - SPEC-012 Modelo SaaS; - SPEC-014 APIs. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-005 - SPEC-007 - SPEC-008 - SPEC-009 **Desarrolla:** - Fleet Management - Gestión centralizada de dispositivos **Implementación:** - Constituirá el centro de administración de todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-011 — Seguridad **Documento:** SPEC-011 **Título:** Seguridad **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la estrategia de seguridad de ESP Platform. Su objetivo es proteger los dispositivos, el Backend y las comunicaciones, garantizando un funcionamiento seguro sin comprometer la facilidad de uso. La seguridad deberá formar parte del diseño desde el inicio y no añadirse posteriormente. --- # 2. Objetivos La arquitectura deberá proteger: - dispositivos; - firmware; - comunicaciones; - usuarios; - credenciales; - APIs; - actualizaciones; - Backend. La seguridad deberá aplicarse de forma homogénea en toda la plataforma. --- # 3. Filosofía La seguridad deberá basarse en varios niveles de protección. No deberá depender de un único mecanismo. Cada componente protegerá únicamente aquello que le corresponda. La arquitectura evitará confiar ciegamente en cualquier elemento del sistema. --- # 4. Principios generales Se adoptarán los siguientes principios. - mínimo privilegio; - autenticación obligatoria; - autorización explícita; - separación de responsabilidades; - protección por defecto; - registro de acciones relevantes. --- # 5. Seguridad del dispositivo Cada dispositivo deberá proteger: - configuración; - API local; - interfaz web; - actualizaciones; - operaciones críticas. No deberá exponer servicios innecesarios. --- # 6. Seguridad del Backend El Backend deberá proteger: - usuarios; - sesiones; - APIs; - firmware; - auditoría; - base de datos. Todas las operaciones administrativas deberán requerir autenticación. --- # 7. Seguridad de las comunicaciones Inicialmente podrán utilizarse: - HTTP en entornos controlados; - MQTT; - Modbus TCP. La arquitectura deberá permitir evolucionar hacia: - HTTPS; - MQTT TLS; - certificados; - autenticación mutua. Sin modificar el diseño general. --- # 8. Gestión de credenciales Las credenciales nunca deberán almacenarse en texto plano. Siempre que resulte posible se utilizarán mecanismos seguros de almacenamiento. Las contraseñas deberán almacenarse utilizando algoritmos adecuados para este propósito. --- # 9. Seguridad OTA Toda actualización deberá validar: - origen; - integridad; - compatibilidad. La arquitectura permitirá incorporar posteriormente: - firmas digitales; - certificados; - validaciones criptográficas. --- # 10. Seguridad Recovery Las funciones Recovery deberán protegerse especialmente. Entre ellas: - reinstalación; - Factory Reset; - restauración. Estas operaciones requerirán autorización cuando sea técnicamente posible. --- # 11. Seguridad Provisioning El proceso de alta deberá impedir incorporaciones no autorizadas. La arquitectura permitirá incorporar: - tokens; - certificados; - códigos de activación; - validaciones temporales. --- # 12. Auditoría Todas las operaciones relevantes deberán registrarse. Ejemplos: - inicio de sesión; - OTA; - Recovery; - cambios de configuración; - creación de usuarios; - operaciones administrativas. Los registros facilitarán el diagnóstico y la trazabilidad. --- # 13. Gestión de permisos El sistema distinguirá entre autenticación y autorización. Autenticación: - identifica al usuario. Autorización: - determina qué puede hacer. La arquitectura deberá permitir ampliar el sistema de permisos sin rediseños. --- # 14. Evolución futura La plataforma podrá incorporar posteriormente: - autenticación multifactor; - certificados cliente; - HSM; - Secure Boot; - Flash Encryption; - VPN; - Zero Trust. La arquitectura deberá permitir estas mejoras sin modificar el funcionamiento general. --- # 15. Beneficios Para el usuario: - mayor confianza; - protección de datos; - menor riesgo. Para el administrador: - trazabilidad; - control de accesos; - auditoría. Para la plataforma: - arquitectura robusta; - crecimiento seguro; - preparación para entornos profesionales. --- # 16. Relación con otras SPEC Esta especificación complementa todas las SPEC anteriores. Especialmente: - SPEC-004 Edge OS; - SPEC-005 Backend; - SPEC-007 OTA; - SPEC-008 Recovery; - SPEC-009 Provisioning; - SPEC-010 Fleet Management. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-010 **Desarrolla:** - Política de seguridad - Protección de la plataforma **Implementación:** - Constituirá la referencia común para todas las decisiones relacionadas con la seguridad de ESP Platform. -------------------------------------------------------------------------------- # SPEC-012 — Modelo SaaS **Documento:** SPEC-012 **Título:** Modelo SaaS **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la evolución de ESP Platform hacia un modelo SaaS (Software as a Service). El objetivo es que la arquitectura diseñada para una instalación local pueda evolucionar de forma natural hacia un servicio alojado para múltiples clientes sin necesidad de rediseñar la plataforma. El modelo SaaS constituye una evolución de la arquitectura, no una arquitectura diferente. --- # 2. Objetivos El modelo SaaS deberá permitir: - múltiples clientes; - múltiples usuarios; - múltiples organizaciones; - múltiples instalaciones; - aislamiento entre clientes; - administración centralizada; - crecimiento prácticamente ilimitado. --- # 3. Filosofía La plataforma deberá diseñarse desde el primer día pensando en un futuro SaaS, aunque la primera versión funcione únicamente en una instalación local. Las decisiones actuales no deberán impedir esa evolución. --- # 4. Evolución prevista La evolución natural será: ```text Instalación local ↓ Servidor único ↓ Varios usuarios ↓ Varios clientes ↓ Multiempresa ↓ SaaS ``` Cada etapa reutilizará la arquitectura existente. --- # 5. Organización El sistema distinguirá conceptualmente entre: - plataforma; - organización; - usuario; - dispositivo. Cada organización administrará exclusivamente sus propios recursos. --- # 6. Aislamiento Los datos de una organización nunca deberán mezclarse con los de otra. El Backend deberá garantizar el aislamiento lógico entre clientes. La arquitectura permitirá evolucionar posteriormente hacia otros mecanismos de aislamiento si fuese necesario. --- # 7. Gestión de usuarios Cada organización podrá disponer de sus propios usuarios. Inicialmente podrán existir perfiles como: - administrador; - técnico; - operador; - solo lectura. La arquitectura permitirá ampliar estos perfiles. --- # 8. Dispositivos Cada dispositivo pertenecerá a una única organización. El cambio de propietario deberá realizarse mediante los mecanismos definidos en Provisioning. Fleet Management mostrará únicamente los dispositivos autorizados para cada organización. --- # 9. Firmware El repositorio de firmware podrá evolucionar para soportar: - firmware global; - firmware privado; - firmware experimental; - versiones específicas por cliente. La arquitectura deberá permitir estas opciones sin modificar el funcionamiento básico. --- # 10. Administración La plataforma distinguirá entre: Administración del sistema. Administración de la organización. Administración de dispositivos. Cada nivel dispondrá únicamente de las funciones que le correspondan. --- # 11. Escalabilidad El crecimiento del número de clientes no deberá requerir cambios importantes en la arquitectura. La plataforma deberá poder crecer horizontalmente incorporando nuevos servicios cuando sea necesario. --- # 12. Personalización Cada organización podrá personalizar determinados elementos. Ejemplos futuros: - nombre; - logotipo; - idioma; - zonas horarias; - parámetros por defecto; - políticas de actualización. --- # 13. Licenciamiento La arquitectura permitirá incorporar distintos modelos de licencia. Ejemplos: - gratuito; - profesional; - empresarial; - OEM. La gestión de licencias no deberá afectar al funcionamiento interno de los dispositivos. --- # 14. Beneficios Para el usuario: - administración centralizada; - acceso desde cualquier lugar; - crecimiento sencillo. Para el administrador: - mantenimiento simplificado; - reutilización de infraestructura; - despliegue rápido. Para el proyecto: - evolución comercial; - modelo de negocio; - escalabilidad. --- # 15. Evolución futura La arquitectura permitirá incorporar posteriormente: - alta automática de organizaciones; - facturación; - suscripciones; - marketplace; - API pública; - integraciones de terceros. --- # 16. Relación con otras SPEC Esta especificación amplía: - SPEC-005 Backend; - SPEC-010 Fleet Management; - SPEC-011 Seguridad. Servirá de base para: - SPEC-013 Modelo de Datos; - SPEC-014 APIs. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-011 **Desarrolla:** - Arquitectura SaaS - Multiempresa - Multiusuario **Implementación:** - Permitirá evolucionar ESP Platform desde una instalación local hasta una plataforma SaaS sin rediseñar su arquitectura. -------------------------------------------------------------------------------- # SPEC-013 — Modelo de Datos **Documento:** SPEC-013 **Título:** Modelo de Datos **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el modelo conceptual de datos de ESP Platform. Su finalidad es establecer las entidades principales de la plataforma y las relaciones existentes entre ellas. No constituye un diseño físico de base de datos, sino el modelo lógico que servirá como referencia para PostgreSQL y para las APIs del Backend. --- # 2. Objetivos El modelo deberá: - representar toda la plataforma; - evitar duplicidad de información; - facilitar la escalabilidad; - mantener independencia respecto al motor de base de datos; - servir de referencia para toda la implementación. --- # 3. Filosofía Cada entidad deberá representar un único concepto del negocio. Las relaciones deberán ser claras y evitar dependencias innecesarias. El modelo deberá poder evolucionar incorporando nuevas entidades sin alterar las existentes. --- # 4. Entidades principales El modelo inicial estará formado por las siguientes entidades. - Organización - Usuario - Dispositivo - Firmware - Aplicación - Hardware - OTA - Provisioning - Recovery - Auditoría - Grupo - Configuración Estas entidades constituyen el núcleo de la plataforma. --- # 5. Organización Representa una empresa, instalación o cliente. Ejemplos de atributos: - identificador; - nombre; - descripción; - estado; - fecha de creación. Una organización podrá contener múltiples usuarios y múltiples dispositivos. --- # 6. Usuario Representa una persona autorizada para utilizar la plataforma. Ejemplos de atributos: - identificador; - nombre; - correo electrónico; - contraseña; - perfil; - estado. Cada usuario pertenecerá a una organización. --- # 7. Dispositivo Representa un equipo físico. Ejemplos de atributos: - identificador único; - nombre; - hardware; - aplicación; - firmware; - estado; - dirección IP; - MAC; - última conexión. Cada dispositivo pertenecerá a una única organización. --- # 8. Firmware Representa una versión concreta de software. Ejemplos de atributos: - nombre; - versión; - aplicación; - hardware compatible; - fecha; - checksum; - tamaño. Un firmware podrá instalarse en múltiples dispositivos compatibles. --- # 9. Aplicación Representa el tipo funcional del firmware. Ejemplos: - AZ-TEMP; - AZ-POWER; - AZ-NFC; - AZ-IO; - AZ-RELAY. Cada firmware pertenecerá a una aplicación. --- # 10. Hardware Representa la plataforma física. Ejemplos: - ESP32 DevKit; - ESP32-S3; - ESP32-C6; - futuras placas propias. Permitirá comprobar compatibilidades antes de instalar firmware. --- # 11. OTA Representa una operación de actualización. Ejemplos de atributos: - dispositivo; - firmware origen; - firmware destino; - fecha; - estado; - resultado. El historial OTA permanecerá asociado al dispositivo. --- # 12. Provisioning Representa el alta inicial de un dispositivo. Permitirá almacenar: - fecha; - instalador; - organización; - parámetros iniciales. --- # 13. Recovery Representa un proceso de recuperación. Permitirá registrar: - motivo; - fecha; - firmware recuperado; - resultado. --- # 14. Auditoría Representa cualquier operación relevante realizada en la plataforma. Ejemplos: - inicio de sesión; - OTA; - alta; - cambios de configuración; - operaciones administrativas. --- # 15. Grupo Permitirá organizar dispositivos. Ejemplos: - edificio; - planta; - laboratorio; - cliente; - proyecto. Un dispositivo podrá pertenecer a varios grupos si la arquitectura futura así lo requiere. --- # 16. Configuración Representa parámetros persistentes. Existirán dos grandes categorías: Configuración del sistema. Configuración específica de la aplicación. Ambas deberán permanecer separadas conceptualmente. --- # 17. Relaciones principales Conceptualmente: ```text Organización │ ├──── Usuarios │ └──── Dispositivos │ ├──── Firmware │ ├──── Aplicación │ ├──── Hardware │ ├──── OTA │ ├──── Recovery │ └──── Configuración ``` Este modelo constituye la referencia general de toda la plataforma. --- # 18. Evolución futura El modelo permitirá incorporar posteriormente nuevas entidades. Ejemplos: - licencias; - suscripciones; - mapas; - dashboards; - reglas; - IA; - mantenimiento predictivo. Estas ampliaciones no deberán requerir rediseñar el núcleo del modelo. --- # 19. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-010 Fleet Management; - SPEC-012 SaaS. Servirá de base para: - SPEC-014 APIs; - implementación PostgreSQL; - implementación JPA. --- # 20. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-012 **Desarrolla:** - Modelo lógico de datos **Implementación:** - Constituirá la referencia conceptual para toda la persistencia de ESP Platform. -------------------------------------------------------------------------------- # SPEC-014 — APIs **Documento:** SPEC-014 **Título:** APIs **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la arquitectura general de las APIs de ESP Platform. Las APIs constituyen el mecanismo oficial de comunicación entre los distintos componentes de la plataforma. Toda comunicación entre aplicaciones deberá realizarse mediante APIs claramente definidas. --- # 2. Objetivos La arquitectura de APIs deberá: - mantener desacoplados los componentes; - facilitar la reutilización; - simplificar futuras integraciones; - garantizar estabilidad; - facilitar el versionado. --- # 3. Filosofía Las APIs representan contratos. Una API nunca deberá depender de la implementación interna de un componente. Mientras el contrato permanezca estable, la implementación podrá evolucionar libremente. --- # 4. Arquitectura Inicialmente existirán tres grandes grupos de APIs. ## Backend API Utilizada por: - Frontend Web; - futuras Apps móviles; - herramientas externas. --- ## Edge API Implementada por Edge OS. Permitirá administrar el dispositivo localmente. --- ## Internal API Utilizada exclusivamente entre servicios internos del Backend. No estará disponible para aplicaciones externas. --- # 5. Principios generales Todas las APIs deberán cumplir: - simplicidad; - coherencia; - estabilidad; - documentación; - versionado; - seguridad. --- # 6. Formato Las APIs utilizarán inicialmente: - HTTP; - JSON; - UTF-8. La arquitectura permitirá incorporar posteriormente otros formatos cuando resulte necesario. --- # 7. Versionado Todas las APIs públicas deberán estar versionadas. Ejemplo: ```text /api/v1/ ``` Las nuevas versiones nunca deberán romper la compatibilidad sin una justificación clara. --- # 8. Convenciones Las rutas deberán ser: - descriptivas; - consistentes; - predecibles. Ejemplos: ```text /api/v1/devices /api/v1/firmware /api/v1/users /api/v1/groups ``` --- # 9. Operaciones Siempre que resulte razonable se utilizarán los métodos HTTP estándar. Ejemplos: GET POST PUT DELETE PATCH Cada operación deberá tener una responsabilidad claramente definida. --- # 10. Respuestas Las respuestas deberán seguir un formato uniforme. Conceptualmente: ```json { "success": true, "data": {}, "message": "" } ``` Los errores deberán seguir la misma filosofía. --- # 11. Códigos de estado Se utilizarán los códigos HTTP apropiados. Ejemplos: 200 201 400 401 403 404 409 500 No deberán utilizarse códigos ambiguos. --- # 12. Autenticación Las APIs protegidas requerirán autenticación. La arquitectura permitirá evolucionar hacia distintos mecanismos sin modificar las rutas. --- # 13. Documentación Toda API pública deberá estar documentada. La documentación deberá generarse automáticamente siempre que sea posible. --- # 14. Integración Las APIs constituirán el único mecanismo oficial de integración. Ejemplos: - Frontend; - aplicaciones móviles; - automatizaciones; - terceros. No deberán realizarse accesos directos a la base de datos. --- # 15. Evolución futura La arquitectura permitirá incorporar posteriormente: - WebSocket; - GraphQL; - gRPC; - Streaming; - APIs públicas. Estas ampliaciones no deberán afectar al diseño actual. --- # 16. Beneficios Para el desarrollador: - menor acoplamiento; - mayor reutilización; - mantenimiento sencillo. Para la plataforma: - crecimiento ordenado; - integración sencilla; - evolución futura. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-013 Modelo de Datos. Será utilizada por prácticamente todas las implementaciones de ESP Platform. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-013 **Desarrolla:** - Arquitectura de APIs - Contratos de comunicación **Implementación:** - Constituirá la referencia oficial para todas las APIs desarrolladas dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-015 — Estándares de Desarrollo **Documento:** SPEC-015 **Título:** Estándares de Desarrollo **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define los estándares generales de desarrollo que deberán seguir todos los componentes de ESP Platform. Su objetivo es garantizar que todo el software desarrollado mantenga un nivel homogéneo de calidad, legibilidad y mantenibilidad. Estas normas serán aplicables tanto al código desarrollado manualmente como al generado mediante inteligencia artificial. --- # 2. Objetivos Los estándares deberán garantizar: - uniformidad; - claridad; - modularidad; - reutilización; - facilidad de mantenimiento; - facilidad de revisión. --- # 3. Filosofía Todo desarrollo deberá priorizar: - simplicidad; - legibilidad; - estabilidad; - mantenibilidad. La complejidad solo se aceptará cuando aporte un beneficio claramente justificado. --- # 4. Modularidad Cada módulo deberá tener una única responsabilidad. Los módulos deberán comunicarse mediante interfaces claramente definidas. Las dependencias entre módulos deberán mantenerse al mínimo. --- # 5. Organización del código Cada proyecto deberá mantener una estructura coherente. La organización deberá facilitar la localización rápida de cualquier componente. No deberán mezclarse responsabilidades diferentes dentro del mismo módulo. --- # 6. Reutilización Antes de desarrollar una nueva funcionalidad deberá comprobarse si ya existe un componente reutilizable. La duplicación de código deberá evitarse siempre que resulte razonable. --- # 7. Documentación Todo componente relevante deberá estar documentado. La documentación deberá explicar: - propósito; - responsabilidades; - funcionamiento general; - limitaciones. La documentación deberá mantenerse sincronizada con el código. --- # 8. Gestión de errores Los errores deberán tratarse explícitamente. No deberán ignorarse excepciones ni situaciones anómalas. Siempre que resulte posible deberán registrarse para facilitar el diagnóstico. --- # 9. Registro de eventos Las operaciones relevantes deberán generar información de diagnóstico. Los mensajes deberán ser claros y útiles. No deberán utilizarse mensajes ambiguos o poco descriptivos. --- # 10. Calidad del código El código deberá ser: - legible; - consistente; - fácilmente revisable; - fácilmente ampliable. La claridad tendrá prioridad sobre la optimización prematura. --- # 11. Compatibilidad Las nuevas funcionalidades no deberán romper el funcionamiento existente salvo decisión explícita. La compatibilidad deberá considerarse durante todo el ciclo de desarrollo. --- # 12. Pruebas Toda funcionalidad importante deberá verificarse antes de considerarse finalizada. Siempre que resulte posible deberán realizarse: - pruebas unitarias; - pruebas de integración; - pruebas funcionales. --- # 13. Control de versiones Todo el desarrollo deberá gestionarse mediante Git. Los cambios deberán mantenerse organizados y ser fácilmente identificables. --- # 14. Dependencias Las dependencias externas deberán mantenerse al mínimo. Solo se incorporarán cuando aporten un beneficio claro para el proyecto. Siempre que resulte posible deberán utilizarse componentes ampliamente mantenidos. --- # 15. Evolución La arquitectura deberá facilitar futuras ampliaciones. Cada nueva funcionalidad deberá integrarse respetando las decisiones arquitectónicas ya establecidas. No deberán introducirse soluciones aisladas que rompan la coherencia del proyecto. --- # 16. Beneficios Para el desarrollador: - mayor productividad; - menor complejidad; - revisiones más sencillas. Para el proyecto: - mantenimiento reducido; - evolución ordenada; - menor deuda técnica. --- # 17. Relación con otras SPEC Esta especificación complementa todas las SPEC anteriores. Será utilizada especialmente junto con: - SPEC-004 Edge OS; - SPEC-005 Backend; - SPEC-019 Normas para Codex. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-014 **Desarrolla:** - Estándares generales de desarrollo **Implementación:** - Constituirá la referencia común para cualquier desarrollo realizado dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-016 — Estándares UI/UX **Documento:** SPEC-016 **Título:** Estándares UI/UX **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define los estándares de interfaz de usuario (UI) y experiencia de usuario (UX) que deberán seguir todos los componentes de ESP Platform. Su objetivo es proporcionar una experiencia homogénea, intuitiva y profesional en toda la plataforma, independientemente del dispositivo o aplicación utilizada. --- # 2. Objetivos La experiencia de usuario deberá transmitir: - simplicidad; - claridad; - rapidez; - consistencia; - sensación de producto profesional. Todas las aplicaciones deberán compartir la misma filosofía visual. --- # 3. Filosofía La interfaz nunca deberá recordar a una herramienta técnica de desarrollo. ESP Platform deberá percibirse como un producto comercial de alta calidad. La complejidad técnica deberá permanecer oculta siempre que sea posible. --- # 4. Consistencia Todos los componentes deberán compartir: - misma identidad visual; - misma terminología; - misma organización; - mismos criterios de navegación; - mismos mensajes. El usuario no deberá aprender una interfaz diferente para cada módulo. --- # 5. Diseño El diseño deberá priorizar: - espacios amplios; - buena legibilidad; - pocos elementos simultáneos; - navegación sencilla; - jerarquía visual clara. La información importante deberá destacar de forma natural. --- # 6. Navegación Toda la plataforma deberá resultar fácilmente navegable. El usuario deberá saber siempre: - dónde se encuentra; - qué está haciendo; - qué ocurrirá al realizar una acción. --- # 7. Formularios Los formularios deberán minimizar el número de campos. Siempre que sea posible: - valores por defecto; - autocompletado; - validación inmediata; - mensajes claros. --- # 8. Mensajes Todos los mensajes deberán ser: - comprensibles; - breves; - útiles; - consistentes. Nunca deberán mostrarse errores técnicos al usuario cuando puedan sustituirse por explicaciones más claras. --- # 9. Colores Los colores deberán utilizarse con un propósito. Ejemplos: - éxito; - advertencia; - error; - información. El color nunca deberá ser el único mecanismo para transmitir información importante. --- # 10. Iconografía Los iconos deberán ser: - sencillos; - reconocibles; - consistentes. Todo icono importante deberá ir acompañado de texto cuando sea necesario. --- # 11. Adaptabilidad Toda la plataforma deberá funcionar correctamente en: - ordenador; - tablet; - teléfono móvil. El diseño será responsive desde el inicio. --- # 12. Rendimiento La interfaz deberá responder con rapidez. El usuario deberá recibir siempre información sobre el progreso de operaciones largas. Ejemplos: - barras de progreso; - indicadores de carga; - mensajes de estado. --- # 13. Accesibilidad Siempre que resulte posible deberán seguirse criterios básicos de accesibilidad. Ejemplos: - contraste adecuado; - tamaño suficiente; - navegación mediante teclado; - etiquetas descriptivas. --- # 14. Experiencia del instalador Las operaciones habituales deberán requerir el menor número posible de pasos. Ejemplos: - Flasher; - Provisioning; - OTA. El objetivo será reducir tiempos de instalación y errores. --- # 15. Beneficios Para el usuario: - aprendizaje rápido; - menor frustración; - sensación de calidad. Para el administrador: - menor tiempo de formación; - menor número de incidencias. Para la plataforma: - identidad propia; - coherencia; - diferenciación frente a otras soluciones. --- # 16. Evolución futura La identidad visual podrá evolucionar. Sin embargo deberán mantenerse: - coherencia; - simplicidad; - facilidad de uso. Las mejoras visuales nunca deberán perjudicar la usabilidad. --- # 17. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-006 Flasher Web; - SPEC-009 Provisioning; - SPEC-010 Fleet Management. Será aplicable a toda interfaz desarrollada para ESP Platform. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-015 **Desarrolla:** - Estándares UI - Estándares UX - Experiencia de usuario **Implementación:** - Constituirá la referencia común para todas las interfaces de usuario desarrolladas dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-017 — Convenciones de Nomenclatura **Documento:** SPEC-017 **Título:** Convenciones de Nomenclatura **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define las convenciones de nomenclatura que deberán utilizarse en todos los componentes de ESP Platform. Su objetivo es mantener una terminología uniforme en el código, la documentación, la infraestructura y los dispositivos. Una nomenclatura coherente reduce errores y facilita el mantenimiento del proyecto. --- # 2. Objetivos Las convenciones deberán garantizar: - claridad; - coherencia; - legibilidad; - escalabilidad; - facilidad de búsqueda. Todos los desarrollos deberán seguir estas normas. --- # 3. Filosofía Cada elemento deberá tener un único nombre oficial. No deberán utilizarse nombres diferentes para representar el mismo concepto. La terminología utilizada en la documentación deberá coincidir con la utilizada en el software. --- # 4. Nombre del proyecto El nombre oficial será: ESP Platform Los componentes internos utilizarán este nombre como referencia. --- # 5. Aplicaciones Las aplicaciones oficiales seguirán el prefijo: AZ- Ejemplos: - AZ-TEMP - AZ-POWER - AZ-NFC - AZ-IO - AZ-RELAY Nuevas aplicaciones deberán respetar este criterio. --- # 6. Edge OS El sistema operativo común recibirá el nombre: Aeizoon Edge OS No deberán utilizarse variantes diferentes. --- # 7. Backend El Backend se identificará como: ESP Platform Backend Los módulos internos podrán disponer de nombres específicos siempre que mantengan coherencia. --- # 8. Firmware Las versiones de firmware deberán identificarse mediante: - aplicación; - versión; - hardware. Ejemplo conceptual: AZ-TEMP v1.2.0 ESP32-S3 --- # 9. Hardware Los modelos deberán identificarse mediante nombres claros y consistentes. Ejemplos: - ESP32 DevKit - ESP32-S3 - ESP32-C6 - Aeizoon Board (futuro) --- # 10. Base de datos Las entidades deberán utilizar nombres descriptivos. Las tablas representarán conceptos del negocio. Se evitarán abreviaturas innecesarias. --- # 11. APIs Las rutas deberán mantener una estructura uniforme. Ejemplo: /api/v1/devices /api/v1/firmware /api/v1/users /api/v1/groups --- # 12. Código Las clases, paquetes y módulos deberán utilizar nombres descriptivos. No deberán utilizarse nombres genéricos como: - Utils - Misc - Temp - Test Salvo justificación clara. --- # 13. Variables Los nombres deberán describir claramente su propósito. Se evitarán abreviaturas ambiguas. La claridad tendrá prioridad sobre la brevedad. --- # 14. Documentación Toda la documentación deberá utilizar la misma terminología definida en esta especificación. No deberán coexistir nombres alternativos para un mismo concepto. --- # 15. Evolución La incorporación de nuevos nombres deberá respetar los criterios definidos en este documento. Cuando aparezca un nuevo concepto, deberá asignársele un nombre único antes de comenzar su implementación. --- # 16. Beneficios Para el desarrollador: - mayor claridad; - menor confusión; - búsqueda más sencilla. Para el proyecto: - documentación consistente; - mantenimiento simplificado; - menor deuda técnica. --- # 17. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-004 Edge OS; - SPEC-005 Backend; - SPEC-014 APIs; - SPEC-015 Estándares de Desarrollo. Será aplicable a todo el ecosistema ESP Platform. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-016 **Desarrolla:** - Convenciones de nomenclatura - Terminología oficial **Implementación:** - Constituirá la referencia oficial para todos los nombres utilizados dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-018 — Architecture Decision Records (ADR) **Documento:** SPEC-018 **Título:** Architecture Decision Records (ADR) **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el uso de Architecture Decision Records (ADR) dentro de ESP Platform. Su objetivo es conservar de forma permanente las decisiones arquitectónicas relevantes adoptadas durante el desarrollo del proyecto. Los ADR permitirán comprender no solo qué se decidió, sino también por qué se tomó cada decisión. --- # 2. Objetivos Los ADR deberán permitir: - documentar decisiones importantes; - justificar alternativas descartadas; - preservar el conocimiento del proyecto; - facilitar futuras revisiones; - reducir la dependencia del conocimiento personal. --- # 3. Filosofía Toda decisión arquitectónica significativa deberá quedar registrada. Las decisiones pequeñas del desarrollo diario no requerirán un ADR. Solo deberán documentarse aquellas decisiones cuyo impacto sea relevante para la evolución del proyecto. --- # 4. Cuándo crear un ADR Se generará un ADR cuando exista una decisión relacionada con: - arquitectura; - tecnologías; - seguridad; - almacenamiento; - comunicaciones; - interfaces; - despliegue; - mantenimiento. --- # 5. Contenido mínimo Cada ADR deberá incluir como mínimo: - identificador; - fecha; - estado; - contexto; - decisión adoptada; - consecuencias. --- # 6. Estados Los ADR podrán encontrarse en alguno de los siguientes estados: - Propuesto. - Aprobado. - Sustituido. - Obsoleto. El historial deberá conservarse. --- # 7. Numeración Cada ADR dispondrá de un identificador único. Ejemplos: ADR-001 ADR-002 ADR-003 La numeración será secuencial. --- # 8. Relación con las SPEC Las SPEC definen la arquitectura general. Los ADR documentan decisiones concretas tomadas durante la implementación. Las SPEC constituyen documentos permanentes. Los ADR reflejan la evolución del proyecto. --- # 9. Modificación Un ADR aprobado no deberá modificarse. Si cambia una decisión, deberá generarse un nuevo ADR indicando cuál sustituye al anterior. Esto permitirá conservar el historial completo. --- # 10. Responsabilidad Los ADR podrán ser redactados por: - desarrolladores; - arquitectos; - Codex. La aprobación corresponderá al responsable del proyecto. --- # 11. Beneficios Los ADR permitirán: - comprender decisiones antiguas; - evitar repetir análisis ya realizados; - facilitar la incorporación de nuevos desarrolladores; - mejorar la continuidad del proyecto. --- # 12. Evolución futura La plataforma podrá incorporar herramientas para consultar automáticamente los ADR. También podrán relacionarse con: - incidencias; - versiones; - Roadmap; - documentación técnica. --- # 13. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-001 Filosofía; - SPEC-002 Arquitectura; - SPEC-015 Estándares de Desarrollo. Será aplicable a todas las decisiones arquitectónicas futuras. --- # 14. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-017 **Desarrolla:** - Gestión de Architecture Decision Records **Implementación:** - Constituirá el procedimiento oficial para registrar las decisiones arquitectónicas relevantes de ESP Platform. -------------------------------------------------------------------------------- # SPEC-019 — Normas para Codex **Documento:** SPEC-019 **Título:** Normas para Codex **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define las normas generales que deberán seguir Codex y cualquier otro agente de inteligencia artificial durante el desarrollo de ESP Platform. Su objetivo es garantizar que toda implementación respete la arquitectura, los estándares y la filosofía del proyecto. --- # 2. Objetivos Codex deberá: - respetar la arquitectura definida; - mantener la coherencia del proyecto; - minimizar la deuda técnica; - documentar su trabajo; - facilitar el mantenimiento futuro. --- # 3. Filosofía Codex actuará como desarrollador del proyecto, no como diseñador de la arquitectura. La arquitectura se encuentra definida en las SPEC. Las modificaciones arquitectónicas deberán proponerse, nunca aplicarse automáticamente. --- # 4. Alcance Codex podrá: - implementar; - refactorizar; - documentar; - corregir errores; - realizar pruebas; - mejorar el código. No deberá modificar decisiones arquitectónicas sin aprobación expresa. --- # 5. Principios generales Toda implementación deberá respetar: - simplicidad; - modularidad; - claridad; - mantenibilidad; - reutilización. --- # 6. Arquitectura Antes de implementar cualquier funcionalidad, Codex deberá comprobar que resulta coherente con las SPEC existentes. En caso de conflicto deberá informar antes de continuar. --- # 7. Reutilización Antes de crear un nuevo componente deberá comprobar si ya existe uno reutilizable. La duplicación de código deberá evitarse siempre que sea posible. --- # 8. Documentación Toda funcionalidad relevante deberá ir acompañada de la documentación correspondiente. La documentación deberá mantenerse sincronizada con el código. --- # 9. Calidad Codex deberá priorizar: - código legible; - estructura clara; - responsabilidades bien definidas; - bajo acoplamiento. La claridad tendrá prioridad sobre soluciones excesivamente complejas. --- # 10. Validación Toda funcionalidad implementada deberá verificarse antes de considerarse terminada. Siempre que resulte posible deberán realizarse pruebas adecuadas. Los resultados deberán documentarse. --- # 11. Cambios Los cambios importantes deberán explicarse. Cuando una implementación implique decisiones relevantes, Codex deberá indicar: - qué cambia; - por qué cambia; - consecuencias. --- # 12. Comunicación Las respuestas deberán ser: - claras; - técnicas; - concisas; - orientadas a la implementación. Cuando exista incertidumbre deberá indicarse explícitamente. --- # 13. Gestión de incidencias Ante un problema, Codex deberá: - identificar la causa; - proponer alternativas; - justificar la solución adoptada. No deberá ocultar limitaciones conocidas. --- # 14. Relación con los ADR Cuando una decisión implique un cambio arquitectónico significativo, Codex deberá proponer la creación de un nuevo ADR. Las SPEC únicamente cambiarán mediante decisión expresa del responsable del proyecto. --- # 15. Relación con el Roadmap Codex deberá respetar el Roadmap definido para ESP Platform. No deberá adelantar fases sin autorización. Cada implementación deberá corresponder con la fase activa del proyecto. --- # 16. Beneficios Estas normas permitirán: - mantener la coherencia; - reducir errores; - facilitar revisiones; - preservar la arquitectura; - acelerar el desarrollo. --- # 17. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-015 Estándares de Desarrollo; - SPEC-018 ADR. Será aplicable durante todo el ciclo de vida del proyecto. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-018 **Desarrolla:** - Normas de trabajo para Codex - Reglas de implementación **Implementación:** - Constituirá el marco de trabajo obligatorio para cualquier agente de inteligencia artificial que participe en el desarrollo de ESP Platform. -------------------------------------------------------------------------------- # SPEC-020 — Roadmap **Documento:** SPEC-020 **Título:** Roadmap **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el Roadmap oficial de ESP Platform. Su objetivo es establecer el orden de ejecución del proyecto para garantizar un desarrollo progresivo, coherente y alineado con la arquitectura definida en las SPEC anteriores. El Roadmap constituye la planificación de alto nivel del proyecto. --- # 2. Filosofía El desarrollo deberá realizarse mediante fases incrementales. Cada fase deberá generar un resultado funcional antes de comenzar la siguiente. No deberán iniciarse fases posteriores mientras la fase actual no se considere suficientemente estable. --- # 3. MVP El primer objetivo del proyecto será disponer de un MVP completamente funcional. El MVP deberá permitir: - instalar firmware mediante Flasher Web; - arrancar un ESP32; - acceder a la interfaz web del dispositivo; - gestionar firmware desde el Backend. La finalidad del MVP será validar toda la arquitectura definida. --- # 4. Fase 1 Infraestructura. Objetivos: - crear la máquina virtual; - desplegar el Backend; - configurar PostgreSQL; - desplegar el Frontend; - preparar el repositorio de firmware. Resultado esperado: Infraestructura completamente operativa. --- # 5. Fase 2 Flasher Web. Objetivos: - cargar firmware; - seleccionar hardware; - conectar mediante USB; - flashear un ESP32; - verificar el resultado. Resultado esperado: Primer dispositivo funcionando. --- # 6. Fase 3 Edge OS. Objetivos: - estructura común del firmware; - configuración; - interfaz web; - MQTT; - Modbus TCP. Resultado esperado: Primer firmware oficial. --- # 7. Fase 4 Provisioning. Objetivos: - alta automática; - identidad; - QR; - registro en Backend. Resultado esperado: Primer dispositivo integrado completamente en ESP Platform. --- # 8. Fase 5 OTA. Objetivos: - actualización remota; - verificación; - rollback. Resultado esperado: Actualizaciones seguras. --- # 9. Fase 6 Recovery. Objetivos: - recuperación; - Factory Reset; - diagnóstico. Resultado esperado: Arquitectura resiliente. --- # 10. Fase 7 Fleet Management. Objetivos: - inventario; - monitorización; - operaciones remotas. Resultado esperado: Administración centralizada. --- # 11. Fase 8 Aplicaciones. Desarrollo progresivo de: - AZ-TEMP; - AZ-POWER; - AZ-NFC; - AZ-IO; - AZ-RELAY. Cada aplicación reutilizará Edge OS. --- # 12. Fase 9 Industrialización. Objetivos: - hardware propio; - fabricación; - certificaciones; - documentación; - soporte. Resultado esperado: Producto comercial. --- # 13. Fase 10 Modelo SaaS. Objetivos: - multiempresa; - multiusuario; - licencias; - suscripciones; - despliegue cloud. Resultado esperado: ESP Platform como servicio. --- # 14. Prioridades El orden de prioridad será siempre: 1. Arquitectura. 2. Estabilidad. 3. Funcionalidad. 4. Rendimiento. 5. Optimización. Nunca deberá sacrificarse la arquitectura por acelerar una implementación. --- # 15. Gestión del conocimiento Durante todo el desarrollo deberán mantenerse actualizados: - SPEC; - ADR; - documentación técnica; - Roadmap. La documentación formará parte del producto. --- # 16. Evolución El Roadmap podrá ampliarse. Las nuevas fases deberán respetar la arquitectura definida en las SPEC anteriores. Las modificaciones importantes deberán documentarse mediante ADR. --- # 17. Finalización Se considerará completada una fase cuando: - los objetivos se hayan alcanzado; - las pruebas sean satisfactorias; - la documentación esté actualizada. Solo entonces podrá iniciarse la siguiente fase. --- # 18. Relación con otras SPEC Esta especificación resume y coordina todas las SPEC anteriores. Constituye el documento de referencia para planificar el desarrollo de ESP Platform. --- # 19. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-019 **Desarrolla:** - Planificación general - Roadmap oficial **Implementación:** - Constituirá la guía oficial para la ejecución del proyecto y la priorización de todas las fases de desarrollo de ESP Platform. -------------------------------------------------------------------------------- --- Document ID: architecture-database # Modelo de datos ## Firmware firmware representa la ficha. firmware_segment conserva orden, nombre, offset y referencia a artifact. artifact posee SHA-256 único, ruta y tamaño. firmware_derived_artifact conserva resultados derivados como merged bin. ## Backups device_backup representa una captura aceptada. backup_artifact registra dump y ZIP. backup_region describe particiones. backup_capture_session controla subidas temporales. backup_restore_session registra restauraciones. backup_audit_log registra eventos operativos. ## Integridad Las claves foráneas eliminan relaciones al borrar una ficha, pero artifact usa restricción para impedir borrar contenido todavía referenciado. La deduplicación se apoya en unicidad SHA-256. Las migraciones Flyway V1 a V12 reflejan la evolución estable. ## Datos fuera de PostgreSQL Las tablas nunca contienen el cuerpo de firmware o dump. Guardan rutas, tamaño, checksum y estado. El archivo y su fila deben verificarse como una sola operación de servicio. --- Document ID: architecture-filesystem # Rutas y almacenamiento ## Repositorio /opt/esp-platform/repo contiene Git, backend, documentación y scripts. Es la fuente de verdad de desarrollo dentro de la VM. ## Datos operativos - /srv/esp-platform/artifacts: biblioteca binaria deduplicada. - /srv/esp-platform/firmware: compatibilidad con almacenamiento inicial. - /srv/esp-platform/backups: dumps, paquetes y sesiones. - /srv/esp-platform/documentation: manifiestos derivados, nunca fuentes. - journal de systemd: logs de aplicación. Ninguna ruta de srv es una raíz web pública. Las descargas pasan por controladores que validan el identificador y entregan Content-Disposition. ## Permisos El usuario del servicio solo necesita lectura del repositorio y escritura en las rutas operativas asignadas. Los temporales se aíslan por sesión y se eliminan al cancelar, descartar o expirar. --- Document ID: api-overview # API REST v1 La API usa JSON para metadatos y application/octet-stream para binarios. ## Firmware GET /api/v1/firmware lista fichas. GET por id devuelve detalle. POST crea firmware. Los endpoints download entregan firmware, segmentos y derivados. Las acciones de edición, clonado, bloqueo, merged y limpieza pertenecen al mismo dominio. ## Backups /api/v1/backups gestiona fichas, sesiones de captura por bloques, verify, complete, discard, ZIP y descargas. /restore valida paquetes guardados o subidos, entrega archivos de una sesión validada y registra resultado. ## Documentación GET /api/v1/documentation devuelve el catálogo legible por máquina. search acepta q. manifest incluye hashes y commit. export/markdown, export/text y export/package generan formatos completos desde Markdown. POST regenerate reconstruye el índice; debe quedar reservado a administradores cuando exista autenticación. ## Errores Los dominios de firmware y backup usan una envoltura con success, data y message. Los errores de validación deben ser comprensibles, no incluir secretos ni rutas internas y usar códigos HTTP coherentes. --- Document ID: development-codex-live-session # Codex Live Session ## Arquitectura Codex trabaja dentro de la única sesión tmux `aeos-dev`. El servicio ttyd adjunta un cliente web de solo lectura a esa sesión y escucha exclusivamente en `127.0.0.1:7681`. Nginx publica el transporte HTTP y WebSocket bajo `/development/terminal/live/`, mientras Spring Boot sirve la página `/development/terminal`. ```text Codex -> tmux aeos-dev -> ttyd solo lectura -> Nginx -> /development/terminal ``` No existe escritorio gráfico, X11, VNC ni acceso directo a ttyd desde la red. La opción `--writable` de ttyd no se utiliza. ## Componentes instalados - tmux 3.3a-3, instalado desde Debian 12 mediante APT. - ttyd 1.7.7, binario oficial x86_64 instalado en /usr/local/bin/ttyd después de verificar SHA256SUMS. La dependencia nativa libevent-core-2.1-7 es instalada automáticamente por APT para tmux. No se instala ningún escritorio, servidor gráfico o servicio de escritorio remoto. ## Funcionamiento `aeos-dev.service` ejecuta un script idempotente al arrancar. Si la sesión exacta `aeos-dev` existe, la reutiliza; si no existe, crea una sola sesión con `/opt/esp-platform/repo` como directorio de trabajo. tmux mantiene la sesión aunque no haya clientes conectados. `esp-platform-ttyd.service` depende de la sesión y ejecuta ttyd como el usuario `codex`. El navegador solo recibe la salida de terminal y no puede escribir, pegar, enviar teclas ni interrumpir procesos. ## Conexión La vista HTTPS normal está disponible en: ```text https://iot.aeizoon.com/development/terminal ``` Para trabajar desde SSH dentro de la misma sesión: ```bash tmux attach-session -t aeos-dev ``` Para salir sin detenerla, use la secuencia tmux `Ctrl+B`, seguida de `D`. ## Operación Comprobar o recrear la sesión si falta, sin duplicarla: ```bash sudo systemctl restart aeos-dev.service ``` Reiniciar la publicación web sin detener tmux: ```bash sudo systemctl restart esp-platform-ttyd.service ``` Consultar estado y logs: ```bash systemctl status aeos-dev.service esp-platform-ttyd.service journalctl -u esp-platform-ttyd.service -n 100 --no-pager ``` ## Verificación ```bash tmux list-sessions systemctl is-active aeos-dev.service esp-platform-ttyd.service nginx ss -ltnp | grep 7681 curl -I http://127.0.0.1:7681/development/terminal/live/ curl -I http://127.0.0.1:88/development/terminal ``` Debe existir exactamente una sesión `aeos-dev`; ttyd debe escuchar solo en `127.0.0.1:7681`; la página debe responder a través de Nginx. El servicio ttyd no debe contener `--writable` ni `-W`. ## Configuración versionada - `scripts/ensure-aeos-dev-session.sh`: creación idempotente de la sesión. - `infrastructure/systemd/aeos-dev.service`: persistencia tras reinicio. - `infrastructure/systemd/esp-platform-ttyd.service`: ttyd de solo lectura. - `infrastructure/nginx/codex-live-session.conf`: proxy WebSocket. Los archivos efectivos se instalan en `/etc/systemd/system/` y en el sitio Nginx de ESP Platform. Los cambios se realizan primero en el repositorio y después se despliegan. ## Política de redimensionado La sesión utiliza la política global `window-size largest` de tmux 3.3a y mantiene `aggressive-resize off`. Con varios clientes conectados, la ventana toma las dimensiones del cliente más grande; una conexión SSH de 80x24 no puede reducir la vista web. ttyd fija `fontSize=18` y `lineHeight=1.35`. El navegador permanece en modo de solo lectura porque ttyd no se inicia con `--writable` ni `-W`. El cliente tmux no usa `attach-session -r`: tmux 3.3a excluye los clientes de solo lectura del cálculo de tamaño y eso impediría que la vista web aportase sus dimensiones a `window-size largest`. La página reajusta xterm.js tras la carga del iframe, una recreación del terminal, cambios del contenedor, cambios de pantalla completa y redimensionados de la ventana. Se usa `ResizeObserver`, con dos reintentos cortos después de cada evento; no existe un bucle periódico de redimensionado. Durante una caída del WebSocket la vista puede mostrar temporalmente el estado de desconexión. Al reabrirse la conexión, ttyd conserva o recrea el terminal y el observador vuelve a ajustarlo al contenedor. Para verificar la política: ```bash tmux show-window-options -g | grep -E 'window-size|aggressive-resize' tmux list-clients -F '#{client_tty} #{client_width}x#{client_height} readonly=#{client_readonly}' tmux list-windows -F '#{session_name} #{window_index} #{window_width}x#{window_height}' ``` --- Document ID: development-repository # Desarrollo y releases ## Entorno único Todo desarrollo se realiza directamente en /opt/esp-platform/repo dentro de la VM. El Mac solo aporta SSH, navegador y USB. No existe copia de trabajo paralela. ## Estructura backend contiene Spring Boot, recursos, Flyway y frontend. docs contiene Markdown oficial e histórico. scripts contiene validación y operación reproducible. Los datos binarios no se versionan en Git. ## Flujo Lea la Constitución y SPEC antes de diseñar. Cree una rama cuando proceda, implemente de forma acotada, ejecute Maven test, valide la UI y los flujos físicos según riesgo. Actualice documentación y ADR. Después cree commit, tag, release interna y snapshot aprobado. ## Migraciones Flyway es la única vía para cambiar esquema. Una migración aplicada no se modifica; se añade otra. Las entidades usan ddl-auto validate para detectar divergencias. ## Documentación Edite Markdown, ejecute scripts/build-documentation.sh y compruebe manifest, enlaces, descargas y paquete. La web no edita archivos críticos. ## Estabilidad v0.1.0-flasher-backups está congelada como producto estable. Solo admite correcciones, seguridad, compatibilidad o mejoras expresamente aprobadas. --- Document ID: releases-v0-1-0-flasher-backups # ESP Platform v0.1.0 - Flasher and Backups Date: 2026-07-14 Status: internal release candidate after physical validation ## Scope This release closes the MVP toolchain for firmware catalog, Web Serial flashing, device backup and restore. It does not include OTA, Provisioning, Fleet Management, Edge OS, Compare with repository or Import firmware from connected ESP32. ## Included Capabilities - Simple single-file firmware upload and download. - Multi-part ESP32 firmware packages with offsets. - Merged firmware image generation through `esptool merge-bin`. - Artifact library with SHA-256 based reuse. - Web Serial ESP32 flashing at default baudrate `115200`. - ESP32 erase flash action. - Serial monitor and hardware reset actions. - Read flash region diagnostics. - Complete 4 MB device dump. - Partition table analysis and selected-region download. - Backup ZIP generation with `manifest.json`, `full-flash.bin` and `checksums.sha256`. - Complete restore from `full-flash.bin`. - Selective restore by region. - Safety backup before restore. - Restore cancellation with incomplete-state warning. - Restore audit events. ## Physical Validation Summary Validated with ESP32-D0WD revision 1, MAC `2c:bc:bb:75:f2:74`, Flash ID `16405e`, 4 MB flash. - Complete restore passed with SHA-256 verification. - Selective `app0` restore passed and preserved NVS. - Cancellation during writing passed and recovery by complete restore passed. - Invalid region package was blocked before writing. - Altered checksum package was blocked before writing. ## Known Notes - Default baudrate remains `115200`; higher speeds remain advanced options. - Backups can contain credentials and device-specific data. They must remain outside public web paths. - Full flash dumps do not include eFuses, so Secure Boot and Flash Encryption devices require special caution. - `Execute restore` requires a connected ESP32, validated package, non-incompatible compatibility report and exact `RESTORE` confirmation. --- Document ID: release-documentation-1-0 # Portal documental 1.0 Complemento documental de ESP Platform v0.1.0-flasher-backups. ## Incluye - Navegación Firmware, Flasher, Backups, Diagnostics y Documentación. - Portal por categorías, accesos rápidos y documentos recientes. - Renderizado seguro desde Markdown. - Búsqueda por metadatos y contenido. - Descarga individual Markdown y TXT. - Exportación maestra Markdown y texto. - ZIP con fuentes, texto, manifest, checksums y commit Git. - API documental legible por máquina. - Clasificación Official, Historical, Diagnostic, Validation, ADR, Release e Internal. - Presentación aprobada y congelada de la Constitución. - Documentación oficial de producto, firmware, artifacts, Flasher, Diagnostics, Backups, Restore, seguridad, infraestructura y desarrollo. El portal no añade funciones al producto estable ni modifica la Constitución. --- Document ID: reference-troubleshooting # Resolución de problemas ## Web Serial no aparece Use Chrome o Edge de escritorio y HTTPS. Cierre otras aplicaciones que usen el puerto. Compruebe cable de datos y autorización del sistema operativo. ## No entra en bootloader Mantenga BOOT al iniciar la conexión o controle EN/IO0 según la placa. Los adaptadores USB-TTL no siempre automatizan las líneas. ## Falla a velocidad alta Vuelva a 115200. La validación física mostró conexiones estables a esa velocidad y fallos de flujo tras cambiar a 921600 en cierto hardware. ## El archivo no cabe Compruebe tamaño detectado, offset final y parámetro flash size. Para imágenes completas merged use 0x0. No cargue binarios como texto o Base64 en esptool-js. ## Restore no se habilita Debe existir paquete validado, ESP32 conectado, compatibilidad no incompatible y texto RESTORE exacto. Seleccionar todas las regiones no deshabilita por sí mismo la acción, aunque muestra advertencias sensibles. ## Servicio web no responde Revise systemd, journal, PostgreSQL, permisos de /srv, Nginx y espacio. No exponga contraseñas del entorno al recopilar logs. --- Document ID: reference-terminology # Terminología - Artifact: bytes inmutables identificados por SHA-256. - Firmware: ficha distribuible y versionable. - Firmware segment: relación entre firmware, artifact y offset. - Multipart: firmware con varios segmentos. - Merged image: imagen única generada con esptool merge-bin. - Device backup: copia de estado destinada a restauración. - Region: rango de flash descrito por offset y tamaño. - NVS: almacenamiento persistente de claves y valores. - OTA data: estado de selección de aplicaciones OTA. - Firmware fingerprint: hash de regiones reutilizables. - Full dump SHA-256: hash del estado completo. - Safety backup: copia previa a Restore. - Web Serial: API del navegador para puerto serie. - SPEC: arquitectura oficial congelada en la Constitución. - ADR: registro de una decisión arquitectónica. --- Document ID: documentation-home # Documentación de ESP Platform Esta carpeta contiene la fuente oficial de documentación de ESP Platform. El producto estable cubierto es ESP Platform Flasher/Backups, versión v0.1.0-flasher-backups. ## Fuente única de verdad Los archivos Markdown versionados en Git son la fuente de verdad. La aplicación los indexa y renderiza para la web, genera texto plano y construye las exportaciones completas. Los formatos derivados nunca se editan manualmente. ## Clasificación - Official: guía vigente para uso, arquitectura, seguridad u operación. - Historical: decisiones o fases anteriores conservadas como contexto. - Diagnostic: investigación técnica de un caso concreto. - Validation: evidencia de pruebas y aceptación. - ADR: decisión arquitectónica. - Release: alcance congelado de una versión. - Internal: planes o plantillas que no describen comportamiento público. La Constitución conserva su contenido original. Su estado general de presentación es aprobado y congelado, aunque queden textos heredados del proceso de redacción. ## Actualización Toda modificación documental se realiza en esta VM, pasa por scripts/build-documentation.sh, se revisa visualmente y se versiona en Git junto al código que describe. --- Document ID: validation # ESP Platform Phase 1E Validation Required checks: - Backend is active through systemd. - Web is available at `http://192.168.1.62:88/`. - `.bin` upload works. - Firmware binary is stored under `/srv/esp-platform/firmware`. - Metadata is stored in PostgreSQL table `firmware`. - Size and SHA-256 are calculated automatically. - Firmware list displays the uploaded firmware. - Download endpoint returns the stored `.bin`. API endpoints: ```text GET /api/v1/firmware GET /api/v1/firmware/{id} POST /api/v1/firmware GET /api/v1/firmware/{id}/download ``` ## Phase 1E Validation Run - 2026-07-06 Validation was executed directly inside VM `esp-platform`. Result: passed. Observed test values: - Uploaded firmware id: `1` - Uploaded filename: `validation.bin` - Metadata name: `Validation Firmware` - Application: `AZ-TEST` - Hardware: `ESP32 DevKit` - Stored filesystem path: `/srv/esp-platform/firmware/038cfdcf-3ff2-45c5-ba5f-d7ec5515593c.bin` - Size: `33` bytes - SHA-256: `82d3c475f7f8e72e521e38e41e60efc6b6375452fbf2ea336e4430daea54c4f8` Checks passed: - `esp-platform-backend` active through systemd. - Web accessible through Nginx at `http://192.168.1.62:88/`. - API accessible through Nginx at `http://192.168.1.62:88/api/v1/firmware`. - Upload stored metadata in PostgreSQL. - Upload stored `.bin` in filesystem. - Downloaded file matched original size and SHA-256. ## Phase 2 Browser Validation - 2026-07-06 Validation performed: - `http://192.168.1.62:88/flasher` loads successfully. - `GET /api/v1/firmware` is consumed by the page. - Direct HTTP access by VM IP is not a secure Web Serial context; the page shows a warning and disables serial connection. - Temporary local tunnel tested: ```bash ssh -N -L 18888:127.0.0.1:88 codex@192.168.1.62 ``` - `http://localhost:18888/flasher` loads successfully. - Through localhost, the secure-context warning is not shown and the Connect ESP32 button is enabled. Pending physical validation: - Upload real firmware `.bin` from the administration page. - Select the firmware in `/flasher`. - Connect ESP32 by USB in Chrome/Edge. - Grant serial-port permission. - Flash firmware and confirm ESP32 boots. ## Phase 2 HTTPS Pre-Validation - 2026-07-06 NPM HTTPS route configured by project owner. Checked URL: ```text https://iot.aeizoon.com/flasher ``` Result: - Page loads correctly through HTTPS. - Insecure-context warning is not displayed. - Connect ESP32 button is enabled by the page. - Firmware catalog loads successfully. - Catalog currently contains no firmware after removal of the Phase 1E validation test firmware. Physical validation remains pending with a real firmware `.bin` and ESP32 connected to the Mac. ## Phase 2 Physical Validation Attempt - ESP32 Ethernet/WiFi AliExpress - 2026-07-06 Hardware and connection: - Board: ESP32 Ethernet/WiFi AliExpress board. - USB connection: external USB-TTL adapter. - Browser route: `https://iot.aeizoon.com/flasher`. Observed successful steps: - Web Serial works through HTTPS. - Flasher connects to the ESP32. - Chip detected: `ESP32-D0WD rev 1`. - MAC address detected. - Stub upload works. - Flash ID is read. - Firmware download from backend works. - Downloaded firmware size: `1,274,512` bytes. Observed baudrate behavior: - `115200` is stable. - `921600` fails after baudrate change with errors similar to: - `Unable to verify flash chip connection` - `Serial data stream stopped` Decision applied: - Default baudrate changed to `115200`. - Higher baudrates remain available under the advanced speed group. Observed flashing failure before correction: ```text File 1 doesn't fit in the available flash ``` The error occurred with both: - flash address `0x0` - flash address `0x10000` Review result: - `esptool-js` expects `fileArray: [{ data: Uint8Array, address: number }]`; the implementation uses `Uint8Array` from `response.arrayBuffer()`. - The library performs a fit check when `flashSize !== "keep"`. - Passing `flashSize: "detect"` directly to `writeFlash()` is unsafe because `flashSizeBytes("detect")` does not resolve to the detected byte size for the fit check. - The Flasher now calls `detectFlashSize()` after connecting and sends the resolved size string, such as `4MB`, to `writeFlash()`. - If auto-detection is unavailable, the Flasher sends `keep` to avoid the false fit check. Additional logging added before flashing: - detected flash size; - configured flash size sent to `esptool-js`; - firmware byte length; - binary data type and `Uint8Array` check; - flash start address; - calculated end address. Second physical validation result: - The same `File 1 doesn't fit in the available flash` error was observed again. - The browser output did not include the newly added diagnostic lines, which confirmed that the HTTPS route was still serving a cached older `flasher.js`. Correction applied after second attempt: - Flasher assets now use cache-busting version `phase2-20260706-3`. - The Flasher logs its build at page load: `Flasher build: phase2-20260706-3`. - Internal Spring/Nginx delivery for static assets now uses no-cache headers. - NPM still adds external cache headers, so every Flasher JS change must also bump the asset version query string. - Default Flash size changed to `Keep firmware setting` to bypass the `esptool-js` pre-write fit check. - `Auto-detected size check` remains available as a diagnostic option, not the default. Current status: - Ready for another physical validation attempt at `115200` baud. - Confirm the Flasher console starts with `Flasher build: phase2-20260706-3`. - Use Flash size `Keep firmware setting`. - If it still fails, capture the Flasher console log and browser console output. ## Phase 2 Physical Flash Success - 2026-07-06 Physical flashing succeeded through `https://iot.aeizoon.com/flasher` using Flasher build `phase2-20260706-3`. Observed result: - Firmware `freepocket 0.3.5j` downloaded from backend. - Firmware size: `1,274,512` bytes. - ESP32 detected: `ESP32-D0WD revision 1`. - Flash size detected: `4MB`. - Flash address: `0x0`. - Configured flash size sent to `esptool-js`: `keep`. - Written bytes: `1,274,512`. - Compressed bytes: `804,935`. - Write duration: `72.507` seconds at `115200`. - `esptool-js` requested hard reset via RTS after flashing. Follow-up UI adjustment: - Flasher build `phase2-20260706-4` adds an `Erase ESP32` button. - The erase button is enabled only after a serial connection is established. - It asks for confirmation before calling `eraseFlash()`. - The button is visually separated from `Disconnect` with a `4cm` left margin on desktop layouts. ## Phase 2 Serial Monitor and Hardware Reset - 2026-07-06 Flasher build `phase2-20260706-6` adds post-flash serial diagnostics: - `Start Serial Monitor` opens the selected Web Serial port at the currently selected baudrate. - If the esptool flasher connection is still open, it is closed first and the same port is reopened for serial reading. - Serial bytes are written directly into the Flasher console so the ESP32 boot log can be inspected. - `Stop Monitor` closes the serial monitor and releases the port. - `Hardware Reset` sends reset through esptool when the flasher connection is active. - When the serial monitor is active, `Hardware Reset` pulses RTS through Web Serial so boot output can be observed immediately. Operational test path: 1. Flash firmware successfully. 2. Click `Start Serial Monitor`. 3. Click `Hardware Reset` or press the board reset button. 4. Confirm boot output appears in the console. ## Phase 2 FreePocket Firmware Layout Finding - 2026-07-07 A comparison with `https://freepocket.chrisoft.io/` showed that the external FreePocket installer is powered by ESP Web Tools and uses a manifest with multiple flash parts, not a single binary written at `0x0`. Observed external manifest layout: - bootloader: `0x1000` - partitions: `0x8000` - boot_app0: `0xE000` - application: `0x10000` - LittleFS: `0x290000` The firmware uploaded to ESP Platform as `freepocket 0.3.5j` has size `1,274,512` bytes and starts with an ESP image header at offset `0x0`: - magic: `0xE9` - segments: `6` - flash mode byte: `0x02` - flash size/frequency byte: `0x2f` - entry point: `0x400827ac` This indicates that the uploaded file is likely an application image intended to be written at `0x10000`, not a complete flash image intended for `0x0`. Important consequence: - Flashing this app image at `0x0` overwrites the bootloader area and can prevent the ESP32 from booting correctly. - Flashing it at `0x10000` only works if the target ESP32 already has compatible bootloader, partition table, boot_app0 and filesystem/data partitions. - A clean device or a previously erased device requires a multi-part firmware package/manifest, not only the application `.bin`. Next required platform correction: - ESP Platform should distinguish between single full-image firmware and multi-part ESP32 firmware packages. - For ESP-IDF/Arduino app-only binaries, the flasher should require or infer address `0x10000` instead of defaulting to `0x0`. - For FreePocket-style installs, ESP Platform needs manifest/multi-part upload support before it can reproduce the external installer behavior exactly. ## Phase 2 External FreePocket Files Retrieved - 2026-07-07 The public files referenced by `https://freepocket.chrisoft.io/manifest_latest.json` were downloaded for technical comparison and validation reference into: ```text /opt/esp-platform/repo/firmware/reference/freepocket ``` Downloaded layout: | Offset | File | Size | SHA-256 | | --- | --- | ---: | --- | | `0x1000` | `pincho_solax.bootloader.bin` | `18,992` | `644de0067047e22380034b8989c39e5d2882f7538c698788866ca5130427322e` | | `0x8000` | `pincho_solax.partitions.bin` | `3,072` | `148b959cbff1c38aa8e1d5c0ba9d612c54997b945e56a63f41223eef650653a1` | | `0xE000` | `boot_app0.bin` | `8,192` | `f94c5d786a7a8fab06ac5d10e33bf37711a6697636dc037559ea19cc410a17f0` | | `0x10000` | `pincho_solax.bin` | `1,072,320` | `026f043621c2338c3172751f54e2c9ca9bb9f1741b78c0b8799cf78f6843f9ac` | | `0x290000` | `pincho_solax.littlefs.bin` | `1,441,792` | `0edc7b60e8162ab7177992783648dd8d5857dab463c2f0a60715aa40af57a0e1` | Important version note: - The public manifest reports version `0.3.5f`. - The firmware currently uploaded to ESP Platform is labeled `0.3.5j` and has size `1,274,512` bytes. - These should not be treated as the same firmware package. Use of the retrieved files: - They are suitable as a reference to reproduce the external installer behavior in a validation environment. - ESP Platform still needs explicit multi-part package support before these files are represented cleanly in the database and web UI. ## Phase 2 Multi-Part Firmware Support - 2026-07-07 ESP Platform now supports a minimal multi-part firmware package model for Phase 2 validation. Backend changes: - Added `firmware.package_type` with values `SIMPLE` and `MULTIPART`. - Added `firmware_part` table with per-part metadata: - part order; - display name; - original filename; - filesystem path; - flash offset; - size; - SHA-256 checksum. - Added API download endpoint for parts: - `GET /api/v1/firmware/{id}/parts/{partId}/download` - `GET /api/v1/firmware` now returns `packageType`, `partCount` and `parts[]`. Seeded validation package: - Firmware id: `3` - Name: `FreePocket full install` - Version: `0.3.5f` - Type: `MULTIPART` - Total size: `2,544,368` bytes - Source reference: public FreePocket ESP Web Tools manifest. Flasher changes: - Flasher build: `phase2-20260706-7`. - Multi-part firmware cards are displayed with a distinct blue `Multi-part` badge. - Simple `.bin` firmware remains supported as `Single .bin`. - For `MULTIPART`, the Flasher downloads all parts and sends a multi-entry `fileArray` to `esptool-js`. - For `MULTIPART`, the Flasher uses: - `eraseAll: true` - `flashMode: keep` - `flashFreq: keep` - configured flash size from the UI, default `keep`. Validation performed: - Backend service active after Flyway V3 migration. - API lists both the existing simple firmware and the new multi-part FreePocket package. - All five part download endpoints return HTTP 200 with expected sizes. Physical validation pending: - Select `FreePocket full install 0.3.5f` from `/flasher`. - Confirm the card is marked `Multi-part`. - Connect ESP32 at `115200`. - Flash selected firmware. - Start Serial Monitor. - Send `Hardware Reset` or press reset manually. - Confirm complete boot log and device operation. ## Phase 2 FreePocket AP Password and Version Search - 2026-07-07 The FreePocket documentation page states that, after first boot, the ESP32 creates an AP named `fp_xxxxxx` and the default password is ``. The same page states the default local IP is `192.168.4.1` with web user `admin` and password ``. Binary inspection confirms related defaults inside the downloaded public package: - LittleFS contains `WEB_USERNAME`: `admin`. - LittleFS contains `WEB_PASSWORD`: ``. - Application strings contain AP creation format `fp_%02x%02x%02x` and log text `enabling AP: ssid:%s, password:****`. Public installer version search: - `https://freepocket.chrisoft.io/` references only `manifest_latest.json`. - The public manifest reports version `0.3.5f`. - Tested common manifest/version names such as `manifest_0.3.5g.json`, `manifest_0.3.5j.json`, `manifest_stable.json`, `manifest_beta.json`: only `manifest_latest.json` is exposed. Current conclusion: - Public direct ESP Web Tools installer exposes only FreePocket `0.3.5f`. - The `0.3.5j` binary uploaded manually to ESP Platform appears to come from another source or unpublished package and should not be assumed to match the public multi-part package. Additional version finding: - `manifest_latest.json` reports `0.3.5f`. - The downloaded `pincho_solax.bin` application image contains internal string `0.3.5g`. - ESP Platform display metadata was updated to `manifest 0.3.5f / app 0.3.5g` to avoid confusing this package with the manually uploaded app-only `0.3.5j` firmware. ## Phase 2 Patched AP Password Package - 2026-07-07 A test firmware package was created by binary patching the public FreePocket multi-part package from default string `` to ``. Reason: - The ESP32 AP appears as `fp_xxxxxx`, but the default password did not work reliably in physical testing. - The string `` appears once in the application image and once in the LittleFS image. - The replacement `` has the same length as ``, so the patch does not shift binary offsets. Created package: - Firmware id: `4` - Name: `FreePocket full install AP ` - Version label: `manifest 0.3.5f / app 0.3.5g / AP ` - Type: `MULTIPART` - Expected AP/web password for validation: `` Changed checksums: - application `pincho_solax.bin`: `4454f8d1ecb422741ff7fa535f664bb063286d687c98f1beeda98d6b2655a16b` - littlefs `pincho_solax.littlefs.bin`: `cabb88ab8b621e56eece8f74173ec4014cebb3e3965c8232ccc96fcc026ddbd0` Unchanged parts: - bootloader - partition table - boot_app0 Validation performed: - The patched package appears in `/api/v1/firmware`. - All five part download endpoints return HTTP 200. - The patched application and LittleFS files contain `` and no longer expose `` through simple string inspection. Risk note: - This is a binary patch for validation only. If LittleFS metadata or firmware logic validates file contents internally, the device may ignore the patched value or behave differently. A source-level firmware build would be cleaner once source/build inputs are available. ## Phase 2 Patched AP Password Package Repair - 2026-07-07 Physical test result: - Flashing `FreePocket full install AP ` caused repeated `SW_RESET` before FreePocket printed its normal `[general] starting program` log line. - The bootloader reached `entry 0x400805f0`, then the ESP32 reset repeatedly. Cause found: - Binary patching the application image changed bytes inside `pincho_solax.bin`. - The ESP32 application image footer still contained the original checksum and validation SHA-256 digest. - `esptool image_info` reported: - checksum invalid; - validation hash invalid. Repair applied: - Recomputed the ESP image checksum byte from `0x82` to `0x87`. - Recomputed the appended validation SHA-256 digest. - Replaced the application part for firmware id `4` with the repaired image. Repaired application checksum: - File SHA-256: `fff0335928c92bc3150b5e527d11543b1db28c2dca22bde69ce152f33e105e22` - ESP image checksum: valid - ESP validation hash: valid Next physical validation: - Flash `FreePocket full install AP ` again from `/flasher`. - Confirm the normal FreePocket boot log appears. - Try AP password ``. ## Admin Firmware UI Maintenance - 2026-07-07 Changes validated: - `/admin/firmware` now exposes a delete action for stored firmware records and their filesystem files. - `/admin/firmware` now exposes a multi-part ESP32 package upload form with explicit offsets for bootloader, partitions, boot_app0, application, and filesystem/LittleFS images. - Multi-part firmware entries are visually distinguished with blue badges. - The shared web palette was adjusted away from green success/console accents toward blue. - `/flasher` and `/admin/firmware` were checked for horizontal page overflow after the layout/CSS changes. Functional validation: - Temporary single `.bin` upload returned HTTP 302, appeared through `/api/v1/firmware`, and was deleted through `/admin/firmware/{id}/delete`. - Temporary multi-part upload with five `.bin` files returned HTTP 302, appeared through `/api/v1/firmware` as `MULTIPART` with `partCount=5`, and was deleted through `/admin/firmware/{id}/delete`. - After deletion, no temporary validation firmware remained in `/api/v1/firmware`. - Backend service `esp-platform-backend` was rebuilt, redeployed, restarted, and remained active. Browser validation through `https://iot.aeizoon.com`: - `/admin/firmware` loaded CSS `app.css?v=phase2-20260707-1`. - `/admin/firmware` showed the multi-part upload form and delete buttons. - `/admin/firmware` reported no horizontal overflow at 1280 px viewport width. - `/flasher` loaded CSS `app.css?v=phase2-20260707-1`. - `/flasher` showed `Erase ESP32`, `Start Serial Monitor`, `Stop Monitor`, and `Hardware Reset` controls. - `/flasher` reported no horizontal overflow at 1280 px viewport width. ## Firmware Lock/Edit Administration - 2026-07-07 Changes validated: - Firmware records now have an `enabled` state stored in PostgreSQL. - Existing firmware records were migrated as enabled by default through Flyway `V4__firmware_enabled.sql`. - `/admin/firmware` shows firmware status as `Enabled` or `Locked`. - Clicking a firmware name in `Available firmware` opens `/admin/firmware/{id}/edit`. - The edit screen allows updating name, version, application, compatible hardware, description, and enabled state without replacing stored binaries. - `/admin/firmware` provides quick `Lock` / `Unlock` actions. - Locked firmware is hidden from `GET /api/v1/firmware`, so it is not offered by the Flasher Web catalog. - Locked firmware download endpoints return an error instead of serving the binary/parts. Functional validation: - Temporary firmware upload returned HTTP 302 and appeared in `/api/v1/firmware` as enabled. - Lock action returned HTTP 200. - After locking, the temporary firmware no longer appeared in `/api/v1/firmware`. - Direct download of the locked firmware returned HTTP 400. - Unlock action returned HTTP 200. - Edit action returned HTTP 200 and changed metadata visible from `/api/v1/firmware/{id}`. - Delete action returned HTTP 200 and removed the temporary firmware. Browser validation through `https://iot.aeizoon.com`: - `/admin/firmware` loaded CSS `app.css?v=phase2-20260707-2`. - Firmware names rendered as edit links. - Lock buttons rendered for enabled firmware. - `/admin/firmware/{id}/edit` rendered the metadata form and enabled checkbox. - `/admin/firmware` and `/admin/firmware/{id}/edit` reported no horizontal overflow at 1280 px viewport width. ## Firmware Part Download And Replacement - 2026-07-08 Changes validated: - Multipart firmware edit pages now expose a `Download` action for each current firmware part. - Multipart firmware edit pages now expose a per-part `.bin` replacement form. - Admin part downloads use `/admin/firmware/{id}/parts/{partId}/download` and are intended for maintenance/review. - Public/API part downloads remain protected by firmware enabled state. - Replacing a part stores the new binary in filesystem, updates original filename, size, SHA-256, and recalculates the parent package size/checksum. Functional validation: - Temporary multipart firmware upload returned HTTP 302. - Admin download of the temporary bootloader part returned the expected original bytes. - Replacing that bootloader part returned HTTP 200. - The part filename, size, and SHA-256 changed to match the replacement `.bin`. - The parent multipart package total size changed and package SHA-256 was recalculated. - Temporary multipart firmware was deleted successfully and did not remain in `/api/v1/firmware`. Browser validation through `https://iot.aeizoon.com`: - `/admin/firmware/4/edit` loaded CSS `app.css?v=phase2-20260708-1`. - The edit page rendered 5 part rows, 5 `Download` links, 5 file inputs, and 5 `Replace` buttons. - The page reported no horizontal overflow at 1280 px viewport width. ## ESP32 Merged Image Assembler - 2026-07-12 Implementation validated: - Added derived artifact storage for merged ESP32 images linked to the source multipart firmware. - Added PostgreSQL migration `V5__firmware_derived_artifacts.sql` with merge parameters on `firmware` and derived artifact metadata in `firmware_derived_artifact`. - Installed and exposed official `esptool` as `/usr/local/bin/esptool` on the VM. - Backend generation uses `esptool --chip merge-bin --flash-mode --flash-freq --flash-size -o ...`. - Backend validates segment existence, offsets, overlap, flash-size range, stored file sizes, SHA-256 checksums, and supported esptool parameters before merge. - Merged output is stored under `/srv/esp-platform/firmware/derived/firmware-/`. - Generated artifacts record source firmware, filename, size, SHA-256, generated date, flash address `0x0`, parameters, status, error message, and command line. - Admin firmware edit page now shows merge parameters, `Generar imagen unificada`, derived artifacts, download, regeneration by creating a new artifact, and delete-artifact-only actions. - Flasher Web catalog now exposes generated `MERGED_BIN` artifacts as selectable flashable items, using address `0x0` without manual offsets. - Existing multipart flashing remains available and unchanged. Validation results: - Initial generation with FreePocket forced to filesystem/spiffs offset `0x310000` and flash size `4MB` failed correctly with: `Segment spiffs exceeds configured flash size 4MB.` - The existing FreePocket binaries stored in ESP Platform have a final filesystem image of `1,441,792` bytes. At `0x310000` that image exceeds 4 MB; at the previously validated `0x290000` layout it fits exactly inside 4 MB. - FreePocket package id `4` was kept on its effective validated layout to preserve existing multipart flashing behavior. - Generated merged artifact for firmware id `4`: - Artifact id: `2` - Filename: `firmware-4-merged.bin` - Size: `4,128,768` bytes - SHA-256: `3b0eb453795260d52c0ce7eae731f618ced9a2cc98720b6a32e5aab279d2a516` - Flash address: `0x0` - Parameters: `ESP32 / dio / 80m / 4MB` - Download of `/api/v1/firmware/4/artifacts/2/download` returned HTTP 200 and SHA-256 matched PostgreSQL. - A temporary multipart package was created to validate derived artifact deletion: - upload returned HTTP 302; - generation returned HTTP 302 and produced a `GENERATED` artifact; - deleting only the derived artifact returned HTTP 302 and left the firmware record intact; - deleting the temporary firmware then removed the source package. - Service was restarted after Flyway repair/checksum alignment; Flyway validates 5 migrations and backend starts successfully. Operational note: - A requested layout of `0x310000 -> spiffs.bin` with `4MB` is only valid when the spiffs/filesystem image size is small enough to end at or before `0x400000`. The backend now rejects invalid combinations instead of producing a misleading merged image. ## Merged Image Published As Autonomous Firmware - 2026-07-12 Decision update: - A merged image generated from a multipart package is now published as a normal `SIMPLE` firmware record. - The generated firmware is operationally autonomous: it can be edited, locked/unlocked, downloaded and selected by the Flasher Web like any single-block `.bin` uploaded manually. - The origin is preserved only as descriptive context and generation audit metadata; the generated firmware is not behaviorally dependent on the source multipart package. Validated generated firmware: - Firmware id: `16` - Name: `FreePocket full install AP - merged image` - Type: `SIMPLE` - Original filename: `firmware-4-merged.bin` - Size: `4,128,768` bytes - SHA-256: `3b0eb453795260d52c0ce7eae731f618ced9a2cc98720b6a32e5aab279d2a516` - Download endpoint: `/api/v1/firmware/16/download` - Source firmware dependency: none (`sourceFirmwareId = null`) Validation: - `/admin/firmware` shows `FreePocket full install AP - merged image` as a normal firmware row. - `/admin/firmware/16/edit` is available. - `/api/v1/firmware/16/download` returned HTTP 200. - Downloaded file size and SHA-256 matched the database metadata. - Backend logs after deployment showed no new errors or Flyway validation failures. ## Artifact Library And Firmware Clone Safety - 2026-07-12 Implementation validated: - Added independent `artifact` storage library backed by `/srv/esp-platform/artifacts`. - Added `firmware_segment` as the active firmware-to-binary relation table. - Removed legacy `firmware_part` with migration `V9__drop_legacy_firmware_part_table.sql`; the active model is now `firmware`, `firmware_segment`, and `artifact`. - Each `firmware_segment` references one `artifact` through a PostgreSQL foreign key. - Artifacts are identified by SHA-256 and reused when the same binary is uploaded again. - Existing firmware binaries were consolidated into `/srv/esp-platform/artifacts//.bin`. - Firmware deletion now removes the firmware record and its segment relations only; it does not delete physical artifacts directly. - Orphan physical artifact deletion is performed only through the explicit orphan cleanup operation. - Firmware records can share the same artifact path after migration `V8__allow_firmware_records_to_share_artifacts.sql` removed the legacy `firmware.stored_filename` uniqueness constraint. Validation script: - Script: `/opt/esp-platform/repo/scripts/validate-artifact-library.sh` - Base URL used: `http://127.0.0.1:8080` Validated flow: - Created a temporary single-file firmware through `/admin/firmware`. - Verified metadata in `firmware`, `firmware_segment`, and `artifact`. - Cloned the firmware through `/admin/firmware/{id}/clone`. - Verified clone and original shared the same `artifact_id`. - Deleted the original firmware. - Verified the clone still downloaded successfully from `/api/v1/firmware/{cloneId}/download` and SHA-256 matched. - Deleted the clone. - Verified the artifact became orphaned but still existed physically. - Ran `/admin/artifacts/cleanup-orphans`. - Verified the orphan artifact row and physical `.bin` were removed. Result: - `Artifact library validation passed. Test firmware was cloned, original deleted, clone download verified, clone deleted, orphan artifact cleaned.` - The same validation script was re-run successfully after applying `V9__drop_legacy_firmware_part_table.sql`. ## FreePocket NVS Diagnostic Preparation - 2026-07-12 Prepared diagnostic workflow after LittleFS preconfiguration failed to change runtime Wi-Fi behavior. Findings: - FreePocket NVS partition is `nvs` at offset `0x9000`, size `0x5000` / 20480 bytes. - Partition table source artifact: `/srv/esp-platform/artifacts/14/148b959cbff1c38aa8e1d5c0ba9d612c54997b945e56a63f41223eef650653a1.bin`. - Official ESP-IDF NVS parser installed under `/opt/esp-platform/tools/esp-idf/components/nvs_flash/nvs_partition_tool/nvs_tool.py`. - Repo scripts prepared: - `/opt/esp-platform/repo/scripts/freepocket-nvs-info.sh` - `/opt/esp-platform/repo/scripts/analyze-nvs-dump.sh` - `/opt/esp-platform/repo/scripts/compare-nvs-dumps.sh` - Diagnostic guide: `/opt/esp-platform/repo/docs/diagnostics/freepocket-nvs-diagnostics.md`. Next required physical data: - NVS dump immediately after flashing and before manual configuration. - NVS dump after manual configuration with SSID `Solax`, Wi-Fi password ``, web user `admin`, and web password . ## Flasher Web Read Flash Region - 2026-07-12 Implemented an advanced read-only flash dump function in `/flasher` for NVS diagnostics. Validated by HTTP/HTTPS delivery: - `/flasher` now contains advanced section `Read flash region`. - Preset `FreePocket NVS` sets offset `0x9000` and size `0x5000`. - Suggested filenames are available: - `freepocket-nvs-before.bin` - `freepocket-nvs-after-solax-admin.bin` - The operation uses the current Web Serial/esptool-js connection and calls `readFlash(offset, size, progressCallback)`. - The downloaded artifact is produced locally in the browser as an `application/octet-stream` `.bin` file. - The function is disabled until an ESP32 is connected and is disabled during flashing, erasing, and serial monitor use. - Baudrate default remains `115200`. - No firmware, LittleFS, or NVS image generation was added or modified. Deployment validation: - Backend service active after deployment. - `https://iot.aeizoon.com/flasher` serves JS build `phase2-20260712-2`. - Backend logs after restart show Flyway validation success and no runtime errors. Physical validation still pending: - Read `freepocket-nvs-before.bin` from the real ESP32 immediately after flashing. - Configure the device manually for `Solax` / `` and web user `admin` with password . - Read `freepocket-nvs-after-solax-admin.bin` from the same board. - Upload both dumps to `/opt/esp-platform/repo/diagnostics/nvs/` and run `scripts/compare-nvs-dumps.sh`. ## Backups Stage 1 - Read-Only Capture - 2026-07-12 Implemented Stage 1 only: - Navigation now includes Firmware, Flasher, Diagnostics and Backups. - `/backups` exposes five backup sections, with only Stage 1 operations enabled: - Read complete flash; - Read partitions. - Stage 2, Stage 3 and Stage 4 actions are visible but disabled pending approval. - `/diagnostics` provides an entry point for current NVS diagnostic workflow. Implemented read-only behavior: - Backups page connects to ESP32 through Web Serial and esptool-js. - It detects chip, revision, MAC, flash ID and flash size when available. - Complete flash reads use offset `0x0` and detected flash size. - Partition table reads use offset `0x8000` and size `0x1000`. - Partition parser interprets ESP-IDF partition entries: name, type, subtype, offset, size and flags. - Synthetic readable regions are added for bootloader and partition table. - Downloads are local browser `.bin` files plus metadata JSON with SHA-256 values. - No backend upload, ZIP creation, restore, firmware import, firmware modification, LittleFS modification or NVS modification was implemented. Static validation: - Maven package completed successfully. - Parser logic was checked against the FreePocket partition artifact and detected 6 real partitions: - `nvs` `0x9000` / `0x5000`; - `otadata` `0xE000` / `0x2000`; - `app0` `0x10000` / `0x140000`; - `app1` `0x150000` / `0x140000`; - `spiffs` `0x290000` / `0x160000`; - `coredump` `0x3F0000` / `0x10000`. Physical validation still pending: - Detect flash size of 4 MB from a real ESP32. - Read full flash and verify exact size `4,194,304` bytes. - Verify SHA-256 from metadata. - Read partition table through Web Serial. - Download at least one selected partition. - Confirm the ESP32 is unchanged after read-only operations. ## Backups Stage 1 UX Review and Stage 2 Package Base - 2026-07-12 Implemented and deployed: - UI terminology changed to `Create complete device backup`, `Analyze flash layout` and `Download selected regions`. - Partition table now includes Description and Classification. - Badges classify regions as Reusable, Sensitive, Device state or Diagnostic. - Safe defaults exclude NVS, OTA data, coredump and NVS keys. - Sensitive/manual selections show a warning. - `Cancel operation` is available during reads and uploads. - Destination selector added: local download or save in ESP Platform. - Backend backup model added: `device_backup`, `backup_artifact`, `backup_region`, `backup_capture_session`, `backup_audit_log`. - Server backups stored in `/srv/esp-platform/backups`. - Backup ZIP package creation implemented for saved server backups. - Restore and import remain disabled. Backend validation completed: ```text POST /api/v1/backups/capture-sessions POST /api/v1/backups/capture-sessions/{id}/chunks POST /api/v1/backups/capture-sessions/{id}/verify POST /api/v1/backups/capture-sessions/{id}/complete POST /api/v1/backups/{id}/package GET /api/v1/backups/{id}/package/download DELETE /api/v1/backups/{id} ``` Results: - Flyway migration V10 applied successfully. - Backend service active through systemd. - `/backups` served correctly through backend. - `/api/v1/backups` served correctly through Nginx on port 88. - Temporary 4-byte validation capture saved, packaged and deleted. - ZIP content validated with `unzip -l`: - `manifest.json` - `full-flash.bin` - `checksums.sha256` - Partial capture discard validated: no temp file and no backup record remained. Physical validation pending with ESP32 connected through browser: 1. Create a complete capture and save it in ESP Platform. 2. Cancel a capture and verify no partial file remains. 3. Download a complete local capture. 4. Verify size and SHA-256. 5. Select NVS manually and verify warning. 6. Save and discard a real temporary session. 7. Create ZIP from real backup and validate manifest/checksums. 8. Confirm the ESP32 is not modified by read operations. ## Backups Physical Validation Attempt - 2026-07-14 Route used: ```text https://iot.aeizoon.com/backups ``` Browser build shown by the page: ```text stage1-stage2-20260712-2 ``` ### Server-side real backup already present A real ESP32 backup exists in ESP Platform and was validated from the VM: - Backup id: `2` - Name: `ESP32 2CBCBB75F274 backup 2026-07-13` - Chip: `ESP32-D0WD (revision 1)` - Chip revision: `1` - MAC: `2CBCBB75F274` - Flash ID: `16405e` - Flash size: `4,194,304` bytes - Stored file: `/srv/esp-platform/backups/device-backup-c403ea4c-51eb-4e65-9989-8f48e8df23bc/full-flash.bin` - Stored size: `4,194,304` bytes - SHA-256: `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a` Checksum command result: ```text ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a full-flash.bin ``` ### Real ZIP package validation Generated package: ```text /srv/esp-platform/backups/device-backup-c403ea4c-51eb-4e65-9989-8f48e8df23bc/esp-platform-backup-2.zip ``` ZIP artifact: - Size: `773,498` bytes - SHA-256: `a8f67972d6d8fa39cecb2a6032e4138de9942b0e17ec590f8ab13eead4cb4006e29767b0` ZIP content: ```text manifest.json full-flash.bin checksums.sha256 ``` `unzip -t` result: ```text No errors detected in compressed data ``` `checksums.sha256` content: ```text ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a full-flash.bin 74072f72c15855ecefd15e59497a09ac1c70d58796bed71b54b5141f31d16cf7 manifest.json ``` ### Session and partial-file state After validation: - `backup_capture_session`: `0` open sessions. - `/srv/esp-platform/backups/tmp`: no partial capture files observed. ### Browser/Web Serial attempt Chrome was opened at `https://iot.aeizoon.com/backups`. First connect attempt: ```text No serial port was selected. ``` Second connect attempt: ```text Serial port WebSerial VendorID 0x403 ProductID 0x6001 ERROR: Could not connect to ESP32. Failed to execute open on SerialPort: Failed to open serial port. ``` Observed possible cause: - Chrome showed several existing ESP Platform tabs, including `/flasher`, `/diagnostics` and another `/backups` tab from previous work. - The automation could not close those user tabs because Chrome denied that operation. - The USB serial adapter was detected, but Chrome could not open it. This usually means another tab/application owns the port, the serial monitor is still active, or the USB adapter needs to be unplugged/replugged. Pending physical checks after freeing the serial port: 1. Cancellation during a real read. 2. Local full dump download from browser. 3. Partition read and selected-region download. 4. Confirmation that the ESP32 continues booting normally after read-only operations. ### Technical notes reviewed Chunk size: - Browser read/upload chunk size is `0x10000` bytes, i.e. `65,536` bytes. Connection loss behavior: - If Web Serial or esptool-js throws during a read/upload, the UI reports a readable error. - For server captures, the current session is discarded in the error path when the session id is still active in the browser flow. - Existing completed backups are not modified. Retries: - There is no automatic retry for failed flash read chunks or failed uploads. - This is intentional for now because re-reading flash over Web Serial after an interruption may leave the port state ambiguous. Manual retry is required. Duplicate detection: - Backups currently record SHA-256 but do not prevent duplicate `device_backup` rows with the same full-flash checksum. - Firmware artifacts have SHA-256 reuse logic; backup artifacts do not yet deduplicate storage. Session timeout: - Capture sessions are created with `expires_at = created_at + 6 hours`. - The timeout is recorded in PostgreSQL. Automatic cleanup: - Explicit discard removes temporary files. - Successful complete moves the temp file into the backup directory and removes the temporary session directory. - No scheduled automatic cleanup job for abandoned expired sessions exists yet. - Operational cleanup should be added before relying on long unattended captures. ## Backups Final Physical Validation Closure - 2026-07-14 Route used: ```text https://iot.aeizoon.com/backups https://iot.aeizoon.com/flasher ``` Device: - Chip: `ESP32-D0WD (revision 1)` - Revision: `1` - MAC: `2c:bc:bb:75:f2:74` - Flash ID: `16405e` - Flash size: `4MB` / `4,194,304` bytes - Browser baudrate: `115200` ### Complete local dump Local dump downloaded successfully from the browser: ```text /Users/juan/Downloads/ESP32_2CBCBB75F274_full_20260713T222532Z.bin ``` Result: - Size: `4,194,304` bytes - SHA-256: `ed346457ca6b4be74719292c4761f7cdc39f7f3abdca6356e261d922c421e350` Expected previous server backup SHA-256: ```text ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a ``` The full-image SHA-256 does not match the previous server backup. Region comparison shows the difference is limited to NVS: | Region | Result | | --- | --- | | bootloader | same | | partition-table | same | | nvs | different | | otadata | same | | app0 | same | | app1 | same | | spiffs | same | | coredump | same | Conclusion: firmware/application regions are unchanged. The complete dump differs because NVS changed between captures, which is expected for device state/configuration. ### Partition download Downloaded real partition: ```text /Users/juan/Downloads/ESP32_2CBCBB75F274_app0_0x10000_20260713T223331Z.bin ``` Result: - Partition: `app0` - Offset: `0x10000` - Size: `1,310,720` bytes / `0x140000` - SHA-256: `d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948` - Matches server backup app0 SHA-256: yes ### Reset and boot confirmation Reset method: - Opened `/flasher`. - Connected to the same ESP32 at `115200`. - Started Serial Monitor. - Pressed `Hardware Reset`. Observed serial boot output: ```text rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) mode:DIO, clock div:1 entry 0x400805f0 [general] starting program (boot #0), version 0.3.5g (esp32) [files] reading config file [io] starting taskserial [webif] starting webserver [wireless] enabling AP: ssid:fp_75f274, password:**** [ethernet] eth connected [ethernet] eth disconnected ``` Conclusion: - ESP32 still boots after read-only backup operations. - Application starts as before. - Webserver starts. - AP starts. - Ethernet behavior remains the same observed device behavior and was not changed by Backups. ### Final state Server cleanup/state after validation: - `backup_capture_session`: `0` rows. - `/srv/esp-platform/backups/tmp`: no partial files. - Persisted backup count: `1` real backup. Validated requirements: 1. Complete 4 MB server capture: passed. 2. Server SHA-256 and exact size: passed. 3. Real ZIP creation/download/content validation: passed. 4. ZIP content: `manifest.json`, `full-flash.bin`, `checksums.sha256`: passed. 5. Real cancellation during read: passed. 6. No partial files after cancellation: passed. 7. No orphan sessions: passed. 8. Local full dump download: passed, with expected NVS-only SHA drift from previous capture. 9. Real partition download: passed with `app0`. 10. ESP32 unchanged and booting: passed. Decision: - Backups Stage 1 is closed and approved. - Backups Stage 2 package creation is closed and approved. - Restore backup package remains not implemented. - Import firmware from connected ESP32 remains not implemented. ## Backup Progress and Firmware Fingerprint - 2026-07-14 Implemented: - Total progress bar for full-operation progress. - Current-step progress bar for active block, selected region, upload chunk or flashing segment. - Visual states: Waiting, Reading, Uploading, Processing, Completed, Cancelled, Failed. - Backups UI no longer uses a chunk-local bar as the only progress indicator. - Flasher UI uses the same dual-progress model for read flash region and multi-segment writes. - Device Backup SHA-256 remains the full flash hash. - Firmware Fingerprint SHA-256 excludes NVS, OTA data, coredump and diagnostic/device-specific regions. - Firmware Fingerprint includes bootloader, partition table, app partitions and reusable filesystem regions. - Saved backup rows show both hashes and repository match count. Physical validation result: approved. Date: 2026-07-14. Environment: - URL: `https://iot.aeizoon.com/backups` - Build: `stage1-stage2-20260714-1` - Device: ESP32-D0WD revision 1 - MAC: `2c:bc:bb:75:f2:74` - Flash size: `4,194,304` bytes / 4 MB - Baudrate: `115200` Validated results: 1. Global progress remained continuous and monotonic during a complete 4 MB read. 2. Partial progress reset correctly by current block/region. 3. Complete local dump downloaded successfully. 4. Complete local dump size: `4,194,304` bytes. 5. Complete local dump SHA-256: `a9ea663ba7afc32f90e73bf25d4e535aeeb182e9285ec5e7c974e4cc67d58600`. 6. Existing server backup SHA-256 remains: `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`. 7. SHA drift between complete dumps is accepted because mutable NVS/device state can change between captures. 8. Firmware Fingerprint SHA-256 is stored separately from Device Backup SHA-256. 9. Current Firmware Fingerprint SHA-256: `4ee0ccd14c1d85ed814cfe8067e6834bec7081a1bf5005768a087cd2e8e6283f`. 10. Firmware Fingerprint size: `4,096,000` bytes. 11. Repository match count: `1`. 12. Real `app0` partition downloaded successfully. 13. `app0` size: `1,310,720` bytes / `0x140000`. 14. `app0` SHA-256: `d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948`. 15. Metadata JSON for local single-file captures now exposes top-level `sha256` and `sizeBytes`, while preserving `files[]`. 16. ESP32 reset was validated manually after read operations. 17. Firmware boot was validated manually after read operations. 18. Read-only complete dump and partition download did not alter the device. Decision: - Progress global continuo: approved. - Progress parcial por bloque/region: approved. - Complete 4 MB local download: approved. - `app0` partition download: approved. - Metadata JSON correction: approved. - Firmware Fingerprint separated from full dump SHA: approved. - ESP32 functional integrity after read-only operations: approved. - Restore backup package remains not implemented. - Import firmware from connected ESP32 remains not implemented. ## Restore Backup Package - 2026-07-14 Status: implemented, software validated and physically validated on ESP32 test device. Implemented: - Restore from saved ESP Platform backup. - Restore from uploaded `esp-platform-backup.zip`. - Backend package validation before restore options are shown. - Complete restore from `full-flash.bin` at `0x0`. - Selective restore by region. - Safe defaults excluding NVS, OTA data, coredump and sensitive/diagnostic/device-state regions. - Explicit `RESTORE` confirmation. - Optional safety backup before writing. - Optional post-write verification by reading back written bytes. - Best-effort Secure Boot and Flash Encryption detection warnings. - Restore audit through `backup_restore_session` and `backup_audit_log`. Software validation completed: 1. Saved backup `#2` validates as restorable. 2. Restore validation returns ESP32 family, 4 MB flash size and 8 regions. 3. Safe defaults are `bootloader`, `partition-table`, `app0`, `app1`, `spiffs`. 4. Backend restore-session download returns `4,194,304` bytes. 5. Backend restore-session download SHA-256 is `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`. 6. Real `esp-platform-backup-2.zip` upload validates successfully. 7. Corrupted checksum ZIP is rejected with HTTP 400 and message `Restore package validation failed: Checksum mismatch for full-flash.bin.` 8. Restore UI loads without JavaScript console errors. 9. Restore UI renders package summary, compatibility report and region table. Physical validation completed on 2026-07-14: 1. Complete restore from saved backup `#2`: passed. - Target: ESP32-D0WD revision 1, MAC `2c:bc:bb:75:f2:74`, Flash ID `16405e`, detected flash size `4,194,304` bytes / 4 MB. - Safety backup was enabled and downloaded before writing. - Safety backup file: `ESP32_2CBCBB75F274_safety_before_restore_20260714T000935Z.bin`. - Safety backup size: `4,194,304` bytes. - Safety backup SHA-256: `cd3517473707d59c3d915b52a3e16213cadce80d9ffb2b4371958fb7acb51a08`. - Restore wrote `4,194,304` bytes from offset `0x0`. - Restore source SHA-256: `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`. - Post-write verification read back `full-flash.bin` and matched SHA-256 `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`. - RTS hard reset was requested after restore. 2. Selective `app0` restore: passed. - Only `app0` was selected. - NVS, OTA data and filesystem were not selected. - `app0` write offset: `0x10000`. - `app0` size: `1,310,720` bytes. - `app0` SHA-256 verified after write: `d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948`. - NVS before SHA-256: `83db022f60712229ae24ca0412897611d656ea5c66102d3f87d5eb3014619172`. - NVS after SHA-256: `83db022f60712229ae24ca0412897611d656ea5c66102d3f87d5eb3014619172`. - Result: NVS remained unchanged. 3. Cancellation during write: passed. - A complete restore was started with erase enabled. - Cancel was requested during the writing phase after erase and after writing had begun. - UI result: `Restore cancelled; device state may be incomplete.` - No success state was shown for the cancelled operation. - Serial port was released and the device could be reconnected. - Audit event recorded: `RESTORE_CANCELLED` at `2026-07-14 00:46:44 UTC`. - Device was recovered afterwards using a complete restore with verification. 4. Incompatibility blocking: passed. - Controlled package with valid checksums but invalid region metadata was rejected before writing. - Backend response: `Restore package validation failed: Region bootloader exceeds flash size.; Region bootloader overlaps coredump.` - No restore execution session was allowed for that package. 5. Altered checksum ZIP: passed at restore validation boundary. - Controlled ZIP with altered `checksums.sha256` was rejected before writing. - Backend response: `Restore package validation failed: Checksum mismatch for full-flash.bin.` - The package does not reach executable restore state. - Browser automation could not attach the ZIP through Chrome native file chooser because Chrome returned `Not allowed`; the same uploaded-package validation path was verified through the backend endpoint and had previously been validated with a good ZIP from the UI. Operational observations: - `Execute restore` is enabled only when an ESP32 is connected, a restore package is validated, compatibility is not `incompatible`, and the confirmation field contains exactly `RESTORE`. - Selecting all partitions does not disable execution by itself; selecting NVS, OTA data or coredump triggers explicit warnings because those regions are device-specific or diagnostic. - Historical restore events are tracked in `backup_audit_log`; repeated executions from the same validated package may update the same `backup_restore_session` row. Decision: - Restore backup package is physically validated and approved for MVP Flasher/Backups closure. - Compare with repository remains postponed. - Import firmware from connected ESP32 remains postponed. - OTA, Provisioning, Fleet Management and Edge OS remain out of scope for this phase. --- Document ID: phases-phase-1-infrastructure # Phase 1 - Infrastructure Goal: prepare the dedicated ESP Platform VM and the native infrastructure required for the MVP. Scope: - Proxmox VM 675 `esp-platform`. - Debian 12 Bookworm. - DHCP network with future MikroTik reservation. - User `codex` with sudo. - SSH, QEMU guest agent, UFW, fail2ban. - PostgreSQL native. - Nginx native on port 88. - Java, Maven, Python, PlatformIO, esptool. - Firmware storage in filesystem. - Project documentation and Git repository inside the VM. No backend application code is implemented in this preparation step. --- Document ID: phases-phase-2-flasher-web # Phase 2 - Flasher Web Goal: flash an ESP32 from a browser using Web Serial and a firmware `.bin` uploaded through the Phase 1 controller. Implemented scope: - `/flasher` page. - Firmware catalog loaded from `GET /api/v1/firmware`. - Firmware cards display name, version, application, compatible hardware, size, and SHA-256. - Firmware selection. - Firmware download from `GET /api/v1/firmware/{id}/download`. - Web Serial connection flow. - ESP32 flashing flow through Espressif `esptool-js`. - Progress bar and status messages. - User-readable errors for unsupported browser/context, denied access, missing port, disconnection, download failure, and write failure. Out of scope for Phase 2: - OTA. - Provisioning. - Fleet Management. - Edge OS. - Firmware generation. ## Secure Context Web Serial requires a secure browser context. Accessing the VM directly through plain HTTP by IP address is not enough for real Web Serial use: ```text http://192.168.1.62:88/flasher ``` Observed behavior on that URL: - `/flasher` loads. - Firmware catalog loads. - Web Serial is blocked by browser context. - The page displays a warning. Minimal approved test path for Phase 2 is a local SSH tunnel from the Mac: ```bash ssh -N -L 18888:127.0.0.1:88 codex@192.168.1.62 ``` Then open: ```text http://localhost:18888/flasher ``` Observed behavior through localhost tunnel: - `/flasher` loads. - No secure-context warning is shown. - The Connect ESP32 button is enabled. For real use through `iot.aeizoon.com`, HTTPS must be configured. ## Flash Address The current firmware catalog does not yet store a flash address. The Flasher page therefore provides an operational `Flash address` field with default value: ```text 0x0 ``` If a provided `.bin` requires a different address, set it manually before flashing. ## HTTPS Validation Route As of 2026-07-06, HTTPS access is configured through NPM. Operational URLs: ```text https://iot.aeizoon.com/ https://iot.aeizoon.com/flasher http://192.168.1.62:88/ # internal access only ``` Physical Phase 2 validation must be performed from: ```text https://iot.aeizoon.com/flasher ``` Do not use the localhost tunnel except for punctual diagnostics. Browser pre-check performed: - `https://iot.aeizoon.com/flasher` loads. - Page protocol is `https:`. - The insecure-context warning is not shown. - The Connect ESP32 button is enabled by the page. - Firmware catalog currently loads with `0` items until a real `.bin` is uploaded. ## Physical Validation Adjustment After testing an ESP32 Ethernet/WiFi AliExpress board through an external USB-TTL adapter, the default baudrate was changed to `115200` because this board was stable at `115200` and unstable at `921600`. The Flasher also now resolves `Auto-detected` flash size before calling `writeFlash()` instead of passing `detect` directly to `esptool-js`. ## Cache and Fit-Check Adjustment - 2026-07-06 A repeated physical test still showed `File 1 doesn't fit in the available flash`, and the browser log did not include the latest diagnostic messages. This indicated that the HTTPS path was serving an older cached Flasher script. Applied correction: - `/flasher` now references `/js/flasher.js?v=phase2-20260706-3`. - `/flasher` now references `/css/app.css?v=phase2-20260706-3`. - `flasher.js` logs `Flasher build: phase2-20260706-3` on load. - Static resources served by the Spring backend are configured with no-cache headers. - Because NPM may still add external cache headers, asset version query strings must be bumped after Flasher JS/CSS changes. - Flash size now defaults to `Keep firmware setting`, avoiding the `esptool-js` fit check that can reject a valid image before writing. - `Auto-detected size check` remains available for diagnostics. Next validation should use: - URL: `https://iot.aeizoon.com/flasher` - Baudrate: `115200` - Flash size: `Keep firmware setting` - Confirm first log line: `Flasher build: phase2-20260706-3` --- Document ID: validation-documentation-portal-20260714 # Validación del portal documental 1.0 Fecha: 2026-07-14. ## Resultado funcional - Servicio systemd activo tras despliegue. - Portal /documentation devuelve HTTP 200. - Navegación verificada en el orden aprobado. - Índice generado con 40 documentos antes de añadir esta evidencia final. - Constitución descargada con SHA-256 idéntico al archivo fuente. - Búsqueda por artifact devuelve resultados enlazados. - Manifest incluye producto, versión documental, commit, clasificación, rutas, hashes y tamaños. - Exportación Markdown, TXT y ZIP completada. - ZIP abierto correctamente con 82 entradas antes de añadir esta evidencia final. - checksums.sha256 validado sin errores. - Pruebas JUnit: 2 ejecutadas, 0 fallos. - Validador bloquea patrones de secretos y relaciones documentales rotas. ## Resultado visual - Escritorio validado a 2560 px sin scroll horizontal. - Móvil validado a 390 px sin scroll horizontal. - Navegación, búsqueda, categorías, exportaciones y documento individual visibles. - Tabla de contenidos enlazada y limitada en móvil para documentos extensos. - Paleta azul coherente con el producto. ## Seguridad Los valores de credenciales encontrados en un diagnóstico histórico fueron retirados de la documentación exportable. HTML crudo de Markdown se escapa. Las fuentes permanecen en Git y los derivados fuera de la raíz web pública. --- Document ID: security-overview # Modelo de seguridad ## Transporte y dispositivo Web Serial solo se usa en contexto HTTPS y requiere permiso explícito. El navegador conecta al puerto local; el backend nunca accede directamente al USB del usuario. ## Datos sensibles NVS, filesystem y backups pueden contener redes, credenciales, tokens, certificados y datos de clientes. No se muestran contenidos sensibles en logs ni se publican backups. Los binarios residen fuera de rutas web públicas y las descargas pasan por backend. ## Operaciones destructivas Erase y Restore se diferencian visualmente. Restore exige paquete validado, compatibilidad y texto RESTORE. NVS está excluida por defecto. Cancelar durante escritura deja advertencia de estado incompleto. ## Auditoría Lectura completa, guardado, ZIP, restore, cancelación y eliminación generan eventos adecuados. La auditoría registra actor, fecha, backup, dispositivo, modo, regiones, resultado y build, nunca credenciales. ## Roles futuros Viewer consultará documentación oficial; Operator accederá a operación; Administrator administrará backups y regenerará documentación; Developer verá API, ADR y arquitectura. La versión actual prepara estas fronteras, pero no debe considerarse acceso público irrestricto permanente. ## Límites criptográficos Un dump no contiene eFuses. Secure Boot y Flash Encryption pueden impedir restaurar en otro dispositivo. ESP Platform informa y bloquea incompatibilidades conocidas, pero no elude protecciones. --- Document ID: security-web-serial # Seguridad de Web Serial Web Serial permite al navegador hablar con un puerto serie local, pero no concede acceso automático. ## Contexto seguro La interfaz física se valida en https://iot.aeizoon.com. HTTP por dirección IP puede mostrar la web, pero no es un contexto seguro para Web Serial. Localhost queda reservado a diagnóstico puntual. ## Permisos El selector de puerto solo se abre tras una acción del usuario. El navegador muestra los dispositivos disponibles y recuerda permisos según su propia política. ESP Platform no enumera puertos sin consentimiento ni transmite datos serie al backend. ## Sesión esptool-js toma el puerto durante detección, lectura o escritura. Serial Monitor requiere cerrar esa sesión y volver a abrir el puerto con parámetros de monitor. Disconnect libera el puerto de forma ordenada. ## Riesgos Autorice solo dispositivos reconocidos. Una página con permiso serie puede enviar comandos al hardware. Use el dominio oficial, compruebe el certificado HTTPS y cierre la conexión al terminar. --- Document ID: adr-adr-000-template # ADR-000 - Title Date: YYYY-MM-DD Status: Proposed ## Context Describe the situation and forces that require a decision. ## Decision Describe the decision adopted or proposed. ## Consequences Describe positive, negative, and operational consequences. --- Document ID: adr-adr-001-backup-fingerprint-and-progress # 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. --- Document ID: adr-002-documentation-source # ADR-002: Fuente documental y exportaciones ## Estado Accepted, 2026-07-14. ## Contexto El producto necesita documentación web, descargas, búsqueda y consumo por IA sin mantener copias divergentes. ## Decisión Markdown en docs es la única fuente editable. Spring Boot escanea metadatos, renderiza HTML con HTML crudo escapado, genera texto, manifiesto, documentos maestros y ZIP. Cada resultado incluye SHA-256 y commit. Los documentos sin front matter se clasifican por ruta para conservar historia sin reescribirla. ## Consecuencias Git controla contenido y revisión. La web es de consulta. Los formatos derivados siempre reflejan la fuente cargada. La regeneración será una acción administrativa cuando exista autenticación. Los documentos críticos, incluida la Constitución, no se editan desde navegador.