# 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

```text
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

```bash
npm ci
npm test
```

Ejecute en dos terminales:

```bash
EZO_MODE=demo npm run acquire
EZO_MODE=demo npm start
```

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

En PowerShell:

```powershell
$env:EZO_MODE = "demo"
npm run acquire
```

Y en una segunda terminal:

```powershell
$env:EZO_MODE = "demo"
npm start
```

## Raspberry Pi

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

```bash
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`](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`:

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

Tambien puede forzarlo temporalmente por entorno:

```bash
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`](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:

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

## Documentación

- Estado actual: [`PROJECT_STATUS.md`](PROJECT_STATUS.md)
- Comandos y calibración: [`docs/EZO_COMMANDS.md`](docs/EZO_COMMANDS.md)
- Despliegue: [`docs/RASPBERRY_PI_DEPLOYMENT.md`](docs/RASPBERRY_PI_DEPLOYMENT.md)
- Telegram: [`docs/TELEGRAM_BOT_SETUP.md`](docs/TELEGRAM_BOT_SETUP.md)
- Diseño extendido: [`ARCHITECTURE.md`](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.