MQTT_STATUS (n)
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:

  1. Connection FAILED. Not connected to broker           
    • MQTT_STATUS(1) = -1
    • MQTT_STATUS(2) = 0  
  2. Connection COMPLETED. Connected to brokder
    • MQTT_STATUS(1) = 1
    • MQTT_STATUS(2) = 1  
  3. Lost Connection. Previous connection was lost involuntarily               
    • MQTT_STATUS(1) = -1
    • MQTT_STATUS(2) = -1
  4. Reconnected to broker         
    • MQTT_STATUS(1) = 1
    • MQTT_STATUS(2) = 2 
  5. 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:
  1. MQTT_DISCONNECT.  
    • MQTT_STATUS(1) = 2
  2. MQTT_PUBLISHED    
    • MQTT_STATUS(1) = 3
  3. MQTT_SUBSCRIBED   
    • MQTT_STATUS(1) = 4
  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
See Also MQTT_CONNECT, MQTT_DISCONNECTMQTT_PUBLISH, MQTT_SUBSCRIBE, MQTT_UNSUBSCRIBE

backbutton.gif (507 bytes)  Basic to TBASIC Reference Manual