bioreactor-multiparametric-.../docs/EZO_COMMANDS.md

# Comandos y calibración Atlas Scientific EZO

Esta guía cubre los cuatro circuitos utilizados por el dashboard. La sintaxis,
los tiempos y el orden de calibración se verificaron contra los datasheets
oficiales indicados al final del documento.

## Sensores del proyecto

| Variable | Circuito | Dirección I2C | Lectura |
|---|---|---:|---:|
| Temperatura | EZO-RTD | `0x66` | 600 ms |
| pH | EZO-pH | `0x63` | 900 ms |
| Oxígeno disuelto | EZO-DO | `0x61` | 600 ms |
| Conductividad | EZO-EC | `0x64` | 600 ms |

## Uso desde el dashboard

La consola web envía los comandos por la API y el helper `EZO_COMMAND`. El
bloqueo compartido de `/tmp/photobioreactor-i2c.lock` evita que una lectura y
un comando usen el bus al mismo tiempo. No es necesario abrir una terminal en
la Raspberry para consultar, compensar o calibrar.

Los comandos que borran datos, importan calibraciones, reinician el circuito,
cambian la dirección o cambian el protocolo exigen confirmación. La consola
acepta únicamente sintaxis documentada para el sensor seleccionado.

Después de cada comando de calibración enviado desde el panel se ejecuta
automáticamente `Cal,?` para mostrar el número real de puntos guardados.

## Protocolo I2C

La primera posición de cada respuesta es un código Atlas:

| Código | Significado |
|---:|---|
| `1` | Comando procesado correctamente |
| `2` | Error de sintaxis |
| `254` | El circuito sigue procesando |
| `255` | No hay datos disponibles |

`EZO_COMMAND` espera el tiempo oficial y vuelve a consultar si recibe `254`.
Los comandos `Sleep`, `Factory`, `I2C,n` y `Baud,n` no entregan respuesta.

## Diagnóstico básico

Desde la consola web seleccione el sensor y use:

```text
i
Status
R
Cal,?
```

Respuestas esperadas:

```text
?i,pH,2.17
?Status,P,3.83
6.982
?Cal,3
```

`Cal,0` significa cero puntos guardados. El significado de los demás números
depende del sensor y del esquema de calibración.

## Calibración EZO-RTD

El RTD usa una calibración de un punto contra una referencia conocida:

```text
Cal,25.00
Cal,?
```

Espere a que la sonda y la referencia alcancen equilibrio térmico antes de
enviar `Cal,<temperatura>`. Atlas permite cualquier temperatura válida. El
comando tarda 600 ms. Para borrar el punto use `Cal,clear`.

Comandos adicionales exclusivos del RTD:

```text
S,c             salida en Celsius
S,k             salida en Kelvin
S,f             salida en Fahrenheit
S,?             consultar escala
D,n             registrar cada n x 10 segundos; n entre 1 y 32000
D,0             desactivar registrador interno
D,?             consultar intervalo
M               recuperar la siguiente lectura guardada
M,?             consultar última posición guardada
M,clear         borrar memoria interna
```

El historial principal del proyecto se guarda en CSV; el registrador interno
del RTD es independiente y normalmente puede permanecer desactivado.

## Calibración EZO-pH

Compruebe primero que la sonda cambia de lectura. Una sonda bloqueada de forma
permanente en 0, 7 o 14 no debe calibrarse. Enjuague la sonda entre soluciones,
no regrese solución usada al frasco y observe lecturas hasta que se estabilicen,
normalmente durante 1 a 2 minutos.

Orden Atlas para tres puntos:

```text
Cal,mid,7.00
Cal,low,4.00
Cal,high,10.00
Cal,?
Slope,?
```

El punto medio siempre va primero. Enviar de nuevo `Cal,mid,n` elimina los
puntos bajo y alto existentes. Cada punto tarda 900 ms. `Slope,?` informa la
pendiente ácida, la pendiente básica y el desplazamiento del punto neutro;
sirve para revisar calibración y salud de la sonda.

Compensación temporal de temperatura:

```text
T,25.0
T,?
RT,25.0
```

`T,n` no se conserva al cortar energía. `RT,n` aplica la temperatura y toma una
lectura en la misma operación.

## Calibración EZO-DO

Para calibrar mantenga primero los valores predeterminados: temperatura 20 °C,
salinidad 0 y presión 101.3 kPa. Atlas indica calibrar primero y aplicar las
compensaciones reales después.

Calibración de un punto:

```text
Cal
```

Calibración de dos puntos, en este orden:

```text
Cal,0
Cal
Cal,?
```

