❄️ DataServ HVACR Monitor
Manual de Usuario · v2.2

Manual de Usuario

Guía completa para operadores y clientes del sistema de monitoreo de refrigeración y climatización HVACR. Cubre todos los procesos de gestión, configuración de dispositivos, alertas y análisis de datos.

Contenido
Parte A — Manual del Operador
  1. Descripción del sistema  2. Acceso y roles de usuario  3. Panel Operador — Gestión de clientes  4. Panel Operador — Gestión de gateways  5. Catálogos — Modelos y tipos de variables  6. Fleet Manager — Firmware OTA y CI/CD    3.5 Bandeja de tareas del operador
Parte B — Manual del Cliente
  7. Dashboard — Monitoreo en tiempo real  8. Wizard — Configuración inicial paso a paso  9. Alertas y notificaciones  10. Módulo Analytics    8.x Activar dispositivo pre-provisionado (Claim QR)    9.x Auto-discovery de sensores nuevos    9.x Ciclo offline automático
Parte C — Referencia Técnica
  11. API de integración para dispositivos  12. Referencia rápida API REST  13. Solución de problemas (Troubleshooting)
Parte A — Manual del Operador
Para administradores del sistema: gestión de clientes, gateways, catálogos y firmware.

1. Descripción del sistema

DataServ HVACR Monitor es una plataforma multi-tenant de monitoreo en tiempo real para equipos de refrigeración y climatización. El operador gestiona múltiples clientes desde un panel centralizado. Cada cliente accede únicamente a sus propios datos.

Arquitectura general

Dispositivos (ESP32 WiFi / LoRaWAN Milesight) │ ▼ POST /api/v1/ingest/[apiKey] ┌─────────────────────────────────┐ │ Servidor Next.js │ │ ├── Recibe y almacena datos │ │ ├── Evalúa reglas de alerta │ ← cualquier variable (temp, humedad, presión…) │ └── Envía notificaciones │ └─────────────────────────────────┘ │ ├── PostgreSQL (datos históricos) ├── pg-boss (cola de jobs: email, SMS, OTA) └── Resend / Twilio (notificaciones)

Capacidades por plan

LímiteValor por defectoConfigurable por el operador
Gateways por cliente5
Sensores por cliente20
Retención de telemetría30 días

2. Acceso y roles de usuario

RolDescripciónRedirige a
OperadorAdministrador del sistema. Sin tenantId asignado. Accede a todos los clientes./operator
ClienteUsuario final. Solo ve sus propios gateways y sensores./dashboard

Proceso de inicio de sesión

  1. Abre https://dataserv-hvacr-monitor.duckdns.org/login
  2. Ingresa correo electrónico y contraseña
  3. Haz clic en Iniciar sesión
  4. El sistema detecta tu rol y te redirige automáticamente
💡 Sesión segura: La sesión utiliza cookies firmadas con JWT. Se cierra automáticamente al cerrar el navegador o después de inactividad prolongada.

3. Panel Operador — Gestión de clientes

Accede en /operator. Muestra la lista de todos los clientes activos con sus estadísticas y permite crear, editar o eliminar cuentas.

3.1 Crear un nuevo cliente

Cuándo usarlo: Cuando un nuevo cliente contrata el servicio de monitoreo.

1
En el panel operador, localiza el formulario Nuevo cliente en la parte superior.
2
Escribe el nombre del cliente (ej. "Restaurante La Paloma").
3
Escribe el correo de contacto. Este será el email de acceso del cliente.
4
Haz clic en + Crear cliente.
5
El sistema muestra las credenciales temporales. Cópialas antes de cerrar la ventana.
✓ Cliente creado. Comparte estas credenciales con el cliente: Email: gerente@restaurante.com Contraseña temporal: ab12CD34 URL de acceso: https://dataserv-hvacr-monitor.duckdns.org/login
La contraseña temporal no se puede recuperar después de cerrar o recargar la página. Si la pierdes, usa la función "Reset contraseña".

3.2 Editar un cliente

Cuándo usarlo: Cambio de nombre, email de contacto o ajuste de límites del plan.

