MQTT

Devices that publish through an external MQTT broker, in plain MQTT or Sparkplug B, with the broker modeled as the node every device under it shares, and the station's own data published to a broker.

The MQTT driver reads and writes the tags of equipment that publishes through an external MQTT broker: a gateway, a wireless sensor, a Node-RED flow, an edge node that speaks Sparkplug B. The station is a client of that broker: it subscribes to the topics its tags read and publishes the writes you make, and each broker can publish the station's own data, the tags, Logic variables and alarms listed on its Publish card, as JSON or in Sparkplug B. It is a client and not a broker, so the equipment and the station both connect to a broker: when you have none, the station's own MQTT broker can be that broker, and turning it on adds the broker This station to this driver; Installing a broker shows how to set up a separate one.

Every device behind a broker rides the same connection, so the topology is Driver → Broker → Device → Tag: the broker owns where it answers and how the station signs in, typed once; each device under it owns only how it publishes, Plain MQTT or Sparkplug B, and its tags. Both protocols live side by side under one broker. Values arrive by subscription, not by polling, so no MQTT device or tag has a poll interval.

The driver's page

The MQTT driver's page lists brokers instead of devices. The line under its header reads "Each broker is one connection to an external MQTT broker. Configure where it answers and how the station signs in, then add the devices that publish through it." The MQTT brokers table carries Add broker at the right of its title and one row per broker: Name, Address (mqtt://host:port, or mqtts://host:port over TLS, empty while the broker has no host), Devices, State (a dot and the broker's state with what its devices are doing, such as "Online · 2/2 devices online"), then Open and, for Configure connector, Enable, Disable and Delete. The empty table reads "No brokers yet." A broker that refused the station carries the tree's red marker after its name, and the page names under its header the brokers with an error ("1 broker with an error: Plant").

In the tree the driver row counts both levels ("1 broker · 2 devices"), and the page header shows the broker count in parentheses. In the column's New… menu the MQTT entry offers New broker, then each broker with its own New device and its devices, and right-clicking the driver row offers Add broker. The driver's bar has no Discover: a scan listens on one broker, so it lives on the broker's page. Once added, the driver stands under the Drivers folder of the tree, with or without a broker.

The broker

Add broker, New broker in the New… menu and the driver row's right-click menu create a broker named "New broker" (then "New broker 2") and disabled, so its connection is filled in before the station connects. The feed says so: "Added disabled broker 'New broker'. Enter where it answers, then enable it." The broker is not opened: it is marked in the MQTT brokers table of the driver's page, where the screen goes from New… or the right-click. Its page, reached by Open on its row or its row in the tree, carries the line "One MQTT broker: where it answers and how the station signs in to it. Every device under it shares this connection." and, in the header, the state, its dot and the address. Under the header, the broker's devices that have an error of their own are named ("1 device with an error: Pump"); while the broker itself has an error, its devices point to it instead: a device's page says "This device goes through broker Plant, which has an error. The broker's page says why."

The Broker connection card

Under the fields, a line says what the broker and its devices are doing, what the broker still lacks, and "Every device under this broker and what the station publishes to it share this connection: the session opens when the first enabled device or published row needs it." Every field stays editable while the broker is enabled. A saved change of where it answers, the transport, the sign-in, the client ID or the keep-alive reconnects the one session every device under the broker shares.

The command bar

Right-clicking a broker row offers Add device, Enable, Disable and Delete.

Broker states

The broker reports its session apart from its devices, in the tree row, in the driver's brokers table and in its own header:

The tree row reads the state and the device count ("Online · 2 devices"), and the summary under the card adds what the devices are doing: "Online · 2/2 devices online", "Online · 1 online · 1 with issues", "No session · no enabled devices". A Sparkplug B device that announced its death takes only itself off the air: the broker stays Online. The session speaks MQTT 5 and falls back to MQTT 3.1.1 for a broker that does not, starts clean, and reconnects by itself, waiting longer between attempts while the broker stays away.

The Discover devices card

Drawn only for Configure connector, under the line "Listens on this broker for a while: the Sparkplug B edge nodes and devices that announce themselves, and the topics under a filter."

