Gateway 2.0 y soporte MQTT

Aprende a crear la conexión entre MQTT y el gateway más potente.

Soporte MQTT del PHANTOM® Gateway 2.0

El Gateway 2.0 que se usa en el sistema de sensores inalámbricos ERBESSD INSTRUMENTS® PHANTOM®, y el monitor cableado DEFIANT™, soportan el protocolo IoT MQTT. Todos los datos de los sensores están disponibles por MQTT, incluidos temperatura, RPM, bandas de frecuencia y valores globales de los canales cableados, así como las formas de onda completas de los sensores de vibración (la FFT debe procesarla el usuario a partir de la TWF).

El gateway actúa como cliente MQTT y se conecta al broker MQTT que elijas, publicando todo lo que recolecta en JSON plano y autodescriptivo.

Puedes usar el soporte MQTT al mismo tiempo que el resto de los protocolos que soporta el Gateway, incluidos EI-Analytic™, EI Monitor, OPC UA y Modbus.

Algunas de las opciones descritas aquí se agregaron en versiones posteriores del gateway. Si no encuentras alguna en tu consola de administración, actualiza el gateway al firmware más reciente.

Resumen del soporte del protocolo

Cómo habilitar el soporte MQTT

Para habilitar el soporte MQTT en la consola de administración del Gateway 2.0, actívalo en la página de configuración MQTT marcando la casilla “Enable MQTT connection”.

Luego llena las opciones de tu broker MQTT. Soportamos los siguientes protocolos para conectarse al broker MQTT:

• mqtt://
• mqtts:// (cifrado)
• ws:// (websocket)
• wss:// (websocket cifrado)

Debes ingresar el nombre de host o la dirección IP de tu broker MQTT, el puerto y, opcionalmente, el usuario y la contraseña para la autenticación.

Si deseas recibir las formas de onda completas de los sensores de vibración, marca la casilla correspondiente. Las formas de onda son mensajes grandes, así que si no piensas usarlas puedes dejar la opción sin marcar.

La opción “Allow Gateway management though MQTT” te permite usar toda la API de administración para controlar el gateway y sus sensores mediante la conexión MQTT.

Después de guardar la configuración, el Gateway 2.0 se reiniciará. Al reiniciarse intentará conectarse al broker MQTT y mostrará un estado en la misma sección MQTT de la parte superior si hay algún problema: connecting, connected, reconnecting, closed o error, incluyendo el mensaje de error del broker cuando la conexión es rechazada.

Referencia de campos

Seguridad: TLS y autenticación

Selecciona mqtts:// o wss:// para cifrar el enlace. El selector Certificate validation controla cómo se verifica el certificado del broker:

El panel Advanced acepta un certificado de cliente y su llave privada, ambos en formato PEM, y solo se usan con mqtts:// o wss://. Es lo que esperan los brokers que exigen identidad de dispositivo X.509, como AWS IoT Core.

El usuario y la contraseña viajan en el paquete CONNECT de MQTT. Sobre mqtt:// o ws:// se envían en texto claro, así que acompaña siempre las credenciales con mqtts:// o wss://.

El broker MQTT dentro del gateway

El hardware PHANTOM® Gateway también puede ejecutar su propio broker MQTT embebido, de modo que un PLC, un SCADA o una aplicación de borde en la misma red pueda suscribirse directamente al gateway sin infraestructura externa. No está disponible en el gateway USB/PC. Habilítalo con Enable local MQTT broker.

El broker local tiene su propio Publish Topic, interruptor de Append serial, interruptor de formas de onda, de compresión y de administración, independientes de la configuración del broker remoto. Ambos pueden funcionar a la vez: la misma lectura se publica entonces en tu broker remoto y en el local.

mosquitto_sub -h <ip-del-gateway> -p 1883 -t "phantom/#" -v

Como el broker local no lleva autenticación, mantenlo en un segmento de red OT de confianza.

Estructura de tópicos

