Modbus连接器配置

• 概述
• 配置模式
• 通用设置
• 主连接（网关作为主站）设置
  • 服务器（从站）设置
  • 连接设置
  • 高级连接设置
  • 数据映射
    • 属性和时间序列
      • Report strategy（上报策略）
      • Enum mapping（枚举映射）
      • Modifier（修饰符）
      • Batch reading（批量读取）
    • 使用示例
  • 请求映射
    • “属性更新”子部分
    • “RPC请求”子部分
    • 使用示例
  • 高级配置
    • 主站
      • 从站
      • 从站连接类型
        • TCP/UDP
        • 串口
      • 设备属性和时间序列
      • 设备属性更新
      • 设备RPC方法
• 服务器（网关作为从站）设置
  • 启用网关作为从站并向平台发送数据
  • 连接设置
  • 高级连接设置
  • 数据映射
  • 高级配置
    • 从站
    • 从站连接类型
      • TCP/UDP
      • 串口
      • 安全配置
    • 值
      • 属性和时间序列
      • 属性更新
      • RPC方法
• 附加信息
  • Modbus功能码
  • 数据类型
• 下一步

概述

本文档将帮助您为ThingsBoard物联网网关设置Modbus连接器。我们将用简单的术语解释配置参数，使您能够轻松理解和操作。Modbus是一种广泛应用于工业自动化和控制系统的协议，允许设备通过网络相互通信，该连接器可以与ThingsBoard平台无缝集成。使用通用配置来启用此扩展。

此外，如果您是ThingsBoard物联网网关的新用户，我们建议您阅读快速入门指南，以了解ThingsBoard物联网网关的基本概念及其与Modbus协议的工作方式。

该连接器可以通过用户界面表单进行配置，帮助您建立与Modbus服务器的连接、采集数据并向从设备写入数据。让我们来看看所有可用的设置并逐一清晰地解释，这将帮助您了解一切是如何工作的。

请注意： 在创建连接器之前请先连接网关。否则，界面将显示旧的配置字段以保持向后兼容性。

配置模式

Modbus连接器可以通过两种模式进行配置：基础模式和高级模式。

• 基础模式专为ThingsBoard物联网网关新用户设计，旨在以最少的配置快速设置连接器。它提供了带有基本设置的简化界面。
• 高级模式面向需要更多配置控制权的有经验用户。它为高级用例提供了额外的选项和灵活性。

请注意： 如果您是物联网网关的新用户，请使用“基础”配置模式。如果您熟悉物联网网关的配置，可以使用“高级”配置模式。

您可以使用配置页面顶部的切换按钮在这些模式之间切换：

通用设置

本配置部分包含 connector 的通用设置，例如：

• Name - 用于日志和保存到持久化设备的 connector 名称；
• Logs configuration（日志配置） - 本地和远程日志设置：
  • Enable remote logging - 为 connector 启用远程日志；
  • Logging level - 本地和远程日志级别：NONE、ERROR、CRITICAL、WARNING、INFO、DEBUG、TRACE；
• Report strategy - 向 ThingsBoard 发送数据的策略：
  • Report period - 向 ThingsBoard 发送数据的周期（毫秒）；
  • Type - report strategy 类型：
    • On report period - 在上报周期后向 ThingsBoard 发送数据；
    • On value change - 值变化时向 ThingsBoard 发送数据；
    • On value change or report period - 值变化或到达上报周期时向 ThingsBoard 发送数据；
    • On received - 从设备接收数据后向 ThingsBoard 发送数据（默认策略）。

更多关于 report strategy 的信息请参见此处。

通用选项卡对于基础和高级配置都是相同的。

主连接（网关作为主站）设置

Modbus主站用于从Modbus服务器（从站）查询数据。要配置用于数据检索的服务器，您需要指定从站列表。

服务器（从站）设置

Modbus从站是响应Modbus主站请求的设备。在此部分中，您可以配置主站将从中查询数据的Modbus从站。您可以向列表中添加多个从站，每个从站可以有自己的配置。

以下参数用于配置从设备、其名称和配置文件，以及上报策略：

• Unit ID - Modbus从站的ID。
• Device name -平台上的设备名称。
• Device profile -平台上的设备配置文件名称。
• Report strategy -向ThingsBoard发送数据的策略：
  • Report period -向ThingsBoard发送数据的周期（毫秒）；
  • Type -上报策略类型：
    • On report period -在上报周期后向ThingsBoard发送数据；
    • On value change -当值发生变化时向ThingsBoard发送数据；
    • On value change or report period -当值发生变化或上报周期到达时向ThingsBoard发送数据；
    • On received -从设备接收到数据后向ThingsBoard发送数据（默认策略）。

有关上报策略的更多信息，请参阅此处。

所有配置参数列表及其详细描述可在高级配置部分找到。

要添加新的服务器连接配置，请导航到”Master Connections“选项卡并点击”加号“图标：

连接设置

根据 Modbus 主站偏好的通信方式，有三种配置选项：使用 TCP、UDP 或串口。

所有配置参数列表及详细说明请参阅 高级配置 章节。

高级连接设置