Para `Cal,0`, coloque la sonda en solución de cero oxígeno, agite para retirar
burbujas y observe lecturas hasta estabilizar. Una sonda con electrolito nuevo
puede tardar varias horas en llegar a cero. Después exponga la sonda al aire;
normalmente estabiliza en 5 a 30 segundos. Ambos comandos tardan 1300 ms.

Compensaciones, aplicadas después de calibrar:

```text
T,<grados Celsius>
T,?
S,<conductividad en µS/cm>
S,<salinidad>,ppt
S,?
P,<presión en kPa>
P,?
RT,<grados Celsius>
```

La compensación de salinidad es irrelevante por debajo de 2500 µS/cm. Los
valores de temperatura, salinidad y presión cambian la lectura calculada, no
los puntos guardados en la sonda.

## Calibración EZO-EC

Configure primero la constante real de la sonda. El firmware actual admite
valores de K 0.01 a K 10.2:

```text
K,1.0
K,?
```

No cambie la compensación predeterminada de 25 °C durante la calibración. Si la
solución está 5 °C o más alejada de 25 °C, use el valor que indique la tabla de
temperatura del frasco, manteniendo `T,25` en el circuito.

La calibración en seco siempre es obligatoria, aunque la lectura ya marque 0:

```text
Cal,dry
```

Dos puntos, para precisión en una banda estrecha:

```text
Cal,dry
Cal,<valor>
```

Tres puntos, para un rango amplio:

```text
Cal,dry
Cal,low,<valor>
Cal,high,<valor>
```

Valores recomendados por Atlas:

| Sonda | Bajo | Alto |
|---|---:|---:|
| K 0.1 | 84 µS/cm | 1413 µS/cm |
| K 1.0 | 12880 µS/cm | 80000 µS/cm |
| K 10 | 12880 µS/cm | 150000 µS/cm |

Use recipientes limpios, retire burbujas de la zona sensible, espere estabilidad
y enjuague antes del punto alto. Todos los comandos de calibración EC tardan
600 ms. Nunca use `Cal,0`; el cero de EC se establece con `Cal,dry`.

Después de calibrar puede aplicar compensación temporal:

```text
T,<grados Celsius>
T,?
RT,<grados Celsius>
```

Otros comandos EC admitidos son `TDS,n`, `TDS,?`, `O,?` y
`O,<EC|TDS|S|SG>,<0|1>`. El factor TDS válido está entre 0.01 y 1.00.

## Comandos comunes admitidos

```text
L,0 | L,1 | L,?
Find
Name,<nombre> | Name, | Name,?
i
Status
Plock,0 | Plock,1 | Plock,?
*OK,0 | *OK,1 | *OK,?
Export,? | Export
Import,<bytes hexadecimales separados por espacios>
Sleep
Factory
I2C,<1-127>
Baud,<300|1200|2400|9600|19200|38400|57600|115200>
```

`Export` se envía repetidamente hasta recibir `*DONE`. Cada bloque exportado se
importa preservando los espacios entre bytes, por ejemplo:

```text
Import,59 6F 75 20 61 72
```

No importe datos de un tipo de circuito distinto ni interrumpa la secuencia;
una importación incorrecta es rechazada y puede reiniciar el EZO.

## Uso manual en Raspberry Pi

La consola web es la vía normal. Para diagnóstico manual detenga adquisición:

```bash
sudo systemctl stop photobioreactor-acquisition
sudo rm -f /tmp/photobioreactor-i2c.lock
```

Formato:

```bash
/opt/photobioreactor/sensors/EZOCommand/EZO_COMMAND <bus> <dirección> <delay_ms> <comando> [--no-response]
```

Ejemplos:

```bash
/opt/photobioreactor/sensors/EZOCommand/EZO_COMMAND /dev/i2c-1 0x63 300 i
/opt/photobioreactor/sensors/EZOCommand/EZO_COMMAND /dev/i2c-1 0x63 900 R
/opt/photobioreactor/sensors/EZOCommand/EZO_COMMAND /dev/i2c-1 0x63 900 Cal,mid,7.00
```

Reinicie el servicio al terminar:

```bash
sudo systemctl start photobioreactor-acquisition
```

## Fuentes oficiales

- [EZO-RTD Datasheet](https://files.atlas-scientific.com/EZO_RTD_Datasheet.pdf), versión 3.7, revisión 10/24.
- [EZO-pH Datasheet](https://files.atlas-scientific.com/pH_EZO_Datasheet.pdf), versión 6.1, revisión 2/24.
- [EZO-DO Datasheet](https://files.atlas-scientific.com/DO_EZO_Datasheet.pdf), versión 5.8, revisión 3/25.
- [EZO-EC Datasheet](https://files.atlas-scientific.com/EC_EZO_Datasheet.pdf), versión 6.6, revisión 3/26.