Con Append gateway and sensor serial number as subtopics deshabilitado, todos los mensajes se publican en el Publish Topic base tal como lo escribiste.

Con la opción habilitada, el gateway construye un árbol de tópicos. Usando un tópico base phantom, un número de serie de gateway EIGW12345 y un número de serie de sensor (phantomCode) 40217:

Suscríbete a todo con phantom/#, a un solo gateway con phantom/EIGW12345/#, o a un solo sensor con phantom/EIGW12345/40217/#.

Distingue siempre por el campo dataType, no por el tópico. Cuando Append serial está desactivado, todos los tipos de mensaje llegan al mismo tópico.

Formato del payload

El Gateway empieza a publicar mensajes cada vez que un sensor actualiza sus datos (en su propio intervalo interno de actualización) o cuando se toma una medición de forma de onda. Los mensajes son objetos JSON en UTF-8, un objeto por mensaje. Nada es binario, propietario ni depende de un registro de esquemas: puedes consumirlos con JSON.parse, json.loads, un nodo json de Node-RED, el parser json_v2 de Telegraf o cualquier lector de tags JSON de SCADA.

Dos reglas aplican a todos los mensajes:

• Los campos que un sensor o firmware no reporta se omiten, no se envían como null. Lee de forma defensiva.
• timestamp es tiempo Unix en segundos, no en milisegundos.

Variables comunes a todos los sensores

Estas son las propiedades incluidas para cada tipo de sensor.

Acelerómetro triaxial (3, 5, 6, 8 y 9)

Ejemplo de mensaje stateupdate:

{
  "rssi": -63,
  "type": 6,
  "version": 195,
  "phantomCode": 40217,
  "gwSerial": "EIGW12345",
  "timestamp": 1756231043,
  "dataType": "stateupdate",
  "friendlyName": "Bomba 3 - Motor LA",
  "seq": 184,
  "advFlags": 0,
  "batteryType": 1,
  "battery": 3.61,
  "temperature": 41.25,
  "updateInterval": 300,
  "txPower": 4,
  "minRMSFreq": 10,
  "maxRMSFreq": 1000,
  "rms": [1.42, 0.88, 2.07],
  "range": 16,
  "recordingSettings": 3,
  "minRMSFreqAccel": 1000,
  "maxRMSFreqAccel": 10000,
  "arms": [0.412, 0.298, 0.677]
}

Acelerómetro triaxial con dataType “collection”

{
  "serialNumber": 40217,
  "sampleRate": 3200,
  "gwSerial": "EIGW12345",
  "timestamp": 1756231043,
  "type": 6,
  "dataType": "collection",
  "friendlyName": "Bomba 3 - Motor LA",
  "isAlarm": false,
  "rpm": 1478,
  "temperature": 41.25,
  "data": [
    [0.0123, -0.0044, 0.0187],
    [0.0091, 0.0102, -0.0058],
    [-0.021, 0.0176, 0.0031]
  ]
}

Los tres arreglos de muestras están recortados en este ejemplo; un mensaje real lleva el registro completo. El número de muestras por eje es data[n].length, y la duración del registro en segundos es data[n].length / sampleRate.

Mensaje de bandas de frecuencia (dataType “bandsUpdate”)

Los sensores triaxiales que anuncian datos extendidos de bandas publican un bandsUpdate junto con la actualización de estado.

{
  "dataType": "bandsUpdate",
  "serialNumber": 40217,
  "phantomCode": 40217,
  "type": 6,
  "version": 195,
  "gwSerial": "EIGW12345",
  "timestamp": 1756231043,
  "seq": 184,
  "rpmMin": 1450,
  "rpmMax": 1495,
  "bands": [
    {
      "min": 1.0,
      "max": 2.5,
      "measurement": "velocity",
      "unit": "orders",
      "output": "rms",
      "values": { "x": 1.12, "y": 0.74, "z": 1.88 },
      "valueUnit": "mm/s"
    }
  ]
}

