MQTT

MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. The design principles are to minimise network bandwidth and device resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery. These principles also turn out to make the protocol ideal of the emerging “machine-to-machine” (M2M) or “Internet of Things” world of connected devices, and for mobile applications where bandwidth and battery power are at a premium. (source MQTT.org)

Tago has it own MQTT broker that is responsible to push the data to the clients in case something new is published in the specific topics subscribed by them. As a simple example, we can build a system where a sensor sends temperature data to a topic whenever it gets an update. From the other side, we may have devices that would like to be notified when this data arrive, so they subscribe to this topic. When the data is ready, the temperature sensor publishes the data in that topic, and the broker is responsible to push it to all devices that subscribed to the same topic.

_images/Basic_MQTT.png

With this basic idea, it is possible to combine the MQTT with Tago’s amazing capabilities to not only to enable the communication among devices, but also to create dashboards, analytics, notifications, reports and data storage.

MQTT methods

MQTT defines methods (sometimes referred to as verbs) to indicate the desired action to be performed on the identified resource. What this resource represents, whether pre-existing data or data that is generated dynamically, depends on the implementation of the server. Often, the resource corresponds to a file or the output of an executable residing on the server. (source Wikipedia)

Connect: Waits for a connection to be established with the server.

Disconnect: Waits for the MQTT client to finish any work it must do, and for the TCP/IP session to disconnect.

Subscribe: Waits for completion of the Subscribe or UnSubscribe method.

UnSubscribe: Requests the server unsubscribe the client from one or more topics.

Publish: Returns immediately to the application thread after passing the request to the MQTT client.

Security

Encryption across the network can be handled with SSL, independently of the MQTT protocol itself (it is worth noting that SSL is not the lightest of protocols, and does add significant network overhead). Additional security can be added by an application encrypting data that it sends and receives, but this is not something built-in to the protocol, in order to keep it simple and lightweight. At Tago, you can send your data encrypted direct to your Analysis and decrypt it then insert the data on your Bucket, you can use this way to increase your security if your data are sensitive or you want to add an extra layer of security.

Connection

Host mqtt.tago.io
TCP/IP port 1883
TCP/IP port over SSL 8883
username any value
password <Account token or Device token>

Topics

Tago MQTT broker gives you two ways to access the topics: you can connection with your Account token or Device Token.

If you prefer to use Device Token, you can access any topic limited to those devices that are associated with the same data Bucket. If you prefer to use Account Token, you can access any topic, from any device, all over your account. Check out the diagram below:

_images/diagram_channels.png

PUBLISHING TO TAGO

The Tago MQTT Broker reserves a topic named tago, you can use that topic only to send data or trigger an Analysis, but not for any other specific function. Below is a list of the functions that you can use. You can use any topic to create a communication among the devices, but if you want to reach the devices/data buckets/analysis/actions in your account at Tago, you need to use these reserved topics.

Topic MQTT Method Content Type Token Type
tago/data/post publish JSON as String Device
tago/analysis/Analysis_ID publish Anything Device / Account

tago/data/post

Use this topic to send data from any device to the data bucket in your account. The figue below shows the flow from the device to its bucket. At Tago, the device-token used should be linked to the desired data bucket. When the data arrives in your bucket, it is stored, and it will be ready for visualization or to take any other action.

_images/Publishing_to_Bucket.png

You should send the data using the same JSON format as you would send it by API, you can see all your options here.

tago/analysis/Your_Analysis_ID_HERE

Use this topic to send a payload data from a device in any format to be first parsed by your own script. The script should be uploaded on the analysis that is identified by the analysis_id. This option gives you a lot of flexibility to interpret any kind of data or protocol according to your own application. The figure below, shows the data flow from the device to the specific analysis associated with the ID used in the topic.

_images/Publishing_to_Analysis.png

You can send any data format with any content to this topic, your data will go directly to your Analysis inside the scope on the first position of the array. The data will not be stored automatically, your script needs to take care of it.

PUBLISHING FROM TAGO

You can also publish to your MQTT topics by coding a script that can run from an Analysis. When the analysis runs, your script can publish a topic that can be received by any device that subscribed to that specific topic. There are different ways to start an analysis, it may be by timer (defined in the analysis configuration section), an Action, or called by another analysis. The figure below shows the data flow from the analysis to the MQTT network.

_images/Publishing_from_Analysis.png

Remember, don’t publish to any of the reserved topics if you want to reach external devices.