MQTT stands for MQ Telemetry Transport. It is an extremely simple and lightweight publish-subscribe messaging protocol. It was designed for constrained devices and low-bandwidth, high-latency or unreliable networks. These design principles serve 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 its own MQTT broker that is responsible for pushing data to clients in case something new is published in the specific topics they are subscribed to. For example, you can build a system where a sensor sends temperature data to a topic whenever it gets an update. Here, you have devices that would like to be notified when this data arrives, 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 MQTT with Tago’s amazing capabilities to not only enable 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 to 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 application encrypting data that is sent and received; take note that this is not something built-in to the protocol in order to keep it simple and lightweight.
At TagoIO, you can send your data as encrypted directly to your Analysis and decrypt it there to then insert the data on your Bucket. You can use this procedure to increase your security if your data is sensitive or if you want to add an extra layer of security.
TCP/IP port: 1883
TCP/IP port over SSL: 8883
username: any value
password: <Device token>
Learn how to access TagoIO by also using a Static IP.
If the Device token is removed from the device, or if your device is deleted from TagoIO, you'll be disconnect from the MQTT broker.
A topic is used to send messages to the connected clients, and it consists of one or more topic levels 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, this means that 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:
The 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 from any topic
- a client publishes to any topic
Retained messages are normal MQTT messages, but are sent with the retained flag set to true. The Tago MQTT broker will save the last retained message and QoS for that topic, and each client that subscribes to that topic will immediately receive the message 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 that matches 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, the 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 must use these reserved topics.
Make sure to always include the device-token in the password field when publishing data from your device.
Content Type: JSON
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 when sending it by API; you can see the options here.
Content Type: JSON
Use this topic to send 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, as the data will go directly to your Analysis inside the scope on the first position of the array. The data will not be stored automatically, as 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.