Publishing¶
Artek-MQTT-Pub publishes tag values to MQTT from declarative mappings: you name a tag folder, a connection profile, a topic scheme and a trigger, and Pub keeps the broker up to date. Mappings are managed on Artek MQTT → Publishers in the gateway web interface, which also shows per-mapping counters.
To publish from a script instead, use system.artekmqtt.publish (see Scripting). For Sparkplug B, see Sparkplug B.
Mappings¶
A mapping set is a named configuration that takes a tag folder subtree as its source and publishes the tags in it.
| Setting | What it does |
|---|---|
| Source | The tag folder whose subtree is published. |
| Connection profile | Which broker connection this mapping publishes through. |
| Topic | UNS mode or a topic template (see UNS mode). |
| Trigger | On change, periodic, or both (see Triggers). |
| QoS | 0, 1 or 2, per mapping. |
| Retain | On or off, per mapping. |
| Payload format | Raw, JSON envelope or custom template (see Payload formats). |
| Date format | How DateTime values are written (see Dates). |
| MQTT 5 options | Message expiry, user properties, topic alias (see MQTT 5 options). |
Tag expansion is capped, so a mapping cannot expand an unbounded number of tags or folder levels.
Per-mapping broker routing¶
Each mapping chooses its own connection profile, so different subtrees of the same tag tree can go to different brokers. For example, one area's tags can go to a site broker while another's go to an enterprise broker.
UNS mode¶
UNS mode makes the topic mirror the tag tree, which is the usual way to build a Unified Namespace from Ignition tags. Topics are built from a configurable prefix and template using these tokens:
| Token | Replaced with |
|---|---|
{tagPath} |
The tag's path. |
{tagName} |
The tag's name. |
Triggers¶
| Trigger | Behavior |
|---|---|
| On change | Publishes when the value changes, with an optional deadband and a minimum interval between publishes. |
| Periodic | Publishes on a fixed interval (a heartbeat), whether or not the value changed. |
| Both | On change, plus the periodic heartbeat. |
Payload formats¶
| Format | Payload |
|---|---|
| Raw | The value alone. |
| JSON envelope | A JSON object {value, quality, timestamp}, optionally with metadata. |
| Template | A custom template. |
In JSON payloads:
- A null value is written as
"value":null. - NaN and infinite numbers are written as the strings
"NaN","Infinity"and"-Infinity".
Dates¶
Each mapping has a dateFormat setting that controls how DateTime values are written in JSON, raw and template output:
dateFormat |
Output |
|---|---|
EPOCH_MS |
Epoch milliseconds. The default for new mappings. |
ISO8601 |
ISO 8601 text. |
LEGACY |
The date text earlier releases produced, byte for byte. Use it to keep existing consumers working unchanged. |
MQTT 5 options¶
On an MQTT 5.0 connection each mapping can set:
- Message expiry: how long the broker keeps an undelivered message.
- User properties: key/value pairs attached to every message.
- Topic alias: lets the broker replace a long topic with a short number to save bandwidth.
Delivery and outages¶
With QoS 1 or 2, messages published while the broker is unreachable go into the connection's store-and-forward queue and are sent in order when it reconnects. QoS 0 messages are not buffered. See Store-and-forward.
On a redundant gateway pair, only the active node publishes; the standby refuses publishes rather than buffering them (see Security).