1
Localiza al cliente en la lista y haz clic en Editar.
2
Modifica los campos necesarios:
CampoDescripción
NombreNombre comercial del cliente
Email contactoCorreo de acceso al sistema (actualiza la cuenta de usuario automáticamente)
Max gatewaysMáximo de gateways permitidos en el plan contratado
Max sensoresMáximo de sensores totales permitidos
Retención (días)Días de historial de telemetría que se conserva
3
Haz clic en Guardar. Los cambios aplican inmediatamente.

3.3 Resetear contraseña de un cliente

Cuándo usarlo: El cliente olvidó su contraseña o se requiere un acceso de emergencia.

1
Localiza al cliente en la lista.
2
Haz clic en Reset contraseña.
3
El sistema genera una nueva contraseña aleatoria y la muestra en pantalla.
4
Comparte la nueva contraseña con el cliente por un canal seguro (llamada, mensaje directo).
⚠ La contraseña anterior queda invalidada inmediatamente. El cliente no podrá entrar hasta que reciba la nueva.

3.4 Eliminar un cliente

Cuándo usarlo: El cliente dio de baja el servicio definitivamente.

1
Localiza al cliente en la lista.
2
Haz clic en Eliminar.
3
Confirma la eliminación en el diálogo de confirmación.
🗑 Operación irreversible. Se elimina permanentemente en cascada: toda la telemetría, alertas, reglas, sensores, gateways, cuenta de usuario y el registro del cliente. No hay papelera de reciclaje.

3.5 Bandeja de tareas del operador

Accede en /operator/tareas. El sistema genera tareas automáticas cuando se detectan situaciones que requieren intervención del operador. El sidebar muestra un badge amarillo con el número de tareas pendientes.

Tipo de tareaCuándo se generaAcción recomendada
device_offline_24hUn gateway activo lleva más de 24 h sin enviar datosContactar al cliente y coordinar revisión técnica
💡 Las tareas se resuelven automáticamente cuando el gateway vuelve a enviar datos. No es necesario marcarlas manualmente.

4. Panel Operador — Gestión de gateways

Dentro de cada tarjeta de cliente existe una sección de Gateways que permite agregar, editar, eliminar y rotar las API keys de los dispositivos.

4.1 Crear un gateway

Cuándo usarlo: Se instala un nuevo dispositivo en las instalaciones del cliente.

1
En la tarjeta del cliente, haz clic en + Agregar gateway.
2
Escribe el nombre del gateway (ej. "Cámara Fría Cocina").
3
Selecciona el protocolo: wifi (ESP32 directo) o lorawan (Milesight EM300).
4
Haz clic en Crear. El sistema genera y muestra el API Key.
5
Copia el API Key — se muestra una sola vez. Lo necesitas para programar el dispositivo.
✅ El API Key tiene el formato DSV-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX (32 caracteres hexadecimales).

4.2 Rotar API Key de un gateway

Cuándo usarlo: Sospecha de compromiso de seguridad, dispositivo robado o mantenimiento de seguridad rutinario.

1
Localiza el gateway en la tarjeta del cliente.
2
Haz clic en Rotar key.
3
El sistema genera un nuevo API Key y lo muestra. La key anterior queda inválida de inmediato.
4
Reprograma el dispositivo con el nuevo API Key (portal 192.168.4.1 o firmware update).
⚠ El dispositivo dejará de enviar datos hasta que sea reprogramado con la nueva key.

4.3 Eliminar un gateway

Cuándo usarlo: El dispositivo fue retirado o remplazado.

1
Localiza el gateway en la tarjeta del cliente.
2
Haz clic en Eliminar y confirma.
🗑 Se elimina en cascada: todos los sensores, telemetría histórica y alertas asociadas a ese gateway.

4.4 Verificar conectividad del gateway

En la lista de gateways de cada cliente aparece el campo Última conexión. Un gateway se considera offline si no ha enviado datos en más de 10 minutos. El sistema genera automáticamente una alerta interna y puede enviar una notificación al cliente.


5. Catálogos — Modelos de dispositivos y tipos de variables

