CoAP 集成

• Prerequisites
• Create the integration and the converter templates
  • Basic settings
  • Uplink data converter
  • Connection
• Add the attribute to the Edge
• Assign the integration to the Edge.
• Send an uplink message
• 下一步

Edge CoAP Integration 与 CoAP Integration 实现方式类似。 区别仅在于 integration 的创建与部署方式。 操作前请参阅 CoAP Integration 文档。

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

To learn more, please review the integration diagram.

Prerequisites

This tutorial explains how to configure the CoAP integration with the NO SECURE security mode.

• To simulate a CoAP device, please install the coap-client. This utility simulates a CoAP client that connects to the CoAP integration.

1
2
sudo apt update
sudo apt install libcoap2-bin

• To verify that the coap-client utility is installed, run:

1
coap-client --version

• For example, consider a sensor that transmits temperature and humidity values periodically. The sensor device SN-001 publishes its temperature and humidity readings to the CoAP Integration at coap://10.7.3.0. Here, 10.7.3.0 represents the IP address of the ThingsBoard Edge within the local network. Replace this address with the actual IP of the relevant Edge instance in the target environment.

For demonstration purposes, it is assumed that the device can transmit data using three different payload types:

• The Text payload is:

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

• The JSON payload is:

  1
  2
  3
  4
  5
  6
  {
  "deviceName": "SN-001",
  "deviceType": "default",
  "temperature": 25.7,
  "humidity": 69
  }
  

• The Binary payload (in HEX string):

  1
  \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: The device name. If we convert it to text, it is SN-001;
  • 6-12 bytes - \x64\x65\x66\x61\x75\x6c\x74: The device type. If we convert it to text, it is default;
  • 13-16 bytes - \x32\x35\x2e\x37: The temperature telemetry. If we convert it to text, it is 25.7;
  • 17-18 bytes - \x36\x39: The humidity telemetry. If we convert it to text, it is 69;

The payload type selection should be based on the device’s capabilities and the intended use case.

Create the integration and the converter templates

Only the ThingsBoard Professional Edition creates converters and integration templates.

So please use ThingsBoard Cloud or install your own platform instance to log in as a Tenant administrator.

Basic settings

To add the CoAP integration:

• Go to the Edge management > Integration templates section and click the “plus” button to add a new integration.
• On the Basic settings step, select the Integration type and enter the Integration name in the corresponding fields. Enable Debug mode. Click the "Next" button.

Debug 模式在开发与故障排查中非常有用，但在生产环境中保持启用会显著增加数据库存储需求，因为所有调试数据均会存入数据库。

强烈建议在调试完成后 禁用 Debug 模式。

Uplink data converter

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. Attributes and telemetry are flat key-value objects. Nested objects are not supported.

For this example, use the code below.

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

Select the device payload type to for the decoder configuration:

Text payload

JSON payload

Binary payload

