Photobioreactor Dashboard

Sistema de monitoreo para Raspberry Pi y circuitos Atlas Scientific EZO:

Variable	Circuito	Dirección	Unidad
Temperatura	EZO-RTD	0x66	°C
pH	EZO-pH	0x63	pH
Oxígeno disuelto	EZO-DO	0x61	mg/L
Conductividad	EZO-EC	0x64	µS/cm

El sistema incluye dashboard responsive, históricos Chart.js, alarmas, exportación CSV/Excel, consola de comandos y panel de calibración.

Arquitectura

EZO por I2C
    |
EZO_ACQUIRE / EZO_COMMAND
    |
Recolector Node ---------> data/*.json
    |                      logs/*.csv
    |
API Express <------------ Dashboard
    ^
    |
Nginx

EZO_ACQUIRE obtiene las cuatro lecturas en un ciclo agrupado. EZO_COMMAND ejecuta comandos interactivos y calibraciones. Ambos comparten el bloqueo /tmp/photobioreactor-i2c.lock.

Desarrollo sin sensores

npm ci
npm test

Ejecute en dos terminales:

EZO_MODE=demo npm run acquire
EZO_MODE=demo npm start

Abra http://localhost:3000/frontend/index.html.

En PowerShell:

$env:EZO_MODE = "demo"
npm run acquire

Y en una segunda terminal:

$env:EZO_MODE = "demo"
npm start

Raspberry Pi

El despliegue de producción usa EZO_MODE=hardware, systemd y Nginx:

chmod +x scripts/install-raspberry-pi.sh
sudo ./scripts/install-raspberry-pi.sh

La guía de preparación, detección I2C, calibración y prueba integral está en docs/RASPBERRY_PI_DEPLOYMENT.md.

Sensores conectados parcialmente

Para pruebas con solo EZO-RTD conectado, limite la adquisicion al sensor de temperatura desde el panel de configuracion o en config/runtime.json:

{
  "loggingRateSeconds": 1,
  "enabledSensors": ["temperature"]
}

Tambien puede forzarlo temporalmente por entorno:

EZO_MODE=hardware EZO_ENABLED_SENSORS=temperature npm run acquire

En produccion puede dejar EZO_ENABLED_SENSORS=temperature en /etc/default/photobioreactor como override. Cuando esten conectados los cuatro circuitos, deje la variable vacia y habilite RTD, pH, DO y EC desde el panel.

Seguridad operativa

En produccion configure API_AUTH_TOKEN en /etc/default/photobioreactor para proteger comandos EZO, calibracion, cambios de configuracion y borrado de historicos. El dashboard incluye un campo "Token API" que guarda el valor solo en el navegador local y lo envia como header X-API-Token. La API aplica comparacion de token en tiempo constante y headers defensivos basicos (nosniff, DENY, same-origin, no-store). Los POST criticos aplican rate limit en memoria mediante API_RATE_LIMIT_WINDOW_MS y API_RATE_LIMIT_MAX.

Bitacora de alarmas

El recolector registra transiciones de alarma en logs/alarms.csv y la API las expone en GET /api/alarms. Se registran entradas a WARNING, CRITICAL y OFFLINE, ademas de recuperaciones a NORMAL.

Retencion historica

config/runtime.json define historyRetentionDays. El valor puede ser 7, 30, 90, 365 o 0 para conservar indefinidamente. El recolector poda filas antiguas de CSV sin cambiar los nombres que usa el dashboard.

Las graficas del dashboard muestran solo los datos del dia actual para evitar saturacion visual. Los CSV conservan el periodo completo configurado por retencion y siguen disponibles para exportacion.

Umbrales de alarma

Los limites se guardan en config/alarms.json, se consultan con GET /api/config/alarms y pueden editarse desde el dashboard. Guardar cambios requiere API_AUTH_TOKEN cuando esta configurado.

Notificaciones

config/notifications.json define canales de webhook y Telegram. El recolector envia notificaciones cuando una alarma persistente alcanza minSeverity. La API expone configuracion redactada en GET /api/config/notifications; guardar requiere token y nunca devuelve secretos sin redaccion.

La configuracion completa del bot, chatId, pruebas y diagnostico esta en docs/TELEGRAM_BOT_SETUP.md.

Archivos de datos

• Lecturas actuales: data/EZORTD.json, EZOPH.json, EZODO.json, EZOEC.json.
• Históricos: logs/temperature.csv, ph.csv, do.csv, ec.csv.
• Umbrales: config/alarms.json.
• Frecuencia de adquisición: config/runtime.json.

Los CSV usan una única nomenclatura y el formato:

timestamp,value
2026-06-22T12:00:00.000Z,25.123

Documentación

• Estado actual: PROJECT_STATUS.md
• Comandos y calibración: docs/EZO_COMMANDS.md
• Despliegue: docs/RASPBERRY_PI_DEPLOYMENT.md
• Telegram: docs/TELEGRAM_BOT_SETUP.md
• Diseño extendido: ARCHITECTURE.md

No se utiliza un driver personalizado del kernel. Linux ya proporciona la capa I2C mediante /dev/i2c-1; el protocolo ASCII, la adquisición y la calibración se mantienen en espacio de usuario para facilitar mantenimiento y diagnóstico.