Dispositivos y radares

Los dispositivos son los radares y sensores que alimentan a TankOS con telemetría: nivel, temperatura, presión, densidad e interfaz. Esta página documenta el flujo de creación y configuración de un radar o device (flujo 5) paso a paso: cómo se crean en el pool, se asignan a un tanque, se configuran por pestañas, cómo se controla su ciclo de vida de cinco estados, cómo se registran las calibraciones con cadena HMAC, y cómo el administrador rota las credenciales MQTT.

Precondición y roles

Quién hace qué

El perfil ingeniero (engineering:edit) crea, asigna, configura y transiciona el ciclo de vida de los dispositivos. La gestión de credenciales MQTT corresponde exclusivamente al administrador (admin:system).

La lista de dispositivos (Ingeniería › Dispositivos) muestra cada dispositivo con su TAG, fabricante y modelo, estado de ciclo de vida (con badge) y el tanque asignado. El botón Nuevo dispositivo crea uno.

Los dispositivos sin tanque aparecen en el grupo "SIN ASIGNAR" (tankId = null). La asignación de un dispositivo a un tanque se hace desde la pestaña Dispositivos del editor de tanque.

Pasos — creación en el pool

1. Abrir el diálogo de nuevo dispositivo. En /engineering/devices, el botón Nuevo dispositivo (visible solo con engineering:edit) abre el NewDeviceDialog.
2. Completar el formulario. Campos: tag (hasta 120 caracteres), serial (opcional), deviceModelId (el modelo del catálogo), protocolVersion (1 o 2) y las capacidades del dispositivo, un subconjunto de: level, temp_avg, temp_spot, temp_multispot, pressure, density, interface.
3. Crear en el pool. Al guardar, el dispositivo se crea sin tanque asignado (tankId = null) y queda en el grupo "SIN ASIGNAR". El esquema de creación rechaza un tankId incluido por error.
4. Asignar a un tanque. Desde la pestaña Dispositivos del editor de tanque, el botón Asignar (AssignDeviceModal) vincula el dispositivo al tanque.

Captura pendiente

Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md (NewDeviceDialog).

Detalle del dispositivo (5 pestañas)

La página de detalle (/engineering/devices/[id]) organiza la información en cinco pestañas:

Pestaña	Contenido
Resumen	Datos generales, tanque asignado, etiqueta del faultCode (si hay falla), lecturas en vivo y el control de ciclo de vida (LifecycleControl).
Configuración	Overrides de unidad de entrada (levelInputUnit, tempInputUnit, pressureInputUnit, densityInputUnit), dirección de medición (innage/ullage), referencia de presión (pressureReference) y demás parámetros. La configuración resuelta se guarda en unitConfigSnapshot.
Multipunto	Layout de sensores de temperatura multipunto (tempSensorLayout).
Calibración	Historial de la cadena HMAC de calibraciones y carga del PDF del certificado.
Mantenimiento	Bitácora append-only de intervenciones (inspección, reparación, reemplazo, transición de ciclo, nota).

Captura pendiente

Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md (pestañas Configuración, Multipunto, Calibración y Mantenimiento por separado).

Ciclo de vida del dispositivo (5 estados)

El estado de un dispositivo se controla desde el LifecycleControl de la pestaña Resumen. El reductor de la máquina de estados se ejecuta antes de cualquier escritura a la base de datos, de modo que una transición inválida nunca se persiste.

Los cinco estados son installed, calibrated, maintenance, fault y retired. Las transiciones se disparan con las acciones CALIBRATE, TO_MAINTENANCE, TO_FAULT y RETIRE.

Reglas de la máquina de estados

• fault → calibrated está PROHIBIDO. Un dispositivo en falla debe pasar primero por maintenance antes de volver a calibrated. No hay atajo directo desde la falla a la calibración.
• retired es TERMINAL. No tiene transiciones salientes; un instrumento nuevo es un dispositivo nuevo, no un retired reactivado.
• La razón (reason) es obligatoria en las transiciones adversas o terminales (TO_MAINTENANCE, TO_FAULT, RETIRE).

Captura pendiente

Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md (LifecycleControl con el grafo de estados y el botón de transición).

Calibración: cadena HMAC

Registrar una calibración (pestaña Calibración) sube el PDF del certificado SENCAMER a MinIO y crea un evento inmutable. TankOS calcula el hash SHA-256 del PDF y, sobre una cadena canónica que enlaza cada evento con el anterior (prevEventHash), un HMAC-SHA256 encadenado. El resultado es un historial append-only y a prueba de manipulación (tamper-evident).

La cadena de calibración es inmutable

A nivel de base de datos se han revocado las operaciones UPDATE y DELETE sobre los eventos de calibración: una vez registrado, un evento no se puede modificar ni borrar. Esto garantiza la trazabilidad de grado custody exigida para transferencia.

La calibración está desacoplada del ciclo de vida: registrar un evento de calibración no cambia automáticamente el estado del dispositivo. Son acciones independientes — la transición a calibrated se hace por separado desde el LifecycleControl.

Dónde profundizar

Aquí se documenta el evento de calibración del dispositivo. La gestión a fondo de las tablas de aforo (booklet, diff y publicación con separación de funciones) está en calibración y tablas de aforo.

Credenciales MQTT (rotación copy-once)

Las credenciales con las que el dispositivo se autentica contra el broker MQTT (EMQX) las gestiona el administrador desde /admin/devices/[id]/credentials. La pantalla es un stepper de rotación:

1. Emitir una nueva contraseña para el dispositivo.
2. Solapamiento (grace period). Durante la rotación pueden coexistir dos credenciales activas como máximo, para reconfigurar el dispositivo sin cortar la conexión.
3. Revocar la credencial anterior una vez que el dispositivo usa la nueva.

La contraseña se muestra una sola vez

El texto plano de la contraseña generada se muestra exactamente una vez al emitirla; después, solo su hash vive en la base de datos (no hay endpoint de lectura). Cópiala en ese momento — si la pierdes, hay que emitir una nueva y revocar la anterior.

Captura pendiente

Screenshot pendiente del barrido diferido — ver 61-DEFERRED-SWEEP.md (stepper de credenciales MQTT con el "mostrar contraseña una vez").

Páginas relacionadas

• Para asignar un dispositivo a un tanque desde su configuración, ver el editor de tanque.
• Los modelos de dispositivo del catálogo (que aportan los valores por defecto de configuración) se documentan en la página de catálogos.