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 minimize network bandwidth and device resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery. (source MQTT.org)
TagoIO 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.
With this basic idea, it is possible to combine the MQTT with Tago’s amazing capabilities to not only enable the communication among devices, but also to create dashboards, analytics, notifications, and reports.
MQTT defines methods (or verbs) to indicate the desired action to be performed on the identified resource.
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.
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 TagoIO, 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.
TCP/IP port: 1883
TCP/IP port over SSL: 8883
password: <Device token>
A topic is used to send messages to the connected clients, and it consists of one or more topic levels, the levels are separated by a forward slash ‘/’.
Wildcards are used by the clients to subscribe to multiple topics at once, the client can only use wildcards to subscribe to topics, it means the client cannot publish to a topic using wildcards.
Tago MQTT broker supports single level and multi level wildcards
The single level is represented by the
+ sign, by adding a
+ sign to the topic.
If the client subscribes to the topic
home/+/temperature, the following topics will match:
That means if any client publishes data to these topics above, the subscribed client will receive it.
The following topics WILL NOT match:
The multi level is represented by the
# sign, by adding a
# sign to the topic the client will subscribe to all the following levels of that topic.
If the client subscribes to the topic
home/#, the following topics will match:
Tago MQTT broker has a debug topic which is
tago/debug if a client subscribes to this topic, it will receive debug messages.
The messages are triggered with the following actions.
- a client subscribes to any topic
- a client unsubscribes to any topic
- a client publishes to any topic
Retained messages are normal MQTT messages, but sent with the retained flag set to true. Tago MQTT broker will save the last retained message and QoS for that topic and each client that subscribes to that topic will receive this message immediately after subscribing to the topic. If the client sends another retained message to the same topic, the old retained message will be overwritten.
If the subscribing client uses a wildcard and match the topic, it will receive the message.
Send a retained message
To send a retained message, the client must set the payload and the retained flag to true, each MQTT client library provides an easy way to do that.
Delete a retained message
To delete a retained message, the client must set the retained flag to true and no payload. By sending a retained message without a payload Tago MQTT broker will delete it.
PUBLISHING TO TagoIO
The TagoIO 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 TagoIO, you need to use these reserved topics.
Content Type: JSON
Content Type: JSON
Make sure you always include the device-token in the password field when publishing data from your device.
Use this topic to send data from any device to the data bucket in your account. The figure below shows the flow from the device to its bucket. At TagoIO, 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.
You should send the data using the same JSON format as you would send it by API, you can see the options 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.
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 TagoIO
You can publish to your MQTT topics by coding a script that will 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, an Action, or called by another analysis. The figure below shows the data flow from the analysis to the MQTT network.
Remember, don’t publish to any of the reserved topics if you want to reach external devices.