Quick Start

This guide will walk you through subscribing to an application’s activations and messages as well as send a response to a specific device, using Eclipse Mosquitto’s CLIs to subscribe and to publish messages.

This guide assumes the sketch and payload functions of The Things Uno / Quick Start, but can be easily applied to any other.

Setup #

Install or download Mosquitto.
Download and save the PEM encoded CA certificate if you’d like to use TLS.

Credentials #

On console.thethingsnetwork.org, navigate to the application you’d like to use. Here you can find the Application ID and an Access Key needed to authenticate over MQTT. Under Handler you will also find the region the application is registered to. You will need the part that follows ttn-handler-, e.g. eu.

Single or double quotes #

On many systems, including Linux and macOS, quotes might not be needed or single quotes are used. On Windows, use double quotes.

Receive Activations #

Let’s listen for new device activations first.

Open a terminal window and execute the following command:
```
mosquitto_sub -h <Region>.thethings.network -t '+/devices/+/events/activations' -u '<AppID>' -P '<AppKey>' -v
```
When using Windows, use double quotes to make the above code work:
```
mosquitto_sub -h <Region>.thethings.network -t "+/devices/+/events/activations" -u "<AppID>" -P "<AppKey>" -v
```
- Replace <Region> with the region you looked up.
- Replace <AppID> with your Application ID.
- Replace <AppKey> with your Access Key (base64).
We add -v to also see the topics of the incoming messages.

For TLS - assuming mqtt-ca.pem is in the same folder - append:
```
--cafile mqtt-ca.pem -p 8883
```

Power up, reset or upload a new sketch to a device to force it to activate and you should see something like:

hello-world/devices/my-uno/events/activations {"app_eui":"70B3D57EF000001C","dev_eui":"0004A30B001B7AD2","dev_addr":"26012723","metadata":{"time":"2016-09-13T09:59:02.90329585Z","frequency":868.5,"modulation":"LORA","data_rate":"SF7BW125","coding_rate":"4/5","gateways":[{"eui":"B827EBFFFE87BD22","timestamp":1484146403,"time":"2016-09-13T09:59:02.867283Z","channel":2,"rssi":-49,"snr":7,"rf_chain":1}]}}

Use Ctrl C to exit.

Receive Messages (up) #

Now let’s listen for actual messages coming in from devices.

Open another terminal window and execute the following command:
```
mosquitto_sub -h <Region>.thethings.network -t '+/devices/+/up' -u '<AppID>' -P '<AppKey>' -v
```
Don’t forget to replace <Region>, <AppID>, <AppKey> and append the options for TLS if you used that.

If you uploaded the The Things Uno / Quick Start sketch you should see something like:

hello-world/devices/my-uno/up {"port":1,"counter":5,"payload_raw":"AQ==","payload_fields":{"led":true},"metadata":{"time":"2016-09-14T14:19:20.272552952Z","frequency":868.1,"modulation":"LORA","data_rate":"SF7BW125","coding_rate":"4/5","gateways":[{"eui":"B827EBFFFE87BD22","timestamp":1960494347,"time":"2016-09-14T14:19:20.258723Z","rssi":-49,"snr":9.5,"rf_chain":1}]}}

Warning: not every cluster publishes uplink fields to individual topics. See status.thethings.network for details.

You can also subscribe to a specific field. Building on The Things Uno / Quick Start you could subscribe to get just the led field:

mosquitto_sub -h <Region>.thethings.network -t '+/devices/+/up/led' -u '<AppID>' -P '<AppKey>' -v

hello-world/devices/my-uno/up/led true

Send Messages (down) #

To send a message you will have to address a specific device by its Device ID. Let’s send the same message used in the The Things Uno / Quick Start:

{
  "led": true
}

If you have followed The Things Uno / Quick Start / Encode Messages you can send this as is using the payload_fields key:

{
  "payload_fields": {
    "led": true
  }
}

Otherwise, you’ll have to use payload_raw and send a base64 encoded array of bytes, e.g.:

{
  "payload_raw": "AQ=="
}

Open another terminal window and execute the following command:

mosquitto_pub -h <Region>.thethings.network -t '<AppID>/devices/<DevID>/down' -u '<AppID>' -P '<AppKey>' -m '{"payload_fields":{"led":true}}'

When using Windows, extra quotation marks have to be added to make the above code work:

mosquitto_pub -h <Region>.thethings.network -t "<AppID>/devices/<DevID>/down" -u "<AppID>" -P "<AppKey>" -m "{""payload_fields"":{""led"":true}}"

If you are running The Things Uno / Quick Start sketch you should see something like:

-- LOOP
Sending: mac tx uncnf 1 with 1 bytes
Successful transmission. Received 1 bytes
LED: on

🎉 Congratulations! Now you know how to monitor and send messages via MQTT. Go build something awesome!

Warning: