CoAP集成

概述
前置条件
上行转换器
CoAP集成配置
- CoAP集成配置项
发送上行消息
下一步

概述

CoAP集成用于从使用CoAP协议连接ThingsBoard的设备流式传输数据，并将这些设备的负载转换为ThingsBoard格式。

请参阅集成示意图了解更多。

前置条件

本教程演示CoAP集成作为tb-core服务一部分、选择NO SECURE安全模式时的工作方式。我们将使用：

ThingsBoard专业版实例——eu.thingsboard.cloud；
coap-client工具，用于模拟连接CoAP集成的CoAP客户端；

假设我们有一台正在发送当前温度和湿度读数的传感器。传感器设备SN-001将温度和湿度读数发布到CoAP集成的coap://int.eu.thingsboard.cloud URL。

演示中假设我们的设备支持3种负载类型：

Text — 负载格式为：

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

JSON — 负载格式为：

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

Binary — 负载示例（十六进制字符串）：

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

负载字节说明：

0-5字节 - \x53\x4e\x2d\x30\x30\x31 - 设备名称。转换为文本为SN-001；
6-12字节 - \x64\x65\x66\x61\x75\x6c\x74 - 设备类型。转换为文本为default；
13-16字节 - \x32\x35\x2e\x37 - 温度遥测。转换为文本为25.7；
17-18字节 - \x36\x39 - 湿度遥测。转换为文本为69；

可根据设备能力和业务场景选择负载类型。

上行转换器

配置CoAP集成前，需创建Uplink Converter，即用于将CoAP集成接收的数据解析并转换为ThingsBoard格式的脚本。deviceName和deviceType为必填，attributes和telemetry可选。attributes和telemetry为扁平键值对象，不支持嵌套。

创建Uplink Converter：进入Data Converters部分，点击Add new data converter —> Create new converter。命名为“CoAP Uplink Converter”，选择类型Uplink。暂时启用debug mode。

调试模式

启用调试模式可追踪与integrations执行相关的事件、状态及潜在错误，便于开发和排障。

调试模式设置可组合使用或完全关闭。

选择解码器配置使用的设备负载类型：

Text payload

可使用 TBEL（TBEL）或 JavaScript 开发用户自定义函数。建议使用 TBEL，其在ThingsBoard 中的执行效率远高于 JS。

TBELRecommended

JavaScript

请将以下脚本复制并粘贴到 Decoder function 区域：

/** 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;

请将以下脚本复制并粘贴到 Decoder function 区域：

/** Decoder **/

// decode payload to string
var strArray = decodeToString(payload);
var payloadArray = strArray.replace(/\"/g, "").replace(/\s/g, "").replace(/\\n/g, "").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 **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}
return result;

JSON payload

可使用 TBEL（TBEL）或 JavaScript 开发用户自定义函数。建议使用 TBEL，其在ThingsBoard 中的执行效率远高于 JS。

TBELRecommended

JavaScript

请将以下脚本复制并粘贴到 Decoder function 区域：

/** 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;

请将以下脚本复制并粘贴到 Decoder function 区域：

/** 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 **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);

   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}

return result;

Binary payload

TBELRecommended

JavaScript

请将以下脚本复制并粘贴到 Decoder function 区域：

/** 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;

请将以下脚本复制并粘贴到 Decoder function 区域：

/** 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 **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);

   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}

return result;

CoAP集成配置

Go to Integrations section and click Add new integration button. Name it CoAP Integration, select type COAP.
Add recently created CoAP Uplink Converter.
Copy CoAP endpoint URL - we will use it later in coap-client for testing CoAP Integration. Click "Add" to create an integration.

Go to Integrations section and click Add new integration button. Name it CoAP Integration, select type COAP.

Add recently created CoAP Uplink Converter.

Copy CoAP endpoint URL - we will use it later in coap-client for testing CoAP Integration. Click "Add" to create an integration.

CoAP集成配置项

CoAP集成可配置安全模式：

NO SECURE（默认模式）
DTLS
MIXED

此外，CoAP集成会根据Base URL路径及下列路径前缀自动生成CoAP endpoint URL：

/i - CoAP服务器中的集成资源
/$INTEGRATION_ROUTING_KEY — 自动生成的集成路由键

也可通过在基础URL前添加额外路径前缀来更新CoAP endpoint URL：

每个额外路径前缀都会作为CoAP资源添加到CoAP服务器，其中：

api - 父资源
v2 - api资源的子资源，也是集成资源i的父资源

发送上行消息

CoAP集成创建后，CoAP服务会注册相应资源并等待设备数据。

选择设备负载类型以发送上行消息

Text payload

JSON payload

Binary payload

使用以下命令向托管在 int.eu.thingsboard.cloud 上的 CoAP 服务器发送消息。请将 $YOUR_COAP_ENDPOINT_URL 替换为实际值。

echo -e 'SN-001,default,temperature,25.7,humidity,69' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t text/plain -f-

使用以下命令向托管在 int.eu.thingsboard.cloud 上的 CoAP 服务器发送消息。请将 $YOUR_COAP_ENDPOINT_URL 替换为实际值。

echo -e -n '{"deviceName": "SN-001", "deviceType": "default", "temperature": 25.7, "humidity": 69}' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t application/json -f-

使用以下命令向托管在 int.eu.thingsboard.cloud 上的 CoAP 服务器发送消息。请将 $YOUR_COAP_ENDPOINT_URL 替换为实际值。

echo -e -n '\x53\x4e\x2d\x30\x30\x31\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t application/octet-stream -f-

命令执行后，进入Device groups -> All，应能看到由集成配置的SN-001设备。点击该设备，进入Latest Telemetry标签页，可看到”temperature”键及其值（25.7），以及”humidity”键及其值（69）。

下一步

快速入门指南 - 快速了解ThingsBoard主要功能，约15-30分钟完成。
数据可视化 - 配置ThingsBoard复杂仪表盘的说明。
数据处理与操作 - 学习使用ThingsBoard规则引擎。
IoT数据分析 - 学习使用规则引擎执行基本分析任务。
高级功能 - 了解ThingsBoard高级功能。
贡献与开发 - 了解ThingsBoard贡献与开发。