In this document you will learn the basics of how to connect your networked devices to thethings.iO with MQTT.

📘
Before you start learning how to use our platform to connect your devices, we recommend that you first read our Getting Started guide in order to create your Account and set up the platform.

Publish/Subscribe
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 using MQTT can connect. thethings.iO has a broker at mqtt.thethings.io where you can connect your apps.

You can get more documentation about the protocol at mqtt.org

Getting Started

MQTT thethings.iO broker host: mqtt.thethings.io

The port is the default for mqtt: 1883.
The secure port is: 8883. TLS 1.0 to 1.3.

Examples: MQTT with NodeJS.

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 via the Activate message. The purpose of this code is to identify you as the creator of the thing at the same time 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.

To get your Thing 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.

Mosquitto
For Debian based distributions: sudo apt-get install mosquitto-clients

Node MQTT
sudo npm install mqtt -g

MQTT Basics

🚧
In the examples, the { {SOMETHING} } (braces included) indicate variables that you may replace for the appropriate 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 Platform panel.

You have to subscribe to a channel identified by a random string generated by you. This 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.

mosquitto_sub -h "mqtt.thethings.io" -t "v2/activations/ACTIVATION_CODE/RANDOM_STRING" -d

mqtt sub -h 'mqtt.thethings.io' -t 'v2/activations/ACTIVATION_CODE/RANDOM_STRING'
 -v

# Result in case of success:
  { "status": "created", "thingToken": "YOUR THING TOKEN" }
  # Result in case of error:
  { "status": "error", "message": "Error creating thing" }

Subscribe

Subscribes to the thing token and gets realtime updates.

mosquitto_sub -h "mqtt.thethings.io" -t "v2/things/THING_TOKEN" -d

mqtt sub -h 'mqtt.thethings.io' -t 'v2/things/THING_TOKEN' -v

# Each time a publish is sent you get:
  [{"key":"fun","value":9000}]

Publish

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

mosquitto_pub -h "mqtt.thethings.io" -t "v2/things/THING_TOKEN" -f data.json -d

mqtt pub -h "mqtt.thethings.io" -t "v2/things/THING_TOKEN" -m '[{"key":"fun","value":9000}]'

# data.json content
  [{"key":"fun","value":9000}]

Examples

See the examples to connect your device to thethings.iO at our GitHub Repository for different programming languages.