平台集成

ThingsBoard PE 功能

仅专业版支持Platform Integrations功能。
请使用ThingsBoard Cloud或自行安装平台实例。

• 工作原理
• 上行数据转换器
  • 通用上行数据转换器
  • 类型化上行数据转换器
  • 测试解码函数
    • Payload
    • Metadata
    • Converter output
• 下行数据转换器
  • Converter output
  • 同步与异步下行
  • 示例
• 转换器库
• Debug mode
• 部署方式
  • 嵌入式集成
  • 远程集成
• 平台集成与IoT Gateway
• 功能规划
  • 使用统计
  • 更多集成与协议
  • 更多数据转换器
• 另见
• 视频教程
• 下一步

ThingsBoard平台集成功能面向两大用例/部署方式：

• 将采用特定负载格式的NB IoT、LoRaWAN、SigFox等设备直接接入ThingsBoard平台。
• 从已接入现有物联网平台的设备流式传输数据，以支持实时交互式仪表板及高效数据处理。

两类用例有若干共同点。部署拓扑中均有服务端组件阻止直接访问设备，并提供一组API与现场设备交互。 设备负载格式未统一，同类传感器的不同厂商甚至不同版本往往使用不同格式。

ThingsBoard集成的职责是在核心平台能力（遥测采集、属性与RPC调用）与特定第三方平台API之间提供安全、可靠的API桥接。

工作原理

ThingsBoard目前支持多种集成协议，以HTTP、MQTT、OPC-UA最为常用。 平台也支持与LoRaWAN网络服务器、Sigfox后端、各类NB IoT设备等的集成，可通过原始UDP和TCP集成。 AWS IoT、IBM Watson、Azure Event Hub等支持通过MQTT或AMQP订阅设备数据流。

平台集成列表持续增加，但整体集成概念相同，说明如下。

消息从外部平台到达ThingsBoard后，会按平台特定负载格式和安全规则进行校验。 校验通过后，ThingsBoard集成会调用已配置的上行数据转换器，从入站消息中提取有效信息子集。 消息将设备及平台特定的负载转换为ThingsBoard所需格式。

自TB PE v2.0起，规则引擎也可向集成推送下行消息。此类消息示例包括：

• 共享属性（配置）更新的通知；
• 单向RPC调用以触发设备侧操作的通知；
• 来自规则引擎的任意自定义消息。

常见用例包括：

• 根据共享属性变化调整数据上报频率；
• 根据共享属性变化触发固件更新；
• 根据RPC调用改变设备状态；

规则引擎推送消息后，ThingsBoard会调用已配置的下行数据转换器，将规则引擎消息转换为集成所需的数据格式。

上行数据转换器

上行数据转换器的主要作用是将来自设备的入站消息负载（如MQTT、HTTP、CoAP等协议）解析并转换为ThingsBoard可处理的格式。

自ThingsBoard 4.0起，对于接收具有相同结构的负载消息的集成，编写转换器的流程已简化。 您可直接在界面中选择集成消息字段应写入属性还是遥测，无需在解码函数中手动定义。

该功能适用于下列集成的上行转换器：

• ChirpStack
• Loriot
• The Things Stack Community
• The Things Stack Industries
• ThingPark
• ThingPark Enterprise

4.0之前创建的转换器仍可使用并正常工作。

通用上行数据转换器

创建适用于所有集成类型的通用上行数据转换器，请按下列步骤操作：

• 进入“Integration center”的“Data converters”部分，点击“plus”图标，在下拉菜单中选择“Create new converter”。
• 在新窗口中：
  • 将转换器类型选择器设为“Uplink”。
  • 选择使用该转换器的integration type（如MQTT、OPC-UA等），若在多种集成中使用则保持”All”。
  • 输入转换器名称。
  • （可选）开发或测试时启用Debug mode以便排查问题。

调试模式

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

注意：调试模式可能迅速增加磁盘占用，因为所有调试事件都会存入数据库。 自ThingsBoard 3.9起，平台仅在uplink converter创建后的前15分钟内存储完整调试事件，之后仅保留错误事件。

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

• 在Main decoding configuration部分定义解码逻辑：使用提供的默认脚本或输入自定义脚本解析并转换入站数据。

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