El módulo de Catálogos en /operator/catalogos permite al operador administrar dos tablas maestras que el resto del sistema usa dinámicamente:

💡 Antes de este módulo, los modelos de dispositivo eran una lista fija en el código. Ahora son editables sin necesidad de modificar el software.

5.1 Modelos de dispositivos

Accede a la sección Modelos de dispositivo dentro de la página de Catálogos.

CampoDescripciónEjemplo
IDIdentificador único (sin espacios, minúsculas)dsv_node
NombreEtiqueta visible en el Fleet ManagerDSV Node v1
ChipMicrocontrolador del hardwareESP32
Firmware defaultVersión de firmware de referencia1.0.0
NotasInformación adicional (opcional)Nodo de temperatura y humedad

Agregar un modelo

1
Llena el formulario en la parte inferior de la tabla de modelos.
2
El campo ID debe ser único y en minúsculas sin espacios (ej. heltec_v3).
3
Haz clic en Guardar modelo. El modelo aparece de inmediato en el Fleet Manager.

Editar un modelo

Haz clic en el botón Editar junto al modelo. El formulario se pre-llena con los datos actuales. Modifica lo necesario y haz clic en Guardar modelo.

💡 El ID no se puede cambiar una vez creado (es la clave primaria). Si necesitas cambiar el ID, elimina el modelo y crea uno nuevo.

Eliminar un modelo

1
Haz clic en el botón Eliminar junto al modelo.
2
Confirma la acción.
⚠ No elimines un modelo que tenga firmware publicado o rollouts activos en el Fleet Manager. Los dispositivos con ese modelo dejarán de recibir actualizaciones OTA.

5.2 Tipos de variables de sensor

Las variables de sensor definen qué campos de telemetría pueden monitorearse con reglas de alerta. Por defecto el sistema incluye temperatura, humedad y presión.

CampoDescripciónEjemplo
IDNombre del campo en el payload de ingesttemperature
NombreEtiqueta visible en alertas y reglasTemperatura
UnidadUnidad de medida°C
ÍconoEmoji representativo (opcional)🌡️
MínimoValor mínimo de referencia (informativo)-40
MáximoValor máximo de referencia (informativo)125

Agregar un tipo de variable

1
Llena el formulario en la parte inferior de la tabla de variables.
2
El ID debe coincidir exactamente con el nombre del campo que el dispositivo envía en el JSON de ingest (ej. humidity si el dispositivo envía "humidity": 82.5).
3
Haz clic en Guardar variable. Desde ese momento se puede usar como campo en reglas de alerta.
Ejemplo de uso: Si agregas la variable co2 con unidad ppm, podrás crear reglas de alerta del tipo "disparar alerta si CO₂ > 1000 ppm" para cualquier sensor que envíe ese campo.

6. Fleet Manager — Firmware OTA y CI/CD

El Fleet Manager permite publicar actualizaciones de firmware y desplegarlas remotamente a todos los gateways de un modelo específico, sin visitar físicamente las instalaciones. Los modelos disponibles provienen del Catálogo de modelos (Sección 5).

6.1 Subir firmware manualmente

1
En el panel operador, localiza la sección Fleet Manager.
2
Selecciona el modelo de gateway al que aplica el firmware.
3
Haz clic en Subir firmware y selecciona el archivo .bin.
4
Ingresa el número de versión (ej. 1.3.0).
5
Confirma la subida. El archivo queda disponible en el servidor.

6.2 Pipeline CI/CD automático (DSV Node)

El repositorio dsv-node-firmware en GitHub incluye un pipeline que compila y publica el firmware automáticamente al crear un tag de versión. No se requiere VS Code ni PlatformIO instalado localmente.

# Para publicar una nueva versión del firmware DSV Node: git tag v1.2.0 git push origin v1.2.0 # GitHub Actions ejecuta automáticamente: # 1. Instala PlatformIO en Ubuntu # 2. Compila el firmware (pio run -e dsv_node) # 3. Publica el .bin en el servidor vía POST /api/v1/firmware/upload # 4. El archivo queda disponible en el Fleet Manager
💡 El pipeline usa el secret FIRMWARE_CI_SECRET para autenticarse en el endpoint de subida. Este secret debe estar configurado en GitHub → Settings → Secrets del repositorio de firmware.

