CoAP Endpoint

CoAP Overview

The CoAP Endpoint coap://coap.os.1nce.com:5683 hosts a POST endpoint on the server root path (/) or on the /data path if device firmware for some reason cannot send to the root path. The endpoint supports both normal, non-translatable messages and translatable messages by using the Energy Saver, with a safe payload size of up to 1024 bytes.

The POST endpoint takes an optional query parameter (or Location-Query) t to provide the MQTT topic used for forwarding this message to an MQTT broker (e.g., coap://coap-service:5683/?t=topicName or coap://coap-service:5683/data?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 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) response 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 a message confirmation mechanism. Each CoAP request has to be acknowledged by the server, so that the client can be sure that the message was processed:

There are a few key moments that allow reliable communication:

1. To maximize the chance that the message succeeds even in a lossy network environment, CoAP has a retransmission mechanism. The client re-sends 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, the EXCHANGE_LIFETIME value is 247 seconds.
2. CoAP messages contain a Message ID (also known as MID) to detect duplicates due to retransmissions. The Message ID has to be unique during the EXCHANGE_LIFETIME, so the client's endpoint should be able to specify a unique MID value if messages are being sent often enough. Most high-level CoAP clients manage MID uniqueness internally, but for low-level clients like the Quectel BG95 modem, it can be specified in the AT command as msgID:

AT+QCOAPHEADER=<clientID>,<msgID>,<mode>[,<TKL>,<token>]

There are two examples of the retransmission situation in a single exchange lifetime:

• The client's CON message did not reach the server. The client resends the same CON message with the same MID.
• The server's ACK message did not reach the client. The client resends the same CON message with the same MID (because there was no acknowledgment). The server responds with the same ACK because it sees the already-processed MID and does not process the request again.

DTLS Encryption for CoAP

Ensuring data is securely sent from a device to 1NCE OS is an important part of gaining customer trust. 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 without the possibility of messages being read or modified along the way. The diagram above describes this process. First, when the device is ready to onboard itself, it calls the CoAP bootstrapping endpoint. This retrieves the necessary DTLS credentials to onboard securely and initialize the CoAP connection using a PSK.

To utilize DTLS encryption with 1NCE OS, a pre-shared key (PSK) is essential for securing data. This key encrypts and decrypts transmitted data. Devices can connect securely using CoAP with DTLS by accessing the endpoint coaps://coap.os.1nce.com:5684 or coaps://coap.os.1nce.com:5684/data. To retrieve the PSK, send a GET request to coap://coap.os.1nce.com:5683/bootstrap. This endpoint will return an existing key, or if none is available, it will generate and provide a new one. Additionally, you can manually set the PSK (in plaintext or HEX format):

• Through the 1NCE OS API endpoint described in API Explorer.
• In the 1NCE OS portal Device Integrator when testing the CoAP endpoint.

DTLS Bootstrapping Information

The pre-shared key is valid indefinitely. If the bootstrapping is called 5 or more minutes after the last time bootstrapping was called and the pre-shared key was not set previously by the user, 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
coapsEndpointUrl	string	The CoAPS endpoint URL for DTLS-encrypted communication

Example response:

8988280666000000000,aB3dEf7hIjKlMnOp,coaps://coap.os.1nce.com:5684

For a complete runnable example of sending CoAP messages (with optional DTLS), see the CoAP Code Examples page.

Location Endpoint

The Location Endpoint at path /location allows IoT devices to retrieve their last known geographic position. The device is identified using the SIM-as-an-Identity principle and supports only the GET method. Non-GET requests receive a CoAP 4.05 (Method Not Allowed) response.

The endpoint is accessible via:

• Plain CoAP: coap://coap.os.1nce.com:5683/location
• DTLS-encrypted CoAPS: coaps://coap.os.1nce.com:5684/location

Response Format

A successful request returns a CoAP 2.05 (Content) response with Content-Format set to text/plain. The response body is formatted as CSV with a comma (,) delimiter and line-feed (\n) line ending. The first row is a header line with column names.

Response information model:

Name	Type	Description
Longitude	string (decimal degree numeric)	Geographic longitude of the device
Latitude	string (decimal degree numeric)	Geographic latitude of the device
Source	string	Identifier of the location source (e.g., GPS, CellTower)
SampleTime	string (integer EPOCH seconds)	Timestamp of the location measurement in seconds since 1970-01-01 UTC

Example response:

Longitude,Latitude,Source,SampleTime
13.404954,52.520008,GPS,1700000000

Authentication

The device is authenticated by source IP address lookup. The CoAP server resolves the device identity from the requesting IP address. Devices can access the Location Endpoint via plain CoAP (coap://coap.os.1nce.com:5683/location) or securely via DTLS-encrypted CoAPS (coaps://coap.os.1nce.com:5684/location) using a PSK obtained from the /bootstrap endpoint.

For details on obtaining PSK credentials for DTLS encryption, see the DTLS Encryption for CoAP section.

If the source IP address does not match any registered device, the endpoint returns CoAP 4.01 (Unauthorized).

Response Codes

The following table lists all response codes returned by the Location Endpoint:

Code	Description	Payload
2.05	Content — Successful response with CSV location data	CSV location data
4.00	Bad Request — Invalid request	Empty
4.01	Unauthorized — Device not recognized	Empty
4.03	Forbidden — Access denied	Empty
4.04	Not Found — No location data available for the device	Empty
4.05	Method Not Allowed — Non-GET request sent to the endpoint	Empty
5.02	Bad Gateway — Service temporarily unavailable	Empty
5.04	Gateway Timeout — Service did not respond in time	Empty

All error responses (4.xx and 5.xx) return an empty payload.

For runnable examples of retrieving device location (plain CoAP and DTLS), see the CoAP Code Examples page.

CoAP Endpoint Information

Base URL: coap.os.1nce.com
Protocol: CoAP(s)
Supported Paths:

• / or /data — for telemetry data
• /bootstrap — for DTLS bootstrapping
• /location — for device location retrieval (GET only)

Response Codes

Code	Description	Payload
2.04	Changed — Telemetry data accepted (/ and /data)	Empty
2.05	Content — Successful response	/bootstrap: CSV with clientIdentity, preSharedKey, coapsEndpointUrl; /location: CSV with Longitude, Latitude, Source, SampleTime
4.00	Bad Request — Invalid request	Empty
4.01	Unauthorized — Device not recognized	Empty
4.03	Forbidden — Access denied	Empty
4.04	Not Found — No data available for the device	Empty
4.05	Method Not Allowed — Unsupported method for the path	Empty
5.00	Internal Server Error	Empty
5.02	Bad Gateway — Service temporarily unavailable	Empty
5.04	Gateway Timeout — Service did not respond in time	Empty

Features & Limitations

Features

• Reliable messaging via CoAP confirmable messages with retransmission
• DTLS encryption for secure data transport using pre-shared keys
• Telemetry data forwarding to MQTT brokers via topic query parameter
• Device location retrieval via GET /location (plain CoAP and DTLS)
• Automatic device authentication via SIM-as-an-Identity

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 datagrams, and data larger than the size of a datagram network packet.