Skip to main content





Note MQTT is currently available as a public beta release and so is not available to all agents. Agents without access to the beta will throw the error the index ‘mqtt’ does not exist. To make use of MQTT, please sign up here to request access to the beta program. You will also need to sign up if you wish to use our Azure IoT Hub MQTT integration, which is also currently in public beta.

The mqtt object provides agent code with a means to initiate and maintain communication using MQTT, a lightweight publish/subscribe messaging protocol with an emphasis on Internet of Things applications

Note The mqtt object only supports connections to MQTT brokers based on MQTT 3.1.1 only. Details of version 3.1.1 of the specification, on which the Electric Imp implementation is based can be found here.

The connection to a chosen MQTT broker is handled by an mqttclient object, and it is through this object that topic subscriptions are managed, and messages are received and created. Messages are published by calling either of the mqttmessage object’s own send methods:

MQTT Error Codes

Electric Imp’s implementation of MQTT is currently based on Paho which defines the following errors and code values that may be returned by mqtt methods. However, this may change in the future, so do not write agent code that depends on particular values having particular meanings.

MQTT Error Error Code Description
MQTTASYNC_SUCCESS 0 No error. Indicates successful completion of an MQTT client operation
MQTTASYNC_FAILURE -1 A generic error code indicating the underlying socket has failed
MQTTASYNC_PERSISTENCE_ERROR -2 An MQTT asynchronous persistence error
MQTTASYNC_DISCONNECTED -3 The client is disconnected
MQTTASYNC_MAX_MESSAGES_INFLIGHT -4 The maximum number of messages allowed to be simultaneously in-flight has been reached
MQTTASYNC_BAD_UTF8_STRING -5 An invalid UTF-8 string has been detected
MQTTASYNC_NULL_PARAMETER -6 A null parameter has been supplied when this is invalid
MQTTASYNC_TOPICNAME_TRUNCATED -7 The topic has been truncated (the topic string includes embedded null characters). String functions will not access the full topic. Use the topic length value to access the full topic
MQTTASYNC_BAD_STRUCTURE -8 A structure parameter is malformed
MQTTASYNC_BAD_QOS -9 A QoS parameter is not 0, 1 or 2
MQTTASYNC_NO_MORE_MSGIDS -10 All 65535 MQTT message IDs are being used
MQTTASYNC_OPERATION_INCOMPLETE -11 The request is being discarded when not complete
MQTTASYNC_MAX_BUFFERED_MESSAGES -12 No more messages can be buffered
MQTT_BAD_SUBSCRIBE 0x80 Bad return code from subscribe

The values assigned to the constants may change in a future impOS release.

QoS Constants

The mqtt object includes the following Quality of Service (QoS) constants:

Constant Value Description
mqtt.AT_MOST_ONCE 0 Only provide the message once or not at all
mqtt.AT_LEAST_ONCE 1 The message may be delivered more than once
mqtt.EXACTLY_ONCE 2 Provide the message once

The values assigned to the constants may change in a future impOS release.

Member Entities

The mqtt object has the following member method: