iot.aeizoon.com

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.

Edge OS
+
aplicación específica
+
backend común
+
OTA
+
provisioning
+
fleet management

                           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

Usuario
   │
   │ Navegador
   ▼
Backend
   │
   ├───────────── OTA
   │
   ├───────────── API
   │
   ├───────────── Inventario
   │
   ▼
Dispositivo
   │
   ├──────── MQTT
   ├──────── Modbus
   ├──────── API Local
   ├──────── Web Local
   └──────── Hardware

Arquitectura
        │
        ▼
Codex
        │
        ▼
PlatformIO
        │
        ▼
Compilación
        │
        ▼
Firmware (.bin)
        │
        ▼
Repositorio Firmware
        │
        ▼
Flasher Web
        │
        ▼
ESP32

Repositorio Firmware

↓

OTA

↓

Dispositivos en producción

+--------------------------------------+
|          Aplicación                  |
| (AZ-TEMP / POWER / NFC / ...)        |
+--------------------------------------+
|             Edge OS                  |
|--------------------------------------|
| Configuración                        |
| MQTT                                 |
| Modbus                               |
| OTA                                  |
| Recovery                             |
| Logging                              |
| Seguridad                            |
| Web                                  |
| API                                  |
+--------------------------------------+
|             ESP-IDF                  |
+--------------------------------------+
|             Hardware                 |
+--------------------------------------+

Frontend Web

↓

API

↓

Servicios

↓

PostgreSQL

↓

Repositorio Firmware

1 ESP32

Centenares de dispositivos

                 Aplicación

                      │

 ┌────────────────────┼────────────────────┐

 │                    │                    │

 Configuración     Comunicaciones     Servicios internos

 │                    │                    │

 MQTT             Web Local          OTA

 Modbus           API REST           Recovery

 WiFi             Logging            Seguridad

 Ethernet         Diagnóstico        Storage

                      │

                   ESP-IDF

Arranque

↓

Inicialización Edge Platform

↓

Carga de configuración

↓

Inicialización de comunicaciones

↓

Inicialización de aplicación

↓

Funcionamiento normal

↓

OTA (cuando proceda)

↓

Reinicio

+------------------------------------------------+

                Aplicación

--------------------------------------------------

                Servicios Edge OS

--------------------------------------------------

Configuración

Comunicaciones

Seguridad

Storage

OTA

Recovery

Logging

Diagnóstico

API

Web

--------------------------------------------------

ESP-IDF

--------------------------------------------------

Hardware

+------------------------------------------------+

Reset

↓

Bootloader

↓

Edge OS

↓

Inicialización Core

↓

Configuración

↓

Red

↓

Servicios

↓

Aplicación

↓

Funcionamiento normal

Config

↓

Storage

↓

Network

↓

Web

↓

API

↓

MQTT

↓

Modbus

↓

OTA

↓

Aplicación

                Navegador

                     │

                     ▼

              Frontend Web

                     │

                     ▼

               API REST

                     │

     ┌───────────────┼────────────────┐

     │               │                │

 Firmware      Inventario       Usuarios

     │               │                │

 OTA         Fleet Manager     Auditoría

     │               │                │

     └───────────────┼────────────────┘

                     │

                PostgreSQL

                     │

          Repositorio Firmware

Una instalación doméstica

Múltiples instalaciones

↓

Múltiples clientes

↓

Backend multiusuario

↓

SaaS

Usuario

↓

Accede al Flasher

↓

Selecciona modelo de ESP32

↓

Selecciona firmware

↓

Conecta USB

↓

Permitir acceso al dispositivo

↓

Flashear

↓

Verificación

↓

Resultado

Conectar USB

↓

Abrir puerto

↓

Comprobar comunicación

↓

Borrar Flash (si procede)

↓

Escribir firmware

↓

Verificar escritura

↓

Reiniciar ESP32

↓

Resultado

Abrir la web

↓

Seleccionar firmware

↓

Conectar un ESP32 vacío

↓

Flashearlo completamente

↓

Comprobar que arranca correctamente

Repositorio Firmware

↓

Backend

↓

OTA Service

↓

Dispositivo

↓

Verificación

↓

Confirmación

↓

Funcionamiento normal

Bootloader

↓

Firmware A

↓

Firmware B

↓

Configuración

↓

Datos

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

Firmware nuevo

↓

Error

↓

Reinicio

↓

Bootloader

↓

Firmware anterior

↓

Funcionamiento normal

OTA

↓

Rollback

↓

Recovery

Bootloader

↓

Recovery Manager

↓

Diagnóstico

↓

Opciones de recuperación

↓

Reinicio

Flasheo

↓

Primer arranque

↓

Modo Provisioning

↓

Configuración inicial

↓

Registro en Backend

↓

Asignación de identidad

↓

Funcionamiento normal

Flashear

↓

Escanear QR

↓

Asignar nombre

↓

Finalizar

Instalación local

↓

Servidor único

↓

Varios usuarios

↓

Varios clientes

↓

Multiempresa

↓

SaaS

Organización

│

├──── Usuarios

│

└──── Dispositivos

          │

          ├──── Firmware

          │

          ├──── Aplicación

          │

          ├──── Hardware

          │

          ├──── OTA

          │

          ├──── Recovery

          │

          └──── Configuración

/api/v1/

/api/v1/devices

/api/v1/firmware

/api/v1/users

/api/v1/groups

{
  "success": true,
  "data": {},
  "message": ""
}

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:
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á:
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:
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.
                           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.
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.
Arquitectura
        │
        ▼
Codex
        │
        ▼
PlatformIO
        │
        ▼
Compilación
        │
        ▼
Firmware (.bin)
        │
        ▼
Repositorio Firmware
        │
        ▼
Flasher Web
        │
        ▼
ESP32
En el futuro:
Repositorio Firmware

↓

OTA

↓

Dispositivos en producción
***
9. Arquitectura del dispositivo
Cada dispositivo seguirá siempre el mismo esquema.
+--------------------------------------+
|          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:
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:
1 ESP32
hasta:
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.
                 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.
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.
+------------------------------------------------+

                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.
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:
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.
                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:
Una instalación doméstica
hasta:
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.
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á:
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:
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.
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:
Bootloader

↓

Firmware A

↓

Firmware B

↓

Configuración

↓

Datos
La configuración permanecerá separada del firmware.
***
6. Proceso OTA
El flujo general será:
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:
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:
OTA

↓

Rollback

↓

Recovery
Recovery únicamente actuará cuando los mecanismos anteriores no puedan resolver el problema.
***
5. Arquitectura general
Recovery estará formado por:
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á:
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:
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á:
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:
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:
/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:
/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:
{
  "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.
***