IOT Gateway - ThingsBoard IoT网关入门-转载 - 《Thingsboard 二次开发中文文档》

原文地址]">[原文地址]
先决条件
步骤 1.选择安装选项
步骤 2.按照安装步骤操作
步骤 3.网关配置
步骤 4.网关配置
步骤 5.启动您的网关
步骤 6.查看网关统计信息
步骤 7.选择您的扩展
步骤 8.连接到外部 MQTT 代理
步骤 9.连接到外部 OPC-UA 服务器
步骤 10.连接到 Sigfox 后端
11. 连接到 Modbus 从机
另见
下一步

[原文地址]

本章涵盖 IoT 网关的安装和初始配置。我们将 IoT 网关连接到 ThingsBoard 服务器，并将网关的连接的设备数量和处理的消息等统计数据可视化:。我们还将配置 MQTT 和 OPC-UA 扩展，以便从外部设备或应用程序订阅反馈设备数据。

先决条件

如果您没有正常运行的 ThingsBoard 实例，请使用~~实时演示~~或安装指南来修复此问题。
注意，需要 1.1 或更高版本的 ThingsBoard。

步骤 1.选择安装选项

浏览可用的网关安装选项并选择最合适的安装指南。

步骤 2.按照安装步骤操作

按照所选网关安装指南中的步骤 (1-3) 操作。网关配置步骤如下。

步骤 3.网关配置

为了将 IoT 网关连接到 ThingsBoard 服务器，您需要首先设置网关凭据。我们将使用访问令牌凭据作为最简单的凭据。有关更多详细信息，请参见设备身份验证选项。
以租户管理员身份登录。在本地 ThingsBoard 服务器的情况下使用~~默认凭据~~。打开设备，点击右下角的红色+按钮。

ThingsBoard IoT网关入门-转载 - 图1

填入网关名称并选中是网关复选框。

ThingsBoard IoT网关入门-转载 - 图2

注意: 网关和设备名称在当前租户的范围内应该是唯一的。
打开新的设备卡，点击复制访问令牌按钮。

ThingsBoard IoT网关入门-转载 - 图3

步骤 4.网关配置

Thingsboard 网关支持每个租户配置。这意味着每个租户都可以有自己的连接和扩展配置。
转到网关配置文件夹并编辑 tb-gateway.yml 文件。

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

将gateway.connection.host和gateway.connection.port属性更改为您的 ThingsBoard 主机地址 (如果是实时演示实例，请不要修改)。
将 gateway.connection.security.accessToken 属性更改为在步骤 3 中复制的访问令牌。
您的网关配置应该类似于此文件:

gateways:
  tenants:
    -
      label: "Tenant"
      reporting:
        interval: 60000
      persistence:
        type: file
        path: storage
        bufferSize: 1000
      connection:
        host: "${GATEWAY_HOST:YOUR_HOST}"
        port: 1883
        retryInterval: 3000
        maxInFlight: 1000
        security:
          accessToken: "${GATEWAY_ACCESS_TOKEN:YOUR_TOKEN}"    
      remoteConfiguration: true
server:
  address: "0.0.0.0"
  port: "9090"
updates:
enabled: "${UPDATES_ENABLED:true}"

remoteConfiguration 属性值为true，表示启用远程管理此租户的扩展配置 (通过 ThingsBoard GUI) ，否则为本地管理 (通过当前配置文件)

步骤 5.启动您的网关

按照所选安装指南中的步骤 (5-6) 操作。

步骤 6.查看网关统计信息

打开 ThingsBoard 服务器的 WEB 界面，查看从 ThingsBoard 网关上传的统计数据。以租户管理员身份登录并打开设备页面。点击网关设备卡。打开 最新遥测 选项卡，查看以下统计数据:devicesOnline、attributesUploaded和 telemetryUploaded。所有值都应设置为 0。

ThingsBoard IoT网关入门-转载 - 图4

UI 上存在这些值意味着您的网关已经成功连接到 ThingsBoard 服务器。

步骤 7.选择您的扩展

根据您的用例，您可以选择以下选项:

连接到 MQTT 代理
连接 OPC-UA 服务器
连接到 Sigfox 后端
连接到 Modbus 从机

或者按照说明执行所有步骤。

步骤 8.连接到外部 MQTT 代理

在这一步，我们将连接到外部 MQTT 代理，以便开始从第三方或旧应用程序和设备收集数据。
有两种选择:

File configuration
GUI configuration

8.1 MQTT 代理文件配置