您可以配置其他设置，例如：TLS 连接、轮询时间、字节序和字序等。 下表描述了相关参数：

• 点击「高级连接设置」子部分将其打开；

• 进行必要设置。

此外，您还可以配置 TLS 连接（仅用于 TCP/UDP 连接类型）。下表描述了配置 TLS 连接所需的参数：

数据映射

在数据映射中，您可以指定Modbus主站如何与从站交互。这包括从从站读取数据。您还可以使用此部分配置哪些数据将作为设备属性或遥测数据发送。数据映射包含灵活数据管理所需的所有设置。

属性和时间序列

本单元配置提供 Modbus 服务器上数据处理相关设置。这些设置在ThingsBoard 平台实例中将被解释为设备的 attribute/time series。以下参数用于配置设备 attribute 和 time series：

• Key - 平台上 attribute 或 time series 的 key。
• Type - Modbus 寄存器的数据类型。
• Function code - 读取寄存器的 Modbus 功能码。
• Objects count - 要读取的寄存器数量。
• Address - Modbus 服务器上寄存器的地址。

所有配置参数列表及详细说明请参见高级配置部分。

要添加新的 attribute 或 time series，请按以下步骤操作：

• 在 “Attributes” 或 “Time series” 部分点击 “pencil” 图标（取决于所选部分）；

• 在打开的窗口中点击 “Add attribute” 或 “Add time series“（取决于所选部分）；

• 填写 key、type、function code、objects count 和 address 字段。点击 “Apply”。

Report strategy（上报策略）

您可为每个 time series 或 attribute 启用特定的 report strategy。该策略定义数据发送到 ThingsBoard 服务器的频率。可用策略如下：

• On report period - 在上报周期后向 ThingsBoard 发送数据；
• On value change - 当值变化时向 ThingsBoard 发送数据；
• On value change or report period - 当值变化或在上报周期后向 ThingsBoard 发送数据；
• On received - 从设备接收数据后向 ThingsBoard 发送数据（默认策略）。

有关 report strategy 的更多信息请参见此处。

Enum mapping（枚举映射）

此功能自 ThingsBoard IoT Gateway v.3.8.1 起可用，且仅在高级配置模式下可用。

可使用 enum mapping 功能将寄存器值映射为人类可读的字符串。对于值表示设备状态而非“传感器值”的寄存器特别有用。Enum mapping 适用于所有寄存器类型。上行 RPC to Device 调用可使用 enum mapping 获取解释后的值。 此外，enum mapping 可按预期与批量读取配合使用。

要为特定 attribute 或 time series 设置 enum mapping，需在配置中定义 variants 参数。该参数为对象，每个 key 表示可能的寄存器值，对应的 value 为描述该寄存器值的人类可读字符串。

Enum mapping 配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "tag": "status",
  "type": "16int",
  "address": 1,
  "objectsCount": 1,
  "functionCode": 3,
  "variants": {
    "0": "Stopped",
    "1": "Booting",
    "2": "Running"
  }
}

线圈寄存器 enum mapping 配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "tag": "relay",
  "type": "bits",
  "address": 1,
  "objectsCount": 1,
  "functionCode": 1,
  "bitTargetType": "int",
  "variants": {
    "0": "Disable",
    "1": "Enable"
  }
}

RPC to Device 调用的 enum mapping 配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "method": "getStatus",
  "type": "16int",
  "address": 1,
  "objectsCount": 1,
  "functionCode": 3,
  "variants": {
    "0": "Stopped",
    "1": "Booting",
    "2": "Running"
  }
}

更多使用示例请参见使用示例部分。

Modifier（修饰符）

可通过以下设置对 attribute/time series 值应用 modifier：

更多使用示例请参见使用示例部分。

Batch reading（批量读取）

此功能自 ThingsBoard IoT Gateway v.3.7.9 起可用，且仅在高级配置模式下可用。

为优化读取过程，可将多个寄存器分组到单个批量读取请求中。这种方式可减少发送到 Modbus 服务器的请求数量，从而提高性能并降低网络流量。请注意，批量读取请求中的寄存器必须为相同类型和功能码。

组读取配置中有两个重要参数：address 和 tag。详细说明如下：

• address - 起始寄存器地址与结束寄存器地址，用 - 分隔。例如 0-10 表示组读取从地址 0 的寄存器开始，到地址 10 的寄存器结束（含）。
• tag - 组读取内每个寄存器的唯一标识符，用于在给定地址范围内识别特定寄存器。tag 名称可使用以下变量构成表达式：
  • ${address} - 组读取内的寄存器地址。
  • ${unitId} - slave ID。
  • ${functionCode} - 功能码。
  • ${type} - 寄存器的数据类型。
  • ${objectsCount} - 对象数量。

divider 和 multiplier 参数按预期工作。

组读取配置示例：

1
2
3
4
5
6
7
{
  "tag": "${unitId} - ${type} - ${address}",
  "type": "16int",
  "functionCode": 3,
  "objectsCount": 1,
  "address": "0-10"
}

更多使用示例请参见使用示例部分。

使用示例

读取属性/时序数据

乘数属性/时序数据中

除数属性/时序数据中

