Integración MQTT ​

LumiotLoRaWAN proporciona una interfaz MQTT robusta, segura y completamente aislada mediante tecnología Multi-Tenant (Multi-Inquilino). Esta integración permite que aplicaciones externas, dashboards (como Node-RED o Grafana) y plataformas de terceros consuman la telemetría de los sensores en tiempo real y envíen comandos hacia los dispositivos.

Arquitectura de Seguridad (Edge Broker) ​

Para garantizar la máxima seguridad y el cumplimiento de las normativas de la industria (ISO-Aligned), la plataforma utiliza un Broker MQTT Público (Edge Broker) expuesto en los puertos 8883 (MQTTS - cifrado con TLS 1.3) y 8084 (WSS - WebSockets Secure).

El broker interno del Network Server está completamente aislado (Air-Gapped lógicamente) y nunca se expone a Internet. Un microservicio interno actúa como puente seguro para trasladar únicamente la información autorizada entre el núcleo y el exterior.

Parámetros de Autenticación ​

Para conectarse al broker MQTT de integración, debes proveer:

• Host: La IP o el dominio de tu servidor LumiotLoRaWAN.
• Puerto: 8883 (Para clientes MQTT estándar) o 8084 (Para WebSockets).
• Username: Tu correo electrónico o nombre de usuario registrado.
• Password: El Token MQTT asignado a tu usuario (Este hash se gestiona desde el panel de perfil de usuario y es independiente a tu contraseña de ingreso web).
• TLS/SSL: Activo (Requerido).

Configuración de cliente MQTT para la conexión ​

Para facilitar las pruebas y el desarrollo, recomendamos utilizar el cliente MQTTX.

Para agregar una nueva configuración simple en MQTTX, haz clic en el botón New Connection (o el ícono +) y completa los campos de la sección General de la siguiente manera:

• Name: Un nombre descriptivo para identificar tu conexión (ej. LumiotLoRaWAN Producción).
• Host: Selecciona mqtts:// (o wss:// si usas WebSockets) e ingresa la IP o dominio de tu servidor LumiotLoRaWAN.
• Port: Ingresa 8883 (para mqtts://) o 8084 (para wss://).
• Client ID: Puedes dejar el valor generado aleatoriamente por defecto.
• Username: Tu correo electrónico o nombre de usuario registrado en la plataforma.
• Password: El Token MQTT asignado a tu usuario (lo obtienes desde tu perfil en la plataforma).
• SSL/TLS: Actívalo (toggle encendido) ya que es un requerimiento obligatorio para conexiones seguras.

Los campos de la sección Advanced (como MQTT Version 5.0, Keep Alive, etc.) puedes dejarlos en sus valores por defecto. Una vez completado, haz clic en el botón verde Connect en la esquina superior derecha.

Estructura de Tópicos (Namespace) ​

El árbol de tópicos en LumiotLoRaWAN está diseñado jerárquicamente para garantizar la soberanía y el aislamiento de los datos. La estructura base es:

lumiot/v1/{tenantId}/{subsidiaryId}/devices/{deviceId}/{direction}

• {tenantId}: ID único del inquilino (Distribuidor/Integrador) en la base de datos de Lumiot (PostgreSQL), no el ID interno de LNS.
• {subsidiaryId}: ID único de la filial o aplicación en Lumiot (PostgreSQL), no el Application ID de LNS.
• {deviceId}: DevEUI del dispositivo LoRaWAN (en formato hexadecimal minúscula).
• {direction}: rx para telemetría (recepción), tx para envío de comandos (publicación) y rx/downlink para confirmación de comandos enviados.

Tópicos Disponibles ​

Nota: Para suscribirte a todos los dispositivos de una filial, puedes usar el comodín de nivel único: lumiot/v1/{tenantId}/{subsidiaryId}/devices/+/rx.

Ejemplo de Envío de Comandos (Downlink) ​

Para enviar un comando a un dispositivo, debes publicar un payload en formato JSON al tópico tx de dicho equipo:

Tópico de Publicación:

lumiot/v1/{tenantId}/{subsidiaryId}/devices/{deviceId}/tx

Payload (JSON):

{
  "payloadHex": "030000",
  "fPort": 2,
  "confirmed": true,
  "isEncrypted": false
}

Ejemplos de Respuestas (Telemetría en rx) ​

Los mensajes enviados por los sensores se reciben procesados e interpretados como un JSON plano en el tópico rx:

Ejemplo de Payload Normal:

{
  "Count1_times": 0,
  "First_status": "No",
  "RO2_status": "OFF",
  "Work_mode_desc": "1Count+2AVI+1ACI",
  "ACI1_mA": 0,
  "Hardware_mode": "LT22222",
  "AVI1_V": 0,
  "Work_mode": "MOD5_HYBRID_ANALOG",
  "AVI2_V": 0,
  "DO1_status": "H",
  "DO2_status": "H",
  "RO1_status": "OFF"
}

Ejemplo de Reporte de Error por el Dispositivo:

{
  "error": "Unsupported FPort"
}

Control de Acceso por Roles (ACL) ​

El sistema valida de forma dinámica cada intento de suscripción (Subscribe) y publicación (Publish) contra la base de datos de identidad en tiempo real. Los permisos se aplican de manera estricta según el rol jerárquico del usuario conectado:

1. SuperAdmin (Nivel Infraestructura) ​

• Acceso: Total e irrestricto.
• Permisos: Puede suscribirse y publicar en cualquier tópico de cualquier inquilino o filial (#).
• Uso: Exclusivo para administradores globales y tareas de mantenimiento del cluster.

2. Integrador / Distribuidor (Nivel Tenant) ​

• Namespace Permitido: lumiot/v1/{tenantId}/#
• Permisos: Lectura (Subscribe) y Escritura (Publish).
• Aislamiento: Puede interactuar con todos los dispositivos de todas las filiales que pertenecen a su inquilino. El sistema bloqueará de inmediato a nivel de socket cualquier intento de suscripción a un {tenantId} diferente, previniendo fuga de datos.

3. Cliente (Nivel Subsidiaria) ​

• Namespace Permitido: lumiot/v1/{tenantId}/{subsidiaryId}/#
• Permisos: Lectura (Subscribe) y Escritura (Publish).
• Aislamiento: Solo puede acceder a la telemetría y enviar comandos a los dispositivos de su filial asignada. No tiene visibilidad de otras filiales, incluso si pertenecen al mismo integrador.

4. Operador (Nivel Táctico - Read Only) ​

• Namespace Permitido: lumiot/v1/{tenantId}/{subsidiaryId}/#
• Permisos: Exclusivamente Lectura (Subscribe).
• Restricciones de Seguridad:
  • No puede enviar ningún mensaje a la red (Publish está bloqueado por el ACL).
  • Puede suscribirse a canales de comandos (/tx o /rx/downlink) y telemetría (/rx), pero únicamente para monitoreo pasivo del tráfico de su filial asignada.

Estados de Suspensión (Kill-Switch) ​

La integración MQTT está acoplada al motor de facturación y auditoría. Respeta el ciclo de vida comercial de la plataforma:

• Si un usuario es desactivado, sus conexiones MQTT serán rechazadas en la autenticación y cualquier sesión abierta será cortada.
• Si un Inquilino (Tenant) es suspendido por morosidad o fin de contrato, todos los clientes, operadores e integradores asociados a ese inquilino perderán inmediatamente su acceso al broker MQTT público, interrumpiendo el flujo de datos sin necesidad de borrar los equipos.