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

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

👍
At this guide, we only show the basics of the CoAP, you can access CoAP reference to get the full list of endpoints available and detailed documentation.

Getting Started

The CoAP endpoints are very similar to the REST API. There are the same methods (Activate, Write Read and Subscribe) 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 Thing Activate API call. The purpose of this code is 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.

CoAP Test

To test your connectivity with coap.thethings.io we recommend you to use this:

CoAP-CLI is a command line interface for CoAP, built on node.js and node-coap.

CoAP Basics

The next examples are created using the COAP CLI library.

🚧
At the next examples, you have to replace the variables inside brackets {{THING TOKEN}}, brackets that include your actual value. Note that we use < " > in instead of < " >

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 Platform.

# coap-cli
coap post coap://coap.thethings.io/v2/things/ -p '{"activationCode" : "ACTIVATION_CODE"}'

// Everything has gone well:

  {
    "status": "created",
    "thingToken": "NwFbEqwEQ-ucyW8aET34EWi6L_tte6fumxTSU-Pkw"
  }

// Error

  {
    "status": "error",
    "message": "Error creating thing"
  }

Write

Writes the records of data from the thing corresponding to the specified THING_TOKEN. Only alphanumeric characters and ".", "-", "" symbols are permitted for the resource name "key".

# coap-cli
coap post coap://coap.thethings.io/v2/things/THING_TOKEN/ -p '{"values":[{"key":"fun","value":"9000"}]}'

// Everything has gone well
  {
    "status": "Success",
    "message": "Created"
  }

Read

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

# coap cli
  coap get coap://coap.thethings.io/v2/things/THING_TOKEN/resources/KEY

[
    {
      "key": "fun",
      "value": "9000",
      "datetime": "2015-01-30T15:35:33.000Z"
    },
  ... (more values) ...
  ]

Query parameters

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

Subscribe

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

# coap-cli
  coap get coap://coap.thethings.io/v2/things/THING_TOKEN -o

// Each time a Write is sent you get:
 [
    {
      "key": "fun",
      "value": "9000",
      "datetime": "2015-01-30T15:35:33.000Z"
    }
  ]

Examples

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