批量读取（仅高级配置模式）

枚举映射（仅高级配置模式）

以下示例使用 ThingsBoard Modbus 演示服务器，可通过 Docker 及以下命令运行： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器地址为 0.0.0.0:5021，结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Relay Coil bits 1 此处关注寄存器 1，用于表示继电器状态（关/开）。 要读取该寄存器，需在设备配置中将其作为属性/遥测添加。按以下步骤操作： 在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择已创建的 Modbus 连接器并点击“主站连接”标签。请确保已配置并连接设备（若不清楚如何操作，可参阅入门指南或本指南中的连接设置和数据映射）。点击要配置属性更新的设备旁的“铅笔”图标。 向下滚动至“属性或时序数据”部分，点击“铅笔”图标编辑属性和遥测。 点击“添加属性”或“添加遥测”按钮。此处添加 relay 时序数据，故在“键”中填 relay，将“类型”选为 bits，“功能码”选为“01 - 读线圈”，“位目标类型”选为“布尔”，“地址”填 1。该地址为要读取的 Modbus 寄存器。 记得点击“应用”按钮保存更改。 可以检查属性/遥测是否生效。依次进入“实体”→“设备”→选择已创建设备→“最新遥测”标签，查看 relay 遥测值。默认继电器为关，应为 false。 上述示例的 Modbus 连接器完整配置如下： 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 36 37 38 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "method": "socket", "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "timeout": 35, "byteOrder": "LITTLE", "wordOrder": "LITTLE", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "connectAttemptTimeMs": 500, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 30000, "type": "tcp", "attributes": [], "timeseries": [ { "tag": "relay", "type": "bits", "address": 1, "objectsCount": 1, "functionCode": 1, "bitTargetType": "bool" } ], "attributeUpdates": [], "rpc": [] } ] } }

以下示例使用 ThingsBoard Modbus 演示服务器，可通过 Docker 及以下命令运行： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器地址为 0.0.0.0:5021，结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Relay Coil bits 1 使用 Modbus 设备时，常需将寄存器读到的数值乘以某个系数才能得到正确值。例如，若寄存器中功率为 2534，而实际需要 253400 瓦，则需乘以 100。 在设备配置中，可在属性和遥测设置里使用“乘数”字段实现。按以下步骤配置带乘数的寄存器读取： 在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择已创建的 Modbus 连接器并点击“主站连接”标签。请确保已配置并连接设备（若不清楚如何操作，可参阅入门指南或本指南中的连接设置和数据映射）。点击要配置属性更新的设备旁的“铅笔”图标。 向下滚动至“属性或时序数据”部分，点击“铅笔”图标编辑属性和遥测。 点击“添加属性”或“添加遥测”按钮。此处添加 power 时序数据，故在“键”中填 power，将“类型”选为 16int，“功能码”选为“03 - 读保持寄存器”，“地址”填 2，启用“修改器”，将“类型”选为“乘数”，“值”填 10。 记得点击“应用”按钮保存更改。 可以检查带乘数的遥测是否生效。依次进入“实体”→“设备”→选择已创建设备→“最新遥测”标签，查看 power 遥测值。 上述示例的 Modbus 连接器完整配置如下： 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 36 37 38 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "method": "socket", "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "timeout": 35, "byteOrder": "LITTLE", "wordOrder": "LITTLE", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "connectAttemptTimeMs": 500, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 30000, "type": "tcp", "attributes": [], "timeseries": [ { "tag": "power", "type": "16int", "address": 2, "objectsCount": 1, "functionCode": 3, "multiplier": 10 } ], "attributeUpdates": [], "rpc": [] } ] } }

以下示例使用 ThingsBoard Modbus 演示服务器，可通过 Docker 及以下命令运行： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器地址为 0.0.0.0:5021，结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Relay Coil bits 1 使用 Modbus 设备时，常需要将寄存器读到的数值除以某个系数才能得到正确值。例如，若寄存器中温度为 2534，而实际需要 25.34 度，则需将值除以 100。 在设备配置中，可在属性和遥测设置里使用“除数”字段实现。按以下步骤配置带除数的寄存器读取： 在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择已创建的 Modbus 连接器并点击“主站连接”标签。请确保已配置并连接设备（若不清楚如何操作，可参阅入门指南或本指南中的连接设置和数据映射）。点击要配置属性更新的设备旁的“铅笔”图标。 向下滚动至“属性或时序数据”部分，点击“铅笔”图标编辑属性和遥测。 点击“添加属性”或“添加遥测”按钮。此处添加 temperature 时序数据，故在“键”中填 temperature，将“类型”选为 16int，“功能码”选为“03 - 读保持寄存器”，“地址”填 0，启用“修改器”，将“类型”选为“除数”，“值”填 10。 记得点击“应用”按钮保存更改。 可以检查带除数的遥测是否生效。依次进入“实体”→“设备”→选择已创建设备→“最新遥测”标签，查看 temperature 遥测值。 上述示例的 Modbus 连接器完整配置如下： 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 36 37 38 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "method": "socket", "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "timeout": 35, "byteOrder": "BIG", "wordOrder": "LITTLE", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "connectAttemptTimeMs": 500, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 30000, "type": "tcp", "attributes": [], "timeseries": [ { "tag": "temperature", "type": "16int", "address": 0, "objectsCount": 1, "functionCode": 3, "divider": 10 } ], "attributeUpdates": [], "rpc": [] } ] } }

