|Top Previous Next|
This function will initiate a connection to a MQTT server. When this function returns, the connection may not be finally established. The establishing of the connection must be determined by using the mqttConnected() function.
The function must return a valid handle before any other MQTT functions can be called. The handle will no longer be valid after calling the mqttClose() function, and can no longer be used with MQTT functions.
A valid handle is an integer value in the range 1 and 32767.
When the MQTT connection is opened, there is no need for further intervention from the VPL program to keep the connection up. If, for some reason, the MQTT connection terminates, the firmware will automatically reconnect and establish the MQTT connection again.
Although the interface is prepared for multiple simultaneous MQTT connections the current implementation is limited to a single connection.
Using secure connection
For NX32L devices a secure TLS (TLS v1.2, v1.1 or 1.0) connection can be established assuming that a matching X509 certificate(s) is present.
To use server verification:
1. Ensure the root certificate needed to verify the MQTT server is present.
2. Set 'useTLS := TRUE' and 'port' according to server configuration (standard for secure connections is 8883) when calling mqttOpen.
If client verification is required by server then:
1. Ensure the client certificate needed to verify the device is present.
2. Set 'tls_certificate' and 'tls_password' according to the installed client certificate when calling mqttOpen.
Using Unicode strings
Support for Unicode strings are included in the MQTT API so that text (topics, username, etc.) can be in the local language rather than in English.
The problem with Unicode strings is that only the navigation API and the MQTT API supports Unicode directly.
While it is not possible to enter Unicode text directly into a string variable, it can be done as a string of special characters (see STRING).
This approach requires 3 steps for each character:
1. Find the character at the Unicode homepage (www.unicode.org).
2. Encode the character into UTF-8 (Wikipedia gives a good description of this here: en.wikipedia.org/wiki/Utf-8).
3. Type in the special characters from step 2 (e.g. "$CF$86" for the Greek character "phi").
ip : STRING
The IP address of the MQTT server.
port : DINT (default 1883)
The port where the MQTT server listens for clients
iface : SINT (default 0)
The network interface to use. 0 = Default network, 1 = Mobile network, 2 = LAN network, etc. (See Network)
Note: For backwards compatibility the Mobile network is used as default network.
username : STRING
The user name required to connect to the server.
password : STRING
The password required to connect to the server.
clientid : STRING
The id to use when connecting to the server.
keepalive : INT (30..30000, default 600)
Frequency for sending a ping to the server in seconds.
clean : BOOL
If TRUE the server will clear old information about client, if FALSE the old information is kept.
lwt_topic : STRING
The topic where the Last Will and Testament (LWT) is published.
Leave this empty to disable LWT.
lwt_message : STRING
The message that is published with the LWT.
Minimum length is 1 character if lwt_topic is not empty.
lwt_retained : BOOL
If TRUE the LWT will be retained on the broker, if FALSE it is not.
lwt_qos : SINT (0..2)
The QoS used to publish the LWT.
useTLS : BOOL
tls_certificate : STRING
The client certificate if required by the broker.
tls_password : STRING
The password for the client certificate.
Handle of the MQTT connection.
FUNCTION mqttOpen : INT;