6.3 Iniciar un rollout OTA

Cuándo usarlo: Corrección de bug crítico, nueva funcionalidad o mejora de seguridad en el firmware.

1
En la sección Fleet Manager, localiza la versión de firmware que deseas desplegar.
2
Haz clic en Iniciar rollout.
3
El sistema encola automáticamente una tarea OTA para cada gateway del modelo seleccionado.
4
Cada gateway recibe la URL del firmware en su próxima comunicación con el servidor.
5
El gateway descarga el firmware, lo instala y reinicia. El estado cambia a pending → completed.

6.4 Estados del OTA

EstadoSignificado
noneSin actualización pendiente
pendingTarea OTA encolada — esperando que el dispositivo se conecte
completedFirmware actualizado exitosamente
failedEl dispositivo reportó error durante la actualización
💡 Los gateways consultan actualizaciones pendientes en cada ingest (POST /api/v1/ingest/[apiKey]). La respuesta incluye ota_url y ota_version si hay una actualización pendiente.

6.5 Eliminar una versión de firmware

1
Localiza la versión en el Fleet Manager.
2
Haz clic en Eliminar. El archivo .bin se borra del servidor.
⚠ No elimines una versión que tenga rollouts en estado pending. Los dispositivos no podrán descargar el archivo.
Parte B — Manual del Cliente
Para usuarios finales: monitoreo, configuración de dispositivos y análisis de datos.

7. Dashboard — Monitoreo en tiempo real

Al iniciar sesión, el cliente accede directamente al dashboard en /dashboard. Muestra en tiempo real el estado de todos los sensores asociados a su cuenta.

7.1 Estructura de la pantalla

ElementoUbicaciónDescripción
Banner de alertas activasParte superior (solo si hay alertas)Muestra cuántas alertas están sin reconocer con botones de acción rápida
Secciones por gatewayCuerpo principalCada gateway tiene su propia sección con nombre, estado online/offline y sus sensores
Tarjetas de sensoresDentro de cada gatewayTemperatura, nombre, ID del dispositivo, estado OK/ALERTA y sparkline de historial
Botón AnalyticsBarra superior derechaAcceso directo al módulo de análisis histórico
Botón ManualBarra superior derechaEste manual

7.2 Interpretar el estado de un sensor

IndicadorSignificadoAcción recomendada
Badge verde OKVariable dentro del rango configuradoNinguna — todo normal
Badge rojo ALERTAVariable superó el umbral configuradoVerificar el equipo físicamente
Valor "—"No se han recibido datos de este sensorRevisar conectividad del gateway
Gateway OFFLINEEl gateway no ha enviado datos en +10 minVerificar alimentación y red WiFi del gateway

7.3 Reconocer una alerta

Cuándo usarlo: Cuando ves una alerta activa y has verificado o actuado sobre el equipo. Reconocer una alerta indica que estás al tanto del problema — no la resuelve automáticamente.

1
El banner en la parte superior muestra las alertas sin reconocer.
2
Haz clic en el botón Reconocer junto a la alerta correspondiente.
3
El banner desaparece cuando todas las alertas han sido reconocidas.
💡 La alerta se resuelve automáticamente cuando el sensor reporta un valor dentro del rango normal. Reconocer solo registra que viste la alerta.

7.4 Dashboard vacío — primer acceso

Si el cliente acaba de crear su cuenta, el dashboard mostrará el mensaje"Aún no hay gateways configurados." con un enlace al Asistente de configuración. Haz clic en Ir al asistente de configuración → para iniciar el proceso.


8. Wizard — Configuración inicial paso a paso

El asistente de configuración en /wizard guía al cliente a través de 5 pasos para registrar su primer gateway y sensores, y configurar alertas. Solo necesita completarlo una vez por gateway.

Paso 1 — Registrar el gateway

1
Escribe un nombre descriptivo para el gateway (ej. "Cámara Fría Cocina Principal").
2
Selecciona el protocolo del dispositivo:
  • WiFi — para módulos ESP32/Heltec directos
  • LoRaWAN — para sensores Milesight EM300
3
Haz clic en Crear gateway →
4
El sistema muestra el API Key generado en un recuadro verde.
⚠ Copia el API Key antes de continuar. Solo se muestra UNA VEZ. Si lo pierdes, el operador debe crear un gateway nuevo.
5
Configura el dispositivo físico con este API Key (ver Sección 11).
6
Haz clic en Ya copié el API Key — Siguiente →

Paso 2 — Esperar datos de sensores

1
Enciende el dispositivo ESP32 con el API Key ya configurado.
2
El dispositivo comenzará a enviar lecturas automáticamente (cada 30–60 segundos típicamente).
3
El asistente muestra los sensores detectados conforme llegan los datos. No cierres la página.
4
Cuando aparezcan los sensores en la lista, haz clic en Siguiente →
💡 Si después de 5 minutos no aparecen sensores, revisa que el dispositivo tenga WiFi y que el API Key esté bien configurado.

Paso 3 — Asignar nombres y ubicaciones

1
Verás la lista de sensores detectados (S0, S1, S2…).
2
Para cada sensor, escribe un nombre descriptivo (ej. "Cámara de Carne", "Congelador").
3
Opcionalmente, agrega una ubicación (ej. "Piso 1", "Bodega Norte").
4
Haz clic en Guardar y Siguiente →

Paso 4 — Configurar alertas

Las alertas pueden configurarse para cualquier variable que el sensor envíe: temperatura, humedad, presión u otras variables registradas en el catálogo.

1
Escribe el correo electrónico que recibirá las alertas (puede ser del encargado, supervisor, etc.).
2
Selecciona la variable a monitorear (ej. Temperatura, Humedad).
3
Selecciona el operador de comparación: mayor que, menor que, mayor o igual, menor o igual.
4
Configura el umbral. Valor típico para refrigeración de alimentos: 4°C.
5
Haz clic en Siguiente →. Se crean automáticamente reglas de alerta para todos los sensores.
💡 Valores de referencia para temperatura:Para humedad: Cuartos de almacenamiento típicamente requieren alertas si la humedad supera el 80%.

Paso 5 — Verificación final

1
El asistente muestra un resumen de lo configurado: gateway, sensores y reglas de alerta.
2
Verifica que los datos sean correctos.
3
Haz clic en Ir al dashboard → para ver los datos en tiempo real.
✅ ¡Configuración completa! El sistema comenzará a monitorear y te notificará si algún sensor supera el umbral configurado.

8.x Activar un dispositivo pre-provisionado (Claim QR)

Cuando el operador entrega un kit de hardware ya registrado en el sistema, el cliente lo activa escaneando el código QR de la etiquetadel dispositivo — sin pasar por el wizard completo.

1
Escanea el QR de la etiqueta del dispositivo con tu celular.
2
El navegador abre /claim?code=XXXXXXXX. Si no tienes sesión iniciada, el sistema te redirige al login y regresa automáticamente.
3
La pantalla muestra los datos del dispositivo (nombre y modelo). Haz clic en "Activar dispositivo".
4
El dispositivo queda registrado en tu cuenta. Serás redirigido al dashboard en unos segundos.
💡 El código QR es de un solo uso. Una vez activado, el enlace ya no funciona. Si ves el mensaje "Este dispositivo ya fue activado", el gateway ya aparece en tu dashboard.

Después del claim, el dispositivo necesita conectarse al WiFi del local. Consulta la Guía de instalación (/help) para configurar la red WiFi vía el portal 192.168.4.1.


9. Alertas y notificaciones

9.1 Cómo funciona el sistema de alertas

El sistema evalúa todas las variables registradas en cada recepción de datos. Cada regla de alerta especifica qué variable monitorear (temperatura, humedad, presión, etc.):