Discover starts the scan and turns into Cancel while it runs. The line under the fields says what it will do ("Listens to 192.168.0.20:1883 for 10 s."), and the progress line counts the window ("Listening to 192.168.0.20:1883 · 4 of 10 s…"). The scan needs a host stored on the broker: until then the card says "Enter the broker's host and let the edit save before discovery." A pending edit on the broker is saved first; when it cannot be, nothing starts: "Discovery was not started because the broker edit could not be saved."

What a scan does on the broker:

• It connects under a client ID of its own, so it never pushes the devices' session off the broker, and it may run while the broker is enabled and in use.
• It subscribes to every Sparkplug B topic (spBv1.0/#) and to the topic filter. Sparkplug B birth certificates are not retained, so an edge node heard without one is asked to announce itself again (the Node Control/Rebirth command, the only message the scan publishes); an edge node that is running answers inside the window.
• Each edge node and each device behind it that announces itself (NBIRTH, DBIRTH) becomes a candidate with its metrics as tags, typed by what the birth declares. The edge node's own plumbing (bdSeq and the Node Control/… and Device Control/… metrics) is left out, and so are the metrics no tag reads (arrays, data sets, templates, property sets, bytes, files), counted under their reason. An edge node heard but not born within the window is offered with no tags.
• With a topic filter, the plain topics heard under it become one candidate of their own: each topic is a tag, or, for a JSON payload, each value inside it is one by its value path (up to 32 per topic, four levels deep, the first 8 elements of an array). A number is offered as Double, true or false as Boolean, anything else as String. The list stops at 500 topics. A topic whose publisher retains its last message is heard at once; any other only if it publishes during the window.
• Nothing is saved until you add a candidate. Cancel ends the window at once.

The results card, Discovered devices, lists Publishes as (group/edge node, with /device behind an edge node, or "Plain topics"), Device (the name to add it under, editable: the device or edge node ID, or the levels of the filter before its first wildcard), Result ("12 of 12 tags selected") and Add device, which creates the device under this broker with those tags. A Sparkplug B identity already configured on the broker reads "Already configured" and offers Open instead. A scan that heard nothing says "Nothing announced itself on this broker while the scan listened."

A device you already have finds what it does not read yet from its own page: Discover tags, on the head of its Tags card, listens on its broker for 10 s. A Sparkplug B device hears its own edge node alone, which is asked for its birth while no other edge node is asked anything; a plain device hears the topics under the levels its tags share (plant/oven/# for plant/oven/temperature and plant/oven/count), and every topic on the broker when they share none. Only the values it has no tag for yet are offered (see Discovering a device's tags).

The Devices card

"Each device reads plain topics, or one Sparkplug B edge node or device. The connection is inherited from the broker and cannot be changed here." Add device creates "New device" under this broker, enabled, in Plain MQTT, marked in this table and scrolled into view: "Added device 'New device' on 'Plant'." The table lists Device, Publishes as, Tags and Health, with Open, Enable, Disable and Delete on each row; empty, it reads "No devices configured on this broker." A device with an error of its own carries the tree's red marker after its name.

The Publish card

The last card publishes the station's own data to this broker, under the line "The station publishes each row to this broker as JSON on its topic whenever the value or its quality changes, and every row again each time the connection opens. The broker keeps the last message of each topic for whoever subscribes later. The station subscribes only to the write topic of each row set to Read and write." Viewing the Connector reads the card; configuring it changes it. The broker This station of the station's own MQTT broker carries the same card.

In Sparkplug B the line under the title says instead "The station is a Sparkplug B edge node on this broker: Logic variables and alarms are its own metrics, and each device with rows is a Sparkplug B device. It announces every metric when the connection opens and whenever the list changes, then publishes each value or quality that changes. Only a row set to Read and write takes a value from a command.", and under the fields Edge node ID (the station's name) shows the edge node it publishes as.

The table lists Source, Topic and Access, by topic; a row whose source is not chosen yet reads "No source yet". With none, it reads "Nothing is published to this broker yet. Add a row with New row." In Sparkplug B the Topic column is Metric: a tag after its device (Oven · Temperature), a variable or an alarm by its name on the edge node (Logic/Oven/Setpoint, Alarms/High). While the broker is disabled and the list has rows, a note says "The broker is disabled, so nothing is published until it is enabled." While a row of the broker is set to Read and write, a second note says "Rows set to Read and write take values published on their write topic. Anyone who can publish to this broker can change those sources, so the broker's username and password are their only guard." In Sparkplug B it says "Rows set to Read and write take values from Sparkplug B commands (NCMD, DCMD). Anyone who can publish to this broker can change those sources, so the broker's username and password are their only guard."

A row's fields are stored the moment they change:

Under the fields a line says what the row publishes:

Under that line, in JSON, a row set to Read and write shows its Write topic, the row's topic followed by /set. In Sparkplug B a second line names the metric the row is published as instead: of its Sparkplug B device for a tag, of the station's edge node for a variable, and for an alarm the five metrics under its name (Active, Acked, State, Priority and Message).

A change the list refuses is not stored: the reason is said in red above the row's fields, and the change stays on the screen so you can correct it.

What is published, and when, is on Publishing.

Device

The device has no host, port, credentials or poll interval of its own: all of that is the broker's. Each Sparkplug B ID is one topic level: "A Sparkplug B id may not contain '/', '+' or '#'." A broker names one Sparkplug B edge node or device once, so a second device with the same group, edge node and device IDs on that broker is refused: "Sparkplug B device Plant/Line1/Press1 on broker 'Plant' already belongs to device 'Press'." Plain devices name nothing of their own on the broker, and two of them may read the same topics.

The Base URI the header shows is the runtime address: mqtt://<broker id>?host=…&port=…&tls=0&keepAlive=60&clientId=…&mode=plain, with &silence=… when the device sets a maximum time without a message, and for a Sparkplug B device mode=sparkplug&group=…&node=…, with &device=… behind an edge node. It names the broker by its stable identity, never by its friendly name, and it never carries the username or the password.

A copy of an MQTT device stays on the same broker. A Sparkplug B copy takes the first identity no device on that broker has: its innermost ID, the device ID or, for the edge node's own metrics, the edge node ID, is numbered the way the copy's name is ("Press1 (2)").

Tag addressing

The address field is Topic on a Plain MQTT device and Metric on a Sparkplug B one, and it is required ("Topic is required for this driver."). A plain tag has three more fields; a Sparkplug B metric has none, because it carries its own type and is written by the protocol's own command.

The data types are Boolean, Int16, Int32, Int64, Float, Double, String and DateTime. The read-only preview of the wire address is the topic followed by what applies of path, command and payload (plant/line1/temperature?path=sensors[0].value&command=plant/line1/setpoint), or the metric name; a character that would end a part (%, ?, &, =, #, +, a space) is written as %XX.

Reading

The session keeps the last message of every topic it subscribed to, and a tag reads from it:

A Boolean tag takes true or false, 1 or 0, on or off. An integer tag takes a fractional number rounded and refuses one outside its range. A DateTime tag takes ISO 8601 text or Unix milliseconds. A String tag takes the text as it is, and a JSON object or array as its raw JSON. A Sparkplug B metric of an unsigned type reads into the next wider signed one (UInt8 as Int16, UInt16 as Int32, UInt32 and UInt64 as Int64), so its whole range reads.

Writing

A write goes through the same funnel as any other driver's: the write box takes the engineering value, and the conversion stages are reversed before the raw value is published (see Connector).

While the broker is unreachable, or the edge node or device has announced its death, a write is refused as disconnected and nothing is sent. A Sparkplug B write to a metric the birth certificate does not declare is refused, since the edge node would not take it, and so is a value the metric's type cannot carry. A write is never retained: a retained setpoint would be applied again by every subscriber that connects later.

Publishing

With Publication format set to JSON, each row of a broker's Publish card is published on its topic, retained, at QoS 1, through the connection the broker's devices use: the station never opens a second one to a broker. A broker used only to publish needs no device. It stays under the MQTT driver, and its state (Connecting…, Online, Unreachable) is the state of that connection. It publishes while it is enabled and its list has rows; it has no switch of its own.

A value travels as its JSON type: a number, true or false, text, a date and time as ISO 8601 text; a number JSON cannot hold (NaN, an infinity) travels as null. A tag of a disabled device publishes null and bad.

The station reads what it publishes and computes nothing for it: a tag's last reading, a variable's value, an alarm's state. It subscribes to no topic of a read-only row, so a message another system publishes there never reaches the station; a row set to Read and write takes values on its write topic (Writing back). An agent reads the lists with mqtt_publish_list and changes them with mqtt_publish_upsert and mqtt_publish_delete (Tools):

mqtt_publish_upsert(brokerId: "<id from mqtt_broker_list>", source: "Connector.Simulated.Oven.Temperature")
mqtt_publish_upsert(brokerId: "<id from mqtt_broker_list>", source: "Alarms.Oven.HighTemperature", topic: "plant/oven/alarms/high")
mqtt_publish_upsert(id: "<id from mqtt_publish_list>", access: "ReadAndWrite")
mqtt_publish_list()

Publishing in Sparkplug B

With Publication format set to Sparkplug B, the broker publishes the same list by the Sparkplug B specification, with the station as an edge node: a Sparkplug B host, Ignition's MQTT Engine for one, lists the station under its group and edge node, each device under it and every metric with its type, without any mapping built by hand. The connection is the one the broker's devices use, as in JSON.

A / inside one name becomes _, so the folders are the only levels. Two devices, or two metrics, whose names become the same take _2, _3 in the order of their own names. The rows keep their topics, which nothing is published on in Sparkplug B and which the list publishes on again when the broker goes back to JSON.

Every message goes out at QoS 0, never retained, except the NDEATH. The sequence number seq starts at 0 with each NBIRTH and counts every message after it up to 255, then starts again; bdSeq counts the connections, so the NBIRTH and the NDEATH of one connection carry the same number. Nothing waits in a queue while the broker is down.

A tag is published as its own type; a variable as the type the OPC UA server serves it as (a whole number as Int64, a real number as Double, a presentation value as text). Each metric carries its quality in the property Quality, the convention Sparkplug B hosts read: 192 good, 64 uncertain (with the value last published when the reading stopped arriving), 0 bad (the metric then has no value).

The station listens for commands to the edge node always, so a host can ask for a rebirth, and for commands to a device only while one of its rows is set to Read and write. Switching a broker to Sparkplug B makes its connection open again once, so the broker holds the edge node's last will; the broker's devices ride through it as through any reconnection. The station is an edge node and not a primary host application: it does not wait for a host's STATE message before it is born.

mqtt_broker_upsert(id: "<id from mqtt_broker_list>", publishFormat: "SparkplugB", sparkplugGroupId: "Plant1")
mqtt_publish_list()

Writing back

A row of a Publish card set to Read and write takes values on its write topic, the row's topic followed by /set: a cloud dashboard that reads plant/oven/setpoint sends a new setpoint on plant/oven/setpoint/set. The station writes it the way a client of its Modbus server or its OPC UA server writes a row marked read and write.

The journal records each write with the origin MQTT <broker name> under the Connector area, as it records an operator's write. A message that was not written is recorded under the Connector area and the component MQTT publication, once and then in a summary every few minutes while it repeats.

The broker's username and password are the only guard: whoever the broker lets publish on a write topic can change that source, and on a cloud broker shared with other people that is more than the plant. Give the dashboard's account on the broker only the topics it needs. On a broker set to Sparkplug B the same rows take Sparkplug B commands (NCMD, DCMD) instead of a write topic (Publishing in Sparkplug B).

"C:\Program Files\mosquitto\mosquitto_pub" -h localhost -u dashboard -P <password> -t plant/oven/setpoint/set -m 65

Security

With Use TLS, the broker's certificate is accepted in one of two ways: its chain and host name validate against the Windows certificate store, as any HTTPS connection of this computer does, or you approved that very certificate under Equipment access on this driver's page. A broker whose certificate comes from a certificate authority of your own is trusted once that authority is installed in the Windows store, and one with a self-signed certificate needs nothing installed once its certificate is approved. Revocation is not checked, and nothing accepts a certificate on sight: an unknown one is refused, the broker reads Unreachable with the reason, and its devices wait for the approval. The password travels inside the TLS connection; without TLS it travels in the clear, as the card warns.

Equipment access

A broker with a self-signed certificate, or one issued by an authority of its own, presents a certificate no root installed in Windows vouches for. That root does not need to be installed on this computer. With Use TLS, the first connection is refused, the broker reads Unreachable with the reason, its devices read Waiting for certificate approval in the tree and on their pages, whose Review certificate button opens this card on the certificate, and the certificate waits under Equipment access at the end of the MQTT driver's page, the same card the OPC UA driver's page carries, until you decide:

Check the fingerprint with whoever manages the broker before you approve it. An approval accepts that certificate and no other, and only within its validity dates; it stands in for the root Windows lacks and for the name the certificate carries, so a broker reached by its IP address connects although its certificate names another host, and nothing else about the certificate is relaxed. When the broker answers an address whose certificate you approved with another one, its devices stop reading, the new one waits here, and the station raises "Certificate changed: <name>" with a Review button. A scan of the broker from the Discover devices card meets the same decisions. A certificate Windows already trusts is accepted as before and never appears here; nothing is approved automatically.

The broker's cause says the reason instead of a nameless TLS error: "The certificate of the broker at <host>:<port> (the first 16 characters of the fingerprint) is waiting for your approval under Equipment access on the MQTT driver's page. Reading starts once you approve it." A blocked one reads "…is blocked at this station. Review it under Equipment access on the MQTT driver's page." A certificate outside its validity dates, revoked or with a broken signature is refused with that reason and is never listed, since no approval makes it sound.

The decisions are kept in the station's data folder, under ua\pki\mqtt, and survive a restart. Only a role that may configure the Connector is drawn the verbs, and they act only in the station's own window: a browser on another device reads the card without changing it, and no agent tool approves a certificate (connector_browse reports the broker's devices with awaitingCertificate). The list holds up to 100 certificates waiting for approval; once it is full, a new one is still refused but not listed, and the card says so.

Prepare the broker

A broker has to accept connections from the station's computer, and to accept the station's sign-in. Eclipse Mosquitto 2, the most common broker, does neither out of the box: with no listener in its mosquitto.conf it listens only on its own computer, and once it has one it refuses a client without a user name. MQTT does not say which broker answered, so the station names Mosquitto as the common case, never as a certainty.

The first two are said on the broker's page, in place of its English error, with these steps and the port; its devices keep pointing up to the broker. The notice goes away by itself once the session connects. The tree's mark and the journal keep the English cause, which ends with the same Mosquitto steps.

Installing a broker

The station needs a broker to connect to, and so does the equipment. Where you have none, Eclipse Mosquitto is a small broker that runs as a Windows service:

1. Download the Windows installer from the downloads page of mosquitto.org and run it. It installs the service Mosquitto Broker in C:\Program Files\mosquitto.

2. Out of the box Mosquitto answers only on the computer it runs on. To let equipment on the network in, add a listener and a password file to mosquitto.conf in that folder:

   listener 1883
   password_file C:\Program Files\mosquitto\passwd
   

   Create the file with the account the station and the equipment will use (the command asks for the password):

   "C:\Program Files\mosquitto\mosquitto_passwd" -c "C:\Program Files\mosquitto\passwd" station
   

3. Restart the service from an administrator prompt, and allow TCP port 1883 in through Windows Defender Firewall for the equipment's network:

   net stop mosquitto
   net start mosquitto
   

4. On the broker's page, enter localhost as Host when the broker runs on the station's own computer, or that computer's address otherwise, Port 1883 and the account you created, then Enable.

To try a plain tag before the equipment is connected, publish a retained test value from the same folder and point a tag's Topic at it:

"C:\Program Files\mosquitto\mosquitto_pub" -h localhost -u station -P <password> -t plant/line1/temperature -m 21.5 -r

Limits worth knowing

• The MQTT driver is a client, not a broker: the equipment and the station connect to a broker, the station's own MQTT broker or another one.
• A broker's Publish card goes out as JSON or as Sparkplug B, never both at once. In Sparkplug B the station is an edge node, not a primary host application, and uses no aliases, templates or historical values.
• The station is not a Sparkplug B host application: it publishes no STATE message. An edge node set to wait for a primary host before it publishes stays silent.
• Plain MQTT says nothing about a publisher that went quiet: a plain tag keeps the last value it received while the broker connection holds, dated by its arrival, unless its device sets a Maximum time without a message (s). A topic published only when its value changes cannot tell a quiet publisher from a steady value, so its device keeps 0. Sparkplug B does say it, through the death certificate.
• The session starts clean: what was published while the station was not connected is not replayed, and a topic's retained message is what gives its tag a value again.
• A tag reads one topic, never a filter, and one value of it; a Sparkplug B metric that is an array, a data set, a template or a property set is not read.
• Only TCP, with or without TLS: no MQTT over WebSockets, no client certificate, and no broker older than MQTT 3.1.1.
• A device cannot be moved to another broker: create it under the other broker and delete the old one.