Basics of MQTT

What is MQTT?

As Wikipedia says: "MQTT (Message Queue Telemetry Transport) is a publish-subscribe based "light weight" messaging protocol for use on top of the TCP/IP protocol. It is designed for connections with remote locations where a 'small code footprint' is required and/or network bandwidth is limited."


When a thing publishes a message it publishes the message in a topic. A topic is like a channel where each thing subscribed to that topic will receive that message. You can imagine this like a Twitter of Things.

MQTT Broker

An MQTT Broker is a server where the things (from Internet of Things) using MQTT can connect. thethings.iO has a broker in where you can connect your apps.

You can get more documentation about the protocol in the page

Getting Started

MQTT thethings.iO broker host:
The port is the default for mqtt: 1883.

Get tokens

To be able to follow the examples you will need an activation code or a thing token.

An activation code is a unique code that will enable your devices to be activated. The purpose of this code is at the same time identify you as the creator of the thing and when some day you start selling your awesome IoT product, avoid that somebody can activate things in your name. As a result of this call your thing will receive a unique thing token that will identify your thing at thethings.iO platform.
You can also activate your things manually at the Panel as explained on the getting started guide. You can activate a thing with the API REST and Coap too.

If you are in the developers tier you will get some activation codes for free. If you are in the premium tier you will be able to generate as many activation codes as you need. To get your tokens go to the things manager page and click the get activation codes button.

MQTT setup

To be able to follow the next examples you will need to install the package mosquitto-clients from Mosquitto or with the mqtt node package.

sudo apt-get install mosquitto-clients


brew install mosquitto
sudo npm install mqtt -g

Activate, Subscribe & Publish

In the examples, the { {SOMETHING} } (braces included) indicate variables that you may replace for the appropiate value.

Activate (subscription)

Activates a thing with an activation code. The result is a thing token. You will be able to retrieve this thing token at any time from the panel

You have to subscribe to a channel identified by a random string generated by you. Thi is to avoid that two devices listening could get the same thing token. After a few seconds a thing token will be published by the server to this channel

SUBSCRIBE v2/activations/{ {activationCode} }/{ {some random string } }


Subscribes to the thing token and gets realtime updates.

SUBSCRIBE v2/things/{ {thingToken} }


Publish a single message on a topic. Only alphanumeric characters and ".", "-", "_" simbols are admited for the resource name "key".

PUBLISH v2/things/{ {thingToken} }

Node.js MQTT Examples

You can explore code examples that show how to interact with thethings.iO MQTT broker at or Github repository.

This examples use the MQTT.js library for Node.js. This examples are about:

  • a complete example to activate a thing and subscribe to a thing topic
  • an example to connect with thethings.iO with SSL encryption
  • an example to show how to configure last will