Sensor envía lectura (ej. temperatura=9.5°C, humedad=85%) │ ▼ Para cada regla activa del sensor: ¿El valor del campo monitoreado supera el umbral? (ej. ¿temperatura > 4°C? / ¿humedad > 80%?) │ SÍ ──────────────────────────────────────────┐ │ ▼ │ ¿Ya había una alerta abierta? │ │ │ NO ──▶ Crea evento de alerta │ Envía email / SMS │ SÍ ──▶ No hace nada (evita spam) │ NO ──▶ ¿Había una alerta abierta? │ SÍ ──▶ Resuelve la alerta automáticamente NO ──▶ No hace nada

9.2 Variables soportadas

El catálogo de variables (administrado por el operador en /operator/catalogos) determina qué campos pueden usarse en reglas de alerta:

VariableCampo en ingestUnidad
Temperaturatemperature°C
Humedadhumidity%
PresiónpressurehPa
💡 El operador puede agregar nuevas variables en el Catálogo (Sección 5) y los clientes podrán crear reglas para ellas de inmediato.

9.3 Tipos de notificaciones

TipoCuándo se envíaRequisito
EmailCuando la alerta se dispara por primera vezResend configurado + email en la regla
SMSCuando la alerta se dispara por primera vezTwilio configurado + número en la regla
Visual (dashboard)Siempre, en tiempo realNinguno — siempre activo

9.4 Proceso ante una alerta activa

Proceso recomendado cuando recibes una notificación de alerta:

1
Verifica el dashboard — confirma que la alerta es real y qué sensor la generó.
2
Inspecciona el equipo físico — revisa si la puerta está abierta, si el compresor funciona, etc.
3
Toma acción correctiva — cierra la puerta, llama al técnico, traslada los productos, etc.
4
Reconoce la alerta en el dashboard para indicar que estás al tanto.
5
Cuando el equipo regrese a valores normales, la alerta se resuelve automáticamente en el dashboard.

9.5 Auto-discovery de sensores nuevos

Cuando el gateway envía datos de un sensor que el sistema nunca ha visto, lo registra automáticamente sin intervención del operador.

💡 Si conectas un sensor DS18B20 adicional al gateway ya instalado, aparecerá solo en el dashboard en el siguiente ciclo de envío (típicamente en menos de 60 segundos).

9.6 Ciclo offline automático

El sistema monitorea la conectividad de cada gateway cada 15 minutos y gestiona el ciclo de vida automáticamente:

Gateway activo → deja de enviar datos 10 min sin datos → Badge OFFLINE en dashboard (visual) Estado interno: sin_datos Notificación interna al operador 24 h sin datos → Tarea en bandeja del operador (kind: device_offline_24h) Dispositivo reconecta → Estado automáticamente: activo Tarea se cierra sola Badge OFFLINE desaparece

Como cliente, no necesitas hacer nada cuando el gateway vuelve online — el sistema lo detecta y actualiza el dashboard automáticamente. Si el gateway lleva más de 24 h offline, el operador se encargará de contactarte.


10. Módulo Analytics

El módulo Analytics permite visualizar el historial de temperaturas en gráficas interactivas. Se accede desde el botón 📊 Analytics en el dashboard — no requiere login adicional.

10.1 Acceder al módulo

1
En el dashboard, haz clic en 📊 Analytics (barra superior derecha).
2
El sistema genera automáticamente un token temporal y abre el módulo en una nueva pestaña.
3
No se requiere ingresar contraseña nuevamente.
💡 El token de acceso es válido por 5 minutos. Si el módulo no carga, regresa al dashboard y vuelve a hacer clic en Analytics.

10.2 Vista de monitoreo en vivo

La pantalla principal del módulo muestra todos tus gateways con:

Los datos se actualizan automáticamente cada 30 segundos.

10.3 Vista de detalle histórico

Haz clic en VER DETALLE → de cualquier gateway para ver:

Parte C — Referencia Técnica
Para integradores y técnicos: API, formato de datos y solución de problemas.

11. API de integración para dispositivos

11.1 Configurar un ESP32 (WiFi)

Endpoint: POST /api/v1/ingest/{apiKey}

