Subscribing¶
Artek-MQTT-Sub subscribes to MQTT topics and turns what arrives into Ignition tags, with no tags to create by hand. It can also run a gateway script for each message and, if you allow it, publish back to MQTT when someone writes one of those tags. Subscriptions are managed on Artek MQTT → Subscriptions in the gateway web interface, which also shows per-subscription counters.
For Sparkplug B data, use a host application instead (see Sparkplug B).
Subscriptions¶
A subscription set is a named configuration with a topic filter and a QoS, using a connection profile.
- Wildcards (
+and#) are supported in topic filters. - Subscriptions are durable. They are re-made automatically after every reconnect and survive any edit to the connection profile.
- A subscription that names a connection profile that does not exist yet reports
subscribed=falsewith an error until that profile is created, then starts receiving.
Shared subscriptions (MQTT 5)¶
On an MQTT 5.0 connection you can subscribe as part of a shared group with a filter of the form $share/<group>/<topic filter>. The broker load-balances the messages across all members of the group, so several gateways can split one stream of messages instead of each receiving all of it.
The managed tag provider¶
Subscribed topics appear automatically as tags in a tag provider that Sub manages. By default the provider is named MQTT, so tags appear under [MQTT].
| Setting | Where | Default | What it does |
|---|---|---|---|
tagProviderName |
Sub module settings | MQTT |
The name of the managed tag provider. Takes effect on the next gateway restart. |
tagFolder |
Each subscription | empty | The folder the subscription's tags go in. Leave it empty to mirror the topic path one-to-one under the provider. |
maxTagPathDepth |
Sub configuration | 64 levels | The deepest tag path Sub will create. |
maxTags |
Each subscription or host application | 10 000 | The most tags one subscription or host application may create. |
maxPayloadBytes |
Each subscription or host application | 8 MiB | Larger payloads are dropped before they are decoded. |
If the module settings cannot be loaded, Sub stops
If the Sub module settings resource cannot be loaded at startup, Sub faults (the cause is in the gateway log) rather than falling back to the [MQTT] provider name. Fix the settings resource (com.artek.mqtt.sub / settings) and restart the module.
One owner per tag path. If a second subscription or host application would write to a tag path that another already feeds, it is refused (counted, and logged once). Each tag has exactly one source.
Payloads to tags¶
Sub detects the payload type automatically:
| Payload | Result |
|---|---|
| JSON object | Expanded into member tags, including nested objects. |
| Single primitive value | One tag holding that value. |
| Anything else | Kept as a raw string. |
JSON nested too deeply to expand safely is kept as a raw string instead of failing.
Empty payloads. Clearing a retained message (publishing an empty retained payload) no longer breaks a JSON subscription's tags. The subscription setting emptyPayload controls how an empty payload is treated.
Tag quality¶
- When the connection to the broker is lost, the subscription's tags go Bad / stale rather than holding their last value as good.
- NaN and infinite values arrive with Bad quality.
Script callbacks¶
Each subscription can name a gateway script to run for every message it receives. The script gets the topic, the payload, the timestamp and, on MQTT 5, the message's user properties.
- Callbacks run on a thread the subscription owns, never on the thread that receives messages, so a slow script does not hold up message delivery or other subscriptions.
- Each run has a timeout and is interrupted when it expires. While a timed-out run is still executing, new runs for that subscription are dropped and counted.
- Payloads waiting for the script are capped by
maxScriptBacklogBytes(default 64 MiB) per subscription.
Sub has no system.* scripting functions of its own: subscriptions are configured, and the per-subscription callbacks cover scripting on the receive side.
Write-back¶
Write-back is off by default and enabled per subscription. When it is on, writing to one of the subscription's tags publishes the new value to MQTT. The publish happens off the tag-write thread, so a slow broker does not block tag writes.
Leave write-back off on any subscription whose tags should be read-only to Ignition users.