Select the “Create new” tab and enter the converter name. Copy and insert the TBEL Decoder function script: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 /** 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; After adding the uplink converter, click the “Next” button. 若需使用 JavaScript 开发转换函数，请使用 适用于 JS 的 text payload 脚本。

Select the “Create new” tab and enter the converter name. Copy and insert the TBEL Decoder function script: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 /** 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; After adding the uplink converter, click the “Next” button. 若需使用 JavaScript 开发转换函数，请使用 适用于 JS 的 JSON payload 脚本。

Select the “Create new” tab and enter the converter name. Copy and insert the TBEL Decoder function script: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 /** 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; After adding the uplink converter, click the “Next” button. 若需使用 JavaScript 开发转换函数，请使用 适用于 JS 的 binary payload 脚本。

Connection

• Enter the IP address of your Edge instance (host) and the CoAP binding port in format host:port as the Base URL.
• Alternatively, use the placeholder ${{ATTRIBUTE_KEY}} substitute the integration field with an attribute value from a specific Edge entity. In this example, the placeholder ${{edgeIp}} is used for the Base URL.
• Click the “Add” button to create the integration.

Add the attribute to the Edge

After creating the converter and integration templates, the integration template can be assigned to the Edge instance.

Since the placeholder ${{edgeIp}} is used in the integration configuration, it is necessary to add the edgeIp attribute to the Edge instance first.

Use the IP address of the Edge instance and the CoAP binding port as the edgeIP attribute (e.g., 10.7.3.0:15683). Once the attribute is added, the integration can be assigned.

• Go to the Edge management > Instances section, click on the Edge instance to open the Edge details page and select the "Attributes" tab. To add a new server attribute to Edge, click the "Add" button (the + icon) .
• Enter the name of the attribute (i.g. "edgeIp") and use the Edge IP address and CoAP bind port in the following format: host:port. Then, click the "Add" button.
• Confirm the added "edgeIP" server attribute to the Edge.

Assign the integration to the Edge.

To assign the integration to the Edge, on the Edge management > Instances section:

• Click the "Manage edge integrations" button of the Edge entity.
• Click the "+" button in the top right of the corner. Specify your integration and click the "Assign" button to assign it to the Edge.
• Login to your ThingsBoard Edge instance and go to the Integrations center > Integrations section. You should see your integration. To open the "Integration details" window, click on it.
• In the "Integration details"" window, the ${{edgeIP}} placeholder will be replaced with the value of the attribute.

Send an uplink message

Once the CoAP Integration has been created, the CoAP server registers appropriate resources, and then it waits for data from the devices.

To send the uplink message:

• Log in to ThingsBoard Edge and go to the Integrations center > Integrations section.
• Click on the CoAP integration.
• Copy the CoAP endpoint URL and insert it into the uplink message.

Select the device payload type:

Text payload

JSON payload

Binary payload

发送上行消息： 1 echo -e 'SN-001,default,temperature,25.7,humidity,69' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t text/plain -f- 请将 $YOUR_COAP_ENDPOINT_URL 替换为对应值。 查看上行消息： 进入 Integrations center > Integrations（集成中心 > 集成）部分并点击该集成 在 「Integration details」（集成详情）页面选择 「Events」（事件）选项卡 检查上行消息状态。若配置正确，状态将显示为 「OK」。 消息发送后，将创建新设备。 查看创建的设备及其数据： 进入 Entities > Devices（实体 > 设备）部分并点击该设备 在 「Device details」（设备详情）页面选择 「Latest telemetry」（最新遥测）选项卡。 接收到的数据可在 Uplink converter（上行转换器）中查看： 进入 Integrations center > Data converters（集成中心 > 数据转换器）部分并点击 Uplink converter 在 「Data converter details」（数据转换器详情）页面，选择 「Events」（事件）选项卡 在 「In」 和 「Out」 列中查看消息详情。

发送上行消息： 1 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- 请将 $YOUR_COAP_ENDPOINT_URL 替换为对应值。 查看上行消息： 进入 Integrations center > Integrations（集成中心 > 集成）部分并点击该集成 在 「Integration details」（集成详情）页面选择 「Events」（事件）选项卡 检查上行消息状态。若配置正确，状态将显示为 「OK」。 消息发送后，将创建新设备。 查看创建的设备及其数据： 进入 Entities > Devices（实体 > 设备）部分并点击该设备 在 「Device details」（设备详情）页面选择 「Latest telemetry」（最新遥测）选项卡。 接收到的数据可在 Uplink converter（上行转换器）中查看： 进入 Integrations center > Data converters（集成中心 > 数据转换器）部分并点击 Uplink converter 在 「Data converter details」（数据转换器详情）页面，选择 「Events」（事件）选项卡 在 「In」 和 「Out」 列中查看消息详情。

发送上行消息： 1 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- 请将 $YOUR_COAP_ENDPOINT_URL 替换为对应值。 查看上行消息： 进入 Integrations center > Integrations（集成中心 > 集成）部分并点击该集成 在 「Integration details」（集成详情）页面选择 「Events」（事件）选项卡 检查上行消息状态。若配置正确，状态将显示为 「OK」。 消息发送后，将创建新设备。 查看创建的设备及其数据： 进入 Entities > Devices（实体 > 设备）部分并点击该设备 在 「Device details」（设备详情）页面选择 「Latest telemetry」（最新遥测）选项卡。 接收到的数据可在 Uplink converter（上行转换器）中查看： 进入 Integrations center > Data converters（集成中心 > 数据转换器）部分并点击 Uplink converter 在 「Data converter details」（数据转换器详情）页面，选择 「Events」（事件）选项卡 在 「In」 和 「Out」 列中查看消息详情。

下一步

• Getting started guide（入门指南）- 快速概览 ThingsBoard Edge 主要功能。预计 15–30 分钟完成：

• Installation guides（安装指南）- 了解如何在各种操作系统上安装 ThingsBoard Edge 并连接到 ThingsBoard Server。

• Edge 规则引擎：

  • Rule Chain Templates（规则链模板）- 了解如何使用 ThingsBoard Edge 规则链模板。

  • Provision Rule Chains from cloud to edge（从云端向 Edge 下发规则链）- 了解如何从云端向 Edge 下发边缘规则链。

• 安全：
  • gRPC over SSL/TLS - 了解如何为 Edge 与云端之间的通信配置 gRPC over SSL/TLS。

• 功能：

  • Edge Status（Edge 状态）- 了解 ThingsBoard Edge 上的 Edge Status 页面。

  • Cloud Events（云端事件）- 了解 ThingsBoard Edge 上的 Cloud Events 页面。

• 使用场景：

  • Manage alarms and RPC requests on edge devices（在边缘设备上管理告警和 RPC 请求）- 本指南展示如何在 Edge 上生成本地告警并向连接到 Edge 的设备发送 RPC 请求：

  • Data filtering and traffic reduce（数据过滤与流量削减）- 本指南展示如何从 Edge 向云端仅发送过滤后的设备数据：

• Roadmap（路线图）- ThingsBoard Edge 路线图。