Mensaje de la cámara termográfica (10)

Con dataType: "stateupdate" la cámara reporta avgImageTemperature, la temperatura promedio de la imagen en grados Celsius.

Con dataType: "collection" se publica la imagen completa:

{
  "phantomCode": 60912,
  "serialNumber": 60912,
  "gwSerial": "EIGW12345",
  "timestamp": 1756231400,
  "type": 10,
  "dataType": "collection",
  "columns": 32,
  "rows": 24,
  "frames": 1,
  "frameRate": 1,
  "data": [
    [
      [24.31, 24.55, 25.02],
      [24.28, 24.61, 25.14]
    ]
  ]
}

Mensaje del nodo de temperatura por termopar (20, 21 y 22)

Mensaje del nodo de temperatura infrarroja (25)

Sensor 4-20 mA (26) y voltímetro (27)

Sensor de velocidad (RPM) (40)

Sensor de distancia (50)

Módulo de propósito general (60)

Sensor de corriente (30 y 32)

{
  "dataType": "stateupdate",
  "type": 32,
  "phantomCode": 51844,
  "gwSerial": "EIGW12345",
  "timestamp": 1756231102,
  "rssi": -71,
  "version": 118,
  "battery": 3.58,
  "batteryType": 4,
  "temperature": 33.1,
  "instCurrent": [12.4, 12.1, 12.8, 0.0],
  "averageCurrent": [12.3, 12.0, 12.7, 0.0],
  "minCurrent": [11.9, 11.6, 12.2, 0.0],
  "maxCurrent": [13.1, 12.9, 13.4, 0.0],
  "accumulatedCurrent": [842.5, 838.1, 851.9, 0.0],
  "accumulatedStart": 1753553200,
  "accumulatedEnd": 1756231102
}

Sensor de contactos secos (31)

Canales cableados del DEFIANT™

Los valores globales de los canales cableados se publican según la cadencia de Send wired channels overalls (Never, As fast as possible, o limitada por Wired overall send timeout). En el payload, wiredChannel empieza en 1, y solo se incluyen los globales que realmente se calculan para ese canal.

{
  "dataType": "wiredOveralls",
  "wiredChannel": 1,
  "gwSerial": "EIDF98765",
  "timestamp": 1756231500,
  "sensorType": "accelerometer",
  "friendlyName": "Ventilador 12 - Interior",
  "accel_rms": 0.482,
  "velocity_rms": 2.14,
  "displacement_rms": 18.7,
  "gE": 0.93,
  "rpm": 1786,
  "accel_truepeak": 1.84,
  "accel_peaktopeak": 3.52,
  "accel_kurtosis": 3.11
}

Claves disponibles:

Mientras el DEFIANT™ está en modo proyecto (ruta/grabación), la publicación de wiredOveralls queda suspendida.

Las formas de onda cableadas se publican como wiredCollection, con un solo arreglo data ya escalado por la calibración del canal y la sensibilidad del sensor:

{
  "dataType": "wiredCollection",
  "wiredChannel": 1,
  "gwSerial": "EIDF98765",
  "timestamp": 1756231500,
  "sensorType": "accelerometer",
  "sampleRate": 25600,
  "data": [0.0041, -0.0093, 0.0128]
}

Tags de Modbus y unidades personalizadas

Los valores que el gateway lee de dispositivos Modbus de terceros, o de unidades personalizadas cableadas, se republican en MQTT como customUnitStateUpdate. units y values son arreglos paralelos, y se agrega un campo wiredChannel cuando el valor proviene de un canal cableado del DEFIANT™.

{
  "dataType": "customUnitStateUpdate",
  "gwSerial": "EIGW12345",
  "timestamp": 1756231600,
  "source": "gateway",
  "clientName": "PLC del compresor",
  "tagName": "DischargePressure",
  "functionType": "holdingRegister",
  "address": 40012,
  "byteOrder": "ABCD",
  "tagDataType": "float32",
  "machineCode": "COMP-01",
  "pointIndex": 2,
  "units": ["bar"],
  "values": [7.42]
}

