CoAP 集成

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

概述

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

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

前置条件

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

本地安装的ThingsBoard专业版实例；
coap-client工具，用于模拟连接CoAP集成的CoAP客户端；

假设我们有一台正在发送当前温度和湿度读数的传感器。传感器设备SN-001将温度和湿度读数发布到CoAP集成的coap://localhost 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集成配置

进入Integrations部分，点击Add new integration。命名为CoAP Integration，选择类型COAP。
添加刚创建的CoAP Uplink Converter。
复制CoAP endpoint URL，后续将在coap-client中用于测试CoAP集成。点击"添加"创建集成。

进入Integrations部分，点击Add new integration。命名为CoAP Integration，选择类型COAP。

复制CoAP endpoint URL，后续将在coap-client中用于测试CoAP集成。点击"添加"创建集成。

CoAP集成配置项

CoAP集成可配置安全模式：

NO SECURE（默认模式）
DTLS
MIXED

后两种类型在创建集成前，需在 .yml中启用DTLS支持，或在 .conf中覆盖下列环境变量：

# Enable/disable DTLS 1.2 support
export COAP_DTLS_ENABLED=true
# Default CoAP DTLS bind port
export COAP_DTLS_BIND_PORT=5484 
# Path to the key store that holds the SSL certificate
export COAP_DTLS_KEY_STORE=coapserver.jks 
# Password used to access the key store
export COAP_DTLS_KEY_STORE_PASSWORD=server_ks_password
# Password used to access the key
export COAP_DTLS_KEY_PASSWORD=server_key_password
# Key alias
export COAP_DTLS_KEY_ALIAS=serveralias
# Skip certificate validity check for client certificates
export TB_COAP_X509_DTLS_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT=false

注意，上述环境变量使用默认DTLS配置。要在DTLS模式下正确启动CoAP服务，需至少更新key store配置。详见 CoAP over DTLS指南。

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

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

发送上行消息

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

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

Text payload

JSON payload

Binary payload

使用以下命令向托管在 localhost 上的 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-

使用以下命令向托管在 localhost 上的 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-

使用以下命令向托管在 localhost 上的 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贡献与开发。