打开网关配置文件夹并编辑 tb-gateway.yml 文件。配置文件夹位置:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

将 mqtt.Enable 属性值更改为 true。
我们将使用 Mosquitto MQTT 代理进行演示。有关如何安装此代理的说明，请参见 Mosquitto 下载页面。
注意: 默认情况下，Mosquitto 和 ThingsBoard 对 MQTT 服务使用相同的端口 (1883)。如果您想在同一台主机上使用 ThingsBoard 和 Mosquitto，您需要更改其中一台服务器中的 mqtt 端口。有关更多详细信息，请参见相应的 ThingsBoard 或 Mosquitto 文档。
因为我们使用托管在云端的 ThingsBoard 演示实例，所以我们将在本地安装 Mosquitto MQTT 代理，并使用默认的服务配置。
如果你决定使用其他 MQTT 部署外部主机或特定安全配置，请编辑 mqtt-config.json 文件修改连接参数。有关更多详细信息，请参见 MQTT 扩展配置指南。
使用以下命令重新启动网关

Windows: 
net stop tb-gateway
net start tb-gateway
Linux: 
sudo service tb-gateway restart

mqtt-config.json 文件中包含的示例配置允许将来自外部 MQTT 代理的 JSON 映射到 ThingsBoard 设备的属性和遥测。

8.2 MQTT 代理 GUI 配置

要通过 ThingsBoard GUI 配置 ThingsBoard 网关，必须在 tb-gateway.yaml 中启用 remoteConfiguration :

gateways:
  tenants:
    -
      label: "Tenant"
      # Some configuration omitted
      remoteConfiguration: true

如果 remoteConfiguration 设置为 false，GUI 配置将不会生效，ThingsBoard 网关将在配置文件中查找配置。
我们将使用 Mosquitto MQTT 代理进行演示。有关如何安装此代理的说明，请参见 Mosquitto 下载页面。
注意: 默认情况下，Mosquitto 和 ThingsBoard 对 MQTT 服务使用相同的端口 (1883)。如果您想在同一台主机上使用 ThingsBoard 和 Mosquitto，您需要更改其中一台服务器中的 mqtt 端口。有关更多详细信息，请参见相应的 ThingsBoard 或 Mosquitto 文档。
因为我们使用托管在云端的 ThingsBoard 演示实例，所以我们将在本地安装 Mosquitto MQTT 代理，并使用默认的服务配置。.
如果你决定使用其他 MQTT 部署外部主机或特定安全配置，请编辑 mqtt-config.json 文件修改连接参数。有关更多详细信息，请参见 MQTT 扩展配置指南。
转到设备，选择您的网关，然后单击扩展选项卡。
此时我们推荐下载和导入示例 MQTT 配置文件 mqtt-gui-extension-configuration.json。
您也可以一步一步地配置 MQTT 扩展，但这仅推荐已经熟悉 ThingsBoard IoT 网关的用户这么做。
单击导入扩展配置并上传刚下载的 mqtt-gui-extension-configuration.json 文件:

ThingsBoard IoT网关入门-转载 - 图5

导入配置时，单击编辑扩展按钮查看导入的配置。

ThingsBoard IoT网关入门-转载 - 图6

MQTT 扩展配置包含一个或多个代理配置:

ThingsBoard IoT网关入门-转载 - 图7

每个代理配置都有以下部分:

代理连接设置:
- 端口
- 主机
- 重试间隔
- 凭证
映射
连接请求
断开请求
属性请求
属性更新
服务器端 RPC

注意代理连接设置不是 ThingsBoard 服务器连接参数。这些设置适用于外部 MQTT 代理，ThingsBoard IoT 网关从该代理收集数据，然后将其发送到 ThingsBoard 服务器。网关从 tb-gateway.yml 文件中获取 ThingsBoard 服务器连接设置，如前所述。
在 MQTT 扩展配置详细信息部分详细描述了映射

8.3 MQTT 扩展配置详细信息

以下部分描述了 MQTT 扩展配置设置的每个部分，包括基于文件和 GUI 的。

8.3.1 基本映射示例

例如，下面列出的默认映射将强制网关订阅 sensors主题，并使用传入 json 消息中的 serialNumber 作为设备名称。类似，model和 temperaturejson 对象字段将映射到相应的 ThingsBoard 设备属性和遥测字段。

