MQTT Access

Definitions

  • MQTT - Message Queue Telemetry Transport is a protocol for transferring messages in publish-subscribe pattern. It is running on top of TCP/IP protocol.
  • Cloud Of Things Server - The cloud of things platform mqtt endpoint
  • Client - Device connection to MQTT
  • Application - Any software connecting to MQTT that is not part of a physical IOT device like a mobile application, a web application, or a pc software.
  • Topic - A string that can be listened for information or accepting messages.
  • Last Will - a stored message that is kept on the server in case the client/application disconnects from the server for a period of time.
  • Device - A cloud of things client device as represented in the cloud (basically metadata)
  • Stream - A collection of time series data (numbers or strings) which is part of a device and used for collect data from physical sensors.

Basic Protocol Introduction

In the MQTT protocol there are several actions:

  1. Connect - connect to an mqtt server (broker)
  2. Disconnect - close open connection
  3. Subscribe - send request to listen to messages with specific Topic (explained below)
  4. Unsubscribe - send request to stop receiving message in some topic
  5. Publish - Send a new message to some topic with or without payload

As shown above the mqtt protocol is all about messages. An MQTT message according to the protocol could be of many kinds, however the only relevant one for us is the Message type being generated by the Publish action. An MQTT message is comprised of two parts - a topic which is a string. And a payload which contains textual data and can be empty.

Standard operation sequence is as follows:

  1. Connect to Server
  2. Subscribe to topics of interest
  3. Wait for messages/Publish messages

Disconnecting from the server is less relevant as usually you will want to retain the connection for as long as possible.

The connection phase including passing username and password for authentication, setting keep alive time, and passing additional information like last will message.

Topics are simple strings however out of convention they are built in the form of a tree with ‘/’ as the separator.

For example:
hello/world hello/some/other/topic hello/some/super/topic hello/world/2

The MQTT broker supports wildcards for subscription with two specific characters:

  • # specifying everything - so the topic hello/# will listen to all topics from the above examples
    • will only replace values within a single level so hello/+ will only match hello/world and hello/some/+/topic will listen to both hello/some/other/topic and hello/some/super/topic but not to hello/world or hello/some/bbb/topic/b

Cloud of Things MQTT Protocol: The current API version for MQTT is v3 represented by the prefix cot-v3 in all topics.

The concept in v3 is that there are two channels for data transfer and they are in a single direction. - From the Client to applications or Events - specified by evt - From application to the Client or Commands - specified by cmd

Formats

Currently the cloud of things server supports only two formats:

  • Minimal - which basically means a simply string payload without any parsing should contain only the value to be sent
  • Json - a valid json object that will be parsed as json and must include a ‘content’ key

Events

Event topics are in the following format:
cot-v3/device/<Device ID>/evt/<Stream ID>/fmt/<Format>

They are used by clients to send data back to the platform and the listening applications. Events are also delivered into the cloud of things platform and saved in the TSDB

Commands

Command topics have several formats.

Command for stream:
cot-v3/device/<Device ID>/cmd/<Stream ID>/fmt/<Format>

* currently devices listen to minimal.

Command for device:
cot-v3/device/<Device ID>/cmd/<Command String>
Group commands:
cot-v3/group/<Group ID>/cmd/<GroupStream ID>/fmt/<Format>

* group commands are received by all devices that are part of this group.

Commands are sent from applications to the device and are not being updated in the TSDB until the device sends an event.