• 配置advanced decoding parameters：
  • 为避免遥测或属性值的不必要更新，可使用“Update only keys list”字段。该列表中指定的键仅在其值与先前不同时才会更新。若某键出现在转换后的消息中但值未变，则跳过更新。

    注意：集群环境下，若消息由不同集成执行节点接收，或转换器配置已更新，“Update only keys list”中键对应的值可能会被多次更新。

• 配置完成后，点击“Add”创建并保存新转换器。

类型化上行数据转换器

类型化上行数据转换器面向特定集成类型。 为支持新版上行转换器功能的集成（ChirpStack、Loriot、The Things Stack Community、The Things Stack Industries、ThingPark、ThingPark Enterprise）创建上行数据转换器，请按下列步骤：

• “Integration type”字段列出所有支持的集成。本例使用 Loriot。
• 指定转换器名称。
• 进入“Main decoding configuration”部分：
  • 选择集成将创建的实体类型（Device或Asset）并指定实体名称。

    Entity name字段必填。默认遵循Device $eui（或Asset $eui）模式。在设备名称中需突出$模式。输入$时将出现Loriot消息的可用键列表，该列表为标准格式且不依赖具体消息内容。$eui模式将动态从Loriot消息获取设备唯一标识。

• 在Main decoding configuration部分定义解码逻辑：使用提供的默认脚本或输入自定义脚本解析并转换入站数据。

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

• 配置advanced decoding parameters：
  • Device profile、Device label、Customer name、Device group name字段非必填，可使用$模式动态填充。 若Device profile为空，将使用“default”。
  • 在Attributes和Telemetry部分分别指定应解释为属性和遥测的键。 若入站消息中缺少某指定键，转换器将忽略。
  • 为避免不必要更新，可使用“Update only keys list”字段。该列表中指定的键仅在其值发生变化时更新；若某键在转换消息中出现但值相同，则跳过更新。

    注意：集群环境下，若消息由不同集成执行节点接收，或转换器配置已更新，“Update only keys list”中键对应的值可能会被多次更新。

• 配置完成后，点击“Add”创建并保存新转换器。

测试解码函数

创建上行数据转换器时，可验证用于处理入站设备数据的解码逻辑。 点击“Test payload decoder”开始。 可模拟转换器如何处理实际负载，并据此微调解码函数。

Payload

Payload表示从设备接收到的编码输入数据。

注意：各集成类型有预填示例负载。可作为起点，或修改以匹配您集成的消息格式。

格式因集成类型而异，可为：

• JSON
• TEXT
• Binary (Base64)

  对于Binary (Base64) payload content type，负载会自动解码为字节数组，无需在脚本中手动解码。

可在解码脚本中使用payload关键字访问负载。

Metadata

Metadata是包含集成提供的特殊字段的键值映射。 可在解码脚本中使用metadata关键字引用这些值。

此外，可在各集成设置中配置自定义metadata参数。 例如，可定义deviceType等metadata参数，并在脚本中用于在创建设备时自动分配设备类型。

Converter output

Converter output以JSON展示解码函数返回的结果，包括设备值数组（如遥测或属性），也可包含遥测时间戳。 便于比对和验证解码数据如何被ThingsBoard解释与处理。

输出JSON中仅deviceName和deviceType为必填。

注意：自2.4.2起，ThingsBoard也支持使用assetName和assetType替代deviceName和deviceType。

注意：自2.4.2起，ThingsBoard支持可选的customerName和groupName。 这些参数将使ThingsBoard自动创建客户和/或实体组，并将实体分配给客户和/或组。

转换器输出数据示例：

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
26
{
  "entityType": "DEVICE",
  "name": "Device 1000000000000001",
  "profile": "default",
  "telemetry": [{
    "ts": 1684478801936,
    "values": {
      "battery": 95,
      "temperature": 36.6,
      "saturation": 99
    }
  }, {
    "rssi": -21,
    "data": "01755e030001040001",
    "battery": 94,
    "snr": 10,
    "fСnt": 2
  }],
  "attributes": {
    "serialNumber": "SN-12345678",
    "fPort": 85,
    "dr": "SF9 BW125 4/5",
    "frequency": 867500000,
    "eui": 1000000000000001
  }
}

下行数据转换器

下行数据转换器的主要作用是将规则引擎的入站消息及其metadata转换为对应集成使用的格式。

注意：下行转换器通常为可选。仅在集成需要ThingsBoard发送出站消息（如RPC、属性更新或其他命令）时需创建。若集成仅接收数据而不发起出站通信，可跳过创建下行转换器。

创建下行数据转换器步骤：

• 进入“Integration center”的“Data converters”部分，点击“plus”图标，在下拉菜单中选择“Create new converter”。
• 在新窗口中：
  • 将转换器类型选择器切换为“Downlink”。
  • 选择使用该转换器的integration type（如MQTT、OPC-UA等），若在多种集成中使用则保持”All”。
  • 输入转换器名称。
  • （可选）开发或测试时启用Debug mode以便排查问题。

调试模式

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

注意：调试模式可能迅速增加磁盘占用，因为所有调试事件都会存入数据库。 自ThingsBoard 3.9起，平台仅在downlink converter创建后的前15分钟内存储完整调试事件，之后仅保留错误事件。

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

• 在Main encoding configuration部分定义编码逻辑：输入用于解析并转换输出数据的script。

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

• 点击”Add“按钮创建并保存新转换器。

下行转换器本质上是一个用户自定义函数，其签名如下：

1
function encoder(msg, metadata, msgType, integrationMetadata);

其中

ㅤ* msg — 规则引擎消息的JSON
ㅤ* metadata — 与消息相关的键值对列表（由规则引擎产生）
ㅤ* msgType — 规则引擎消息类型。详见预定义消息类型
ㅤ* integrationMetadata — 包含集成特定字段的键值映射。可在集成详情中为各集成配置额外metadata

Converter output

转换器输出应为符合以下结构的有效JSON文档：

1
2
3
4
5
6
7
{
    "contentType": "JSON",
    "data": "{\"tempFreq\":60,\"firmwareVersion\":\"1.2.3\"}",
    "metadata": {
        "topic": "temp-sensor/sensorA/upload"
    }
}

其中

ㅤ* contentType — JSON、TEXT或BINARY（Base64字符串），与集成类型相关
ㅤ* data — 按contentType的字符串数据
ㅤ* metadata — 与消息相关的键值对。例如MQTT集成使用的topic等

同步与异步下行

多数集成可异步处理发往设备的下行消息。 例如，规则引擎推送到基于MQTT的集成的每条消息会立即推送到对应外部MQTT broker。

但SigFox或通用HTTP集成等无法异步推送消息。 由于底层HTTP协议特性，这些集成只能在响应上行消息请求时同步推送下行信息。 此时，由规则引擎产生的最后一条下行消息会保存在队列中，直至该设备收到新的上行消息。

示例

假设通过ThingsBoard REST API更新了温度与湿度上报频率属性，并希望将该更新推送到外部MQTT broker（TTN、Mosquitto、AWS IoT等）。 您可能还想包含先前配置的“firmwareVersion”属性值，而该值在本次请求中并不存在。 推送更新使用的topic应包含设备名称。

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

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
26
27
28
29
30
31
32
33
34
35
// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

/** Encoder **/

var data = {};

// Process data from incoming message and metadata

data.tempFreq = msg.temperatureUploadFrequency;
data.humFreq = msg.humidityUploadFrequency;

data.firmwareVersion = metadata['ss_firmwareVersion'];

// Result object with encoded downlink payload
var result = {

    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",

    // downlink data
    data: JSON.stringify(data),

    // Optional metadata object presented in key/value format
    metadata: {
        topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
    }

};

return result;

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
26
27
28
29
30
31
32
33
34
35
// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

/** Encoder **/

var data = {};

// Process data from incoming message and metadata

data.tempFreq = msg.temperatureUploadFrequency;
data.humFreq = msg.humidityUploadFrequency;

data.firmwareVersion = metadata['ss_firmwareVersion'];

// Result object with encoded downlink payload
var result = {

    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",

    // downlink data
    data: JSON.stringify(data),

    // Optional metadata object presented in key/value format
    metadata: {
        topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
    }

};

return result;

为使集成执行下行处理，租户管理员需配置与下图类似的规则链：

完整规则链配置见此处。

转换器库

ThingsBoard转换器库是内置的上行解码函数集合，支持100多种设备及六种主流LoRaWAN网络服务器。 可显著简化与各类传感器和厂商的集成配置。