我们以 ThingsBoard Modbus 演示服务器为例，可使用 Docker 运行以下命令： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器在 0.0.0.0:5021 可用。服务器结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Relay Coil bits 1 为优化发送到 Modbus 服务器的请求数量，可使用高级配置模式下的批量读取功能。该功能允许在单次请求中读取多个寄存器，从而显著降低 Modbus 服务器负载并提升性能。 下面举例说明如何正确配置批量读取，以从 Modbus 服务器读取 temperature、humidity、power 和 pressure 寄存器。 从上表可知，所需寄存器类型相同（16int）且功能码相同（03 - 读保持寄存器）。因此可将它们合并为一次批量读取请求。需要读取地址 0 到 3 的寄存器，地址范围为 0-3。 此外，需在 tag 字段中使用 ${address} 等变量以唯一标识批量读取中的每个寄存器。本示例在 tag 字段中使用以下表达式：${unitId}.${type}.${address}（更多变量信息请参阅文档相应章节）。 将以下配置复制粘贴到 Modbus 连接器高级配置模式： 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 36 37 38 39 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "type": "tcp", "method": "socket", "timeout": 35, "byteOrder": "BIG", "wordOrder": "LITTLE", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "sendDataOnlyOnChange": true, "connectAttemptTimeMs": 5000, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 300000, "attributes": [], "timeseries": [ { "tag": "${unitId}.${type}.${address}", "type": "16int", "functionCode": 3, "objectsCount": 1, "address": "0-3", "divider": 10 } ], "attributeUpdates": [], "rpc": [] } ] } } 保存更改并启动连接器后，可以看到对应遥测数据正确更新：

Modbus 设备的寄存器可能表示枚举值，例如运行模式、状态码或错误状态。为便于理解，可使用 ThingsBoard IoT 网关 Modbus 连接器的枚举映射功能将其映射为可读字符串。该功能适用于所有寄存器类型，可用于上行数据（属性和时序数据）及上行 RPC 到设备调用。下面说明如何在 Modbus 连接器配置中设置枚举映射。 以下示例使用 ThingsBoard Modbus 演示服务器，可通过 Docker 及以下命令运行： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器地址为 0.0.0.0:5021，结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Operational Mode Holding 16int 4 Relay Coil bits 1 我们要将 Operational Mode 和 Relay 寄存器映射为可读字符串。Operational Mode 可能取值为： 1：正常模式 2：维护模式 3：标定模式 Relay 可能取值为： 0：关闭 1：开启 要为这些寄存器配置枚举映射，需在每个寄存器配置中定义 variants 参数。该参数为对象，键为可能的寄存器值，值为对应的可读描述。 将以下配置复制粘贴到 Modbus 连接器高级配置模式中： 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 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "method": "socket", "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "timeout": 35, "byteOrder": "BIG", "wordOrder": "BIG", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "connectAttemptTimeMs": 500, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 1000, "type": "tcp", "attributes": [], "timeseries": [ { "tag": "operational_mode", "type": "16int", "address": 4, "objectsCount": 1, "functionCode": 3, "variants": { "1": "Normal Mode", "2": "Service Mode", "3": "Calibration Mode" } }, { "tag": "relay", "type": "bits", "address": 1, "objectsCount": 1, "functionCode": 1, "bitTargetType": "int", "variants": { "0": "OFF", "1": "ON" } } ], "attributeUpdates": [], "rpc": [] } ] } } 应用该配置后，operational_mode 和 relay 寄存器在上行数据中会映射为相应的可读字符串，便于理解 Modbus 设备数据：

请求映射

请求映射部分允许您配置ThingsBoard平台实例如何与设备交互。即平台如何从设备请求数据、如何更新设备属性以及如何向设备发送RPC命令。

Modbus连接器支持以下请求映射：

• 属性更新 -允许从ThingsBoard平台实例更新设备节点值。
• RPC方法 -允许向设备发送RPC命令。使用RPC方法，您可以获取或设置Modbus寄存器的值。Modbus连接器支持不同类型的RPC方法，例如：
  • 保留的GET/SET方法 -这些方法会自动为每个属性和时间序列参数创建。 您可以使用它们来获取或设置Modbus寄存器的值。
  • 可配置的设备RPC方法 -这些方法允许您在连接器配置中配置可以发送到设备的自定RPC命令。

“属性更新”子部分

此子部分包含来自ThingsBoard平台实例的属性更新请求配置。

ThingsBoard允许配置设备属性并从设备应用程序中获取其中一些属性。您可以将其视为设备的远程配置。您的设备能够从ThingsBoard请求共享属性。更多详情请参阅用户指南。

以下参数用于配置属性更新：

• Key -共享属性名称。
• Type -值的类型，用于标识正在接收的值的数据类型。
• Function code -用于数据处理的功能码， 具体参见Modbus功能码。
• Objects count -要写入或读取的对象数量，指定请求中将处理多少个寄存器。
• Address -对象地址，用于标识Modbus协议中的特定对象。

