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

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