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:

Blocking And Synchronous Calls

We do not recommend using MQTT with code (eg. a long do... while loop) and/or imp API calls that block (eg. imp.sleep() or httprequest.sendsync()). MQTT relies on being available to accept incoming packets, and this may be disrupted if Squirrel is not running while the agent sleeps or is paused while waiting for a response from a remote server.

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: