Skip to main content


Register a handler for completed connections




Name Type Description
callback Function Optional function to be called upon completion of a connection attempt




This method allows you to register a function that will be called whenever an attempt to connect to an MQTT broker (see mqttclient.connect()) completes, whether successfully or not.

The provided function must have one parameter of its own: resultCode. This will be passed an integer indicating the state of the connection:

Value Description
-1 Socket error: an incorrect URL/port/firewall/SSL issue, etc.
0 Success: the connected was accepted
1 Connection refused: the server does not support MQTT 3.1.1
2 Connection refused: the client ID was rejected
3 Connection refused: the server is unavailable
4 Connection refused: an incorrect username or password was provided
5 Connection refused: access was not authorized for some other reason

Only one callback function may be registered at any one time. To clear a previously registered callback, either provide a new function, or pass in null.

Note Inbound and Outbound MQTT requests and messages are subject to rate limits.

Example Code

The following code sets up an MQTT client and connects to the specified MQTT broker. The outcome of the connection attempt is handled by the function registered using mqttclient.onconnect(): it checks the value passed into resultCode and reports accordingly. If the connection is made, the code attempts to subscribe to a topic.

const URL  = "tcp://";
const PORT = 1883;
const UN   = "generalgrugger";
const PW   = "gaztakh1ghc0mmand";

local client = null;
local cid = "imp.mqtt.test." + imp.configparams.deviceid;

function error(code) {
    switch (code) {
        case -1: return "Socket Error";
        case 1:  return "Unsupported MQTT version";
        case 2:  return "Client ID rejected";
        case 3:  return "Server unavailable";
        case 4:  return "Invalid username/password";
        case 5:  return "Not authorized";
        default: return "Unknown error";

function onMessage(message) {
    // Called on receipt of a message
    server.log("Message \'" + message.message + "\' received under topic \'" + message.topic + "\'");

function onConnect(resultCode) {
    // Called when the client connects (or fails to connect) to the MQTT broker
    local s = URL + ":" + PORT.tostring();
    if (resultCode == 0) {
        server.log("Connected to " + s);

        // We're connected to try to subscribe to a topic
                         function(qosMode) {
                             // This is the subscription acknowledgement callback
                             if (qosMode != 0x80) {
    } else {
        server.error("Failed to connect to " + s + ". Error: " + error(resultCode));

// Instance an MQTT client
client = mqtt.createclient();

// Set up the initial handlers

// Connect with credentials
local options = {};
options.username <- UN;
options.password <- PW;
client.connect(URL + ":" + PORT.tostring(), cid, options);