Gateway 2.0 and MQTT Support

Learn how to create the connection between MQTT and the most powerful gateway.

PHANTOM® Gateway 2.0 MQTT Support

The Gateway 2.0 used in the wireless sensor system ERBESSD INSTRUMENTS® PHANTOM®, and the DEFIANT™ wired monitor, support the MQTT IoT protocol. All sensor data is available through MQTT, including temperature, RPM, frequency bands and wired channel overalls, as well as full time waveforms from vibration sensors (the FFT must be processed by the user from the TWF).

The gateway acts as an MQTT client that will connect to an MQTT broker of your choice, and publishes everything it collects as plain, self-describing JSON.

You can use the MQTT support at the same time as all other protocols supported by the Gateway, including EI-Analytic™, EI Monitor, OPC UA and Modbus.

Some of the options described here were added in later gateway releases. If you cannot find one in your admin console, update your gateway to the latest firmware.

Protocol support at a glance

Enabling MQTT Support

To enable the MQTT support in the Gateway 2.0 admin console, you need to activate it in the MQTT config page by clicking the “Enable MQTT connection” checkbox.

Then fill your MQTT broker options accordingly. We support the following protocols for connecting to the MQTT broker:

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

You need to enter your MQTT broker hostname/IP address, the port, and optionally the user name and password for authentication.

If you wish to receive full time waveforms from vibration sensors please mark the corresponding checkbox. Time waveforms are large messages, so if you are not intending to use them you may leave the option unchecked.

The “Allow Gateway management though MQTT” option allows you to use the full management API to control the gateway and its sensors using the MQTT connection.

After you save the settings the Gateway 2.0 will restart. After it restarts it will try to connect to the MQTT broker and show a state on the same MQTT section at the top if there are any issues: connecting, connected, reconnecting, closed or error, including the broker error message when a connection is refused.

Field reference

Security: TLS and authentication

Select mqtts:// or wss:// to encrypt the link. The Certificate validation selector controls how the broker certificate is verified:

The Advanced panel accepts a client certificate and its private key, both in PEM format, used only with mqtts:// or wss://. This is what brokers that require X.509 device identity, such as AWS IoT Core, expect.

Username and password travel in the MQTT CONNECT packet. Over mqtt:// or ws:// they are sent in clear text, so always pair credentials with mqtts:// or wss://.

The on-gateway MQTT broker

PHANTOM® Gateway hardware can also run its own embedded MQTT broker, so a PLC, SCADA or edge application on the same network can subscribe directly to the gateway with no external infrastructure. It is not available on the USB/PC gateway. Enable it with Enable local MQTT broker.

The local broker has its own Publish Topic, Append serial switch, waveform switch, compression switch and management switch, independent from the remote broker settings. Both can run at once: the same reading is then published to your remote broker and to the local one.

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

Because the local broker is unauthenticated, keep it on a trusted OT network segment.

Topic structure

With Append gateway and sensor serial number as subtopics disabled, every message is published on the base Publish Topic exactly as typed.

With it enabled, the gateway builds a topic tree. Using a base topic of phantom, a gateway serial of EIGW12345 and a sensor serial (phantomCode) of 40217:

Subscribe to everything with phantom/#, to one gateway with phantom/EIGW12345/#, or to one sensor with phantom/EIGW12345/40217/#.

Always branch on the dataType field rather than on the topic. When Append serial is off, every message type arrives on the same topic.

Payload format

The Gateway will start publishing messages every time a sensor updates its data (in its own internal update interval) or when a time waveform measurement is taken. The messages are UTF-8 JSON objects, one object per message. Nothing is binary, proprietary or schema-registry dependent: you can consume them with JSON.parse, json.loads, a Node-RED json node, the Telegraf json_v2 parser, or any SCADA JSON tag reader.

Two rules apply to every message:

• Fields a given sensor or firmware does not report are omitted, not sent as null. Read defensively.
• timestamp is Unix epoch time in seconds, not milliseconds.

Common Variables for All Sensors

The following are the properties included for each sensor type.

