MQTT driver

14 min readCommunication

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

When to use it

The MQTT driver turns Live into an MQTT 3.1.1 or MQTT 5.0 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. The Demo Project has no MQTT connection.

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.
If the server requires a client certificate (mutual TLS), prepare a client certificate (with its private key) for Live.
Find out the topic names that the devices publish and the payload format (plain value or JSON).

Setting up a connection

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).
Enter the parameters
123456
A connection with MQTT 5.0, TLS and a client certificate from a PFX file selected; the Target card shows the mqtts:// address.
1. MQTT version — 3.1.1 or 5.0.
2. Security — the client certificate is used only with TLS.
3. Client certificate — None, PFX file or Windows certificate store.
4. PFX file — full path on the Live computer; its password is entered in Live.
5. Certificate thumbprint — for the certificate in the store (40 hexadecimal characters).
6. Target — mqtts:// if TLS is selected.
MQTT version
MQTT 3.1.1 (default) or MQTT 5.0 (below).

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

Client certificate
None (default), PFX file or Windows certificate store. Used only with TLS (below).

PFX file
Full path on the Live computer (e.g. C:\Sertifikalar\istemci.pfx). Its password is entered in Live.

Certificate thumbprint
Thumbprint of the certificate in the Windows certificate store (40 hexadecimal characters; spaces and : are allowed).

Authentication
Anonymous or User name and password. Can also be used together with a client certificate.

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.
Add a tag
Enter the topic name as the tag address (Tag addresses).

Topic addresses

Address	Meaning
`fabrika/hat1/sicaklik`	The whole payload is the value of the tag (number, `true` / `false`, `on` / `off`, text, ISO date).
`hat1/durum#motor.hiz`	The payload is a JSON document; the tag is the value inside the document (`#` separates the topic from the JSON path).
`hat1/olcumler#deger[2]`	Element of the JSON array (the index starts at 0).
`cihaz/role/durum\|cihaz/role/komut`	Read and write use separate topics (separated by `\|`).

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.

MQTT 5.0

When MQTT 5.0 is selected in MQTT version, the topic addresses, QoS and write behavior stay the same. Differences:

Clear rejection messages. The reason code with which the server rejects a connection, subscription or publication is translated into a plain-language message (e.g. The MQTT broker rejected the subscription to this topic (not authorized): hat1/durum). If the server also sends an explanatory text, it is appended to the message as Broker message: "…". An unknown code is written in hexadecimal (such as 0xA5).
The server's limits are applied. If the server announces its own keep-alive interval, that interval is used; if its maximum QoS is 0, writes are sent with QoS 0. If the server does not support retained messages, writes on a connection with Keep written message on the broker switched on are rejected; a publication that exceeds the server's maximum packet size is not sent.
Redirection is not followed. If the server redirects the connection to another server, the message states the new address; you change the address of the connection yourself.
If the server does not support MQTT 5.0, the connection is not established and the message The MQTT broker does not support MQTT 5.0. Select 3.1.1 as the MQTT version in the connection parameters. is shown.

Client certificate (mutual TLS)

Some servers require a certificate from the connecting client. The certificate is presented in the TLS connection; it can be used with MQTT 3.1.1 and 5.0. While Security is None, the selected certificate is not used and Studio gives a warning in Problems.

Option	How to prepare it
PFX file	Place the certificate together with its private key as a `.pfx` / `.p12` file on the Live computer and enter its full path in PFX file. Enter the password of the file in Live via system menu › Connections › Enter password; the password is not written to the project file (Connection security).
Windows certificate store	Import the certificate with its private key into the Personal store and enter its thumbprint in Certificate thumbprint. The Personal store of the user who runs Live is searched first, then that of the local computer. This user must have permission to read the private key.

In a redundant server pair, the PFX file must be at the same path on both computers and the password must be entered on both.

Driver reference

MQTT

MQTT 3.1.1 / 5.0 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.

Parameter	Type	Default	Description
MQTT version	choice	MQTT 3.1.1	MQTT 3.1.1 · MQTT 5.0
Security	choice	None (unencrypted)	For TLS the port is usually 8883. For servers that use a self-signed certificate, add the certificate to Windows as trusted; "not verified" should be used only in closed networks. None (unencrypted) · TLS (server certificate is verified) · TLS (certificate is not verified)
Client certificate	choice	None	If the server requires a client certificate (mutual TLS). Used only with TLS. None · PFX file · Windows certificate store
PFX file	text	—	Full path on the Live PC (e.g. C:\Certificates\client.pfx). Its password is not written to the project file; it is entered on the Live PC.
Certificate thumbprint	text	—	Thumbprint of the certificate in the Windows certificate store (40 hexadecimal characters). It is searched in the Personal store of the current user first, then of the local computer; the certificate must have its private key.
Authentication	choice	Anonymous	Anonymous · User name and password
User name	text	—	The password is not written to the project file; it is entered on the Live PC.
Client ID	text	—	If empty, it is generated automatically (fv-computer-connection). When two clients connect with the same ID, the broker drops the older one.
Subscription quality (QoS)	choice	QoS 0 — at most once	QoS 0 — at most once · QoS 1 — at least once
Write quality (QoS)	choice	QoS 1 — waits for the broker's acknowledgement	QoS 0 — no reply is awaited · QoS 1 — the server's acknowledgment is awaited
Keep written message on the broker (retain)	on / off	off	The written message is stored on the broker and sent immediately to clients that subscribe later.
Bool write format	choice	true / false	true / false · 1 / 0 · ON / OFF
Keep-alive interval (s)	number (0 – 3600)	`30`	On a quiet connection a ping is sent to the broker at this interval; if nothing arrives for 1.5 times that time, the connection is considered lost. 0 = off.
Arbiter address (Int)	text	—	In a redundant server pair the master writes an incrementing counter to this address every second. It must be a writable Int address not used for anything else in the PLC program. Empty = this PLC is not an arbiter.

