esp/plan.md

Plan de Desarrollo - Sistema ESP Admin

Progreso reciente (2025-10-03)

• Rediseño completo de UI con paleta moderna verde esmeralda

  • Variables CSS globales en layouts/layout.php para coherencia visual
  • Paleta: verde esmeralda (#10b981) como primario, grises slate para fondos
  • Gradientes y transiciones suaves en toda la aplicación

• Sistema de cards para listado de dispositivos (paginas/index.php)

  • Reemplazó tabla por grid responsive de cards (1/2/3 columnas)
  • Fondos dinámicos: verde claro (online), gris (offline)
  • Estados en tiempo real vía SSE con indicadores visuales
  • Mejor UX en móviles con diseño touch-friendly

• Menú responsive moderno (layouts/layout.php)

  • Slide-in desde derecha en móviles (264px)
  • Animación hamburguesa → X suave
  • Avatar circular con gradiente y inicial del usuario
  • Dropdown mejorado con animaciones scale y fade
  • Overlay con backdrop-blur para enfoque

• Login modernizado (paginas/login.php)

  • Fondo con gradiente animado (15s loop)
  • Glassmorphism en card de login
  • Logo flotante con animación de levitación
  • Inputs con íconos internos y focus states
  • Botón con efecto glow pulsante

• Página de Programación Visual (paginas/programacion.php) ⭐ NUEVO

  • Layout de 3 columnas: Entradas | Reglas | Salidas
  • Panel de entradas con cards en grilla responsive
  • Panel de salidas con control manual ON/OFF
  • Editor avanzado de reglas con modal
  • Triggers: cambio de entrada, timer, manual
  • Condiciones múltiples con operadores (==, !=, AND, OR)
  • Acciones múltiples (set, delay)
  • Estados en tiempo real vía SSE
  • Guardado persistente por dispositivo

• API de Reglas (api/api_reglas.php) ⭐ NUEVO

  • Endpoints: get_reglas, save_reglas, delete_regla, toggle_regla
  • Almacenamiento en data/reglas.json por chipid
  • Validación de estructura de reglas
  • Respuestas JSON estructuradas

• Rutas y navegación

  • Agregada ruta /programacion en index.php y .htaccess
  • Enlaces en menú desktop y móvil
  • Integración completa con sistema de autenticación

Progreso reciente (2025-09-17)

• UI Login (paginas/login.php + assets/js/auth.js)
  • Agregado checkbox "Recordar" con Tailwind. Si está activo, se guardan cookies remember_user y remember_pass por 10 años (SameSite=Lax, Secure en HTTPS) y se prellenan en el siguiente acceso.
  • Nota de seguridad: almacenar contraseña en cookies no es recomendado; a futuro se puede migrar a token persistente.
• Sistema de íconos SVG
  • assets/iconos.json centraliza SVG de la UI.
  • layouts/layout.php carga y aplica íconos con window.loadIcons() y window.applyIcons(); se ampliaron mapeos (icon-back, icon-add, icon-assign, icon-chart, icon-bolt, etc.).
  • paginas/dashboard.php reemplaza emojis por spans con clases de íconos.
• Dashboard (paginas/dashboard.php)
  • Se preserva la IP entre refresh utilizando lastKnownIP (no se borra al actualizar y se reinyecta al llegar por SSE ip).
  • Se añadió botón "Mqtt" y modal Tailwind que muestra JSON del dispositivo (estado SSE, IP, pines y firmware si está disponible).
• Firmware y Flasheo
  • data/dispositivos.json: se añadió el campo firmware por dispositivo.
  • paginas/flash.php: se lee version desde assets/flash/esp8266-manifest.json. Tras una OTA exitosa (detectada por SSE reboot del chipid objetivo), se persiste firmware vía POST /api/edit_dispositivo.

Progreso reciente (2025-09-12)

• API Puertos: compatibilidad legacy para dispositivos existentes
  • Se agregó soporte de acceso directo legacy para lectura de puertos sin pasar por el router:
    • Nuevo endpoint: api/get_puertos.php que responde a GET /api/get_puertos.php?chipid=<chipid> y devuelve el mismo JSON que get_puertos.
    • api/api_puertos.php también soporta invocación directa con ?chipid=<chipid> (sin $route) para compatibilidad.
• UI: Crear Dispositivo
  • Corrección: el combo de sectores en el modal “Crear nuevo dispositivo” ahora se llena correctamente (antes solo llenaba el del modal de edición).
  • Se implementó el handler de envío del formulario #form-add para invocar POST /api/index.php?r=add_dispositivo, cerrar el modal y refrescar el listado.
• Listado de Dispositivos (paginas/index.php)
  • Eliminado el uso del campo ip persistido; la columna IP ahora se muestra como placeholder y se actualiza en tiempo real mediante SSE (evento ip).
  • Se mantiene el estado de conexión por SSE; se unificó el consumo con el resto del sistema.
• Dashboard (paginas/dashboard.php)
  • La IP ya no se lee del JSON; se muestra por SSE (evento ip).
  • Se agregó visualización del ChipID en la tarjeta de “Estado de Conexión”.
  • Normalización del estado recibido por SSE (acepta online/offline, 1/0, true/false).
  • Se evitó que un refresh del dashboard muestre Offline por defecto: ahora se conserva el estado previo recibido por SSE o se muestra “Desconocido” hasta recibir evento.
• Backend (api/api_dispositivos.php)
  • En get_dispositivos, se omite el atributo ip en la respuesta (IP ahora viene por SSE).

Notas:

• CORS y cabeceras JSON siguen centralizadas en api/bootstrap.php.
• Las rutas login y sse_states están abiertas según diseño; el resto requiere sesión.

Resumen del Proyecto

Este es un sistema completo de administración para dispositivos ESP8266/ESP32 que permite gestionar dispositivos IoT de forma centralizada. El sistema incluye una interfaz web administrativa, API REST, comunicación MQTT, y firmware para los dispositivos ESP.

Progreso reciente (2025-09-11)

• Instalado Python 3.12 vía winget y PlatformIO Core vía pip (usuario actual).
• Corregida configuración de PlatformIO: src_dir movido a sección [platformio] en firmware/platformio.ini.
• Arreglado error de compilación en firmware/framework_4/framework_4.ino (comillas en <a href='/'>).
• Mejorado tools/build_firmware.ps1 para detectar pio.exe en rutas típicas de Windows (APPDATA/LocalAppData).
• Compilado firmware para env:nodemcuv2 con éxito.
• Artefactos generados:
  • firmware/.pio/build/nodemcuv2/firmware.bin
  • firmware/firmware.bin (copia rápida)
  • assets/flash/firmware/esp8266-nodemcuv2-YYYYMMDD-HHMMSS.bin

Arquitectura del Sistema

1. Frontend Web (PHP + JavaScript)

• Framework: PHP con Bootstrap 5.3.2 y jQuery 3.7.1
• Autenticación: Sistema de sesiones PHP con JWT
• Interfaz: Responsive design con tema claro fijo
• Comunicación: AJAX con API REST + Server-Sent Events (SSE)

2. Backend API (PHP)

• Router: Sistema de rutas basado en parámetro ?r=
• Autenticación: sesiones PHP para la web (con login); endpoints críticos tras autenticación.
• Almacenamiento: Archivos JSON en directorio /data/
• Comunicación: MQTT para control de dispositivos

3. Dispositivos ESP (Arduino/C++)

• Plataforma: ESP8266 con PlatformIO
• Conectividad: WiFi + MQTT
• Funcionalidades: OTA updates, configuración web, monitoreo de pines
• Comunicación: Bidireccional vía MQTT

Estructura de Archivos

esp/
├── index.php                 # Controlador principal con ruteo
├── composer.json             # Dependencias PHP
├── .env.example              # Variables de entorno
├── .htaccess                 # Configuración Apache
│
├── paginas/                  # Vistas del frontend
│   ├── index.php            # Dashboard principal
│   ├── puertos.php          # Gestión de puertos/pines
│   ├── flash.php            # Flasheo de firmware
│   └── login.php            # Página de login
│
├── layouts/                  # Plantillas HTML
│   ├── layout.php           # Layout principal (autenticado)
│   └── layout_login.php     # Layout para login
│
├── api/                      # API REST
│   ├── index.php            # Router de API
│   ├── bootstrap.php        # Configuración común
│   ├── api_dispositivos.php # CRUD dispositivos
│   ├── api_puertos.php      # Gestión de puertos
│   ├── api_sectores.php     # Gestión de sectores
│   ├── login.php            # Autenticación
│   ├── mqtt_publish.php     # Publicación MQTT
│   └── sse_states.php       # Server-Sent Events
│
├── assets/                   # Recursos estáticos
│   ├── css/layout.css       # Estilos principales
│   └── js/                  # JavaScript
│       ├── apiClient.js     # Cliente API
│       ├── auth.js          # Autenticación
│       └── layout.js        # Funcionalidad común
│
├── data/                     # Almacenamiento JSON
│   ├── dispositivos.json    # Registro de dispositivos
│   ├── puertos.json         # Configuración de pines
│   ├── entidades.json       # Tipos de entidades
│   ├── placas.json          # Definición de placas
│   └── sectores.json        # Sectores/ubicaciones
│
├── firmware/                 # Código para ESP
│   ├── platformio.ini       # Configuración PlatformIO
│   ├── framework_3/
│   │   └── framework_3.ino
│   └── framework_4/
│       └── framework_4.ino  # Firmware actualmente en uso
│
├── assets/
│   └── flash/
│       └── firmware/        # Artefactos .bin para OTA/flasheo
│
└── tools/                    # Herramientas
    ├── postman/             # Colección Postman
    ├── make_backup.*        # Scripts de backup
    └── build_firmware.ps1   # Build automatizado con PlatformIO

Funcionalidades Principales

1. Gestión de Dispositivos

• Registro: Agregar dispositivos por ChipID
• Configuración: Tag, modelo, ciudad, sector
• Monitoreo: Estado online/offline en tiempo real
• Control: Reinicio remoto vía MQTT

2. Gestión de Puertos/Pines

• Configuración: Asignación de pines por tipo de placa
• Entidades: Asociación de pines con entidades (Motor, Relé, Sensor, etc.)
• Modos: INPUT, OUTPUT, INPUT_PULLUP
• Monitoreo: Estado en tiempo real de entradas/salidas

3. Comunicación MQTT

• Topics:
  • dispositivo/{chipid}/state - Estado del dispositivo
  • dispositivo/{chipid}/comando - Comandos al dispositivo
  • dispositivo/{chipid}/valores/{pin} - Valores de pines
  • dispositivo/{chipid}/comando/reboot - Reinicio
• Broker: Configurado en .env (mqtt.penki.com.ar:8883)

4. Firmware ESP

• Configuración: Web interface para WiFi y MQTT
• OTA: Actualizaciones over-the-air
• Sincronización: Descarga automática de configuración de puertos
• Monitoreo: Publicación automática de cambios en pines

5. Flasheo de Firmware

• Web Serial: Interfaz para flashear via USB
• ESP Web Tools: Integración con herramientas estándar
• Manifesto: Configuración en /assets/flash/esp8266-manifest.json

Tecnologías Utilizadas

Backend

• PHP 7.4+ con extensiones: json, session, curl
• Composer para dependencias:
  • firebase/php-jwt: ^6.11
  • php-mqtt/client: 1.8
  • vlucas/phpdotenv: 5.6

Frontend

• Bootstrap 5.3.2 para UI
• jQuery 3.7.1 para AJAX
• Server-Sent Events para tiempo real
• Web Serial API para flasheo

Dispositivos

• ESP8266 (NodeMCU v2)
• Arduino Framework con PlatformIO
• Librerías:
  • ArduinoJson ^6.21.3
  • PubSubClient ^2.8
  • ESP8266-OTA

Configuración del Entorno

Variables de Entorno (.env)

# MQTT Broker
MQTT_HOST=mqtt.penki.com.ar
MQTT_PORT=8883
MQTT_TLS=true
MQTT_USERNAME=penki
MQTT_PASSWORD=Penki615

# API Authentication
API_BASIC_USER=api
API_BASIC_PASS=API#2025

# CORS
CORS_ALLOW_ORIGIN=*

Estructura de Datos

Dispositivos (dispositivos.json)

{
  "id_disp": 1,
  "chipid": "69A0FC",
  "tag": "Vivero1",
  "nombre": "Wemos D1 mini",
  "ciudad": "Rosario",
  "sector": "Vivero",
  "start_time": "2025-07-02 15:34:53"
}

Puertos (puertos.json)

{
  "69A0FC": {
    "D0": {
      "gpio": 16,
      "disp": "Interruptor",
      "modo": "INPUT_PULLUP",
      "notas": "Entrada botón"
    }
  }
}

Plan de Mejoras y Desarrollo

Fase 1: Estabilización (Corto Plazo)

1. Seguridad

   • Implementar validación de entrada más robusta
   • Agregar rate limiting a la API
   • Mejorar manejo de errores y logging

2. Usabilidad

   • Agregar confirmaciones para acciones destructivas
   • Mejorar feedback visual en operaciones
   • Implementar búsqueda y filtros en listas

3. Monitoreo

   • Dashboard con métricas de dispositivos
   • Historial de estados y eventos
   • Alertas por dispositivos offline

Fase 2: Funcionalidades Avanzadas (Mediano Plazo)

1. Automatización

   • Sistema de reglas y triggers
   • Programación de tareas
   • Escenarios predefinidos

2. Escalabilidad

   • Migración a base de datos (MySQL/PostgreSQL)
   • API REST más robusta con OpenAPI
   • Implementar caching (Redis)

3. Interfaz

   • Migrar a framework moderno (Vue.js/React)
   • PWA para uso móvil
   • Tema oscuro opcional

Fase 3: Integración y Expansión (Largo Plazo)

1. Integraciones

   • Home Assistant integration
   • Google Assistant/Alexa
   • Webhooks para servicios externos

2. Dispositivos

   • Soporte para ESP32
   • Soporte para otros microcontroladores
   • Sensores especializados

3. Análisis

   • Gráficos y tendencias
   • Machine Learning para predicciones
   • Reportes automatizados

Consideraciones de Seguridad

Actuales

• Autenticación básica implementada
• Sesiones PHP con configuración segura
• HTTPS requerido para funciones críticas

Recomendaciones

• Implementar 2FA
• Audit logs completos
• Encriptación de datos sensibles
• Firewall rules específicas
• Regular security updates

Deployment y Mantenimiento

Requisitos del Servidor

• PHP 7.4+ con extensiones requeridas
• Apache/Nginx con mod_rewrite
• MQTT Broker accesible
• SSL Certificate para HTTPS

Backup Strategy

• Scripts automatizados en /tools/
• Backup de archivos JSON
• Versionado de configuraciones
• Restore procedures documentados

Monitoreo

• Logs de aplicación en /api/logs/
• Monitoreo de dispositivos vía MQTT
• Health checks automatizados
• Alertas por email/SMS

Conclusión

El sistema ESP Admin es una solución completa y funcional para la gestión de dispositivos IoT basados en ESP8266. La arquitectura modular permite escalabilidad y mantenimiento eficiente, mientras que las tecnologías elegidas proporcionan una base sólida para el desarrollo futuro.

El plan de desarrollo propuesto asegura la evolución continua del sistema, priorizando la estabilidad y seguridad en el corto plazo, y expandiendo funcionalidades en fases posteriores.