mqttOpen (Function)

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.

Prior to communicating with the server, the network interface connection must be established. For example by using gsmPower and gprsOpen for Mobile network, or netOpen for LAN network.
 

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").

Input:

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.

Returns: INT

Handle of the MQTT connection.

Declaration:

FUNCTION mqttOpen : INT;
VAR_INPUT
  ip             : STRING;
  port           : DINT;
  iface           : SINT;
  username       : STRING;
  password       : STRING;
  clientid       : STRING;
  keepalive       : INT := 600;
  clean           : BOOL;
  lwt_topic       : STRING;
  lwt_message     : STRING;
  lwt_retained   : BOOL;
  lwt_qos         : SINT;
  useTLS         : BOOL;
  tls_certificate : STRING;
  tls_password   : STRING;
END_VAR;

Example:

INCLUDE rtcu.inc
 
VAR
  mqtt : INT;
  text : STRING;
END_VAR;
 
PROGRAM example;
 
  gsmPower(power := ON);
  gprsOpen();
 
BEGIN
  ...
  // Connect to MQTT server
  IF mqtt < 1 AND gprsConnected() THEN
     text := strFormat(format := "RTCU_\4", v4 := boardSerialNumber());
     mqtt := mqttOpen(ip := "test.mosquitto.org", port := 8883, clientid := text, useTLS := TRUE);
    IF mqtt < 0 THEN
        DebugFmt(message := "Could not connect to MQTT server (errno=\1)", v1 := mqtt);
    ELSE
        DebugMsg(message := "Connection opened");
    END_IF;
  END_IF;
  ...
END;
END_PROGRAM;