Basics of CoAP

As Wikipedia says: 'Constrained Application Protocol (CoAP) is a software protocol intended to be used in very simple electronics devices that allows them to communicate interactively over the Internet.'...' CoAP is designed to easily translate to HTTP for simplified integration with the web.'

In this page you will learn how to use theThings.IO CoAP endpoint.

Getting Started

The CoAP endpoints are very similar to the REST API. There are the same methods (Activate, ThingWrite ThingRead and ThingSubscribe) and also the paths are the same. The only difference is the endpoint base url and protocol: coap.thethings.io (port 5683)

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 registration endpoint call. 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.

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.

CoAP Test

To test your connectivity with coap.thethings.io you have two options:

Activate, Read, Write & Subscribe

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

Activate

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

POST coap://coap.thethings.io/v2/things/

ThingWrite

Writes the records of data from the thing corresponding to the specified THINGTOKEN. Only alphanumeric characters and ".", "-", "" simbols are admited for the resource name "key".

POST coap://coap.thethings.io/v2/things/{ {THING_TOKEN} }

ThingRead

This method returns the values of the specified KEY from the corresponding thing THING_TOKEN.

GET coap://coap.thethings.io/v2/things/{ {THING_TOKEN} }/resources/{ {KEY} }

Request Parameters

The table below indicates the available parameters. For example,
coap://coap.thethings.io/v2/things/{ {thingToken} }/resources/{ {key} }?limit=10
will get the last 10 values.

Parameter Default Format Description
limit 1 Number How many results (max 100)
startDate Jan 1st 1970 YYYYMMDDHHmmss The min date
endDate End of times (for JavaScript) YYYYMMDDHHmmss The max date

ThingSubscribe

This method subscribes to the thing channel and gets realtime updates. You must set the CoAP observe bit.

GET coap://coap.thethings.io/v2/things/{ {thingToken} }

Examples

Node.js

The next Node.js library allows to easily connect to the coap.thethings.io endpoint.

You can visit the github repository: theThings.IO CoAP Node.js library

And get the examples at: theThings.IO CoAP Node.js examples