🌡️ SISTEMA PROFESIONAL DE MONITORIZACIÓN AMBIENTAL

Plataforma Distribuida ESP32 + SHT41 + Servidor Linux

Documentación Técnica Completa
Versión 2.0 - Febrero 2026

Tabla de Contenidos

Resumen Ejecutivo
Arquitectura del Sistema
Componentes del Sistema
Scripts del Servidor
Instalación y Configuración
Operación y Mantenimiento
API REST del ESP32
Sistema de Alertas
Seguridad y Mejores Prácticas
Resolución de Problemas

1. Resumen Ejecutivo {#resumen-ejecutivo}

Sistema robusto y escalable diseñado para monitorizar temperatura y humedad en tiempo real, con capacidades empresariales de histórico, alertas inteligentes y observabilidad completa. Arquitectura probada lista para entornos productivos.

1.1 Características Principales

📡 Recolección de datos vía HTTP REST
🗄️ Almacenamiento histórico eficiente en RRDTool
📊 Generación automática de gráficos (24h, 7d, 30d)
🌐 Dashboard web responsive con auto-actualización
🚨 Sistema de alertas por email ante anomalías
🔍 Descubrimiento automático de sensores en red
♻️ Recuperación autónoma ante fallos
🔐 Seguridad y autenticación opcional

1.2 Casos de Uso

🏠 Hogar inteligente y automatización domótica
🌱 Agricultura de precisión e invernaderos
🏭 Monitorización industrial
🖥️ Data centers y salas de servidores
🏥 Instalaciones médicas y laboratorios
📦 Almacenes y logística

2. Arquitectura del Sistema {#arquitectura}

El sistema implementa una arquitectura distribuida de tres capas con separación clara de responsabilidades:

2.1 Diagrama de Arquitectura

ESP32 + SHT41 ──HTTP/JSON──► Servidor Linux ──► Dashboard Web
 (Sensores) (RRD + Scripts) (Gráficos)

2.2 Componentes y Responsabilidades

Componente	Función Principal	Tecnología
ESP32 + SHT41	Lectura de datos ambientales, API REST, buffer de logs	MicroPython + asyncio
Servidor Linux	Recolección, almacenamiento histórico, alertas, generación de gráficos	Python 3 + Bash
RRDTool	Base de datos de series temporales con consolidación automática	Round Robin Database
Nginx/Apache	Publicación del dashboard web y archivos estáticos	Servidor HTTP
Sistema de Alertas	Detección de anomalías y notificaciones por email	Python + SMTP

2.3 Flujo de Datos

Lectura: Los sensores ESP32 leen temperatura y humedad cada 5 segundos del SHT41
Exposición: Los datos se exponen vía API REST en formato JSON
Consulta: El servidor Linux consulta cada sensor cada 5 minutos (configurable)
Almacenamiento: Los datos se almacenan en bases de datos RRD individuales por sensor
Visualización: Se generan gráficos cada 10 minutos para diferentes períodos
Dashboard: El dashboard web se actualiza automáticamente mostrando datos actuales
Monitorización: El sistema de alertas evalúa umbrales y tendencias continuamente

3. Componentes del Sistema {#componentes}

3.1 Firmware ESP32

Sistema asíncrono basado en MicroPython con arquitectura modular y gestión eficiente de memoria.

3.1.1 Estructura del Firmware

Archivo	Función
boot.py	Inicialización del sistema y conectividad WiFi
main.py	Orquestación de tareas asíncronas (sensor, HTTP, mantenimiento) y sistema de logs
sht41.py	Driver optimizado para sensor SHT41 con reinicialización automática
wifi_service.py	Gestión de conectividad con reconexión automática y supervisión NTP
secrets.py	Credenciales y configuración local (no incluir en git, ver secrets.py.example)

3.1.2 Tareas Asíncronas

Tarea	Función	Intervalo
Sensor Task	Lectura periódica del SHT41 vía I2C	5 segundos
HTTP Task	Servidor REST no bloqueante en puerto 80	Continuo
Maintenance Task	Garbage collection y watchdog	5 segundos (GC cada 30s)
WiFi Monitor	Verificación y reconexión de red	10 segundos

3.1.3 Configuración I2C del SHT41

GPIO: 21 (SDA) / 22 (SCL)
Frecuencia: 100 kHz
Dirección I2C: 0x44 (por defecto)
Buffer optimizado: bytearray(6) reutilizable

3.1.4 Sistema de Watchdog

Watchdog hardware configurable mediante la constante WDT_LEVEL en main.py. Solo está activo un nivel a la vez:

WDT_LEVEL	Timeout	Uso recomendado
0	Desactivado	Desarrollo y depuración
1	30 segundos	Producción estándar (valor por defecto)
2	15 segundos	Entornos que requieren detección rápida de bloqueos
3	8 segundos	Máxima vigilancia (requiere feeds más frecuentes)

El watchdog se alimenta en el loop de lectura del sensor y en el loop de mantenimiento, garantizando un feed mínimo cada 5 segundos con el nivel por defecto.

4. Scripts del Servidor {#scripts}

4.1 config_server.py - Configuración Central

Archivo de configuración centralizado que define todos los parámetros del sistema.

4.1.1 Parámetros Principales

Parámetro	Descripción	Valor por Defecto
RRD_PATH	Ruta de bases de datos RRD	/var/lib/sensores_rrd
SENSOR_FILE	Archivo de mapeo sensores	sensores.json
TEMP_MAX	Temperatura máxima (°C)	35
TEMP_MIN	Temperatura mínima (°C)	5
HUM_MAX	Humedad máxima (%)	80
TEMP_TREND_THRESHOLD	Umbral cambio brusco (°C)	5
ALERT_EMAIL	Email de alertas	tu_correo@gmail.com
BASE_NET	Red base para descubrimiento	192.168.1.
DISCOVERY_WORKERS	Hilos paralelos descubrimiento	20
ALERT_THROTTLE_TIME	Intervalo entre alertas (s)	3600

4.2 discover_sensores.py - Descubrimiento Automático

Script inteligente que escanea la red local en busca de dispositivos con la API del sensor. Utiliza ThreadPoolExecutor para escaneo paralelo de hasta 255 direcciones IP.

Funcionamiento:

Escaneo Paralelo: Utiliza 20 hilos de trabajo simultáneos
Detección: Consulta /api/health en cada IP
Validación: Verifica respuesta JSON con status: ok
Nomenclatura: Asigna nombres únicos (s1, s2, s3...)
Creación RRD: Genera automáticamente la base de datos
Backup: Crea copias de seguridad antes de modificar

Configuración RRD:

Parámetro	Valor	Descripción
Step	300 segundos	Intervalo base de muestreo (5 minutos)
DS:temp	GAUGE:600:-40:80	Temperatura (-40°C a 80°C)
DS:hum	GAUGE:600:0:100	Humedad (0% a 100%)
RRA 1 día	AVERAGE:0.5:1:288	Promedios cada 5 min (288 muestras)
RRA 1 semana	AVERAGE:0.5:12:168	Promedios cada 1 hora (168 muestras)
RRA 1 año	AVERAGE:0.5:288:365	Promedios diarios (365 muestras)

4.3 update_sensores.py - Recolección de Datos

Script principal de recolección que consulta cada sensor, actualiza las bases de datos RRD y ejecuta el sistema de alertas.

Proceso de Recolección:

Carga de Configuración: Lee sensores.json con recuperación desde backup
Consulta HTTP: GET a /api/sensor con timeout de 5 segundos
Validación: Verifica campos temperature y humidity válidos
Actualización RRD: Inserta datos con rrdtool update
Verificación de Anomalías: Compara contra umbrales configurados
Análisis de Tendencias: Detecta cambios bruscos
Gestión de Alertas: Envía notificaciones con throttling

Sistema de Alertas:

Tipo de Alerta	Condición	Directorio de Estado
Anomalía	Valor fuera de rango	/tmp/sensor_anomaly_alerts
Tendencia	Cambio brusco > 5°C	/tmp/sensor_trend_alerts
Sensor Caído	Timeout o error HTTP	/tmp/sensor_down_alerts

4.4 graficas_sensores.sh - Generación de Gráficos

Script Bash que genera gráficos PNG para cada sensor utilizando RRDTool.

Gráficos Generados:

Archivo	Período	Resolución
s1_1d.png	24 horas	5 minutos
s1_7d.png	7 días	1 hora
s1_30d.png	30 días	1 hora consolidada

Características:

Dimensiones: 800x300 píxeles
Colores diferenciados por período
Doble eje Y: Temperatura (°C) y Humedad (%)
Auto-escalado de ejes
Estadísticas: Actual, Promedio, Mínimo, Máximo

4.5 monitor_memory.py - Observabilidad de Memoria

Herramienta de diagnóstico avanzada para monitorizar el uso de memoria del ESP32 en tiempo real.

Métricas Monitorizadas:

Métrica	Descripción	Umbral
heap_free	Memoria libre disponible	< 20 KB Warning
heap_alloc	Memoria asignada	Tendencia
gc_freed_bytes	Bytes liberados por GC	> 5 KB presión alta
leak_rate	Tasa de pérdida	> 1024 B/min sospechoso

4.6 verify_installation.py - Verificación del Sistema

Script de diagnóstico completo que verifica todos los componentes del sistema.

5. Instalación y Configuración {#instalacion}

5.1 Instalación Automática del Servidor

# 1. Descargar el repositorio
git clone https://github.com/usuario/sensor-monitoring.git
cd sensor-monitoring
# 2. Ejecutar instalador como root
sudo bash install_server.sh

5.2 Configuración Post-Instalación

Paso 1: Configurar Parámetros

sudo cp /usr/local/bin/config_server.py.example /usr/local/bin/config_server.py
sudo nano /usr/local/bin/config_server.py

Paso 2: Configurar Email

Para Gmail, generar contraseña de aplicación en Google Account > Security

ALERT_EMAIL = "tu_correo@gmail.com"
SMTP_USER = "tu_correo@gmail.com"
SMTP_PASS = "abcd efgh ijkl mnop" # Contraseña de aplicación

Paso 3: Descubrir Sensores

sudo /usr/local/bin/discover_sensores.py

Paso 4: Verificar Instalación

sudo /usr/local/bin/verify_installation.py

Paso 5: Acceder al Dashboard

Abrir navegador: http://IP_DEL_SERVIDOR/index.html

6. Operación y Mantenimiento {#operacion}

6.1 Tareas Automáticas (Cron)

Tarea	Frecuencia	Log
Actualización	/5 * * *	/var/log/sensores/update.log
Gráficos	/10 * * *	/var/log/sensores/graficas.log
Descubrimiento	0 /6 * *	/var/log/sensores/discover.log

6.2 Agregar Nuevos Sensores

Método Automático (Recomendado):

sudo /usr/local/bin/discover_sensores.py

6.3 Respaldo y Restauración

# Respaldar configuración
tar -czf backup_sensores_$(date +%Y%m%d).tar.gz \
 /var/lib/sensores_rrd/sensores.json \
 /usr/local/bin/config_server.py
# Respaldar histórico
tar -czf backup_rrd_$(date +%Y%m%d).tar.gz \
 /var/lib/sensores_rrd/*.rrd

7. API REST del ESP32 {#api}

7.1 Endpoints Disponibles

Endpoint	Método	Descripción
/api/sensor	GET	Última lectura de temp/hum
/api/health	GET	Estado general del sistema
/api/mem	GET	Estadísticas de memoria
/api/logs	GET	Últimas líneas del log
/log.txt	GET	Archivo completo de log

7.2 Ejemplos de Uso

Obtener Lectura:

curl http://192.168.1.50/api/sensor
# Respuesta:
{
 "temperature": 23.5,
 "humidity": 55.2,
 "timestamp": 1738819200
}

Verificar Estado:

curl http://192.168.1.50/api/health
# Respuesta:
{
 "status": "ok",
 "wifi_connected": true,
 "ip": "192.168.1.50",
 "uptime_sec": 86400,
 "last_sensor_ok": 1738819200,
 "sensor_error_count": 0
}

Estadísticas de Memoria:

curl http://192.168.1.50/api/mem
# Respuesta:
{
 "heap_free": 48200,
 "heap_alloc": 21300,
 "gc_freed_bytes": 3400,
 "heap_total": 69500
}

8. Sistema de Alertas {#alertas}

8.1 Tipos de Alertas

Tipo	Condición	Ejemplo
Temp Alta	temp > 35°C	🌡️ Temperatura: 37.2°C
Temp Baja	temp < 5°C	❄️ Temperatura: 3.1°C
Humedad Alta	hum > 80%	💧 Humedad: 85.5%
Cambio Brusco	Δtemp > 5°C	📈 Cambio: 23°C → 29°C
Sensor Caído	Timeout	⚠️ Sin respuesta

8.2 Throttling de Alertas

Para evitar spam, período mínimo de 1 hora entre alertas similares.

9. Seguridad y Mejores Prácticas {#seguridad}

9.1 Seguridad de Red

Medida	Implementación
VLAN IoT	Segmentar sensores en red dedicada
Firewall	Restringir acceso a puertos 80/443
IP Estática	Configurar DHCP reservation
HTTPS/TLS	Certificado SSL en Nginx

9.2 Credenciales y Git

El archivo secrets.py contiene credenciales WiFi y HTTP y nunca debe incluirse en el repositorio. El fichero .gitignore lo excluye automáticamente. Para configurar un nuevo dispositivo, copiar secrets.py.example a secrets.py y rellenar los valores reales:

cp secrets.py.example secrets.py
# Editar secrets.py con credenciales reales

9.3 Checklist de Producción

✓ IP estática configurada en sensores
✓ NTP sincronizado
✓ /api/mem monitorizado
✓ Alertas activas y probadas
✓ Acceso HTTP restringido
✓ Sensores en VLAN IoT
✓ Backups automáticos
✓ secrets.py en .gitignore
✓ Documentación actualizada

10. Resolución de Problemas {#troubleshooting}

10.1 Sensor No Detectado

Síntomas: discover_sensores.py no encuentra el sensor

Soluciones:

Verificar conexión WiFi del ESP32
Confirmar misma red (BASE_NET)
Probar: ping 192.168.1.50
Verificar API: curl http://192.168.1.50/api/health

10.2 Gráficos No Se Generan

Síntomas: Dashboard muestra error en imágenes