// Ejemplo Arduino / ESP32 — enviar telemetría cada 60 segundos #include <WiFi.h> #include <HTTPClient.h> #include <ArduinoJson.h> const char* API_URL = "https://dataserv-hvacr-monitor.duckdns.org/api/v1/ingest/DSV-XXXX..."; void sendTelemetry(float temp, float temp1, float humidity, bool alarm) { HTTPClient http; http.begin(API_URL); http.addHeader("Content-Type", "application/json"); StaticJsonDocument<256> doc; doc["device_id"] = "CAMARA-01"; // identificador amigable doc["temperature"] = temp; // sensor principal (°C) doc["temp_1"] = temp1; // sensor secundario (°C) doc["humidity"] = humidity; // humedad relativa (%) doc["rssi"] = WiFi.RSSI(); // intensidad de señal doc["battery"] = 95; // nivel de batería 0-100 doc["alarm"] = alarm; // alarma del hardware doc["firmware_version"] = "1.2.0"; // versión del firmware String body; serializeJson(doc, body); int code = http.POST(body); http.end(); // code == 200: OK | code == 402: límite del plan superado }

11.2 Campos del payload de ingest

CampoTipoObligatorioDescripción
temperaturefloatNoTemperatura sensor principal (°C)
temp_1floatNoTemperatura sensor 2 (°C)
temp_2floatNoTemperatura sensor 3 (°C)
temp_3floatNoTemperatura sensor 4 (°C)
humidityfloatNoHumedad relativa (%)
pressurefloatNoPresión atmosférica (hPa)
rssiintNoIntensidad señal WiFi (dBm)
batteryintNoNivel de batería (0–100)
alarmboolNoEstado de alarma del hardware
macstringNoMAC del dispositivo — para identificación estable
device_idstringNoIdentificador amigable del dispositivo
firmware_versionstringNoVersión del firmware instalado

11.3 Respuesta del servidor (OTA incluida)

// Respuesta normal { "ok": true } // Respuesta con actualización OTA pendiente { "ok": true, "ota_url": "https://dataserv-hvacr-monitor.duckdns.org/firmware/dsv_node-1.3.0.bin", "ota_version": "1.3.0" } // El firmware ESP32 debe verificar si ota_url existe y ejecutar la actualización: if (doc.containsKey("ota_url")) { String url = doc["ota_url"].as<String>(); httpUpdate.update(client, url); }

11.4 Ingest LoRaWAN (Milesight EM300)

Endpoint: POST /api/v1/ingest/lorawan

Requiere header: Authorization: <LORAWAN_WEBHOOK_SECRET>

{ "devEui": "0011223344556677", "data": { "temperature": 4.2, "humidity": 82, "battery": 90 }, "rssi": -110, "snr": 7.5 }

12. Referencia rápida API REST

Todos los endpoints (excepto ingest) requieren sesión activa vía cookie o el header:

Authorization: Bearer DSV-<32 caracteres hex>
MétodoRutaRolDescripción
POST/api/v1/wizard/gatewayClienteCrear gateway — devuelve apiKey (solo visible una vez)
GET/api/v1/wizard/sensors?gatewayId=ClienteListar sensores de un gateway
PUT/api/v1/wizard/sensorsClienteRenombrar sensores y asignar ubicaciones
POST/api/v1/wizard/alertsClienteCrear regla de alerta para un sensor
GET/api/v1/gatewaysClienteListar todos los gateways con sus sensores
GET/api/v1/sensors/{id}/telemetryClienteConsultar telemetría histórica con filtros
POST/api/v1/alerts/rulesClienteCrear regla de alerta con campo y umbral dinámicos
GET/api/v1/device-modelsOperadorListar modelos de dispositivos del catálogo
POST/api/v1/device-modelsOperadorCrear o actualizar un modelo de dispositivo
DELETE/api/v1/device-models/{id}OperadorEliminar un modelo de dispositivo
GET/api/v1/sensor-variable-typesOperadorListar tipos de variables de sensor del catálogo
POST/api/v1/sensor-variable-typesOperadorCrear o actualizar un tipo de variable
DELETE/api/v1/sensor-variable-types/{id}OperadorEliminar un tipo de variable
GET/api/v1/firmware/listOperadorListar versiones de firmware disponibles
POST/api/v1/firmware/uploadOperador / CISubir nueva versión de firmware (soporta Bearer CI token)
DELETE/api/v1/firmware/{id}OperadorEliminar versión de firmware
POST/api/v1/ingest/{apiKey}DispositivoIngest WiFi/ESP32 — sin header de auth
POST/api/v1/ingest/lorawanDispositivoIngest LoRaWAN — header especial

