Agent
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 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 the mqttmessage object’s sendasync() method:
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.
The mqtt object includes the following Quality of Service (QoS) constants:
| Constant | Value | Description |
|---|---|---|
| mqtt.AT_MOST_ONCE | 0 | The message is sent but receipt is not confirmed by the recipient so there is no guarantee of delivery. There is no inbound ACK. The message is not stored and re-transmitted by the sender |
| mqtt.AT_LEAST_ONCE | 1 | The message may be delivered more than once. The sender stores and periodically re-transmits the message until the receiver acknowledges receipt of the message (one inbound ACK) |
| mqtt.EXACTLY_ONCE | 2 | The message is delivered only once. The sender stores and periodically re-transmits the message until the receiver acknowledges receipt of the message, but subsequent sends mark the message as a duplicate, allowing the receiver to process the message only once. This also utilizes multiple ACKs transmitted by sender and recipient. It is the safest but slowest QoS level |
The values assigned to the constants may change in a future impOS release.
Note Using the constants mqtt.AT_LEAST_ONCE and mqtt.EXACTLY_ONCE require additional acknowledgement messages (one for mqtt.AT_LEAST_ONCE, two for mqtt.EXACTLY_ONCE), and these will count toward the appropriate rate-limit tally.
Outbound messages are rate-limited. To send one message of any type, including system-sent outbound ACKs, costs one credit. You have 40 outbound message credits, and credits are refreshed at a rate of two each second. As noted above, QoS setting 2 will introduce extra transmissions for message acknowledgement, and these additional ACKs each cost message credits from your current outbound total.
Inbound messages are also rate-limited. To accept one message of any type, including inbound ACKs, costs one credit. You have 40 inbound message credits, and credits are refreshed at a rate of eight each second. QoS settings 1 and 2 will introduce extra transmissions for message acknowledgement, and these additional ACKs each cost message credits from your current inbound total.
If the inbound limit is exceeded, the connection will be dropped. You should register a callback function using mqttclient.onconnectionlost(). The callback can now include a parameter into which the reason for a connection loss will be passed. The reason is provided as an integer code; the value -2 indicates that the message rate was exceeded.
If the outbound limit is exceeded, you will receive an error code when you attempt to send a message (using mqttmessage.sendasync()).
The mqtt object has the following member method: