Gateway 2.0 et support MQTT

Découvrez comment établir la connexion entre MQTT et la passerelle la plus puissante.

Support MQTT du PHANTOM® Gateway 2.0

Le Gateway 2.0 utilisé dans le système de capteurs sans fil ERBESSD INSTRUMENTS® PHANTOM®, ainsi que le moniteur filaire DEFIANT™, prennent en charge le protocole IoT MQTT. Toutes les données des capteurs sont disponibles via MQTT, y compris la température, les RPM, les bandes de fréquence et les valeurs globales des voies filaires, ainsi que les formes d’onde complètes des capteurs de vibration (la FFT doit être calculée par l’utilisateur à partir de la TWF).

La passerelle agit comme un client MQTT qui se connecte au broker MQTT de votre choix, et publie tout ce qu’elle collecte en JSON simple et autodescriptif.

Vous pouvez utiliser le support MQTT en même temps que tous les autres protocoles pris en charge par la passerelle, y compris EI-Analytic™, EI Monitor, OPC UA et Modbus.

Certaines des options décrites ici ont été ajoutées dans des versions ultérieures de la passerelle. Si vous n’en trouvez pas une dans votre console d’administration, mettez à jour la passerelle vers le dernier firmware.

Le support du protocole en un coup d’œil

Activer le support MQTT

Pour activer le support MQTT dans la console d’administration du Gateway 2.0, activez-le sur la page de configuration MQTT en cochant la case « Enable MQTT connection ».

Renseignez ensuite les options de votre broker MQTT. Nous prenons en charge les protocoles suivants pour la connexion au broker MQTT :

• mqtt://
• mqtts:// (chiffré)
• ws:// (websocket)
• wss:// (websocket chiffré)

Vous devez saisir le nom d’hôte ou l’adresse IP de votre broker MQTT, le port et, en option, le nom d’utilisateur et le mot de passe pour l’authentification.

Si vous souhaitez recevoir les formes d’onde complètes des capteurs de vibration, cochez la case correspondante. Les formes d’onde sont des messages volumineux : si vous ne comptez pas les utiliser, vous pouvez laisser l’option décochée.

L’option « Allow Gateway management though MQTT » vous permet d’utiliser l’ensemble de l’API d’administration pour piloter la passerelle et ses capteurs via la connexion MQTT.

Après l’enregistrement des paramètres, le Gateway 2.0 redémarre. Au redémarrage, il tente de se connecter au broker MQTT et affiche un état dans la même section MQTT en haut de page en cas de problème : connecting, connected, reconnecting, closed ou error, y compris le message d’erreur du broker lorsque la connexion est refusée.

Référence des champs

Sécurité : TLS et authentification

Sélectionnez mqtts:// ou wss:// pour chiffrer la liaison. Le sélecteur Certificate validation détermine comment le certificat du broker est vérifié :

Le panneau Advanced accepte un certificat client et sa clé privée, tous deux au format PEM, utilisés uniquement avec mqtts:// ou wss://. C’est ce qu’attendent les brokers qui exigent une identité d’appareil X.509, comme AWS IoT Core.

Le nom d’utilisateur et le mot de passe circulent dans le paquet CONNECT de MQTT. Sur mqtt:// ou ws://, ils sont envoyés en clair : associez donc toujours les identifiants à mqtts:// ou wss://.

Le broker MQTT embarqué dans la passerelle

Le matériel PHANTOM® Gateway peut également exécuter son propre broker MQTT embarqué, afin qu’un automate, un SCADA ou une application de périphérie sur le même réseau puisse s’abonner directement à la passerelle sans infrastructure externe. Il n’est pas disponible sur la passerelle USB/PC. Activez-le avec Enable local MQTT broker.

Le broker local possède son propre Publish Topic, son interrupteur Append serial, celui des formes d’onde, de la compression et de l’administration, indépendants des réglages du broker distant. Les deux peuvent fonctionner simultanément : la même mesure est alors publiée sur votre broker distant et sur le broker local.

mosquitto_sub -h <ip-de-la-passerelle> -p 1883 -t "phantom/#" -v

Comme le broker local n’est pas authentifié, gardez-le sur un segment de réseau OT de confiance.

Structure des topics

Avec Append gateway and sensor serial number as subtopics désactivé, tous les messages sont publiés sur le Publish Topic de base exactement tel que vous l’avez saisi.

Avec l’option activée, la passerelle construit une arborescence de topics. Avec un topic de base phantom, un numéro de série de passerelle EIGW12345 et un numéro de série de capteur (phantomCode) 40217 :

Abonnez-vous à tout avec phantom/#, à une seule passerelle avec phantom/EIGW12345/#, ou à un seul capteur avec phantom/EIGW12345/40217/#.

Distinguez toujours par le champ dataType, jamais par le topic. Lorsque Append serial est désactivé, tous les types de messages arrivent sur le même topic.

Format du payload

La passerelle commence à publier des messages chaque fois qu’un capteur met à jour ses données (selon son propre intervalle interne de mise à jour) ou lorsqu’une mesure de forme d’onde est réalisée. Les messages sont des objets JSON en UTF-8, un objet par message. Rien n’est binaire, propriétaire ni dépendant d’un registre de schémas : vous pouvez les consommer avec JSON.parse, json.loads, un nœud json de Node-RED, le parseur json_v2 de Telegraf ou n’importe quel lecteur de tags JSON de SCADA.

Deux règles s’appliquent à tous les messages :

• Les champs qu’un capteur ou un firmware ne renseigne pas sont omis, ils ne sont pas envoyés à null. Lisez de manière défensive.
• timestamp est un temps Unix en secondes, pas en millisecondes.

Variables communes à tous les capteurs

Voici les propriétés incluses pour chaque type de capteur.

Accéléromètre triaxial (3, 5, 6, 8 et 9)

Exemple de message stateupdate :

{
  "rssi": -63,
  "type": 6,
  "version": 195,
  "phantomCode": 40217,
  "gwSerial": "EIGW12345",
  "timestamp": 1756231043,
  "dataType": "stateupdate",
  "friendlyName": "Pompe 3 - Moteur CA",
  "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]
}

Accéléromètre triaxial avec dataType « collection »

{
  "serialNumber": 40217,
  "sampleRate": 3200,
  "gwSerial": "EIGW12345",
  "timestamp": 1756231043,
  "type": 6,
  "dataType": "collection",
  "friendlyName": "Pompe 3 - Moteur CA",
  "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]
  ]
}

Les trois tableaux d’échantillons sont tronqués dans cet exemple ; un message réel contient l’enregistrement complet. Le nombre d’échantillons par axe est data[n].length, et la durée de l’enregistrement en secondes est data[n].length / sampleRate.

Message de bandes de fréquence (dataType « bandsUpdate »)

Les capteurs triaxiaux qui annoncent des données de bandes étendues publient un bandsUpdate en même temps que la mise à jour d’état.

{
  "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"
    }
  ]
}

Message de la caméra thermique (10)

Avec dataType: "stateupdate", la caméra renseigne avgImageTemperature, la température moyenne de l’image en degrés Celsius.

Avec dataType: "collection", l’image complète est publiée :

{
  "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]
    ]
  ]
}

Message du nœud de température par thermocouple (20, 21 et 22)

Message du nœud de température infrarouge (25)

Capteur 4-20 mA (26) et voltmètre (27)

Capteur de vitesse (RPM) (40)

Capteur de distance (50)

Module à usage général (60)

Capteur de courant (30 et 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
}

Capteur de contacts secs (31)

Voies filaires du DEFIANT™

Les valeurs globales des voies filaires sont publiées selon la cadence de Send wired channels overalls (Never, As fast as possible, ou limitée par Wired overall send timeout). Dans le payload, wiredChannel commence à 1, et seules les globales réellement calculées pour cette voie sont incluses.

