Reglas de alarma de ThinkLink: disparadores, gravedad y notificaciones

1. Los sistemas de alarma rara vez fallan por quedarse en silencio

La mayoría de los proyectos de IoT le piden una sola cosa a las alarmas: «que hagan ruido cuando algo se rompe». Pero lo que realmente mata a un sistema de alarmas no es el silencio, sino las alertas que nadie lee.

Datos públicos sobre la magnitud del problema:

Una cifra que merece convertirse: en una planta que monitorea 180 activos, una tasa de falsos positivos del 35% consume alrededor de 1,200 horas de técnico al año persiguiendo nada — cerca de US$42,000 anuales.

(Las dos primeras filas provienen de operaciones de seguridad, no de IoT. Sin embargo, el mecanismo es idéntico: cuanto más alto es el nivel de ruido, más fácilmente desaparece en él la única alerta que importa.)

Así que este artículo no trata de generar más alertas. Trata de tres propiedades:

1. Llega a tiempo — la alarma se dispara dentro de un ciclo de reporte, garantizado y documentado;
2. No genera spam — un evento produce una alarma, y esta se despeja sola cuando la condición desaparece;
3. Llega a la persona correcta — lo urgente va a un teléfono, lo rutinario va a una lista, y ambos nunca se mezclan.

2. Tres presupuestos de tiempo que hay que calcular primero

En LoRaWAN, el primer paso de diseño no es escribir un script. Es aceptar un hecho físico: un dispositivo final alimentado por batería no se despertará antes solo porque algo haya fallado. Eso produce tres líneas de tiempo:

La conclusión: LoRaWAN no puede entregar alarmas de nivel de segundos, pero sí puede entregar alarmas que nunca lleguen más tarde que un ciclo de reporte. Ponga esa frase en la propuesta antes de que un cliente la descubra durante las pruebas de aceptación.

Lleva esta guía a tu proyecto

ManThink ofrece productos IoT para conectar dispositivos, desplegar redes y trabajar con datos. Consulta estos recursos de producto junto con las recomendaciones técnicas del artículo:

KS52 Sensor de temperatura, humedad y fugas · ThinkLink

Conoce los productos de ManThink y consulta tu proyecto →

3. Tres componentes, y los tres son obligatorios

La generación de alarmas en ThinkLink no es «poner un umbral en el dispositivo». Son tres partes trabajando juntas:

El orden es fijo: asocie el ALARM RPC primero, luego el modelo de disparador y después (opcionalmente) el grupo de notificación. Si falta cualquiera de ellos, la alarma queda muda — no existe eso de «el script existe, así que sonará».

Un dispositivo puede llevar múltiples modelos de disparador, de modo que los escenarios con múltiples condiciones no tienen que amontonarse en un solo script.

4. El entorno de ejecución: cuerpo de función desnudo en un sandbox vm2

Un detalle desconcierta a casi todos: el editor espera un cuerpo de función desnudo. La plataforma envuelve tu código en function triggerRunner() { ... } antes de llamarlo, así que no debes añadir otro function trigger_script(...) {} envoltorio. La trigger_script forma aparece en la documentación solo para ilustrar qué variables están disponibles.

El sandbox es vm2, con estos límites:

Variables inyectadas que puedes usar directamente: device, thingModelId, org_params, env, plugins, Buffer, además de las seis tklHelper clases (BufferTKL, PayloadParser, MSparser, Utils, TriggerHelper, RPCHelper).

Campos de device que más importan para las alarmas:

Ten en cuenta que device y las clases auxiliares se inyectan congeladas — las asignaciones a ellas no tienen efecto. El valor de retorno es el único canal de salida.

5. Cuatro campos de retorno, uno de los cuales es un filtro de ruido libre

Un script de disparador devuelve null (no hacer nada) o un objeto con estos campos:

Campos de cada actions elemento:

should_dispatch con valor predeterminado false es el primer filtro de ruido que obtienes gratis. Datos idénticos en uplinks consecutivos no volverán a despachar acciones. Muchos equipos no lo saben y construyen su propia deduplicación encima de esto.

6. Un script que puedes copiar

Temperatura más batería, con umbrales y grupos de notificación externalizados en server_attrs de modo que cambiar un umbral nunca toque el script:

// El script de disparo es un cuerpo de función desnudo; la plataforma lo envuelve en triggerRunner() let tdata = device?.telemetry_data?.[thingModelId]; if (!tdata) return null;

const LIMIT_TEMP = device.server_attrs?.alarm_temp ?? 60; const LIMIT_BAT = device.server_attrs?.alarm_battery ?? 20; const notify = device.server_attrs?.notify ?? [];

let actions = [];

// 1) Sobrecalentamiento: mantén el título y el nivel estables para que la deduplicación funcione let hot = tdata.temperature >= LIMIT_TEMP; actions.push({ method: "alarm", params: { _eui: device.eui, name: "overheat_alarm", title: "[Overheat] " + device.name, level: "urgent", desc: "Temperature above limit, immediate action required", action: hot ? "new" : "clear", notify: notify } });

// 2) Batería baja: solo registro, no molestar (array notify vacío) let lowBat = tdata.battery <= LIMIT_BAT; actions.push({ method: "alarm", params: { _eui: device.eui, name: "low_battery_alarm", title: "[Low battery] " + device.name, level: "mid", desc: "Battery below threshold, schedule a replacement", action: lowBat ? "new" : "clear", notify: [] } });

return { delayms: 0, abort_previous_timer: true, actions };

Parámetros del RPC ALARM:

Coincidencia server_attrs en el dispositivo:

Si prefieres no construir a mano el objeto de retorno, extiende TriggerHelper y sobrescribe _alarmProcess(info). El constructor lee device.server_attrs.notify automáticamente y produce la estructura de retorno estándar (donde el campo se llama group, correspondiente a notify en el RPC ALARM). Si _alarmProcess devuelve false, o la acción es no, alarm() devuelve null.

7. Cuatro niveles de gravedad y una matriz de enrutamiento

Hay exactamente cuatro niveles: low (informativo), mid (advertencia), high (error), urgent (crítico). El nivel en sí no dispara nada — lo que importa es la combinación nivel × grupo de notificación:

Acuerda esta tabla con el cliente durante el arranque. La gravedad de la alarma no es una cuestión técnica, es una cuestión de propiedad — cada nivel necesita un responsable con nombre, de lo contrario urgent termina tan ignorado como todo lo demás.

8. Seis formas de reducir el ruido

1. Deja should_dispatch en paz. Su false valor predeterminado significa que los datos sin cambios no se vuelven a enviar. Establézcalo solo true cuando realmente se requiera un envío forzado cada vez.

2. Mantenga name, title, level y desc estables. La plataforma suprime una alarma idéntica en nombre, título, descripción y nivel. Por lo tanto, no concatene la lectura en vivo en desc — 61.2 y 61.5 son dos alarmas diferentes, la deduplicación se rompe y se despierta con cuarenta entradas. Si necesita mostrar un valor, muestre una banda o una categoría ("por encima del límite superior").

3. Use por defecto clear. Establezca action en clear y cambie a new solo cuando se cumpla la condición. Cada enlace ascendente actúa entonces también como verificación de recuperación, y las alarmas desaparecen por sí solas una vez que todo es normal. Haga lo contrario (envíe new solo en caso de incumplimiento) y la alarma quedará colgada para siempre si el dispositivo se desconecta.

4. Use delayms para verificaciones de persistencia. Para mediciones ruidosas (contactos de puerta, fugas de agua, excursiones momentáneas), no genere la alarma en el primer incumplimiento. Devuelva un delayms con abort_previous_timer: true para que cada nuevo enlace ascendente cancele la acción pendiente anterior — solo una excursión sostenida sobrevive el tiempo suficiente para convertirse en alarma.

