CoAP Device API Reference
Getting started
CoAP basics
CoAP is a light-weight IoT protocol for constrained devices. You can find more information about CoAP here.
CoAP protocol is UDP based, but similar to HTTP it uses request-response model.
CoAP observes option allows to subscribe to resources and receive notifications on resource change.
NDU server nodes act as a CoAP Server that supports both regular and observe requests.
Client libraries setup
You can find CoAP client libraries for different programming languages on the web. Examples in this article will be based on CoAP cli.
CoAP Authentication and error codes
We will use access token device credentials in this article and they will be referred to later as $ACCESS_TOKEN.
The application needs to include $ACCESS_TOKEN as a path parameter into each CoAP request.
Possible error codes and their reasons:
- 4.00 Bad Request - Invalid URL, request parameters or body.
- 4.01 Unauthorized - Invalid $ACCESS_TOKEN.
- 4.04 Not Found - Resource not found.
By default, NDU supports key-value content in JSON. Key is always a string, while value can be either string, boolean, double, long or JSON.
Using custom binary format or some serialization framework is also possible.
For example:
1
2
3
4
5
6
7
8
9
10
11
| {
"stringKey":"value1",
"booleanKey":true,
"doubleKey":42.0,
"longKey":73,
"jsonKey": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
|
Telemetry upload API
In order to publish telemetry data to NDU server node, send POST request to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/telemetry
|
The simplest supported data formats are:
1
| {"key1":"value1", "key2":"value2"}
|
or
1
| [{"key1":"value1"}, {"key2":"value2"}]
|
Please note that in this case, the server-side timestamp will be assigned to uploaded data!
In case your device is able to get the client-side timestamp, you can use following format:
1
| {"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}
|
In the example above, we assume that “1451649600512” is a unix timestamp with milliseconds precision.
For example, the value ‘1451649600512’ corresponds to ‘Fri, 01 Jan 2016 12:00:00.512 GMT’
resources/coap-telemetry.sh |
|---|
1
2
3
4
5
6
| # Publish data as an object without timestamp (server-side timestamp will be used)
cat telemetry-data-as-object.json | coap post coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/telemetry
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
cat telemetry-data-as-array.json | coap post coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/telemetry
# Publish data as an object with timestamp (server-side timestamp will be used)
cat telemetry-data-with-ts.json | coap post coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/telemetry
|
|
resources/telemetry-data-as-object.json |
|---|
1
2
3
4
5
6
7
8
9
10
11
| {
"stringKey": "value1",
"booleanKey": true,
"doubleKey": 42.0,
"longKey": 73,
"jsonKey": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
|
|
resources/telemetry-data-with-ts.json |
|---|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| {
"ts": 1451649600512,
"values": {
"stringKey": "value1",
"booleanKey": true,
"doubleKey": 42.0,
"longKey": 73,
"jsonKey": {
"someNumber": 42,
"someArray": [1, 2, 3],
"someNestedObject": {
"key": "value"
}
}
}
}
|
|
Attributes API
NDU attributes API allows devices to
- Upload client-side device attributes to the server.
- Request client-side and shared device attributes from the server.
- Subscribe to shared device attributes from the server.
Publish attribute update to the server
In order to publish client-side device attributes to NDU server node, send POST request to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/attributes
|
resources/coap-attributes-publish.sh |
|---|
1
2
| # Publish client-side attributes update
cat new-attributes-values.json | coap post coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/attributes
|
|
resources/new-attributes-values.json |
|---|
1
2
3
4
5
6
7
8
9
10
11
| {
"attribute1": "value1",
"attribute2": true,
"attribute3": 42.0,
"attribute4": 73,
"attribute5": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
|
|
Request attribute values from the server
In order to request client-side or shared device attributes to NDU server node, send GET request to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
|
resources/coap-attributes-request.sh |
|---|
1
2
| # Send CoAP attributes request
coap get coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
|
|
Please note, the intersection of client-side and shared device attribute keys is a bad practice!
However, it is still possible to have same keys for client, shared or even server-side attributes.
Subscribe to attribute updates from the server
In order to subscribe to shared device attribute changes, send GET request with Observe option to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/attributes
|
Once shared attribute will be changed by one of the server-side components (REST API or Rule Chain) the client will receive the following update:
RPC API
Server-side RPC
In order to subscribe to RPC commands from the server, send GET request with observe flag to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/rpc
|
Once subscribed, a client may receive rpc requests. An example of RPC request body is shown below:
1
2
3
4
5
6
7
8
| {
"id": "1",
"method": "setGpio",
"params": {
"pin": "23",
"value": 1
}
}
|
where
- id - request id, integer request identifier
- method - RPC method name, string
- params - RPC method params, custom json object
and can reply to them using POST request to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/rpc/{$id}
|
where $id is an integer request identifier.
resources/coap-rpc-reply.sh |
|---|
1
2
| # Publish response to RPC request
cat rpc-response.json | coap post coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/rpc/1
|
|
Client-side RPC
In order to send RPC commands to the server, send POST request to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/rpc
|
Both request and response body should be valid JSON documents. The content of the documents is specific to the rule node that will handle your request.
Claiming devices
In order to initiate claiming device, send POST request to the following URL:
1
| coap://smartapp.netcad.com/api/v1/$ACCESS_TOKEN/claim
|
The supported data format is:
1
| {"secretKey":"value", "durationMs":60000}
|
Please note that the above fields are optional. In case the secretKey is not specified, the empty string as a default value is used.
In case the durationMs is not specified, the system parameter device.claim.duration is used.