MQTT_STATUS

(only available on Wx PLC firmware >= F94.2)

Purpose

Return the status of MQTT publish, subscribe, and connection events, as well as the status of a MQTT client connection to a broker (server).

Details

There are two valid MQTT_STATUS parameter values; ie. 1 (for event status) and 2 (for connection status).

The value returned by MQTT_STATUS(1) or MQTT_STATUS(2) is an integer that could negative, zero, or positive. Each return value corresponds to the state and circumstances of a MQTT event or connection.

The possible return values for these MQTT_STATUS function parameter values are specified below.

Function

Returned value

MQTT_STATUS (1)

Used to check the status of a MQTT event (publish, subscribe, data received, or connection).

1 = Successfully connected or reconnected to the broker via MQTT_CONNECT
-1 = Connection failure or lost connection

2 = Disconnected from broker following a MQTT_DISCONNECT command
-2 = Disconnect failed

3 = *Publish to broker successful following a MQTT_PUBLISH command
-3 = *Publish command failed
*(applies to QOS 1 or 2 only)

4 = Subscription to topic successful following a MQTT_SUBSCRIBE command
-4 = Subscribe command failed

5 = Unsubscribe from topic successful following a MQTT_UNSUBSCRIBE command
-5 = Unsubscribe failed

Example :

DM[1] = MQTT_STATUS(1)

IF DM[1] = 1 ' connected

ELIF DM[1] = -1 'not connected

ELIF DM[1] = 2 'disconnected cleanly

ELIF DM[1] = -2 'disconnect failed

ENDIF

MQTT_STATUS (2)

Used to check the status of a MQTT client connection to a broker (server).

0 = Not connected. Connection attempt failed following a MQTT_CONNECT command

1 = Successfully connected to the broker following a MQTT_CONNECT command
-1 = Lost connection involuntarily (eg. Internet connection lost at the client or broker side)

2 = Reconnected to the broker automatically

No Change = Incoming message received (ie. from a subscription)

Example :

DM[2] = MQTT_STATUS(2)

IF DM[2] = 1 OR DM[2] = 2 ' connected to broker

IF DM[2] = 2 'reconnected to broker automatically

ENDIF

ELIF DM[2] = -1 'connection to broker was lost

ENDIF

When making a connection via MQTT_CONNECT, a callback function is specified that can be programmed to handle various MQTT events and status updates.

Callback function is invoked in the following events:

Connection FAILED. Not connected to broker

MQTT_STATUS(1) = -1
MQTT_STATUS(2) = 0

Connection COMPLETED. Connected to brokder

MQTT_STATUS(1) = 1
MQTT_STATUS(2) = 1

Lost Connection. Previous connection was lost involuntarily

MQTT_STATUS(1) = -1
MQTT_STATUS(2) = -1

Reconnected to broker

MQTT_STATUS(1) = 1
MQTT_STATUS(2) = 2

Message arrived. Broker sent a message related to a topic from an existing subscription

MQTT_STATUS(1) = 10
MQTT_STATUS(2) = No change

Callback function is not invoked:

Successful MQTT_DISCONNECT, MQTT_PUBLISH, MQTT_SUBSCRIBE and MQTT_UNSUBSCRIBE. These commands briefly block the PLC until completion or until an error occurred. Only MQTT_STATUS(1) is updated, and MQTT_STATUS(2) is NOT affected.

Command successfully completed:

MQTT_DISCONNECT.

MQTT_STATUS(1) = 2

MQTT_PUBLISHED

MQTT_STATUS(1) = 3

MQTT_SUBSCRIBED

MQTT_STATUS(1) = 4

MQTT_UNSUBSCRIBED

MQTT_STATUS(1) = 5

Note: DISCONNECT is not the same as LOST_CONNECTION, the former is voluntary termination of connection and will not result in auto-reconnection. The latter is an involuntary loss of connection. MQTT_STATUS(1)= 2 only after a voluntary MQTT_DISCONNECT command.

Command failed:

The following are values returned by MQTT_STATUS(1) after the command is run:

MQTT_DISCONNECT failed: : -2
MQTT_PUBLISH failed : -3
MQTT_SUBSCRIBE failed : -4
MQTT_UNSUBSCRIBE failed : -5

Note that the only time when MQTT_STATUS(1) = -1 is when connection failed or if there is a lost connection, and this is handled in the callback function.

Examples

' Here we use DM[1] and DM[2] to store the MQTT statuses for easy online viewing.
' You can define other memory location for this purpose

#DEFINELOCAL EVENT_TYPE = DM[1]
#DEFINELOCAL NETWORK_STATUS = DM[2]
#DEFINELOCAL RECEIVE_COUNTER = DM[3]
#DEFINELOCAL MQTT_STATUS_MSG_ARRIVED = 10

#DEFINELOCAL MQTT_LOST_CONNECTION = -1
#DEFINELOCAL MQTT_CONNECTED = 1
#DEFINELOCAL MQTT_RECONNECTED = 2

EVENT_TYPE = MQTT_STATUS(1)
NETWORK_STATUS = MQTT_STATUS(2)

IF EVENT_TYPE = MQTT_STATUS_MSG_ARRIVED   ' message of a subscribed topic arrived
   A$ = MQTT_TOPIC$(1)
   B$ = MQTT_DATA$(1)
                       ' send message to "System & User Log"
   PRINT #7 "MQTT Topic="+ A$
   PRINT #7 "MQTT Data=" + B$
   RECEIVE_COUNTER = RECEIVE_COUNTER + 1
   DRAW_TEXTPOS 0,12,"Received #" + STR$(RECEIVE_COUNTER)+"       "
   RETURN
ELSE
   IF EVENT_TYPE < 0    ' ERROR in previous operations
       SETIO rMQTT_Err
       ERROR_COUNT = ERROR_COUNT + 1
   ELSE
       CLRIO rMQTT_Err
   ENDIF

   ' Now check the network connection status. It is either "not connected", "lost connection", "connected" or
   ' "reconnected". These 4 statuses are mutually exclusive
   '--------------------------------------------------------------------------------------------------------
   CLRIO rLostConnect
   CLRIO rConnected
   CLRIO rReconnected

   ' Connection lost event.
   IF NETWORK_STATUS = MQTT_LOST_CONNECTION
       SETIO rLostConnect

   ' Normal connection event.
   ELIF NETWORK_STATUS = MQTT_CONNECTED
       SETIO rConnected

   ' Reconnection event occurred. Here we indicate it as a separate event from rConnected although you could
   ' combine the two events into a single rConnected instruction. Separating the two events give you a chance
   ' to handle "connected" and "re-connected" events differently if you wish.
   ELIF NETWORK_STATUS = MQTT_RECONNECTED
       SETIO rReConnected
   ENDIF

ENDIF