Parámetros de telemetría

GET /api/v1/sensors/{id}/telemetry ?from=2024-01-01T00:00:00Z (ISO 8601) ?to=2024-01-02T00:00:00Z (ISO 8601) ?interval=5m (raw | 1m | 5m | 15m | 1h | 1d) ?limit=1000 (máximo 10000)

Reglas de alerta — parámetros

POST /api/v1/alerts/rules { "sensorId": "uuid-del-sensor", "operator": "gt", // gt | lt | gte | lte "threshold": 4, // valor numérico del umbral "field": "temperature" // campo a monitorear — debe existir en el catálogo // valores posibles: temperature | humidity | pressure | … }

13. Solución de problemas (Troubleshooting)

El sensor no aparece en el dashboard

Causa posibleVerificaciónSolución
API Key incorrecto en el dispositivoEl dispositivo devuelve HTTP 401Reconfigura el dispositivo con el API Key correcto
El dispositivo no tiene WiFiNo hay tráfico en la redVerifica SSID y contraseña WiFi en el firmware
Límite de sensores superadoEl servidor devuelve HTTP 402El operador debe ampliar el plan del cliente
El gateway fue eliminadoEl API Key devuelve 404Crea un nuevo gateway y reconfigura el dispositivo

No llegan notificaciones de alerta por email

Causa posibleSolución
Email en spamBusca en la carpeta Spam/Correo no deseado y marca como "No es spam"
RESEND_API_KEY no configuradoEl operador debe configurar la variable de entorno en el servidor
Regla sin email configuradoVerifica en el wizard (paso 4) que se ingresó un correo de notificación
Alerta ya estaba abiertaLas notificaciones solo se envían cuando la alerta se dispara por primera vez
Campo de la regla no existe en el payloadVerifica que el dispositivo envía el campo configurado en la regla (ej. humidity)

El firmware CI no sube al servidor

Causa posibleSolución
FIRMWARE_CI_SECRET no configurado en GitHubSettings → Secrets → dsv-node-firmware → agregar FIRMWARE_CI_SECRET
El tag no tiene formato v*Usa git tag v1.2.0 (con "v" minúscula al inicio)
Error de compilación en PlatformIORevisa el log del Action en GitHub para ver el error de C++
URL del servidor incorrecta en el workflowVerifica la URL en firmware.yml — debe apuntar a duckdns.org

El gateway aparece como OFFLINE

  1. Verifica que el dispositivo esté encendido y con alimentación estable.
  2. Verifica que el WiFi del dispositivo esté conectado (LED o serial).
  3. Verifica que el servidor sea accesible desde la red del dispositivo.
  4. Reinicia el dispositivo.
  5. Si el problema persiste, verifica el API Key en el firmware.

No puedo iniciar sesión

  1. Verifica que estás usando el correo correcto (sin espacios extra).
  2. Verifica que la contraseña sea la que te dio el operador.
  3. Si olvidaste la contraseña, contacta al operador para que use la función Reset contraseña.
  4. Si el problema persiste, el operador puede verificar tu cuenta desde el panel.

Los datos de Analytics no cargan

  1. El token de acceso es válido por 5 minutos. Regresa al dashboard y vuelve a hacer clic en Analytics.
  2. Verifica que el módulo Analytics esté corriendo en el servidor (consulta al operador).
  3. Si el gateway no tiene datos históricos, la gráfica aparecerá vacía — esto es normal en instalaciones nuevas.

DataServ HVACR Monitor · Manual de Usuario v2.2 · 2026