Address formats

Format	Meaning
`topic`	The whole payload is the tag value (number, true / false, on / off, text, ISO date)
`topic#alan.altalan`	The payload is a JSON document; the tag is a value inside the document
`topic#dizi[2].alan`	Element of a JSON array (the index starts at 0)
`readTopic\|writeTopic`	Read and write on separate topics (e.g. status \| command)

Sample addresses

Data type	Examples
`Bool`	`cihaz/role/durum` `cihaz/role/durum\|cihaz/role/komut` `hat1/durum#motor.calisiyor`
`String`	`hat1/urun` `hat1/durum#ad`
Other types	`fabrika/hat1/sicaklik` `hat1/durum#motor.hiz` `hat1/olcumler#deger[2]`

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 or in the Problems list. [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.

Message	Cause and solution
[connection] `MQTT sunucusu 2000 ms içinde yanıt vermedi (…). Adresi, portu ve ağ bağlantısını kontrol edin.`	The server cannot be reached.
[connection] `The MQTT broker rejected the user name or password. Check the user name in the connection parameters and the password in the connection password window in Live.`	The user or password is wrong; the password may not have been entered in Live.
[connection] `MQTT sunucusu bu istemcinin bağlanmasına izin vermedi (yetkisiz). …`	There is no access definition on the server for this user or client.
[connection] `MQTT sunucusu istemci kimliğini reddetti (kimlik geçersiz ya da başka bir istemci aynı kimlikle bağlı). …`	Change the Client ID.
[connection] `MQTT sunucusu MQTT 5.0'ı desteklemiyor. …`	Set MQTT version to 3.1.1.
[connection] `MQTT sunucusu bağlantıyı kapattı: aynı istemci kimliğiyle başka bir istemci bağlandı (oturum devralındı). …`	MQTT 5: another client is using the same ID; change the Client ID.
[tag] `MQTT sunucusu bu konuya aboneliği reddetti (kullanıcının bu konuyu okuma yetkisi olmayabilir): konu`	The user has no permission to read that topic. In MQTT 5, the broker's reason is shown in parentheses.
[connection] `Sunucu sertifikasına bu bilgisayar güvenmiyor (kendinden imzalı ya da bilinmeyen sertifika otoritesi). …`	Add the certificate to Windows as trusted; select TLS (certificate is not verified) only in closed networks.
[connection] `Sunucu sertifikasının adı "…" ile uyuşmuyor (adres olarak IP yerine sertifikadaki bilgisayar adını yazın …).`	Enter the name in the certificate as the address.
[connection] `… (Sunucu istemci sertifikası istiyor: bağlantı parametrelerinde "İstemci sertifikası" seçin.)`	The server requires mutual TLS; define a client certificate.
[connection] `… (Sunucu istemci sertifikasını kabul etmedi: sertifikayı veren otorite sunucuda güvenilen olarak tanımlı olmalı.)`	The certificate authority is not defined on the server; if the certificate has expired, the message states the date.
[connection] `PFX dosyası parola istiyor ama parola girilmemiş. …` · `PFX dosyasının parolası yanlış. …`	Enter the password in Live via system menu › Connections › Enter password.
[connection] `İstemci sertifikasının PFX dosyası bulunamadı: …` · `PFX dosyasının tam yolu yazılmalı (ör. C:\Sertifikalar\istemci.pfx): …`	The path is wrong or the file does not exist on this computer.
[connection] `PFX dosyasında özel anahtarlı sertifika yok: …`	Export the certificate together with its private key.
[connection] `Windows sertifika deposunda bu parmak izli sertifika bulunamadı (…): …` · `Windows sertifika deposundaki sertifikanın özel anahtarı yok (…).`	Check that the thumbprint and the store (Personal) are correct; import the certificate as PFX together with its private key.
[connection] `İstemci sertifikasının özel anahtarına erişilemiyor (Live'ı çalıştıran Windows kullanıcısının anahtarı okuma izni olmalı): …`	Add the user who runs Live to the private key permissions of the certificate.
[tag] `"…" Bool olarak okunamıyor (true / false, 1 / 0, on / off, yes / no beklenir).` · `"…" bir sayı değil; Int olarak okunamıyor.`	The format of the payload does not match the tag type.
[tag] `Yük geçerli bir JSON belgesi değil (…). Adreste "#yol" yazdıysanız yük JSON olmalıdır.` · `JSON yolu "…" yükte bulunamadı (… alanı yok).`	The payload is not JSON, or the path is not in the document.
[write] `The MQTT broker did not acknowledge the publish (no PUBACK received).`	The server did not acknowledge the publish while the write quality was QoS 1.
[write] `MQTT sunucusu tutulan mesajı (retain) desteklemiyor: …`	The MQTT 5 broker does not accept retain; turn off Keep written message on the broker.
[Studio] `A client certificate is selected but security is "None": the certificate is used only with TLS.`	Warning: set Security to TLS or set the certificate to None.