# 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)
```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)
```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)
```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.