所有配置参数列表及其详细描述可在高级配置部分找到。

更多使用示例可在示例用法部分找到。

添加新属性更新的步骤：

• 进入「属性更新」部分并点击「铅笔」图标；

• 在打开的窗口中点击「添加属性更新」；

• 设置属性键名、类型、功能码、对象数量和地址。然后点击「应用」。

“RPC请求”子部分

ThingsBoard允许向直接连接到ThingsBoard或通过网关连接的设备发送RPC命令。 此部分提供的配置用于从ThingsBoard向设备发送RPC请求。以下参数用于配置RPC方法：

• Method name - RPC方法名称，用于标识请求。
• Type -值的数据类型，用于标识正在接收的值的数据类型。
• Function code -用于数据处理的功能码， 具体参见Modbus功能码。
• Objects count -要写入或读取的对象数量，指定请求中将处理多少个寄存器。
• Address -对象地址，用于标识Modbus协议中的特定对象。

所有配置参数列表及其详细描述可在高级配置部分找到。

更多使用示例可在示例用法部分找到。

添加新 RPC 方法的步骤：

• 进入「RPC 请求」部分并点击「铅笔」图标；

• 在打开的窗口中点击「添加请求」；

• 填写键、类型、功能码、对象数量和地址。点击「应用」。

此外，每个遥测和属性参数都内置了GET和SET RPC方法，因此您无需手动配置。请参阅指南。

使用示例

属性更新

RPC到设备

预留RPC

属性更新允许您更新 Modbus 服务器中的寄存器值。您可以在设备配置页面的「属性更新」部分添加新的属性更新。 我们以 ThingsBoard Modbus 演示服务器为例，可使用 Docker 运行以下命令： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器在 0.0.0.0:5021 可用。服务器结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Relay Coil bits 1 我们关注寄存器「1」，我们已将此寄存器添加为键名为 relay 的遥测参数。使用遥测是为了便于之后查看通过属性更新更改的值是否已生效。您也可以在设备配置中添加此遥测数据点，或使用保留的 get 方法检查该节点的值。 让我们向配置添加属性更新。请按以下步骤操作： 在左侧边栏进入「实体」→「网关」并选择您的网关。 点击右侧菜单的「连接器配置」按钮。 选择已创建的 Modbus 连接器并点击「主站连接」选项卡。确保已配置并连接设备（如不清楚操作，请参阅 入门指南 或本指南的 连接设置 和 数据映射 章节）。点击要配置属性更新的设备上的「铅笔」图标。 向下滚动到「属性更新」部分，点击「铅笔」图标编辑属性更新。 点击「添加属性更新」按钮。本示例中将添加 relay 属性更新，因此在「键」字段输入 relay，选择「类型」为 bits，「功能码」为「05 - 写单个线圈」，在「对象数量」字段填写 1，选择「位目标类型」为「布尔」，在「地址」字段输入「1」。 记得点击「应用」按钮保存更改。 现在可以检查属性更新是否生效。进入「实体」→「设备」→ 选择已创建的设备 →「属性」选项卡 → 选择「共享属性」→ 点击「+」图标并添加 relay 属性，类型设为「布尔」、值设为「True」。 现在检查继电器寄存器的值。在所选设备中进入「最新遥测」选项卡，查看 relay 遥测的值。应为 true，因为我们已将共享属性设为 true。 尝试将 relay 共享属性的值改为 false。几秒后，relay 遥测值应变为 false，说明属性更新工作正常。 上述示例的 Modbus 连接器完整配置如下： 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 36 37 38 39 40 41 42 43 44 45 46 47 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "method": "socket", "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "timeout": 35, "byteOrder": "LITTLE", "wordOrder": "LITTLE", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "connectAttemptTimeMs": 500, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 30000, "type": "tcp", "attributes": [], "timeseries": [ { "tag": "relay", "type": "bits", "address": 1, "objectsCount": 1, "functionCode": 1, "bitTargetType": "bool" } ], "attributeUpdates": [ { "tag": "relay", "type": "bits", "address": 1, "objectsCount": 1, "functionCode": 5, "bitTargetType": "bool" } ], "rpc": [] } ] } }