目前支持转换器库的集成有：ChirpStack、Loriot、The Things Stack Community、The Things Stack Industries、ThingPark、ThingPark Enterprise。 未来将支持更多集成。

访问转换器库：

• 进入“Integrations center”下的“Integrations”页面，点击“plus”图标开始创建新集成。
  • 选择当前支持转换器库的集成之一。
  • 点击“Next”继续。
• 在“Uplink data converter”标签：
  • 切换到“Library”选项。
  • 从下拉菜单中选择设备厂商。
  • 选择您使用的具体传感器型号，对应解码函数将自动加载到编辑器。
  • 如需要，配置高级解码选项。
  • 点击“Next”。
• 继续完成集成配置。

转换器库为开源项目，由ThingsBoard团队维护，托管在GitHub：链接。

Debug mode

Debug mode对开发和故障排查非常有用。 但长期开启会显著增加数据库占用的磁盘空间，因为所有调试数据都会写入数据库。 因此自3.9起，ThingsBoard仅在前15分钟内保存全部调试事件，之后只保留失败事件。 这些设置可组合或完全关闭。

部署方式

ThingsBoard集成有两种部署方式：嵌入式与远程。详见下方说明与架构图。

嵌入式集成

嵌入式集成运行在主ThingsBoard服务进程中，本质上属于单体部署。

优点： *部署新集成简便（在ThingsBoard UI中几步即可）； *消息交付延迟低；

缺点： *占用主ThingsBoard进程资源：网络连接、OS线程、CPU； *隔离程度低； *若ThingsBoard部署在云端，无法访问本地MQTT broker或OPC-UA服务器。

远程集成

自ThingsBoard PE v2.4.1起支持远程集成，支持新的部署模式。 可在本地网络安装远程集成，将数据流式传输到云。

假设您有本地部署的MQTT broker或OPC-UA服务器。 这些broker或服务器无独立公网IP，云端ThingsBoard实例无法直接连接。 但可将远程集成安装在本地网络内、靠近该服务器。 该集成会连接broker/服务器，拉取数据并存储在本地文件系统。 网络可用时，远程集成会将数据流式传输到云端的ThingsBoard实例。

优点： *支持与本地网络中的服务器集成； *将集成进程与主ThingsBoard进程隔离；

缺点： *需额外安装独立包；

按本指南配置远程运行集成。

平台集成与IoT Gateway

熟悉ThingsBoard的用户可能注意到，集成功能与 IoT Gateway 有部分重叠。 但两者有重要差异：

• IoT Gateway面向本地网络部署，集成面向服务到服务集成。
• IoT Gateway面向 < 1000设备规模，集成面向高吞吐、可扩展及作为ThingsBoard服务一部分的集群部署。
• Gateway添加自定义负载解码器需重新编译并重启，而Integration Converter是可在运行中修改的JS函数。

两者都重要，适用于不同场景。

功能规划

使用统计

计划记录各集成处理的消息数量统计，并可设置租户/系统级别的处理量限制。

更多集成与协议

计划为不同平台及通信协议（如gRPC）提供更多专门集成。

更多数据转换器

计划收集并维护市面主流设备的数据转换器，进一步简化集成。 您可将自己的转换器分享给社区或提交给我们，以便纳入官方发行版。

联系我们为您的用例建议缺失功能。

另见

查看与具体集成相关的指南和视频教程：

• HTTP
• MQTT
• AWS IoT
• AWS Kinesis
• IBM Watson IoT
• Azure Event Hub
• Azure IoT Hub
• Actility ThingPark
• TheThingsIndustries
• SigFox
• OceanConnect
• TheThingsStack
• OPC-UA
• TCP
• UDP
• Custom
• LORIOT
• Kafka
• ChirpStack
• CoAP

视频教程

观看下方视频，了解如何分步配置上行数据转换器。

下一步

• 快速入门指南 - 快速了解ThingsBoard主要功能，约15-30分钟完成。

• 数据可视化 - 配置ThingsBoard复杂仪表盘的说明。

• 数据处理与操作 - 学习使用ThingsBoard规则引擎。

• IoT数据分析 - 学习使用规则引擎执行基本分析任务。

• 高级功能 - 了解ThingsBoard高级功能。