5. Coloque los umbrales y los grupos en server_attrs. Cambiar un umbral entonces no requiere editar el script, ni una nueva versión, ni una reasociación. Quinientos dispositivos pueden compartir un modelo de disparador y cada uno mantener sus propios umbrales — eso es lo que hace posible esta escala.

6. Exija dos señales para la escalada. Temperatura alta mientras la humedad también se mueve es un nivel de confianza distinto al de un pico de temperatura aislado. El incumplimiento de un solo parámetro se queda en mid; dos parámetros juntos escalan a high. Esto elimina una parte significativa de los falsos positivos.

9. Grupos de notificación: qué admiten realmente

Los grupos de notificación se encuentran en Gestión de alarmas → Grupo de notificación. Id, nombre, método de notificación y contactos son obligatorios; las etiquetas y las notas son opcionales.

Esto merece énfasis: describir DingTalk, Slack y Telegram como canales integrados es inexacto. Son accesibles mediante un RPC personalizado, lo cual es real pero no una casilla de verificación. Descríbalo tal cual, o las pruebas de aceptación no coincidirán con la propuesta.

Un hábito práctico: almacene los nombres de los grupos como un arreglo en device.server_attrs (por ejemplo notify: ["ops-team"]) y pásalo directamente a notify. El enrutamiento por gravedad se convierte entonces en un cambio de atributo en lugar de un cambio de script — el mismo modelo de disparador en 500 dispositivos puede enrutar cada dispositivo a su propio grupo.

10. Tres recetas que puede aplicar directamente

Una advertencia sobre la detección de desconexión: la plataforma expone tres nociones distintas de estar en línea (la base de tiempo de actividad usada en listas y estadísticas, el server_attrs.online detector, y la data.online notificación MQTT). No son intercambiables. Cuando implemente alarmas de desconexión en un script de disparador, indique explícitamente que está usando active_time y heart_period, y documéntelo.

11. Lista de verificación previa al lanzamiento

• [ ] El ALARM RPC está asociado al dispositivo de destino (no solo al modelo de disparador)
• [ ] El modelo de disparador está asociado en la pestaña Trigger del dispositivo (no solo creado)
• [ ] _eui está presente dentro de params, no en el nivel superior de la acción
• [ ] name es único y estable, un nombre por tipo de alarma
• [ ] level es uno de los cuatro valores legales — un nivel ausente significa que no hay alarma
• [ ] Los umbrales y los grupos están en server_attrs, y el script tiene valores predeterminados cuando faltan
• [ ] action por defecto es clear, no "enviar new solo al incumplirse"
• [ ] desc no incorpora la lectura en vivo (de lo contrario falla la deduplicación)
• [ ] El grupo de notificaciones se ha habilitado manualmente (por defecto está desactivado)
• [ ] Se han ejercitado tanto las rutas new como clear en la pestaña de prueba del editor

12. Ocho errores vistos repetidamente

Cierre

Un sistema de alarmas utilizable no se define por su script. Se define por tres decisiones de criterio: qué cuenta como una anomalía real, quién debe saberlo y cuándo mantenerse en silencio. ThinkLink entrega las tres a los scripts y a la configuración de atributos — lo bastante flexible como para que un modelo pueda servir a 500 dispositivos con umbrales distintos, a costa de exigir que alguien piense bien las reglas antes de la puesta en marcha.

De las seis técnicas de reducción de ruido anteriores, las dos que más a menudo se omiten son la número 2 (mantener desc estable) y la número 3 (por defecto en clear). Omita cualquiera de las dos y el sistema parecerá correcto durante la primera semana — luego nadie volverá a abrir la lista de alarmas.

Siguiente en la serie (número 23): mantener los datos dentro de la planta — desplegar ThinkLink Edge (TKE) en las instalaciones, desde la selección de hardware y Docker Compose hasta la migración bidireccional de modelos de dispositivos con la nube.