Compresión del payload

La opción Compress (gzip) payload envuelve cada payload JSON en un flujo gzip antes de publicarlo, lo que normalmente reduce los mensajes de forma de onda entre 60 y 80 %. El payload pasa entonces a ser bytes gzip en crudo, no texto, así que hay que descomprimirlo antes de parsearlo:

import gzip, json
import paho.mqtt.client as mqtt

def on_message(client, userdata, msg):
    raw = msg.payload
    if raw[:2] == b"\x1f\x8b":            # número mágico de gzip
        raw = gzip.decompress(raw)
    data = json.loads(raw)
    print(data["dataType"], data.get("phantomCode") or data.get("serialNumber"))

client = mqtt.Client()
client.username_pw_set("phantom", "tu-contrasena")
client.tls_set()                          # requerido para mqtts://
client.on_message = on_message
client.connect("broker.example.com", 8883)
client.subscribe("phantom/#", qos=1)
client.loop_forever()

Deja la compresión desactivada si tu plataforma no puede descomprimir payloads; muchos lectores de tags JSON de SCADA no pueden.

Administración remota por MQTT

Marcar Allow Gateway management through MQTT hace que el gateway se suscriba al Subscribe topic y actúe sobre los comandos JSON que reciba ahí. Las respuestas se publican en el tópico de publicación normal, con /<gwSerial> añadido cuando Append serial está activo. Todo comando debe llevar el número de serie del gateway destino en gwSerial; un gateway ignora los comandos dirigidos a otro número de serie.

Solicitar una forma de onda a un sensor específico:

{
  "type": "requestWaveform",
  "gwSerial": "EIGW12345",
  "phantomCode": 40217
}

Llamar a la API de administración del Gateway:

{
  "type": "observeerequest",
  "gwSerial": "EIGW12345",
  "action": "getstate"
}

El gateway responde con los mismos documentos JSON que recibe la consola de administración por WebSocket, enriquecidos con un campo gwSerial para que puedas enrutar las respuestas. El vocabulario de action cubre todas las funciones de la consola, incluidas getstate, deviceinfo, setbasicconfig, setfriendlyname, pair, unpair, restart, startfwupdate, getofflinefiles y wiredcollectnow. Contacta a un representante de soporte de ERBESSD INSTRUMENTS® para recibir una copia de la documentación de la API de administración.

Este es un canal de control privilegiado. Habilítalo solo en un broker autenticado y protegido con TLS, con una ACL que restrinja quién puede publicar en el tópico de suscripción. Déjalo deshabilitado si solo necesitas telemetría.

Versión de MQTT y formato del payload

Versión de MQTT. El cliente del gateway se conecta en el nivel de protocolo 4, es decir MQTT 3.1.1. Esa es la base interoperable: los brokers MQTT 5.0 aceptan clientes 3.1.1, así que una infraestructura MQTT 5.0 funciona sin cambios. Lo que la sesión del gateway no usa son las funciones exclusivas de 5.0, como suscripciones compartidas, alias de tópico, propiedades de correlación petición/respuesta, expiración de sesión y códigos de razón. Si las necesitas más adelante en la cadena, termina la sesión 3.1.1 del gateway en tu broker y habla 5.0 entre el broker y tus aplicaciones.

¿El payload es propietario? No. Es JSON abierto con nombres de campo estables, documentado por completo arriba. No hace falta ningún registro de esquemas, licencia ni SDK para leerlo.

Inicio rápido con mosquitto_sub

mosquitto_sub -h broker.example.com -p 8883 --cafile /etc/ssl/certs/ca-certificates.crt -u phantom -P "tu-contrasena" -t "phantom/#" -q 1 -v

Filtra únicamente las actualizaciones de estado, que son ligeras:

mosquitto_sub -h broker.example.com -t "phantom/+/+/stateupdate" -v