Using MQTT with MODE

MQ Telemetry Transport, or MQTT, is a messaging protocol that is gaining popularity as a solution to connect low-powered devices. Although MQTT was originally designed for communications based on the pub/sub architecture, it can be used as a general-purpose “machine-to-machine” (M2M) communication protocol.

For device connectivity, MODE supports MQTT 3.1.1 as an alternative to its REST API. Using MQTT, devices can “publish” events to and “subscribe” to commands from the MODE cloud. If you have an existing device implementation that is based on MQTT, you can easily integrate it into a MODE project.

Known Restrictions

While MODE’s MQTT implementation covers many common IoT use cases, currently the following restrictions are in place:

  • Only MQTT version 3.1.1 is supported.
  • For publishing, only QoS levels 0 and 1 are supported.
  • For subscription, only QoS level 0 is supported.
  • Persistent sessions are not allowed.
  • Will topics are not supported.
  • Message retain is not supported.

Making MQTT Connections

Your MQTT client (device) should connect to the host mqtt.tinkermode.com at the standard MQTT port 1883, or for a secure connection, at port 8883. We highly recommend the use of the secure port. (Some MQTT client libraries require you to provide a root CA certificate in order to make TLS connections to the server. MODE’s root CA for the MQTT service is DigiCert and you can download the certificate here.)

Once a connection is established, the client should issue the CONNECT message with the following arguments:

  • clientId should be blank.
  • cleanSession should be true.
  • username should be the device ID.
  • password should be the API key issued to the device.

If the message is successful, your client should proceed to set itself up to receive commands from MODE.

Receiving Commands

To receive commands targetting your device, your client needs to subscribe to the appropriate topic with the SUBSCRIBE message. The topic name must be in the format /devices/DEVICE_ID/command, where DEVICE_ID is the assigned device ID. The only QoS level supported is 0.

If the SUBSCRIBE message is successful, your client will receive a PUBLISH message whenever a command is issued to the the device. The payload of the message is a JSON string as defiend by MODE’s schema for the Device Command object.

Mosquitto has some convenient command-line programs for testing MQTT. In the following example, we are using mosquitto_sub to listen to incoming commands and output the JSON strings to the screen. (Replace DEVICE_ID and DEVICE_API_KEY with the actual device ID and API key.)

$ mosquitto_sub -d -V mqttv311 -h mqtt.tinkermode.com -t /devices/DEVICE_ID/command -u DEVICE_ID -P DEVICE_API_KEY

Sending Events

To send events to MODE, your client simply issues the PUBLISH message with the following arguments:

  • topicName must be in the format /devices/DEVICE_ID/event, where DEVICE_ID is the assigned device ID.
  • payload is a JSON string as defined by MODE’s schema for the Event object.
  • qos can be 0 or 1.

In the following example, we are using mosquitto_pub to send an event to MODE with QoS1. (Replace DEVICE_ID and DEVICE_API_KEY with the actual device ID and API key.)

$ mosquitto_pub -d -V mqttv311 -h mqtt.tinkermode.com -t /devices/DEVICE_ID/event -m '{ "eventType": "test", "eventData": { "x": 123 } }' -u DEVICE_ID -P DEVICE_API_KEY -q 1

Disconnecting Gracefully

If your device no longer wishes to send events or receive commands, it is good practice to gracefully disconnect from the MQTT server. Make sure the client issues an UNSUBSCRIBE message to stop any subscription, then a DISCONNECT message to terminate the session cleanly.