bioreactor-multiparametric-daq-shield/README.md

# Photobioreactor Dashboard

Dashboard web para monitorear un fotobiorreactor con Raspberry Pi y circuitos
Atlas Scientific EZO por I2C.

El sistema ya contempla:

- Lecturas en vivo de temperatura, pH, oxigeno disuelto y conductividad.
- Historial CSV por sensor.
- Graficas Chart.js.
- Alarmas configurables.
- Exportacion CSV y Excel.
- Consola de comandos EZO.
- Panel de calibracion.
- Notificaciones por webhook y Telegram.
- Despliegue permanente con `systemd` y Nginx en Raspberry Pi.

## Lectura Rapida

Si es la primera vez que usas el proyecto, sigue este orden:

1. [Inicio rapido](docs/QUICK_START.md)
2. [Despliegue en Raspberry Pi](docs/RASPBERRY_PI_DEPLOYMENT.md)
3. [Comandos y calibracion EZO](docs/EZO_COMMANDS.md)
4. [Diagnostico de problemas](docs/TROUBLESHOOTING.md)

Si ya conoces el sistema y necesitas detalle tecnico:

- [Arquitectura](ARCHITECTURE.md)
- [Estado del proyecto](PROJECT_STATUS.md)
- [Calculo de almacenamiento](docs/STORAGE_ESTIMATE.md)
- [Telegram](docs/TELEGRAM_BOT_SETUP.md)

## Sensores Esperados

| Variable | Circuito | Direccion I2C | Archivo JSON | CSV historico |
|---|---|---:|---|---|
| Temperatura | EZO-RTD | `0x66` | `data/EZORTD.json` | `logs/temperature.csv` |
| pH | EZO-pH | `0x63` | `data/EZOPH.json` | `logs/ph.csv` |
| Oxigeno disuelto | EZO-DO | `0x61` | `data/EZODO.json` | `logs/do.csv` |
| Conductividad | EZO-EC | `0x64` | `data/EZOEC.json` | `logs/ec.csv` |

El proyecto puede operar con sensores parciales. Un sensor deshabilitado se
muestra como `DESHABILITADO` y no cuenta como alarma. Un sensor habilitado pero
no disponible se muestra como `OFFLINE`.

## Arquitectura Corta

```text
Sensores EZO I2C
    |
    | /dev/i2c-1
    v
EZO_ACQUIRE / EZO_COMMAND
    |
    v
Recolector Node.js  ---> data/*.json
    |                  logs/*.csv
    v
API Express <------ Dashboard web
    ^
    |
Nginx
```

`EZO_ACQUIRE` toma lecturas agrupadas de los sensores habilitados.
`EZO_COMMAND` envia comandos individuales, incluyendo diagnostico y calibracion.
Ambos usan el mismo bloqueo:

```text
/tmp/photobioreactor-i2c.lock
```

Ese bloqueo evita que una lectura automatica y un comando manual usen el bus I2C
al mismo tiempo.

## Prueba Sin Sensores

En una computadora de desarrollo:

```bash
npm ci
npm test
```

Modo demo en dos terminales:

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

```bash
EZO_MODE=demo npm start
```

Abrir:

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

En PowerShell:

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

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

## Raspberry Pi

Instalacion de produccion desde el repo clonado:

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

El instalador:

- Copia la aplicacion a `/opt/photobioreactor`.
- Instala dependencias.
- Compila `EZO_COMMAND` y `EZO_ACQUIRE`.
- Crea el usuario `photobioreactor`.
- Configura servicios `systemd`.
- Configura Nginx.
- Fuerza `EZO_MODE=hardware` para produccion.

Servicios principales:

```bash
systemctl status photobioreactor-api --no-pager
systemctl status photobioreactor-acquisition --no-pager
systemctl status nginx --no-pager
```

Dashboard:

```text
http://IP_DE_LA_RASPBERRY/frontend/index.html
```

## Configuracion Operativa

Archivo principal de operacion:

```text
/opt/photobioreactor/config/runtime.json
```

Ejemplo con tres sensores conectados:

```json
{
  "loggingRateSeconds": 5,
  "historyRetentionDays": 30,
  "enabledSensors": [
    "temperature",
    "ph",
    "ec"
  ]
}
```

Ejemplo con los cuatro sensores:

```json
{
  "loggingRateSeconds": 5,
  "historyRetentionDays": 30,
  "enabledSensors": [
    "temperature",
    "ph",
    "do",
    "ec"
  ]
}
```

Despues de cambiar esta configuracion:

```bash
sudo systemctl restart photobioreactor-acquisition
```

## Datos Guardados

Los JSON en `data/` se sobrescriben; no crecen de forma indefinida.
Los CSV en `logs/` si crecen hasta el limite definido por
`historyRetentionDays`.

Formato CSV:

```csv
timestamp,value
2026-07-07T17:26:13.459Z,25.132
```

En el peor caso operativo:

```text
4 sensores
1 lectura por segundo
30 dias
```

el sistema guarda aproximadamente:

```text
350 a 375 MB por mes
```

Ver el calculo completo en [docs/STORAGE_ESTIMATE.md](docs/STORAGE_ESTIMATE.md).

## Exportaciones

Las graficas del dashboard muestran solo el dia actual para evitar saturacion
visual. Las exportaciones CSV y Excel leen el historico disponible en los CSV.
Por eso un Excel puede pesar mucho mas que lo que se ve en pantalla.

## Seguridad

En produccion configure `API_AUTH_TOKEN` en:

```text
/etc/default/photobioreactor
```

Ese token protege:

- Comandos EZO.
- Calibraciones.
- Cambios de configuracion.
- Borrado de historicos.
- Configuracion de notificaciones.

El dashboard guarda el token solo en el navegador local y lo envia como header:

```text
X-API-Token
```

No exponga el dashboard directamente a Internet. Use una red local confiable o
una VPN.

## Documentacion

- [Inicio rapido](docs/QUICK_START.md)
- [Indice de documentacion](docs/README.md)
- [Despliegue en Raspberry Pi](docs/RASPBERRY_PI_DEPLOYMENT.md)
- [Comandos y calibracion EZO](docs/EZO_COMMANDS.md)
- [Diagnostico de problemas](docs/TROUBLESHOOTING.md)
- [Calculo de almacenamiento](docs/STORAGE_ESTIMATE.md)
- [Telegram](docs/TELEGRAM_BOT_SETUP.md)
- [Arquitectura](ARCHITECTURE.md)
- [Estado del proyecto](PROJECT_STATUS.md)

## Nota Sobre Drivers Del Kernel

No se usa un driver personalizado del kernel. Linux ya expone el bus I2C como
`/dev/i2c-1`. Mantener el protocolo Atlas EZO en espacio de usuario simplifica
diagnostico, mantenimiento, calibracion y despliegue.