MQTT driver

Connecting to an MQTT server (broker) and receiving tag values by subscribing to topics, sending tag writes to a topic as a publish; TLS, user / password, QoS and JSON field addresses.

When to use it

The MQTT driver turns Live into an MQTT 3.1.1 client. Live connects to the server (broker) and subscribes to the topics of the tags; the last message published to a topic becomes the value of that tag. Writing to a tag means publishing the value to the topic. Devices, gateways and IoT systems usually share data this way.

This driver is new and has no connection in the demo project. It has not been tried in the field with a real MQTT server.

Prerequisites on the server side

• The MQTT server must be reachable from the Live computer (default port 1883, usually 8883 with TLS).
• If authentication is used, a user must be defined on the server and the user must have read / write permission. Without permission, the server rejects the subscription.
• Find out the topic names that the devices publish and the payload format (plain value or JSON).

Setting up a connection

1. Add a connection

   In the Connections section: Add, driver MQTT; enter the address of the server, and port 1883 is filled in. If you use TLS, set the port to 8883 or paste the address in the form mqtts://sunucu:8883 (security switches to TLS).

2. Enter the parameters

   

   Security

   None (unencrypted), TLS (server certificate is verified) or TLS (certificate is not verified). TLS 1.2 is used.

   Authentication

   Anonymous or User name and password.

   User name

   The password is not written to the project file; it is entered in Live (Connection security).

   Client ID

   If empty, it is generated automatically in the format fv-<bilgisayar>-<bağlantı>. If two clients connect with the same ID, the server disconnects the older one.

   Subscription quality (QoS)

   QoS 0 — at most once (default) or QoS 1 — at least once.

   Write quality (QoS)

   QoS 0 — no response is awaited or QoS 1 — the server's acknowledgment is awaited (default).

   Keep written message on the broker (retain)

   If on, the published message is stored on the server and sent immediately to clients that subscribe later. Off by default.

   Bool write format

   true / false (default), 1 / 0 or ON / OFF.

   Keep-alive interval (s)

   0 – 3600, default 30. On a connection that stays silent, a ping is sent to the server at this interval; if nothing arrives within 1.5 times that time, the connection is considered lost. 0 = off.

3. Add a tag

   Enter the topic name as the tag address (Tag addresses).

Topic addresses

• A topic does not contain wildcard characters (+, #); a tag is the value of a single topic. The topic and the JSON path are case-sensitive. The write topic cannot start with $.
• A JSON path consists of field names separated by dots and array indexes (motor.hiz, dizi[0].alan); the leading $. is optional; at most 16 steps.

Read and write behavior

• Reading: the driver subscribes to each topic once. The server sends the retained message to the subscription immediately. The tag of a topic for which no message has been published yet does not raise an error; it waits until a value arrives (it appears without a valid quality).
• Value conversion: for Bool, true / false / 1 / 0 / on / off / yes / no are read. A value that does not fit the tag type is not truncated; the tag gets an error. For DateTime, ISO 8601 or Unix seconds / milliseconds are accepted. The payload is UTF-8 text; a payload larger than 1 MB is not read.
• Write: the value is published to the write topic of the tag. If it is the same as the read topic, the value is also applied to the tag without waiting for it to return from the server. If the connection is lost, the write is rejected.
• Writing a JSON field: only the relevant field of the document last received on the topic is changed; the other fields are kept. If there is no document on the topic yet, or if the write topic is separate and the previous document is not known, a new document containing only that field is published.

Driver reference

MQTT

MQTT 3.1.1 client: Live connects to the broker, subscribes to the tags' topics and uses the latest message received as the tag value; a write is published to the topic. The address is a topic (e.g. factory/line1/temperature); if the payload is JSON, select the field inside it with "topic#path"; if the read and write topics differ, write "read|write".

Driver ID

mqtt (name in the project file)

Connection

An IP address / computer name and a port are required (default port 1883)

Data types

Bool Byte SInt Int UInt DInt UDInt Real LReal String DateTime

Same address

Multiple connections can be defined to the same address.

Connection parameters

Appears in the Inspector window when a connection is selected.

Address formats

Sample addresses

Common errors

The marker at the start of each line tells where the message will appear in Live: [connection] in the Connections section of the system menu; [write] in the notification window of the operator who performed the write; [Studio] in the address cell in Studio. [tag] is a tag error during reading: the tag is left with bad quality, the text of the message is not shown in Live in this version (Tag errors); read the text to understand the cause.

Limits