RPC 到设备允许向直接连接或通过网关连接到 ThingsBoard 的设备发送 RPC 命令。 我们以 ThingsBoard Modbus 演示服务器为例，可使用 Docker 运行以下命令： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器在 0.0.0.0:5021 可用。服务器结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Relay Coil bits 1 我们希望通过 RPC 到设备从演示设备获取温度值。 要调用此方法，首先需要配置 Modbus 连接器以支持 RPC 调用。请按以下步骤操作： 在左侧边栏进入「实体」→「网关」并选择您的网关。 点击右侧菜单的「连接器配置」按钮。 选择已创建的 Modbus 连接器并点击「主站连接」选项卡。确保已配置并连接设备（如不清楚操作，请参阅 入门指南 或本指南的 连接设置 和 数据映射 章节）。点击要配置属性更新的设备上的「铅笔」图标。 向下滚动到「RPC 请求」部分，点击「铅笔」图标编辑 RPC 方法。 点击「添加请求」按钮。在「方法」字段填写 getTemperature，选择「类型」为「16int」，「功能码」为「03 - 读保持寄存器」，在「对象数量」字段填写 1，在「地址」字段输入「0」。 记得点击「应用」按钮保存更改。 配置已完成，让我们检查如何调用该方法。在 RPC 调试终端部件中运行以下命令： 1 getTemperature 响应： 上述示例的 Modbus 连接器完整配置如下： 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 36 37 38 39 40 41 42 43 44 45 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "method": "socket", "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "timeout": 35, "byteOrder": "LITTLE", "wordOrder": "LITTLE", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "connectAttemptTimeMs": 500, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 30000, "type": "tcp", "attributes": [], "timeseries": [ { "tag": "some_key", "type": "16int", "address": 0, "objectsCount": 1, "functionCode": 3 } ], "attributeUpdates": [], "rpc": [ { "tag": "getTemperature", "type": "16int", "address": 0, "objectsCount": 1, "functionCode": 3 } ] } ] } }

每个遥测和属性参数都自带 GET 和 SET RPC 方法，无需手动配置。 我们以 ThingsBoard Modbus 演示服务器为例，可使用 Docker 运行以下命令： 1 docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest 服务器在 0.0.0.0:5021 可用。服务器结构如下： 变量名 寄存器类型 数据类型 地址 Temperature Holding 16int 0 Humidity Holding 16int 1 Power Holding 16int 2 Pressure Holding 16int 3 Relay Coil bits 1 我们关注寄存器 1，这是一个线圈寄存器。我们将使用此寄存器设置遥测参数的值。该寄存器类型为 bits，因此遥测参数也使用 bits 类型。该遥测的配置如下： 1 2 3 4 5 6 7 8 { "tag": "relay", "type": "bits", "address": 1, "objectsCount": 1, "functionCode": 1, "bitTargetType": "bool" } 让我们使用保留的 get 方法检查继电器寄存器的值。要获取继电器寄存器的当前值，在 RPC 调试终端运行以下查询： 1 get type=bits;functionCode=1;objectsCount=1;address=1; 响应： 1 {"result":{"value":false}} 因此，get 方法返回继电器寄存器的当前值，可以看到继电器处于关闭状态。 RPC 调试终端仅用于示例演示，您也可以使用任何支持 RPC 调用的其他部件。 要设置继电器寄存器的值并打开继电器，请运行以下查询： 1 set type=bits;functionCode=5;objectsCount=1;address=1;value=1; 响应： 1 {"result":{"value":"1"}} 如下方截图所示，继电器遥测值已变为 1： 再次检查继电器遥测的值：现在为 true，因为在 Modbus 连接器中，布尔值由整数转换而来——0 = false，1 = true（任意非零为 true）——因此寄存器值 1 会被报告为 true。 1 get type=bits;functionCode=3;objectsCount=1;address=1; 响应： 1 {"result":{"value":true}} 上述示例的 Modbus 连接器完整配置如下： 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 36 37 38 { "master": { "slaves": [ { "host": "0.0.0.0", "port": 5021, "method": "socket", "unitId": 1, "deviceName": "Demo Device", "deviceType": "default", "timeout": 35, "byteOrder": "LITTLE", "wordOrder": "LITTLE", "retries": true, "retryOnEmpty": true, "retryOnInvalid": true, "pollPeriod": 1000, "connectAttemptTimeMs": 500, "connectAttemptCount": 5, "waitAfterFailedAttemptsMs": 30000, "type": "tcp", "attributes": [], "timeseries": [ { "tag": "relay", "type": "bits", "address": 1, "objectsCount": 1, "functionCode": 1, "bitTargetType": "bool" } ], "attributeUpdates": [], "rpc": [] } ] } }

高级配置

高级配置部分提供了主站（Master）部分配置的所有可用参数的详细概述。

主站

网关可以作为Modbus主站运行。此配置部分用于Modbus主站，主站用于从Modbus服务器（从站）查询数据。

从站

从站列表用于指定主站将从中查询数据的Modbus从站列表。

从站配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
"master": {
  "slaves": [
    {
      "timeout": 35,
      "byteOrder": "LITTLE",
      "wordOrder": "LITTLE",
      "retries": true,
      "retryOnEmpty": true,
      "retryOnInvalid": true,
      "pollPeriod": 5000,
      "sendDataOnlyOnChange": true,
      "connectAttemptTimeMs": 5000,
      "connectAttemptCount": 5,
      "waitAfterFailedAttemptsMs": 300000,
      "deviceName": "Demo Device",
      "deviceType": "default",
      "unitId": 1, 
      ...
    }
  ]
}

从站连接类型

Modbus连接器支持三种与Modbus从站的连接类型：

• TCP -通过TCP/IP协议连接Modbus从站。
• UDP -通过UDP协议连接Modbus从站。
• Serial -通过串口（RS-232、RS-485等）连接Modbus从站。

TCP/UDP

TCP/UDP从站配置示例：

