MQTT Client
The gateway makes an outbound connection as a client to an external IIoT broker (HiveMQ / Mosquitto / EMQX / AWS IoT / Azure IoT Hub, etc.) and subscribes to / publishes on its topics. Incoming messages are stored in an in-memory cache, and the cached value is read at each tag's collection interval.
| Situation | Which mode to use |
|---|---|
| An external IT system sends values via REST POST | HTTP Push |
| An external server pushes over WebSocket | WebSocket Client |
| An external IIoT MQTT broker pushes on a topic | MQTT Client (this page) |
| Sparkplug B standard (NBIRTH/DBIRTH/DCMD) | Sparkplug B |
| Reading values directly from in-house PLCs | Modbus / OPC-UA, etc. |
Registration form fields
| Field | What to enter | Example |
|---|---|---|
| IP Address | MQTT broker host | broker.hivemq.com, 10.0.0.50 |
| Port | MQTT broker port (plaintext 1883, TLS 8883) | 1883, 8883 |
| USERNAME | Broker authentication username (optional) | iotuser |
| PASSWORD | Broker authentication password (optional) | s3cret |
| TLS | Plaintext / TLS selection | false (tcp) / true (ssl) |
| QoS | subscribe / publish QoS | 0 / 1 / 2 |
| KEEP ALIVE | Keep-alive interval (seconds) | 60 |
| CLEAN SESSION | Clean session flag | true (default) / false |
| CLIENT ID | Explicit client id (optional) | edge-plant-01 |
| Collection interval | Interval at which the gateway reads the cached value (ms) | 1000 |
Actual broker URL: <scheme>://<host>:<port> (e.g. tcp://broker.hivemq.com:1883,
ssl://10.0.0.50:8883).
If CLIENT ID is not specified, one is generated automatically in the form PP-<opc_id>-<random6> (within the 23-character length recommended by MQTT v3.1).
Tag PLC address notation — 4-mode JSON
A tag's PLC address = MQTT topic + 4-mode JSON decoder. Same spec as WebSocket / Apache Kafka.
| Mode | Format | Behavior |
|---|---|---|
| SCALAR | factory/line1/temp or factory/line1/temp.value | Entire message as a String. If the message is a JSON object, falls back to raw. |
| KEY | sensors/multi:temperature | Value of a top-level JSON key (e.g. {"temperature":25.3,"humidity":60} → 25.3) |
| PATH | sensors/multi:$.data.tags.T1 | Dynamic JSON Pointer evaluation (nested keys supported) |
| RAW | sensors/multi:_raw_ | The entire last message (for debugging) |
Wildcard subscribe is also supported:
| Tag PLC address | Meaning |
|---|---|
device/+/status | Single-level wildcard (sensor01/sensor02/... all) |
factory/# | Multi-level wildcard (everything under factory — last arrived message wins) |
The first read call performs a lazy subscribe (returns an empty string). The cached value becomes available from the next polling cycle onward.
Common cases
| Case | How |
|---|---|
| HiveMQ Cloud / public broker | host = broker.hivemq.com 1883 (plaintext), 8883 (TLS + authentication) |
| In-house Mosquitto / EMQX | host = internal IP, 1883 / 8883. Register username/password, etc. |
| AWS IoT Core | host = <account>-ats.iot.<region>.amazonaws.com, 8883 + X.509 (separate truststore configuration) |
| Azure IoT Hub | host = <hub>.azure-devices.net, 8883 + SAS token (username/password) |
| QoS=1 guarantee | Select QoS=1 — the broker retransmits until acknowledged. Higher processing cost |
| Persistent session | CLEAN SESSION=false + fixed CLIENT ID — the broker retains undelivered messages |
write (publish)
Writing a value from the tag page or via the REST API publishes it immediately to the corresponding broker topic (retain=false). The value's String is sent as the payload verbatim — either JSON or plaintext.
plc_address = factory/line1/cmd
value = ON
→ MQTT publish: topic="factory/line1/cmd" payload="ON"
plc_address = devices/dev01/setpoint
value = {"sp":42.5,"unit":"degC"}
→ MQTT publish: topic="devices/dev01/setpoint" payload='{"sp":42.5,"unit":"degC"}'
Common problems and solutions
| Symptom | Cause | Solution |
|---|---|---|
| No values arriving | The broker is not publishing messages | Receive directly with mosquitto_sub -h <host> -p 1883 -t '<topic>' -v and check whether any lines appear |
[MQTT] connect 실패: not authorized | Wrong username/password | Recheck the broker user/password. Check ACL restrictions |
[MQTT] connect 실패: timeout | Firewall / blocked port | Verify with telnet <host> 1883, openssl s_client -connect <host>:8883 |
| TLS handshake failure | Self-signed certificate / missing cacerts | Use a proper certificate in production. As a temporary measure, ask your system administrator to add it to the truststore |
| Wildcard values arrive only intermittently | With wildcards, the last arrived message wins | Register topics separately (a dedicated tag per topic) |
More detailed technical documentation
- Advanced — Driver: MQTT Client
- Sparkplug B (MQTT + standard NBIRTH/DBIRTH/DCMD payloads)
- Eclipse Paho official documentation