CoAP Endpoint
CoAP Overview
The CoAP Endpoint coap://coap.os.1nce.com:5683
hosts a POST endpoint on the server root path (/
). The endpoint supports both normal, non-translatable messages and translatable messages by using the energy saver.
The POST endpoint takes an optional query parameter (or Location-Query) t
to provide the MQTT topic used for forwarding this message to a MQTT broker (e.g., coap://coap-service:5683/?t=topicName\
). The Location-Query is limited to 255 characters by the CoAP protocol, hence the topic name itself can only contain up to 253 characters (t
and `=
also count as characters). The topic name itself can only contain alphanumeric characters, underscores, and forward slashes (no two slashes in a row). If these constraints are violated, a bad request (4.00) will be returned.
If a targeted device could not be found or is in a non-active status, the CoAP service will return an unauthorized (4.01) and no further processing of the message will take place.
CoAP Communication
While using UDP protocol for transport, the CoAP protocol offers reliable communication by using message confirmation mechanism. Each CoAP request has to be acknowledged by the server, so that the client would be sure that the message was processed:
There are few key moments that allow reliable communication:
- To maximize the chance that the message succeeds even in the lossy network environment, CoAP has a retransmission mechanism. The client would re-send the Confirmable message (
CON
) until the Acknowledgement (ACK
) is received or the exchange lifetime has ended. The total exchange lifetime (EXCHANGE_LIFETIME
) is the time from starting to send a Confirmable message to the time when an acknowledgment is no longer expected.
By default, theEXCHANGE_LIFETIME
value is247 seconds
. - CoAP Messages contain Message ID (also known as
MID
) to detect duplicates due to retransmissions. The Message ID has to be unique during theEXCHANGE_LIFETIME
, so the client's endpoint should be able to specify a uniqueMID
value if messages are being sent often enough. Most high-level CoAP clients are managingMID
uniqueness internally, but for low-level clients like modem Quectel BG95, it can be specified in the AT command asmsgID
[2]:
AT+QCOAPHEADER=<clientID>,<msgID>,<mode>[,<TKL>,<token>]
There are two examples of the retransmission situation in a single exchange lifetime:
- client's
CON
message did not reach the server. The client is resending the sameCON
message with the sameMID
. - server's
ACK
message did not reach the client. The client is resending the sameCON
message with the sameMID
(because there was no acknowledgment). The server is answering with the sameACK
because it sees the already processedMID
and does not process the request again.
DTLS encryption for CoAP

CoAP DTLS Support
Ensuring, data is securely sent from a device to 1NCE OS, it is an important part of gaining the trust of customers with their data. To be able to provide this secure connection 1NCE OS has implemented a DTLS layer in the CoAP communication from the device to 1NCE OS. This allows the device to securely send its data to 1NCE OS without the possibility of messages being read or modified along the way. The picture above describes this process. First, when the device is ready to onboard itself, it will call the CoAP bootstrapping endpoint. This will retrieve the necessary DTLS info to onboard itself securely and initialize the CoAP connection using a PSK.
Features & Limitations
DTLS as a security protocol provides secure and fast data streaming. This comes with some advantages but also has some limitations. Below these key points are explored in the context of a CoAP connection.
Features
DTLS is able to provide datastreaming functionality to devices with a low delay compared to TLS. It is able to provide this because it preserves the semantics of the underlying transport. DTLS also has advanced security. As a result, communication between client-server applications cannot be eavesdropped on or tampered with. This ensures that the streamed data is the same data as it was received.
DTLS makes use of the UDP protocol for this functionality. The data is sent in a fire and forget style, so no handshakes occur, and the message is sent without any reception or delivery confirmation. UDP also avoids the TCP meltdown problem, where different transport layers compensate for each other, cause delays in the data transfer.
Limitations
The main limitation of DTLS is the use of the UDP protocol. The major drawbacks of using UDP are, having to deal with packet reordering, loss of datagram, and data larger than the size of a datagram network packet.
Encryption Key
To use DTLS, an encryption key is required to ensure security. For 1NCE OS, a pre-shared key is used to encrypt and decrypt the data. For connecting a device with secure CoAP with DTLS encryption the endpoint coaps://coap.os.1nce.com:5684
can be used. This endpoint allows to specify a pre-shared key manually or use our bootstrapping endpoint to generate a pre-shared key coap://coap.os.1nce.com:5683/bootstrap
.
Example
Below is an example of retrieving the pre-shared key and client identity. First, a request is done to the CoAP bootstrapping endpoint, this request will result in the following CSV object:
preSharedKey,clientIdentity,coapsEndpointUrl
The following piece of code is used to process the shown above response, so the device is fully onboarded with credentials and ready to send messages. In the security parameters object the clientIdentity and preSharedKey will be set and these parameters will be passed to the CoAP DTLS client.
const coapDtls = require("node-coap-client").CoapClient;
async function coapPostDtls(clientIdentity, preSharedKey, postPayload) {
const securityParameters = {
psk: {
[clientIdentity]: preSharedKey,
},
};
coapDtls.setSecurityParams(coapsUrl, securityParameters);
try {
const result = await callPost(coapDtls, coapsUrl, postPayload);
return result;
} catch(e) {
return e;
}
}
In the following snippet, the initialized client will be used to send a message.
const coapDtls = require("node-coap-client").CoapClient;
async function callPost(client, url, postPayload) {
console.log("Calling: ", url);
try {
const pingSuccess = await client.ping(url /* string | url | Origin */, [
2000,
]);
if (!pingSuccess) {
console.log("Ping request failed");
throw Error(`Ping to ${url} failed`);
} else {
console.log("Ping successfull");
}
const res = await client.tryToConnect(url);
console.log("Connection attempt result: ", res);
if (res) {
const payload = Buffer.from(postPayload);
const options = {
/** Whether to keep the socket connection alive. Speeds up subsequent requests */
keepAlive: true,
/** Whether we expect a confirmation of the request */
confirmable: confirmable,
/** Whether this message will be retransmitted on loss */
retransmit: false,
};
const result = await client.request(
url /* string */,
"post" /* "get" | "post" | "put" | "delete" */,
payload /* Buffer */,
options /* RequestOptions */
);
result.code = result.code.toString();
printResponseHeaderBody(result);
const resultObj = generateResponseObject(result.code, result.payload.toString());
if (result.code !== "2.04") {
throw new Error(resultObj);
}
return resultObj;
}
} catch (error) {
console.log("Coap Error ", error);
throw error;
}
}
function generateResponseObject(respCode, body) {
return {
code: respCode,
message: body,
};
}
CoAP Endpoint Information
Base URL: coap.os.1nce.com
Protocol: CoAP(s)
Responses
Code | Description | Schema |
---|---|---|
200 | 200 Response | Client identity, Pre-sharded key (text/csv),coapsEndpointUrl |
401 | 401 Response | UnauthorizedResponse |
500 | 500 Response | ServerSideErrorResponse |
DTLS Bootstrapping Information
Information model:
The pre-shared key is valid indefinitely. If the bootstrapping is called 5 or more minutes after the last time bootstrapping was called, the pre-shared key will be regenerated with a new value.
Name | Type | Description |
---|---|---|
clientIdentity | string | The iccid of the device sim. |
preSharedKey | string | A pre shared key the device can use to authenticate itself on DTLS. |
UnauthorizedResponse
API responses when the Terms of Use and Data Processing Agreement are not accepted for the owner of the device:
Name | Type | Description |
---|---|---|
statusText | string | Http Status Text |
errors | [ object ] | Detailed Error Information |
ServerSideErrorResponse
API response in case of server-side errors:
Name | Type | Description |
---|---|---|
statusText | string | Http Status Text |
errors | [ object ] | Detailed Error Information |
Updated 6 days ago