{
  "topicFilter": "sensors",
  "converter": {
    "type": "json",
    "filterExpression": "",
    "deviceNameJsonExpression": "${$.serialNumber}",
    "attributes": [
      {
        "type": "string",
        "key": "model",
        "value": "${$.model}"
      }
    ],
    "timeseries": [
      {
        "type": "double",
        "key": "temperature",
        "value": "${$.temperature}"
      }
    ]
  }
}

通过 GUI 配置的相同映射:

ThingsBoard IoT网关入门-转载 - 图8

让我们试用这个映射的作用。我们将使用 mosquitto_pub 命令模拟连接到外部 mqtt 代理的设备中的数据:

mosquitto_pub -h localhost -p 1883 -t "sensors" -m '{"serialNumber":"SN-001", "model":"T1000", "temperature":36.6}'

注意: 在 Windows 上，网关可能无法正确解析 JSON 字符串。您可能会在网关日志中看到以下错误:

com.fasterxml.jackson.core.JsonParseException: Unexpected character (''' (code 39)): was expecting double-quote to start field name

如果是这种情况，在外部使用双引号，在消息内部转义双引号，如下所示:

"{\"serialNumber\":\"SN-001\", \"model\":\"T1000\", \"temperature\":36.6}"

您应该在网关日志中观察以下日志消息:

... INFO  o.t.g.service.MqttGatewayService - [SN-001] Device Connected!

日志位于以下文件夹中:

Windows: YOUR_INSTALL_DIR/logs
Linux: /var/log/tb-gateway

现在，您可以到 ThingsBoard web 界面，并在设备页面上观察新的设备 SN-001。您可以单击该设备，并在相应的选项卡中观察传递的属性和遥测数据。
ThingsBoard IoT网关入门-转载 - 图9

8.3.2 映射 JSON 数组

默认情况下，网关通过将每个数组元素映射为单独的实体来支持 json 数组的映射。例如，以下命令将创建或更新两个设备: SN-002 和 SN-003。

mosquitto_pub -h localhost -p 1883 -t "sensors" -m '[{"serialNumber":"SN-002", "model":"M2", "temperature":42.0}, {"serialNumber":"SN-003", "model":"M3", "temperature":73.0}]'

8.3.3 将 MQTT 主题映射到设备名称

在某些情况下，设备名称是 MQTT 主题的一部分。在这种情况下，您可以使用正则表达式提取设备名称值。此正则表达式在 deviceNameTopicExpression 字段中配置。
请参见下面的发布命令和映射示例 (默认配置中已经存在):

mosquitto_pub -h localhost -p 1883 -t "sensor/SN-004/temperature" -m '{"value":36.6}'

{
  "topicFilter": "sensor/+/temperature",
  "converter": {
    "type": "json",
    "filterExpression": "",
    "deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/temperature)",
    "timeseries": [
      {
        "type": "double",
        "key": "temperature",
        "value": "${$.value}"
      }
    ]
  }
}

GUI 中的相同配置:

ThingsBoard IoT网关入门-转载 - 图10

8.3.4 高级映射语法和过滤

网关 MQTT 扩展使用 JsonPath 库提供灵活映射和过滤 JSON 结构的能力。您可以根据路径和过滤器示例定义过滤器表达式。

8.3.5 自定义 MQTT 消息映射器

作为网关开发人员，您可以使用以下接口 新建分支并添加自定义映射程序。如果您认为 PRs 对 ThingsBoard 社区有用，请随时为您的自定义映射器实现代码提交 PRs。

步骤 9.连接到外部 OPC-UA 服务器

这个例子将演示如何

连接到本地安装的运行在 Windows 上的 KEPServerEX 。
将样本 OPC-UA 标签值转换为 ThingsBoard 属性和遥测。
使用 ThingsBoard 小部件可视化 OPC-UA 标签值。

我们假设 KEPServerEX 已经安装在您的 Windows 机器上。我们将使用 Windows 10 和免费演示服务器。

9.1. 向 KEPServerEX 提供网关凭据

打开 KEPServerEXde 的 OPC UA Configuration Manager 应用程序，转到 Trusted Clients 页面。
从网关配置文件夹导入 example.der 证书。配置文件夹位置:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

注意: 为了演示目的，此证书被添加到配置文件夹中。证书和密钥都是公开访问的，因此不安全，也不适合生产使用。您可以为生产使用创建和配置自己的证书对。
注意: 如果提供的 example.der 证书已过期，或者您决定生成新证书，您可以使用以下命令获取新的示例.der:

keytool -genkeypair -v -alias gateway -dname "CN=Thingsboard Gateway, OU=TB, O=ThingsBoard, L=San Francisco, ST=CA, C=US" -keystore example.jks -keypass secret -storepass secret -keyalg RSA -keysize 2048 -validity 9999
keytool -importkeystore -srckeystore example.jks -destkeystore example.pfx  -srcstoretype JKS -deststoretype PKCS12 -srcstorepass secret -deststorepass secret -srcalias gateway -destalias gateway -srckeypass secret -destkeypass secret -noprompt
keytool -exportcert -alias gateway -keypass secret -keystore example.pfx -storepass secret -file example.der

ThingsBoard IoT网关入门-转载 - 图11

9.2. 添加服务器端点 KEPServerEX

如果您想在不同的主机上部署 ThingsBoard IoT 网关和 KEPServerEX，则需要此步骤。
需要将 KEPServerEX 配置为接受远程连接。打开 KEPServerEX 的 OPC UA Configuration Manager 应用程序，导航到 Server Endpoints 页面。

ThingsBoard IoT网关入门-转载 - 图12

注意需要重新启动 KEPServerEX。

9.3 启用 OPC-UA 扩展

9.3.1 OPC-UA 扩展名文件配置

如果您使用的是基于文件的配置，请转到网关配置文件夹并编辑 tb-gateway.yml 文件。配置文件夹位置:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

将启用 opc.enabled 属性值更改为 true。
如果你决定使用不同 OPC-UA 服务器部署外部主机或特定安全配置，请编辑 opc-config.json 文件修改连接参数。有关更多 OPC-UA 详细信息，请参见扩展配置指南。
opc-config.json 包含示例配置允许将 OPC-UA 标签映射到 ThingsBoard 设备属性和遥测。一旦启动，OPC-UA 扩展将使用此预定义配置监控您的 OPC-UA 服务器。
使用以下命令重新启动网关

Windows: 
net stop tb-gateway
net start tb-gateway
Linux: 
sudo service tb-gateway restart

9.3.2 OPC-UA 扩展 GUI 配置

您可以导入示例配置:
opc-ua-gui-extension-configuration.json
或者手动配置 OPC-UA 扩展。扩展配置的配置界面类似如下:
ThingsBoard IoT网关入门-转载 - 图13

注意: 使用远程配置时，网关不会在本地文件系统中查找密钥库文件，而是直接从从 ThingsBoard 服务器接收的配置中读取。示例 opc-ua-gui-extension-configuration.json 不包含密钥库数据。导入示例配置后，您需要通过单击编辑扩展手动添加密钥库:

ThingsBoard IoT网关入门-转载 - 图14

然后删除文件或单击选择要上传的文件:

ThingsBoard IoT网关入门-转载 - 图15

9.4. 从设备中浏览数据

下面列出的默认映射将强制 gateway 将所有可以匹配 **deviceNodePattern** 的 OPC-UA 标签视为 ThingsBoard 设备。网关使用 deviceNamePattern 来计算基于相对于设备节点标签 (例如，_System._DeviceId) 的不同标签的值的设备名称。类似，Tag1 和 Tag2 相对 OPC-UA 标签将被映射到相应的 ThingsBoard 设备属性和遥测字段。

{
  "deviceNodePattern": "Channel1\\.Device\\d+$",
  "deviceNamePattern": "Device ${_System._DeviceId}",
  "attributes": [
    {"key":"Tag1", "type": "string", "value": "${Tag1}"}
  ],
  "timeseries": [
    {"key":"Tag2", "type": "long", "value": "${Tag2}"}
  ]
}

GUI 中的相同映射如下所示:

ThingsBoard IoT网关入门-转载 - 图16

您应该在网关日志中观察以下日志消息:

... INFO  o.t.g.service.MqttGatewayService - [Device 1] Device Connected!

日志位于以下文件夹中:

Windows: YOUR_INSTALL_DIR/logs
Linux: /var/log/tb-gateway

现在，您可以打开 ThingsBoard 网页界面，并在 设备 页面上观察新的设备 Device 1。您可以单击设备卡，并在相应的选项卡中观察传递的属性和遥测。

ThingsBoard IoT网关入门-转载 - 图17

ThingsBoard IoT网关入门-转载 - 图18

步骤 10.连接到 Sigfox 后端

在这一步中，我们将连接到 Sigfox 后端，以便开始从 sigfox 模块收集数据。

10.1 Sigfox 扩展名文件配置:

打开网关配置文件夹并编辑 tb-gateway.yml 文件。配置文件夹位置:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

将 sigfox.Enable 属性值更改为 true。
使用以下命令重新启动网关

Windows: 
net stop tb-gateway
net start tb-gateway
Linux: 
sudo service tb-gateway restart

sigfox-config.json 包含的配置允许将来自 Sigfox 后端 JSON 消息映射到 ThingsBoard 遥测。

10.2 Sigfox 扩展 GUI 配置:

您可以导入示例 Sigfox 扩展配置文件:
sigfox-gui-extension-configuration.json

10.3 您可以导入示例 Sigfox 扩展配置文件:

假设我们想将 Sigfox 模块中的坐标、温度和湿度数据推送到 ThingsBoard。为了实现这一点，您需要选择设备类型，并配置从 Sigfox 后端到我们物联网网关的自定义回调。

ThingsBoard IoT网关入门-转载 - 图19

如下问题需要注意:

这是 UPLINK 数据回调;
URL pattern 包含物联网网关主机、端口和设备类型 id;
header 中 Authorization 用于认证 Sigfox 服务器;
需要使用 HTTP 的 POST 请求;
消息正文是有效的 JSON 文档;
消息正文使用固定变量: device 、lat 、 lng;
消息正文使用区分大小写的自定义变量: Temperature and Humidity 。

我们假设您已经在一些云服务器上部署了网关来获取静态 IP 地址或主机名。

10.4 基本映射示例

下面列出的默认映射将允许将来自于 Sigfox 后端的数据转换并发布到 ThingsBoard。

{
  "deviceTypeConfigurations": [
    {
      "deviceTypeId": "YOUR_DEVICE_TYPE_ID",
      "token": "SECURITY_TOKEN",
      "converter": {
        "deviceNameJsonExpression": "${$.device}",
        "attributes": [
          {
            "type": "string",
            "key": "lat",
            "value": "${$.lat}"
          },
          {
            "type": "string",
            "key": "lng",
            "value": "${$.lng}"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${$.data.temperature}",
            "transformer": {
              "type": "intToDouble"
            }
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${$.data.humidity}",
            "transformer": {
              "type": "intToDouble"
            }
          }
        ]
      }
    }
  ]
}

请注意一下事项:

YOUR_DEVICE_TYPE_ID 需要用实际值替换 (在我们的例子中是 “58cb911a5005742b3b4c41a0”)
SECURITY_TOKEN 需要用随机值替换 (在我们的例子中是 “Basic U0lHRk9YX1RFU1RfVE9LRU4 =”)
JsonPath 表达式用于从传入的 JSON 中提取值 (在我们的例子中是 “$.data.Temp”)。
所有 JsonPath 表达式都需要用 ${} 包裹。
转换器 用于转换数据类型。例如，使用 “(65536-X)/10” 公式将整数加倍。你可以插入你自己的转换器。

10.5 尝试一下

一旦配置了 Sigfox 后端回调，您可以在 ThingsBoard IoT 网关日志中观察到传入的消息。如果一切配置正确，您将在租户管理员设备列表中看到新设备。

ThingsBoard IoT网关入门-转载 - 图20
您可以打开特定设备并检查遥测值是否成功到达。

10.6 自定义数据类型转换器

作为网关开发人员，您可以从以下接口新建分支并添加自定义转换器。如果您认为 PRs 对 ThingsBoard 社区有用，请随时为您的定制转换器实现代码提交 PRs。

11. 连接到 Modbus 从机

相应的扩展页面上包含了 Modbus 的扩展配置。

另见

探索与主要 ThingsBoard 功能相关的指南:

Data Visualization - 如何可视化收集的数据。
Device attributes - 如何使用设备属性。
Telemetry data collection - 如何采集遥测数据。
Using RPC capabilities - 如何向设备发送命令。
Rule Engine - 如何使用规则引擎分析来自设备的数据。

下一步

入门指南 - 这些指南让你快速了解Thingsboard的主要功能，你大概需要花费15~30分钟来阅读。
~~Installation guides~~ - 学习如何在各种支持的操作系统上安装thingsboard。
~~Connect your device~~ - 了解如何根据您的连接技术或解决方案连接设备。
~~Data visualization~~ - 这些指南包含如何配置复杂事物的说明。
~~Data processing & actions~~ - 学习如何使用Thingsboard的规则引擎。
~~IoT Data analytics~~ - 学习如何使用规则引擎执行基本的分析任务。
~~Hardware samples~~ - 学习如何将各种硬件平台连接到thingsboard。
~~Contribution and Development~~ - 了解在thingsboard的二次开发及代码贡献。