{
  "dataType": "wiredOveralls",
  "wiredChannel": 1,
  "gwSerial": "EIDF98765",
  "timestamp": 1756231500,
  "sensorType": "accelerometer",
  "friendlyName": "Ventilateur 12 - Intérieur",
  "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
}

Clés disponibles :

Tant que le DEFIANT™ est en mode projet (ronde/enregistrement), la publication de wiredOveralls est suspendue.

Les formes d’onde filaires sont publiées sous wiredCollection, avec un seul tableau data déjà mis à l’échelle par l’étalonnage de la voie et la sensibilité du capteur :

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

Tags Modbus et unités personnalisées

Les valeurs que la passerelle lit sur des équipements Modbus tiers, ou sur des unités personnalisées filaires, sont republiées sur MQTT sous customUnitStateUpdate. units et values sont des tableaux parallèles, et un champ wiredChannel est ajouté lorsque la valeur provient d’une voie filaire du DEFIANT™.

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

Compression du payload

L’option Compress (gzip) payload encapsule chaque payload JSON dans un flux gzip avant publication, ce qui réduit généralement les messages de forme d’onde de 60 à 80 %. Le payload devient alors des octets gzip bruts, et non du texte : il faut donc le décompresser avant de l’analyser.

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

def on_message(client, userdata, msg):
    raw = msg.payload
    if raw[:2] == b"\x1f\x8b":            # nombre magique 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", "votre-mot-de-passe")
client.tls_set()                          # requis pour mqtts://
client.on_message = on_message
client.connect("broker.example.com", 8883)
client.subscribe("phantom/#", qos=1)
client.loop_forever()

Laissez la compression désactivée si votre plateforme ne sait pas décompresser les payloads ; beaucoup de lecteurs de tags JSON de SCADA en sont incapables.

Administration à distance via MQTT

Cocher Allow Gateway management through MQTT fait que la passerelle s’abonne au Subscribe topic et agit sur les commandes JSON qu’elle y reçoit. Les réponses sont publiées sur le topic de publication habituel, avec /<gwSerial> ajouté lorsque Append serial est actif. Toute commande doit porter le numéro de série de la passerelle cible dans gwSerial ; une passerelle ignore les commandes adressées à un autre numéro de série.

Demander une forme d’onde à un capteur précis :

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

Appeler l’API d’administration du Gateway :

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

La passerelle répond avec les mêmes documents JSON que ceux reçus par la console d’administration via WebSocket, enrichis d’un champ gwSerial pour vous permettre de router les réponses. Le vocabulaire de action couvre toutes les fonctions de la console, dont getstate, deviceinfo, setbasicconfig, setfriendlyname, pair, unpair, restart, startfwupdate, getofflinefiles et wiredcollectnow. Contactez un représentant du support ERBESSD INSTRUMENTS® pour recevoir une copie de la documentation de l’API d’administration.

Il s’agit d’un canal de contrôle privilégié. Ne l’activez que sur un broker authentifié et protégé par TLS, avec une ACL restreignant qui peut publier sur le topic d’abonnement. Laissez-le désactivé si vous n’avez besoin que de télémétrie.

Version de MQTT et format du payload

Version de MQTT. Le client de la passerelle se connecte au niveau de protocole 4, c’est-à-dire MQTT 3.1.1. C’est la base interopérable : les brokers MQTT 5.0 acceptent les clients 3.1.1, donc une infrastructure MQTT 5.0 fonctionne sans modification. Ce que la session de la passerelle n’utilise pas, ce sont les fonctions exclusives à 5.0 : abonnements partagés, alias de topic, propriétés de corrélation requête/réponse, expiration de session et codes de raison. Si vous en avez besoin en aval, terminez la session 3.1.1 de la passerelle sur votre broker et parlez 5.0 entre le broker et vos applications.

Le payload est-il propriétaire ? Non. C’est du JSON ouvert avec des noms de champs stables, entièrement documenté ci-dessus. Aucun registre de schémas, aucune licence ni SDK n’est nécessaire pour le lire.

Démarrage rapide avec mosquitto_sub

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

Ne filtrer que les mises à jour d’état, qui sont légères :

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