TH | EN

CoAP API

CoAP (Constrained Application Protocol) is a type of protocol similar to HTTP, but HTTP is TCP while CoAP is UDP, which was developed to reduce the size of the data packets sent to be smaller, helping to reduce the use of resources, both memory for processing and power. Therefore, it is suitable for Microcontrollers that do not have much memory or want to save power, such as NB-IoT, with the main Endpoint being coap://coap.nexiiot.io, with the following details:

The usage example here is in Command Line format using NodeJS to install CoAP Client (Install NodeJS https://nodejs.org/en/download/ ). To install CoAP Client, run the following command in (Supported CoAP Client version must be 0.5.1 or higher).

npm i coap-cli@0.5.1 -g

1. Publishing messages to various topics

EndPoint	coap://coap.nexiiot.io/message/{any}/{topic}
Method	PUT
Parameter	auth=<ClientID>:<Token>
Payload	-p message
Return	The response code here will be undefined because the returned code has no value set.

Example (Command Line)

coap put "coap://coap.nexpie.io/message/home/bedroom?auth=6c36fdee-5273-4318-xxxx-75dfd2c513db:nzxGsGMYnFdfET6qbpifb32U9z5kxxxx" -p "Hello from CoAP"

In the example above, the message Hello from CoAP is published to the topic @msg/home/bedroom.

2. Reading Device Shadow Data

EndPoint	coap://coap.nexiiot.io/shadow/data
Method	GET
Parameter	auth=<ClientID>:<Token>
Return	Response Object {deviceid => ClientID, data => Shadow Data ของ Device (JSON), rev => Revision ของ Shadow, modified => Timestamp การแก้ไขล่าสุด}

Example (Command Line)

coap get "coap://coap.nexpie.io/shadow/data?auth=6c36fdee-5273-4318-xxxx-75dfd2c513db:nzxGsGMYnFdfET6qbpifb32U9z5kxxxx"

From the example above, it reads the Shadow data of Device ID : 6c36fdee-5273-4318-xxxx-75dfd2c513db and the returned value is:

{
        "deviceid":"6c36fdee-5273-4318-xxxx-75dfd2c513db",
        "data": {
                "humid":76.2, "temp":25
        },
        "rev":3,
        "modified":1605516471534
}

3. Writing to Shadow Data using merge operation

EndPoint	coap://coap.nexiiot.io/shadow/data
Method	PUT
Parameter	auth=<ClientID>:<Token>
Payload	-p {data: { Shadow Data (JSON) }}
Return	Response Object {``deviceid``(ClientID), ``data``(Shadow Data of Device (JSON)), ``modified``(Timestamp of last modification), ``timestamp``(Timestamp to mark data points if stored in Time-series data storage)}

Example (Command Line) {"deviceid":"6c36fdee-5273-4318-xxxx-75dfd2c513db","data":{"temp":30.4},"modified":1605518877506,"timestamp":1605518877506}

coap put "coap://coap.nexpie.io/shadow/data?auth=6c36fdee-5273-4318-xxxx-75dfd2c513db:nzxGsGMYnFdfET6qbpifb32U9z5kxxxx" -p "{data: {temp: 30.4} }"

From the example above, it is writing merged Shadow data of Device ID : 6c36fdee-5273-4318-ba7e-75dfd2c513db and the returned value is:

{
        "deviceid":"6c36fdee-5273-4318-xxxx-75dfd2c513db",
        "data": {
                "temp":30.4
        },
        "modified":1605518877506,
        "timestamp":1605518877506
}

Shadow Batch Update

It is used in cases where the IoT Device cannot send data to the Cloud Platform at the specified time, such as due to internet connection problems, etc. This causes the IoT Device to store data in its own memory first, such as on an SD Card, etc. When the Cloud Platform can be connected, all stored data is sent to the Cloud Platform again. Values can be sent to the Platform at multiple points at the same time.

There are 3 ways to write batch shadows:

1. CoAP API is a batch data writing process that is performed through the CoAP Protocol, which can be written as a merge or overwrite. The details are as follows:

EndPoint	coap://coap.nexiiot.io/shadow/batch
Method	PUT (Merge) or POST (Overwrite)
Parameter	auth=<ClientID>:<Token>
Payload	-p {"ackid" : ID value, "batch" : [ {"data":{ Shadow Data 1 }, "ts": time 1}, {"data":{ Shadow Data 2 }, "ts": time 2}, ...,{"data":{ Shadow Data n }, "ts": time n} ], "merged": true or false }
Return	Response Object {``deviceid``(ClientID), ``response``(Shadow update summary (JSON))}

Example (Command Line)

coap put "coap://coap.nexpie.io/shadow/batch?auth=6c36fdee-5273-4318-xxxx-75dfd2c513db:nzxGsGMYnFdfET6xxxxfb32U9z5kuhvx" -p '{"ackid" : 1234,"batch" : [{"data":{"humid":9.6}, "ts":-90000},{"data":{"humid":9.8}, "ts":-60000},{"data":{"humid":9.1}, "ts":-30000},{"data":{"temp":26.8}, "ts":0}]}'

From the example above, it is writing a batch of Shadow data in a merged format of Device ID : 6c36fdee-5273-4318-xxxx-75dfd2c513db and the returned value is:

{
        "deviceid":"6c36fdee-5273-4318-xxxx-75dfd2c513db",
        "response": {
                "ackid":1234,
                "total":4,
                "mints":1619088626897,
                "maxts":1619088716897
        }
}

Note

The time of each data set is in milliseconds. You can use ts or timestamp as the field name. If the value is less than 1000 * 2^23 = 8388608000, it is considered a relative time with the current time. If the value is greater, it is considered an absolute time. You can use negative values ​​to represent the past time, which is suitable for updating past data points. For example, if ts or timestamp is set to -90000 and the current timestamp is 1619075885, the time of the data point will be 1619075885 - 90000 = 1618985885 (90 seconds back from the present).

The ackid is used as a reference value for the response of each request. It can be set to any value, such as a number or a string. Every response is repeated with the same ackid value, so that the user can match the request with the response.

The merged field specified in the payload when writing to the Shadow determines the data writing method—whether to merge or overwrite.

• If merged : true is set, the data will be merged.

• If merged : false is set, the data will be overwritten.

• If this field is not specified in the payload, the default value is true, meaning the data will be merged.

The operation of the Expression defined in the Schema and Trigger when writing to the Shadow in batch mode.

The Expression will still be calculated according to the formula defined for each data set, similar to a For Loop writing to the Shadow. However, when writing to the Shadow in batch mode, the Shadow read/write quota will only be deducted as 1 operation. The Shadow Expression quota will still be deducted according to the number of data sets. For example, if 100 data points are sent for storage and there is 1 field with an Expression set, the number of Shadow Expressions deducted will be 1 x 100 = 100 operations.

For Triggers, they will only operate on the data set with the latest value (the highest timestamp). The quota will be deducted as if writing only a single data set.

2. MQTT supports batch data writing using Topic and Payload. For more details, see: Shadow Batch Update

3. REST API is a batch data writing method that is performed through a REST API, which can be written in either a merge or overwrite mode. See Shadow Batch Update

Caution

When performing a batch write to the Shadow, there is a limit of 100 records per operation. These records must be included in the batch field as a JSON array. For instance, a sample payload would be:

{ "ackid" : 1234, "batch" : [ {"data":{"temp":25.9, "humid":9.6}, "ts":-90000}, {"data":{"temp":25.3, "humid":9.8}, "ts":-60000}, {"data":{"temp":24.5, "humid":9.1}, "ts":-30000}, {"data":{"temp":26.8, "humid":8.2}, "ts":0}], "merged": true }

In this example, there are 4 data entries. If the number of entries exceeds the allowed limit, the entire batch will be rejected, and a warning message will be returned in JSON format as shown below:

{"ackid":1234,"errcode":429,"message":"batch size exceeds 100","inputsize": 102}

In other words, a batch write request with ackid = 1234 exceeded the limit by including 102 entries instead of the maximum allowed 100.