MQTT Client

The MQTT client is designed in Lua and utilizes the Barracuda App Server socket API. The MQTT client enables business logic implemented in the Lua scripting language to communicate with other MQTT clients via an MQTT broker. The MQTT client can also be used for bridging MQTT clients with protocols such as HTTP, WebSockets, SMQ, etc.

Creating and operating an MQTT client is typically wrapped in a function as follows:

local function onpub(topic,msg) -- publish callback function
   trace("onpub",topic, msg) -- Print topic and payload data
end

local function connectAndRun(brokername)
   local mqttmodule = require"mqttc" -- Load MQTT Client
   local mqtt,err = mqttmodule.connect(brokername, onpub)
   if mqtt then
      mqtt:subscribe("#") -- Subscribe to all topics
      mqtt:run() -- Does not return unless the connection disconnects
   end
end

Example 1: Creating and running an MQTT client.

Code line 6 and 7 above can be optimized as follows:

local mqtt,err = require"mqttc".connect(brokername, onpub)

The MQTT client can operate in the three socket modes provided by the Barracuda App Server socket API: blocking, asynchronous, and cosocket mode. In most cases, the cosocket mode should be used. To start example 1 in cosocket mode, call function connectAndRun as follows:

ba.socket.event(function() connectAndRun(brokername) end)

Example 2: Starting example 1 in cosocket mode.

API for creating an MQTT Client

connect(addr, callback [, op])

Creates and connects an MQTT client instance:
mqtt,err=require"mqttc".connect(addr, callback [, op])

Returns mqtt-object | nil,err - function 'connect' returns an MQTT object if the connection was successful. The function returns nil,error if the connection fails. The error message can be any of the socket error messages, any of the error codes from socket:trusted() if the connection is secure, the string "invalidresp" if the client is unable to decode the response and the following MQTT broker response error codes (number):

If the connection is secure (a SharkSSL object is provided), the server's trust status is validated by calling socket:trusted() if a username or password is provided. The client will not send any credentials to the broker if the broker's certificate is not trusted. The server's trust status is not validated if no credentials are provided, thus you may connect to a non trusted server if no credentials are provided.

The following example shows how to connect using TLS, how to use credentials, and how to provide an MQTT will message:

local mqtt,err = require"mqttc".connect("mybroker.com", onpub, {
   shark = mako.sharkclient(),
   port = 23922,
   keepalive = 5*60, -- 5 minutes
   id = "my-unique-id",
   uname = "admin",
   passwd = "qwerty",
   will = {
      topic = "whoops",
      message = "Someone unplugged my cable!"
   }
})

Example 3: Connecting to a secure broker.

The above example is designed for the Mako Server since the example uses the ready to use SharkSSL object returned by function mako.sharkclient(). You must create your own SharkSSL object and populate the certificate store in the SharkSSL object if you are not using the Mako Server.

MQTT Object Methods

mqtt:publish(topic, msg)

Publish a message.

mqtt:subscribe(topic [, callback])

Subscribe to a topic.

mqtt:unsubscribe(topic [, callback])

Unsubscribe from a topic.

mqtt:disconnect()

Gracefully disconnect from the broker.

mqtt:run()

Run the MQTT socket dispatch loop. This function does not return unless the connection disconnects. The function returns nil,error and the error message can be any of the socket error messages, the string "disconnect" if the connection was gracefully disconnected by calling mqtt:disconnect(), and the string " pingresp" if an MQTT PINGRES was not received when the client sent an MQTT PINGREQ.

The dispatcher loop is preferably called from within a cosocket, but can also be called from a dedicated thread.