Document purpose

This document describes the different features that Carriots offers to work with the MQTT protocol.

The Carriots platform uses the MQTT protocol for two different uses:

  • Send streams to the platform as an alternative to the HTTP protocol. These streams will enter the usual platform flow and therefore will trigger listeners, rules, devices state change...
  • Make available to the user a dedicated broker to exchange the desired information. This information does not pass through the Carriots platform, it is only a broker for the user to use as he sees fit.

Each one will be explained later

Introduction to MQTT

MQTT provides a scalable and cost efficient way to connect your devices over the internet. It iscapable of delivering messages in near real time and guarantees their delivery. Connect thousands of devices to your business, sending instant updates and broadcast push notifications is where MQTT truly excels. It’s made for devices and is lightweight on the wire, enabling low-cost device communication that scales with your business.

MQTT is an open protocol. It is widely adopted by many devices and companies worldwide for data exchange with constrained devices or products out in the field. MQTT keeps bandwidth at an absolute minimum and deals with unreliable networks without complex error handling and a huge implementation effort. It was made for keeping an steady line to your devices at a minimal cost supporting real push notifications and near real time communication.

Paradigm shift from request/response to publish/subscribe. MQTT is based on the publish/subscribe paradigm. This enables easy broadcasting of messages from one publisher to many subscribers.

1. Quality of service (QoS)

The Quality of Service (QoS) level is an agreement between sender and receiver of a message regarding the guarantees of delivering a message. There are 3 QoS levels in MQTT:

  • At most once (0): A message won’t be acknowledged by the receiver or stored and redelivered by the sender.
  • At least once (1): it is guaranteed that a message will be delivered at least once to the receiver. But the message can also be delivered more than once.
  • Exactly once (2): The message will be delivered exactly once but the communication overhead is high (multiple acknowledgement messages).

Carriots MQTT supports QoS 0 and "Last Will and Testament".

  • Carriots QoS
2. Connection

MQTT relies on TCP as transport protocol, which means by default the connection does not use an encrypted communication. To encrypt the whole MQTT communication, most many MQTT brokers allow to use TLS instead of plain TCP.

TCP/IP port 1883 is reserved for use with MQTT and TCI/IP port 8883 is also reserved for use MQTT over TLS.

Note that if you want to use TLS you will need a certificate.

3. Security

When it comes to authentication in MQTT the protocol itself provides username and password fields in the CONNECT message. Therefore a client has the possibility to send a username and password when connecting to an MQTT broker.

  • MQTT authentication

Encryption across the network can be handled with TLS.

4. Topics

A topic is a UTF-8 string, which is used by the broker to filter messages for each connected client. A topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator).

  • MQTT topics
5. Publish / Subscribe

The publish/subscribe pattern (pub/sub) is an alternative to the traditional client-server model, where a client communicates directly with an endpoint. However, Pub/Sub decouples a client, who is sending a particular message (called publisher) from another client (or more clients), who is receiving the message (called subscriber). This means that the publisher and subscriber don’t know about the existence of one another. There is a third component, called broker, which is known by both the publisher and subscriber, which filters all incoming messages and distributes them accordingly:

  • PUBLISH: After a MQTT client is connected to a broker, it can publish messages. MQTT has a topic-based filtering of the messages on the broker, so each message must contain a topic, which will be used by the broker to forward the message to interested clients. Each message typically has a payload which contains the actual data to transmit.
  • SUBSCRIBE: A client needs to send a subscribe message to the MQTT broker in order to receive relevant messages.

Send streams to Carriots using MQTT

1. Introduction

MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium.

You can use the MQTT protocol to send streams to Carriots. Carriots MQTT supports Quos 0 and "Last Will and Testament".

2. Connection
Host Port 1883 8883 ssl

Note that if you want to use ssl you will need a certificate. You can download it here.

3. Authentication

For the authentication you must provide your apikey as username leaving the password field empty.

4. Available Topics

The following topics are available:


You can publish xml or json to these topics.

5. Example

To view a complete example for sending streams using Python and the Paho library click here.

Dedicated broker to exchange the desired information

It may be useful to have a MQTT messaging broker to exchange information with the device. For this purpose, Carriots allows to enable topics on demand for each device. The information exchange using this workflow does not go through the Carriots rule engine flow. You can read the complete documentation of this feature HERE