MQTT glossary

This section provides an overview on the basic MQTT terminology.


In the MQTT word, a client can be any device that connects to a broker -from a microcontroller to a server. Clients are usually both publishers and subscribers.


An MQTT Broker is responsible for routing, filtering and distributing messages to appropriate parties (clients). The Xively MQTT Message Broker performs these actions based on the state of topic subscriptions and permissions set within the Xively Blueprint service.

Channels and Topics

In the world of messaging protocols, channels, topics, and queues are used as interchangeable terms to describe a logical separation of input and output data, similarily to API endpoints in HTTP. In MQTT, the only entity that is defined is called a topic. In the Xively MQTT implementation, channels and topics both exist and have slightly different meanings.

In Xively, an MQTT topic is the full path that a device publishes and subscribes to. This full path includes a channel name, which is defined by Xively’s Blueprint service in a device template.

The MQTT topic formatting in Xively is the following:

xi/blue/v1/<accountId>/d/<deviceId>/<channel name>

where is the Xively account ID, is the Xively device ID, and is the name of one of the device channels.

  • A channel is a Xively concept. A channel template in Blueprint defines the behavior of the Xively broker for all data sent over that channel. The behavior is controlled through two settings: Channel type - whether to use time series to hold all data sent to broker forever; Kinesis Bridge - whether to add the messages to a processing queue in AWS Kinesis. When the channel template is attached to a device template, then all the devices derived from that device template have their own instance of the channel.

Quality of Service (QoS)

QoS or Quality of Service is one of the key features of MQTT. It specifies the following three levels of message delivery:

  • QoS 0: Send only once. This fire and forget method is the default messaging level that does not guarantee message delivery. For example, sending sensor data on QoS 0 may uncommonly result in dropped measurements; however, the relevance of the overall datapool is not compromised. Xively control channels require the use QOS0
  • QoS 1: Deliver at least once. This level guarantees that the message is delivered, but do not enforce one-time delivery.
  • QoS 2: Deliver exactly once: This level guarantees correct delivery. Xively does not support QoS2.

A common use case for both QoS 1 and QoS 2 is the distribution of initial configuration or channel information to newly connected devices.


How QoS works

When the QoS level is set on a message, the minimum value is used between subscriber's and publisher's levels.

Clean / Unclean Sessions

This feature allows persistence of QoS 1 and 2 messages. When a client initiates an unclean session with the same ID it used in previous connections, it receives all QoS 1 and QoS 2 messages that it missed on that queue since it was last subscribed.

Default value: Clean

Important: Requires a persistent unique client ID across connections.

Keep Alive Time

Keep Alive Time is the amount of time in seconds between pings back to the Xively server. The longer the time, the less bandwidth the device uses; however, the higher the latency will be for receiving a last will.

Default value: 60 seconds

Tip: The recommended value range is between 60 and 75 seconds.

Last Will

The Last Will feature allows you to know if a device is still connected to a specific broker. Basically you can set up a message to be sent once the device becomes disconnected from the server for a pre-specified amount of time. See also Keep Alive Time.


The destination topic that you want the message sent to upon disconnect. Similar parameters to PUBLISH message.


The message sent upon disconnect. Similar parameters to PUBLISH message.

Will-QoS and Retain

QoS to send message at. Whether or not to retain the message on the topic.


You can set a message to be retained and it will be received every time a new subscriber starts listening on a channel. Can be very useful for defining configuration or setup options.

Maximum limit: One message at a time per channel

Simple Message

A simple message is a standard MQTT message that contains a topic, a payload (the actual data that is transmitted, for example: {39}), and attributes like Quality of Service level or Retain flag.

Time Series

Xively offers time series channels to store data for later retrieval. The publish method is exactly the same for a time series channel as for a simple message, but each message sent is also stored at the timestamp it was received in Xively's time series database.

  • You can create a time series channel on Xively by selecting "Time series" instead of "Simple" when you add a channel
  • Time series data can consist of float values (numbers) and strings, and it must be the entire contents of the publish message. Learn more about time series data and its accepted formats.

Updated 3 years ago

MQTT glossary

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.