1
2
3
4
5
6
7
8
9
10
"master": {
    "slaves": [
        {
            "host": "127.0.0.1",
            "port": 5021,
            "method": "socket",
            ...
        }
    ]
}

串口

串口从站配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
"master": {
    "slaves": [
        {
            "method": "ascii",
            "baudrate": 4800,
            "stopbits": 1,
            "bytesize": 5,
            "parity": "N",
            "strict": true,
            ...
        }
    ]
}

设备属性和时间序列

属性和遥测配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"attributes": [
  {
    "tag": "string_read",
    "type": "string",
    "functionCode": 4,
    "objectsCount": 4,
    "address": 1
  }
],
"timeseries": [
  {
    "tag": "16uint_read",
    "type": "16uint",
    "functionCode": 4,
    "objectsCount": 2,
    "address": 18
  },
]

设备属性更新

属性更新配置示例：

1
2
3
4
5
6
7
8
{
    "tag": "relay",
    "type": "bits",
    "functionCode": 5,
    "objectsCount": 1,
    "bitTargetType": "int",
    "address": 29
}

设备RPC方法

RPC方法配置示例：

1
2
3
4
5
6
7
8
9
"rpc": [
  {
    "tag": "setValue",
    "type": "16int",
    "functionCode": 6,
    "objectsCount": 1,
    "address": 31
  }
]

服务器（网关作为从站）设置

网关可以作为Modbus从站运行。作为从站的网关可以存储数据，在发生变化时或按固定间隔向平台发送更新，用户还可以通过RPC或共享属性更新来更改存储数据。

启用网关作为从站并向平台发送数据

要启用网关作为Modbus从站，您需要在”Server configuration“部分切换”Enable“按钮。请注意，此选项仅会创建Modbus从站，但不会自动向平台发送任何数据：

要向平台发送数据，您需要在”Server configuration“中启用”Send data to the platform“开关，这将在发生变化时或按固定间隔向平台发送数据：

连接设置

根据 Modbus master 之间的首选通信方式，此部分有三种配置选项：TCP、UDP 或 Serial 端口。

TCP

UDP

Serial

以下参数用于配置 Gateway as Slave 的 TCP 连接： Host - Modbus 服务器的主机名或 IP 地址。 Port - 连接 Modbus 服务器的端口。 Method - framer 类型，Socket 或 RTU。 Unit ID - Modbus 上当前 slave 的 ID。 Device name - 当前 slave 的名称。切勿将 “Device name” 参数设为 “Gateway”！ Device profile - 当前 slave 的 device profile。 Poll period (ms) - 检查 attribute 和 telemetry 的周期（毫秒）。 所有配置参数列表及详细说明请参见高级配置部分。 更多使用示例请参见使用示例部分。

以下参数用于配置作为从站的网关的 UDP 连接： 主机 - Modbus 服务器的主机名或 IP 地址。 端口 - Modbus 服务器连接端口。 方法 - 帧类型，可选 Socket 或 RTU。 单元 ID - Modbus 上当前从站的 ID。 设备名称 - 当前从站名称。请不要使用「Gateway」作为「设备名称」参数的值！ 设备配置 - 当前从站的设备配置。 轮询周期 (ms) - 检查属性和遥测的周期（毫秒）。 所有配置参数列表及详细说明请参阅 高级配置 章节。 更多使用示例请参阅 示例用法 章节。

以下参数用于配置作为从站的网关的串口连接： 端口 - Modbus 服务器连接端口。 方法 - 应用数据单元类型，可选 ASCII 或 RTU。 波特率 - 串口设备使用的波特率。 严格模式 - 波特率 <= 19200 时使用字符间超时。 单元 ID - Modbus 上当前从站的 ID。 设备名称 - 当前从站名称。请不要使用「Gateway」作为「设备名称」参数的值！ 设备配置 - 当前从站的设备配置。 轮询周期 (ms) - 检查属性和遥测的周期（毫秒）。 所有配置参数列表及详细说明请参阅 高级配置 章节。 更多使用示例请参阅 示例用法 章节。

高级连接设置

您可以配置其他设置，例如：TLS 连接、字节序、字序等。以下参数用于配置高级连接设置：

• 字节序 - Modbus 连接的字节序，可选 LITTLE 或 BIG。
• 字序 - Modbus 连接的字序，可选 LITTLE 或 BIG。
• 厂商名称 - Modbus 连接的厂商名称。
• 产品代码 - Modbus 连接的产品代码。
• 厂商 URL - Modbus 连接的厂商 URL。
• 产品名称 - Modbus 连接的产品名称。
• 型号名称 - Modbus 连接的型号名称。
• TLS - 启用或禁用 Modbus 连接的 TLS（仅用于 TCP 和 UDP 连接）：
  • 客户端证书路径 - 客户端证书文件路径。
  • 客户端私钥路径 - 客户端私钥文件路径。
  • 密码 - 客户端私钥文件密码。

所有配置参数列表及详细说明请参阅 高级配置 章节。

更多使用示例请参阅 示例用法 章节。

配置高级连接设置的步骤：

• 点击「高级连接设置」子部分将其打开；

• 进行必要设置。