Triaxial Accelerometer (3, 5, 6, 8 and 9)

Example stateupdate message:

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

Triaxial Accelerometer for dataType “collection”

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

The three sample arrays are truncated in this example; a real message carries the full record. Samples per axis is data[n].length, and record duration in seconds is data[n].length / sampleRate.

Frequency bands message (dataType “bandsUpdate”)

Triaxial sensors that advertise extended band data publish a bandsUpdate alongside the state update.

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

Thermal camera message (10)

For dataType: "stateupdate" the camera reports avgImageTemperature, the average image temperature in Celsius.

For dataType: "collection" the full image is published:

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

Thermocouple temperature node message (20, 21 and 22)

Infrared temperature node message (25)

4-20mA sensor (26) and Voltmeter (27)

Velocity (RPM) sensor (40)

Distance sensor (50)

General purpose module (60)

Current sensor (30 and 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
}

Dry contacts Sensor (31)

DEFIANT™ wired channels

Wired channel overalls are published according to the Send wired channels overalls cadence (Never, As fast as possible, or throttled by Wired overall send timeout). wiredChannel is 1-based in the payload, and only the overalls actually computed for that channel are included.

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

Available keys:

While the DEFIANT™ is in project (route/recording) mode, wiredOveralls publishing is suspended.

Wired waveforms are published as wiredCollection, with a single data array already scaled by the channel calibration and sensor sensitivity:

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

Modbus and custom unit tags

Values the gateway reads from third-party Modbus devices, or from wired custom units, are republished on MQTT as customUnitStateUpdate. units and values are parallel arrays, and a wiredChannel field is added when the value comes from a DEFIANT™ wired channel.

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

Payload compression

The Compress (gzip) payload option wraps every JSON payload in a gzip stream before publishing, which typically cuts waveform messages by 60-80%. The payload is then raw gzip bytes, not text, so decompress before parsing:

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

def on_message(client, userdata, msg):
    raw = msg.payload
    if raw[:2] == b"\x1f\x8b":            # gzip magic number
        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", "your-password")
client.tls_set()                          # required for mqtts://
client.on_message = on_message
client.connect("broker.example.com", 8883)
client.subscribe("phantom/#", qos=1)
client.loop_forever()

Leave compression off if your platform cannot decompress payloads; many SCADA JSON tag readers cannot.

Remote management over MQTT

Ticking Allow Gateway management through MQTT makes the gateway subscribe to the Subscribe topic and act on JSON commands received there. Replies are published on the normal publish topic, with /<gwSerial> appended when Append serial is on. Every command must carry the target gateway serial in gwSerial; a gateway ignores commands addressed to another serial.

Request a waveform from a specific sensor:

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

Call the Gateway Management API:

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

The gateway answers with the same JSON documents the admin console receives over WebSocket, enriched with a gwSerial field so you can route replies. The action vocabulary covers the full console feature set, including getstate, deviceinfo, setbasicconfig, setfriendlyname, pair, unpair, restart, startfwupdate, getofflinefiles and wiredcollectnow. Please contact an ERBESSD INSTRUMENTS® support representative to receive a copy of the management API documentation.

This is a privileged control channel. Enable it only on an authenticated, TLS-protected broker, with an ACL restricting who may publish to the subscribe topic. Leave it disabled if you only need telemetry.

MQTT version and payload format

MQTT version. The gateway client connects at protocol level 4, that is MQTT 3.1.1. This is the interoperable baseline: MQTT 5.0 brokers accept 3.1.1 clients, so an MQTT 5.0 infrastructure works without changes. What the gateway session does not use are 5.0-only features such as shared subscriptions, topic aliases, request/response correlation properties, session expiry and reason codes. If you need those downstream, terminate the gateway 3.1.1 session at your broker and speak 5.0 between the broker and your applications.

Is the payload proprietary? No. It is open JSON with stable field names, fully documented above. No schema registry, licence or SDK is required to read it.

Quick start with mosquitto_sub

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

Filter down to just the light-weight state updates:

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