Home
/
Docs
/
Documentation
/
User Guide
/
CoAP Integration

CoAP Integration

Overview

CoAP Integration allows to stream data from devices that use a CoAP protocol to connect to NexAI and converts payloads of these devices into the NexAI format.

Prerequisites

In this tutorial, we will show you how CoAP integration works as part of tb-core service with NO SECURE security mode selected. In order to do this we will use:

The instance of NexAI
coap-client utility which is intended to simulate CoAP client that will connect to CoAP integration;

Let’s assume that we have a sensor which is sending current temperature and humidity readings. Our sensor device SN-001 publishes it’s temperature and humidity readings to CoAP Integration on coap://localhost URL.

For demo purposes we assume that our device is smart enough to send data in 3 different payload types:

Text – in this case payload is:

SN-001,default,temperature,25.7,humidity,69

JSON – in this case payload is:

{
  "deviceName": "SN-001",
  "deviceType": "default",
  "temperature": 25.7,
  "humidity": 69
}

Binary – in this case, the payload looks like this (in HEX string):

\x53\x4e\x2d\x30\x30\x31\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39

Here is the description of the bytes in this payload:

0-5 bytes – \x53\x4e\x2d\x30\x30\x31 – device name. If we convert it to text – SN-001;
6-12 bytes – \x64\x65\x66\x61\x75\x6c\x74 – device type. If we convert it to text – default;
13-16 bytes – \x32\x35\x2e\x37 – temperature telemetry. If we convert it to text – 25.7;
17-18 bytes – \x36\x39 – humidity telemetry. If we convert it to text – 69;

You can use payload type based on your device capabilities and business cases.

Uplink Converter

Before setting up an CoAP integration, you need to create an Uplink Converter that is a script for parsing and transforming the data received by CoAP integration to format that NexAI uses. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

To create an Uplink Converter go to Data Converters section and Click Add new data converter —> Create new converter. Name it “CoAP Uplink Converter” and select type Uplink. Use debug mode for now.

NOTE
Although the Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode may tremendously increase the disk space, used by the database, because all the debugging data is stored there. It is highly recommended to turn the Debug mode off when done debugging.

Choose device payload type to for decoder configuration:

Text payload

One can use either NAEL (NexAI expression language) or JavaScript to develop user defined functions. We recommend utilizing NAEL as it’s execution in NexAI is much more efficient compared to JS.

 /** Decoder **/ // decode payload to string var strArray = decodeToString(payload); var payloadArray = strArray.replaceAll("\"", "").split(','); var telemetryPayload = {}; for (var i = 2; i < payloadArray.length; i = i + 2) { var telemetryKey = payloadArray[i]; var telemetryValue = parseFloat(payloadArray[i + 1]); telemetryPayload[telemetryKey] = telemetryValue; } // Result object with device attributes/telemetry data var result = { deviceName: payloadArray[0], deviceType: payloadArray[1], telemetry: telemetryPayload, attributes: {} }; /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/ return result;

JSON payload

One can use either NAEL (NexAI expression language) or JavaScript to develop user defined functions.

/** Decoder **/ // decode payload to JSON var data = decodeToJson(payload); // Result object with device/asset attributes/telemetry data var deviceName = data.deviceName; var deviceType = data.deviceType; var result = { deviceName: deviceName, deviceType: deviceType, attributes: {}, telemetry: { temperature: data.temperature, humidity: data.humidity } }; /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/ return result;

Binary payload

/** Decoder **/ // decode payload to string var payloadStr = decodeToString(payload); // decode payload to JSON // var data = decodeToJson(payload); var deviceName = payloadStr.substring(0,6); var deviceType = payloadStr.substring(6,13); // Result object with device/asset attributes/telemetry data var result = { deviceName: deviceName, deviceType: deviceType, attributes: {}, telemetry: { temperature: parseFloat(payloadStr.substring(13,17)), humidity: parseFloat(payloadStr.substring(17,19)) } }; /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/ return result;