数据映射

在此部分中，您可以指定寄存器和线圈的初始值。每个值对应特定类型的寄存器。包括：

1.保持寄存器 2.线圈初始化器 3.输入寄存器 4.离散输入

对于每种寄存器类型，您可以配置用于读写数据的值类型。根据您选择的数据类型，网关将使用相应的Modbus功能码来读取或写入数据。

要配置读取的值类型，请使用属性和遥测部分。要写入数据，请使用RPC方法和共享属性部分。请注意，每种值类型的配置与属性、遥测、RPC方法和共享属性部分中相应的数据类型类似。唯一的例外是您需要在”Value“字段中设置初始值。

根据寄存器所属的值类型，您应将其添加到相应的数组中。

选择基础或高级Modbus配置：

所有配置参数列表及详细说明请参见高级配置部分。

更多使用示例请参见使用示例部分。

要向网关 slave 添加新值，请按以下步骤操作：

• 在所选部分的行中点击 “pencil“（铅笔）图标；

• 在打开的窗口中点击 “Add attribute” 或其他（取决于所选部分）；

• 填写 key、type、function code、objects count、address 和 value 字段。点击 “Apply”。

高级配置

高级配置部分提供了网关作为从站配置部分所有可用参数的详细概述。

从站

网关可以作为Modbus从站运行。此配置部分用于Modbus从站，用于存储数据并在发生变化时或按固定间隔向平台发送更新。

从站配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"slave": {
  "type": "tcp",
  "host": "127.0.0.1",
  "port": 5026,
  "method": "socket",
  "deviceName": "Modbus Slave Example",
  "deviceType": "default",
  "pollPeriod": 5000,
  "sendDataToThingsBoard": false,
  "byteOrder": "LITTLE",
  "wordOrder": "LITTLE",
  "unitId": 0,
  ...
}

从站连接类型

Modbus连接器支持三种与Modbus从站的连接类型：

• TCP -通过TCP/IP协议连接Modbus从站。
• UDP -通过UDP协议连接Modbus从站。
• Serial -通过串口（RS-232、RS-485等）连接Modbus从站。

TCP/UDP

TCP/UDP配置示例：

1
2
3
4
5
6
7
"slave": {
  "type": "tcp",
  "host": "127.0.0.1",
  "port": 5026,
  "method": "socket",
  ...
}

串口

串口配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
"slave": {
  "type": "serial",
  "port": 5026,
  "method": "rtu",
  "baudrate": 4800,
  "stopbits": 1,
  "bytesize": 5,
  "parity": "N",
  "strict": true,
  "handleLocalEcho": false,
  ...
}

安全配置

网关作为从站支持安全配置。此配置用于保护与Modbus从站的连接并对连接进行认证。仅适用于TCP和UDP连接。

安全配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
"slave": {
  "type": "tcp",
  "host": "127.0.0.1",
  "port": 5026,
  "method": "socket",
  "security": {
      "keyfile": "/path/to/keyfile.pem",
      "certfile": "/path/to/certfile.pem",
      "password": "your_password"
  }
  ...
}

值

值列表用于指定寄存器和线圈的初始值。每个值对应特定类型的寄存器。包括：

1.保持寄存器 2.线圈初始化器 3.输入寄存器 4.离散输入

对于每种寄存器类型，您可以配置用于读写数据的值类型。根据您选择的数据类型，网关将使用相应的Modbus功能码来读取或写入数据。

属性和时间序列

属性和时间序列配置示例：

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
"slave": {
  ...
  "values": {
    "holding_registers": {
      "attributes": [
        {
          "address": 1,
          "type": "string",
          "tag": "sm",
          "objectsCount": 1,
          "value": "ON"
        }
      ],
      "timeseries": [
        {
          "address": 2,
          "type": "16int",
          "tag": "smm",
          "objectsCount": 1,
          "value": 12334
        }
      ],
    }
  }
}

属性更新

属性更新配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"slave": {
  ...
  "values": {
    "holding_registers": {
      "attributeUpdates": [
        {
          "tag": "shared_attribute_write",
          "type": "32int",
          "functionCode": 6,
          "objectsCount": 2,
          "address": 29,
          "value": 1243
        }
      ],
    }
  }
}

RPC方法

RPC方法配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"slave": {
  ...
  "values": {
    "holding_registers": {
      "rpc": [
        {
          "tag": "setValue",
          "type": "16int",
          "functionCode": 5,
          "objectsCount": 1,
          "address": 31,
          "value": 22
        }
      ]
    }
  }
}

附加信息

以下是有关Modbus功能码和支持的数据类型的更多详细信息。

Modbus功能码

Modbus连接器支持以下Modbus功能码：

数据类型

用于读写数据的支持数据类型列表及描述。

下一步

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

• 如何使用ThingsBoard物联网网关将Modbus设备连接到ThingsBoard CE
• 数据可视化 -如何可视化采集的数据。
• 设备属性 -如何使用设备属性。
• 遥测数据采集 -如何采集遥测数据。
• 使用RPC功能 -如何向设备发送/接收命令。
• 规则引擎 -如何使用规则引擎分析设备数据。