---

更新日志：

• 20240131 版本：
  • 新增 docker 安装部署时与版本相关的问题；
  • 全部配置文件替换为 tb-gateway 版本 3.4.2，更新配置详解：
    • 主配置文件由 yaml 格式改变为 json 格式配置，可配置内容增加；
    • mqtt 连接器配置内容增加；
    • modbus 连接器配置新增 slave 配置，删除 device 配置；
  • 全部内容重新测试，测试验证图片更新；
  • 新增自定义连接器官方示例的配置测试以及配置步骤总结；
  • 注：3.4 版本 modbus 协议存在问题；3.4.3、3.4.4 版本 opcua 协议存在问题！

---

tb-gateway 安装部署

官方为 ThingsBoard-Gateway 提供了多种安装部署方案，可以根据不同系统进行安装。

centOS 7 安装（不推荐）

采用 centOS 7 作为部署服务器，具体安装步骤如下（注：采用该方法安装2.7以上版本时存在问题，安装会失败）：

1. 下载 ThingsBoard-Gateway 安装包：

   wget https://github.com/thingsboard/thingsboard-gateway/releases/latest/download/python3-thingsboard-gateway.rpm
   

2. 使用 yum 工具安装 ThingsBoard-Gateway：

   sudo yum install -y ./python3-thingsboard-gateway.rpm
   

3. 完成后查看 ThingsBoard-Gateway 的运行状态：

   systemctl status thingsboard-gateway
   

   此时服务运行可能会报错，因为还没有对服务的相关配置进行更改。

Docker 安装（推荐）

服务器安装 docker 后，直接执行以下命令执行安装最新发行版本（本手册版本为 3.4）：

docker run -d -it -v ~/.tb-gateway/logs:/thingsboard_gateway/logs -v ~/.tb-gateway/extensions:/thingsboard_gateway/extensions -v ~/.tb-gateway/config:/thingsboard_gateway/config --name tb-gateway -p 60000-61000:60000-61000 --restart always thingsboard/tb-gateway

其中，-v 指令后冒号之前的文件路径为容器内部文件的挂载位置：

• ~/.tb-gateway/logs：日志挂载路径；

• ~/.tb-gateway/extensions：网关扩展目录挂载路径（各种协议连接器）；

• ~/.tb-gateway/config：配置文件挂载路径；

安装完成后，容器将自动启动，此时查看日志将看到网关连接存在错误，需要修改配置文件。

注：使用 docker 进行安装部署时，需要注意 docker 版本问题，不同版本的 docker 可拉取到的最新 tb-gateway 镜像的版本不同！ 使用docker --version命令可查看 docker 版本。

• 使用 docker 版本为 18.03.1-ce 时，tb-gateway 最新版本镜像为 2.9；

• 使用 docker 版本为时，tb-gateway 最新版本镜像为 3.4.4（截至 2024-01-27）；

【2024-01-27】注：版本 3.4.4\3.4.3 在使用 opcua 协议时存在问题。

建议使用 3.4.2 版本！，本文所有测试及配置内容均为 3.4.2 版本。

tb-gateway 通用配置文件

采用 rpm 安装包进行安装的配置文件路径为/etc/thingsboard-gateway/config，使用 docker 安装的配置文件则在宿主机的挂载路径~/.tb-gateway/config。该文件夹内包含有基础配置文件 tb_gateway.json，以及各种协议的配置文件，如 mqtt.json、modbus.json、opcua.json 等。

通用的基础配置文件 tb_gateway.json 用于配置到 thingsboard 平台的连接、存储模式以及各种协议连接器。

连接配置模块 thingsboard

该模块中主要配置网关到平台的连接参数，核心参数包括：

• host：配置 tb 平台服务器地址；

• port：配置 tb 平台网关消息接收的端口，默认为 1883（即平台 MQTT 服务器端口）；

• remoteShell：官方未解释，与配置远程 shell 指令相关（后续补充），默认 false；

• remoteConfiguration：官方未解释，配置是否使用远程配置（3.4.2 以后版本新功能），建议 false；

• statistics：配置统计收集数据并发送 tb 作为网关设备的属性进行存储（若需要使用的话需要额外的配置文件对要采集的参数进行定义，此处暂不讲解）；

  • enable：配置是否启用该功能；

  • statsSendPeriodInSeconds：配置统计收集数据的传输间隔，默认为 3600；

  • configuration：配置采集数据配置文件；

• deviceFiltering：该功能是可选的，用于配置设备筛选，可以配置筛选允许向 tb 发送数据的设备（若需要使用的话需要额外的配置文件定义筛选设备的规则，此处暂不讲解）；

  • enable：配置是否启用该功能；

  • filterFile：配置设备过滤配置文件；

• maxPayloadSizeBytes：官方未解释，最大的消息负载字节数，默认 1024；

• minPackSendDelayMS：配置发送数据包之间的延迟，配置过小会导致 CPU 使用量上升；

• minPackSizeToSend：官方未解释，配置最小的发送数据包大小，默认 500；

• checkConnectorsConfigurationInSeconds：官方未解释，配置检查连接器配置的时间，默认 60 秒；

• handleDeviceRenaming：官方未解释；

• security：安全配置；

  • accessToken：配置 tb 平台上网关设备对应的 token；

• qos：mqtt 协议消息质量等级，默认为 1；

• checkingDeviceActivity：该功能是可选的，用于配置监控设备的活动；如果对该部分内容进行了配置，网关将每个一段时间对设备的活动状态进行检查；

  • checkDeviceInactivity：配置是否启用该功能；

  • inactivityTimeoutSeconds：配置设备的活跃超时时间，超过该时间的没有响应的设备将被认为处于非活跃状态，默认 200 秒；

  • inactivityCheckPeriodSeconds：配置设备活跃性检查的周期，默认 500 秒；

存储配置模块 storage

存储配置模块主要用于设置数据发送到 tb 平台之前如何进行保存，即采集数据的持久化配置，tb-gateway 提供了三种持久化的方式，分别为：

• memory：内存存储，将接收到的数据保存到 RAM 内存中；

• file：文件存储，将接收到的数据保存到硬盘上；

• sqlite：sqlite 存储，将接收到的数据保存到 .db 文件中；

通过type参数可以指定上述三种模式，并对各模式中的参数进行配置，网关默认设置为内存存储模式，其可配置参数包括：

• read_records_count：从存储中获取并发送至 tb 平台的消息数量；

• max_records_count：存储中可存储的最大消息数量（超出的消息将丢失）；

配置示例：

  "storage": {"type": "memory","read_records_count": 100,"max_records_count": 100000}

选用文件存储模式时，其可配置参数包括：

• data_folder_path：

• max_file_count：

• max_read_records_count：

• max_records_per_file：

配置示例：

  "storage": {"type": "file","data_folder_path": "./data/","max_file_count": 10,"max_read_records_count": 10,"max_records_per_file": 10000}

选用 sqlite 存储模式时，其可配置参数包括：

• data_file_path：

• messages_ttl_check_in_hours：

• messages_ttl_in_days：

配置示例：

  "storage": {"type": "sqlite","data_file_path": "./data/data.db","messages_ttl_check_in_hours": 1,"messages_ttl_in_days": 7}

远程调用配置模块 grpc

该模块目前未测试，官方文档未进行解释，待验证；

连接器配置模块 connectors

该模块用于配置要启动的连接器，每一个连接器需要执行下列 3 个参数：

• useGRPC：可选配置参数，用于配置当前连接器是否开启 rpc 功能，默认为 true；

• name：指定连接器名称；

• type：连接器类型；

• configuration：连接器的配置文件名称；

配置示例：

  "connectors": [{"type": "mqtt","name": "MQTT Broker Connector","configuration": "mqtt.json"},{"type": "modbus","name": "Modbus Connector","configuration": "modbus.json"},{"type": "opcua","name": "OPC-UA Connector","configuration": "opcua.json"}]

tb-gateway 基础使用

gateway 连接至 tb

在修改通用配置文件 tb_gateway.yaml 之前，首先需要在 tb 平台上创建对应的网关设备，如下所示：

完成网关设备创建后，修改 tb_gateway.yaml 配置文件，配置 host、port 以及 accessToken 字段，分别为 tb 平台的服务地址、tb 平台 MQTT 端口号以及网关设备的访问令牌（设备详情中点击“复制访问令牌”按钮获取，也可自定义，详见 thingsboard 使用手册）。简单的配置示例如下：

{"thingsboard": {"host": "192.168.XX.XXX","port": 1883,"remoteShell": false,"remoteConfiguration": true,"statistics": {"enable": true,"statsSendPeriodInSeconds": 3600},"deviceFiltering": {"enable": false,"filterFile": "list.json"},"maxPayloadSizeBytes": 1024,"minPackSendDelayMS": 200,"minPackSizeToSend": 500,"checkConnectorsConfigurationInSeconds": 60,"handleDeviceRenaming": true,"security": {"type": "accessToken","accessToken": "YqZ0moqfS1srMt4OXDWP"},"qos": 1,"checkingDeviceActivity": {"checkDeviceInactivity": false,"inactivityTimeoutSeconds": 200,"inactivityCheckPeriodSeconds": 500}},"storage": {"type": "memory","read_records_count": 100,"max_records_count": 100000,"data_folder_path": "./data/","max_file_count": 10,"max_read_records_count": 10,"max_records_per_file": 10000,"data_file_path": "./data/data.db","messages_ttl_check_in_hours": 1,"messages_ttl_in_days": 7},"grpc": {"enabled": false,"serverPort": 9595,"keepaliveTimeMs": 10000,"keepaliveTimeoutMs": 5000,"keepalivePermitWithoutCalls": true,"maxPingsWithoutData": 0,"minTimeBetweenPingsMs": 10000,"minPingIntervalWithoutDataMs": 5000,"keepAliveTimeMs": 10000,"keepAliveTimeoutMs": 5000},"connectors": [{"type": "mqtt","name": "MQTT Broker Connector","configuration": "mqtt.json"},{"type": "modbus","name": "Modbus Connector","configuration": "modbus.json"},{"type": "opcua","name": "OPC-UA Connector","configuration": "opcua.json"}]
}

配置完成后保存，并重新启动 tb-gateway 服务。docker 采用以下命令重新启动：

docker restart tb-gateway

rpm 安装使用以下命令重新启动：

systemctl restart thingsboard-gateway

tb 平台设备管理页面查看相应的网关设备状态，状态变更为活跃则网关启动并连接成功，如下图：

mqtt 连接器

若需要使用 mqtt 连接器连接下层设备，则需要配置 mqtt.json 配置文件，并在 tb_gateway.yaml 启动相应的连接器（打开相应连接器的注释即可）。

mqtt.json 配置文件可配置的内容如下。

broker

该模块用于配置 tb-gateway 到 MQTT broker 服务器的连接，其主要配置属性包括：

• name：broker 名称，用于日志记录显示等；

• host：MQTT broker 服务器地址；

• port：MQTT broker 监听端口；

• clientId：tb-gateway 连接 MQTT broker 的客户端 id；

• version：配置 MQTT 协议的 version；

• maxMessageNumberPerWorker：配置每个 worker 的最大消息数（官方未提及）；

• maxNumberOfWorkers：配置最大 worker 数量（官方未提及）；

• sendDataOnlyOnChange：配置当数据发生变化时才进行转发；

• security：身份验证配置，用于 tb-gateway 连接 MQTT broker，有 3 种配置模式可供选择：

  • "type": "anonymous"：不进行身份验证，配置示例如下：

    "security": {"type": "anonymous"
    }
    

  • "type": "basic"：需要配置username以及password用于身份的验证，配置示例如下：

    "security": {"type": "basic","username": "username","password": "password"
    }
    

  • Certificates：采用证书验证，需要配置各个证书的路径，配置示例如下：

    "security":{"caCert": "/etc/thingsboard-gateway/ca.pem","privateKey": "/etc/thingsboard-gateway/privateKey.pem","cert": "/etc/thingsboard-gateway/certificate.pem"
    }
    

broker 配置示例：

  "broker": {"name": "Default Local Broker","host": "192.168.XX.XXX","port": 1883,"clientId": "ThingsBoard_gateway","maxMessageNumberPerWorker": 10,"maxNumberOfWorkers": 100,"security": {"type": "basic","username": "","password": ""}}

mapping

该模块用于配置 tb-gateway 监听的主题，以及将监听数据转换为遥测\属性数据并上报至 tb 平台的格式。mapping是一个列表，其中可以配置子 JSON，每一个都包含一个要监听的主题topicFilter以及消息的转换converter：

• topicFilter：监听的 topic；

• converter：数据上报格式转换配置；

  • type：传入消息的数据格式，推荐使用json（官方也提供了bytes字节模式和custom自定义模式）；

  • deviceNameJsonExpression：从消息中获取设备名称的表达式，用于 tb 平台设备的创建；

  • deviceTypeJsonExpression：从消息中获取设备配置名称的表达式，用于 tb 平台设备的创建；

  • deviceNameTopicExpression：从主题中获取设备名称的表达式，用于 tb 平台设备的创建；

  • deviceTypeTopicExpression：从主题中获取设备配置名称的表达式，用于 tb 平台设备的创建；

  • sendDataOnlyOnChange：配置是否当数据变化时才进行上传，默认为 false；

  • timeout：触发设备断开时间的超时时间；

  • attributes：属性消息列表，包含多个子 JSON，其中的属性的值可以通过特定表达式从设备消息内容当中获取；

    • type：属性的数据类型；

    • key：属性的名称；

    • value：属性的值；

  • timeseries：遥测消息列表，包含多个子 JSON，其中的属性的值可以通过特定表达式从设备消息内容当中获取；

    • type：属性的数据类型；

    • key：属性的名称；

    • value：属性的值；

mapping 配置示例：

  "mapping": [{"topicFilter": "/sensor/data","converter": {"type": "json","deviceNameJsonExpression": "${sensorName}","deviceTypeJsonExpression": "${sensorType}","timeout": 60000,"attributes": [{"type": "string","key": "model","value": "${sensorModel}"},{"type": "string","key": "${sensorModel}","value": "on"}],"timeseries": [{"type": "double","key": "temperature","value": "${temp}"},{"type": "double","key": "humidity","value": "${hum}"},{"type": "string","key": "combine","value": "${hum}:${temp}"}]}},{"topicFilter": "/sensor/+/data","converter": {"type": "json","deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/data)","deviceTypeTopicExpression": "Thermometer","timeout": 60000,"attributes": [{"type": "string","key": "model","value": "${sensorModel}"}],"timeseries": [{"type": "double","key": "temperature","value": "${temp}"},{"type": "double","key": "humidity","value": "${hum}"}]}}]

数据上报测试：

上述配置中监听了两个主题，分别使用了从消息中获取设备名称、配置和从主题中获取设备名称、配置的方法。

对于从消息中获取设备名称和配置的方法，按照下列主题和消息格式发送设备数据，tb 平台收到对应消息，根据设备名称和配置创建设备，并将属性以及遥测信息进行存储。

tb 平台查看结果：

对于从主题中获取设备名称和配置的方法，按照下列主题和消息格式发送设备数据，tb 平台收到对应消息，根据设备名称和配置创建设备，并将属性以及遥测信息进行存储。

tb 平台查看结果：

connectRequests

该模块用于新设备的连接，通过该模块的配置，网关将接受到新设备的连接并发送至 tb 平台实现设备的创建，同时设备的服务端属性lastConnectTime将更新。

其配置内容与 mapping 中相同，此处不再赘述，配置示例如下：

  "connectRequests": [{"topicFilter": "sensor/connect","deviceNameJsonExpression": "${sensorName}"},{"topicFilter": "sensor/+/connect","deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/connect)"}]

设备连接测试：

disconnectedRequests

该模块用于设备的断开连接，通过该模块的配置，网关将接受到设备断联的信息告知 tb 平台，设备的服务端属性lastDisconnectTime将随之变化（注：设备状态不会实时变化，tb 平台通过定时轮询实现设备状态的改变）。

其配置内容与 mapping 中相同，此处不再赘述，配置示例如下：

  "disconnectRequests": [{"topicFilter": "sensor/disconnect","deviceNameJsonExpression": "${sensorName}"},{"topicFilter": "sensor/+/disconnect","deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/disconnect)"}]

attributeRequest

该模块的配置是可选的，该配置用于设备侧通过网关向 tb 平台发起 rpc 请求，以获取在平台共享属性。其配置内容包括：

• retain：配置消息是否保留；

• topicFilter：配置接收设备请求的主题，设备应向该主题发送请求的参数；

• deviceNameTopicExpression：配置从消息内容中获取设备的名称；

• attributeNameJsonExpression：配置从消息内容中获取要请求的属性名；

• topicExpression：配置设备接收请求结果的主题，网关获取到 tb 平台返回的数据后，将从消息中提取相应参数拼接主题并发送消息至该主题；

• valueExpression：配置设备期望的返回数据的消息格式；

配置示例：

  "attributeRequests": [{"retain": false,"topicFilter": "v1/devices/me/attributes/request","deviceNameJsonExpression": "${sensorName}","attributeNameJsonExpression": "${queryAttribute}","topicExpression": "devices/${deviceName}/attrs","valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"}]

测试示例：

attributeUpdates

该配置用于订阅设备主动推送的共享属性改变。当配置中的设备的共享属性在 tb 平台端发生修改时，设备可以通过订阅特定主题来及时的获取到对应属性的更改。其配置内容包括：

• retain：配置消息是否保留；

• deviceNameFilter：设备名称过滤器，使用正则表达式配置需要监听哪些设备的共享属性变化；

• attributeFilter：属性名过滤器，使用正则表达式配置要监听的属性名；

• topicExpression：配置设备接收请求结果的主题，网关获取到 tb 平台返回的数据后，将从消息中提取相应参数拼接主题并发送消息至该主题；

• valueExpression：用于配置接收属性变化推送的消息格式；

配置示例：

  "attributeUpdates": [{"retain": false,"deviceNameFilter": "sensor.*","attributeFilter": ".*","topicExpression": "sensor/${deviceName}/${attributeKey}","valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"}]

测试示例：

serverSideRpc

该模块用于配置平台侧通过 tb-gateway 网关向设备传达 rpc 指令，指令存在两种形式，分别为需要回复和不需要回复。该模块的配置内容包括：

• deviceNameFilter：设备名称过滤器，使用正则表达式配置哪些设备需要接收 rpc 指令；

• methodFilter：方法名过滤器，使用正则表达式配置需要接收哪些方法的 rpc 指令；

• requestTopicExpression ：请求主题表达式，配置网关接收到 tb 的 rpc 指令后，将指令推送到的主题；

• responseTopicExpression：响应主题表达式，配置网关订阅的主题，用于接收设备收到 rpc 指令后的响应（对于不需要回复的指令无需配置）；

• responseTimeout：响应超时时间；

• valueExpression：用于配置网关转发指令给设备的消息格式；

配置示例，分别配置了两种形式的 rpc 指令：

  "serverSideRpc": [{"deviceNameFilter": ".*","methodFilter": "echo","requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}","responseTopicExpression": "sensor/${deviceName}/response/${methodName}/${requestId}","responseTimeout": 10000,"valueExpression": "${params}"},{"deviceNameFilter": ".*","methodFilter": "no-reply","requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}","valueExpression": "${params}"}]

测试示例，采用仪表盘的 rpc debug 部件模拟平台向设备发送 rpc 指令（也可以直接调用 API）：

需要回复的 rpc 指令测试，需要注意回复主题中的 requestId 需与接收主题当中的保持一致：

不需要回复的 rpc 指令测试，由网关直接响应已收到：

modbus 连接器

若需要使用 modbus 连接器连接下层设备，则需要配置 modbus.json 配置文件，并在 tb_gateway.json 启动相应的连接器（打开相应连接器的注释即可）。

modbus.json 配置文件可配置的内容如下（此处主要讲解 modbus tcp 配置）。

注：从3.0版本开始，网关可以作为 Modbus 从站运行。其相关配置在 slave 模块，与 master 模块设置处于并列关系，后续将更新相关配置。

master

该模块中可以定义多个 Modbus slave，每一个 slave 都是一个独立的设备。

配置示例：

"master": {"slaves": [...]
}

slaves

该模块中配置相关的设备信息，实际上就是一个 Modbus slave，其为一个列表，其中可配置多个设备，对于每一个设备，都需要配置如下参数：

• host：配置 Modbus server 地址；

• port：配置 Modbus server 连接端口号；

• type：配置连接类型，包括 tcp、udp 以及 serial 三种模式；

• method：连接方式，可选择 socket 或者 rtu；

• timeout：配置连接到 Modbus server 的超时时间，单位为秒；

• byteOrder：配置寄存器字节的读取顺序，默认为 LITTLE；

• wordOrder：配置读取多个寄存器时的顺序，默认为 LITTLE；

• retries：配置是否进行重试，默认为 true；

• retryOnEmpty：配置数据为空时是否进行重试，默认为 true；

• retryOnInvalid：配置失败时是否进行重试，默认为 true；

• pollPeriod：配置数据的拉取周期；

• unitId：当前 slave 的 Id；

• deviceName：设备名称，即注册到 tb 平台上的设备名称；

• sendDataOnlyOnChange：配置是否仅数据变化时发送数据，默认为 true；

• connectAttemptTimeMs：等待连接周期，单位为毫秒；

• connectAttemptCount：尝试连接次数，默认为 5；

• waitAfterFailedAttemptsMs：连接失败后尝试再次连接的等待时间，单位为毫秒；

• attributes：配置网关向外转发的属性属性；

• timeseries：配置网关向外转发的遥测数据；

• attributeUpdates：配置订阅 tb 平台的属性变化；

• rpc：rpc 指令相关配置；

配置示例如下：

    "slaves": [{"host": "192.168.XX.XXX","port": 502,"type": "tcp","method": "socket","timeout": 35,"byteOrder": "LITTLE","wordOrder": "LITTLE","retries": true,"retryOnEmpty": true,"retryOnInvalid": true,"pollPeriod": 5000,"unitId": 1,"deviceName": "Temp Sensor","sendDataOnlyOnChange": true,"connectAttemptTimeMs": 5000,"connectAttemptCount": 5,"waitAfterFailedAttemptsMs": 300000,"attributes": [...],"timeseries": [...],"attributeUpdates": [...],"rpc": [...]}]

attributes

该模块主要用于配置网关向外转发的属性，配置内容包括：

• tag：设置属性的 key 值；

• type：设置属性的类型，可参照本节末尾的属性对应表；

• functionCode：设置Modbus 函数功能码，可参照本节末尾提供的功能码表；

• address：设置要读取的起始寄存器位置；

• registerCount：设置要读取的寄存器数量；

配置示例如下：

        "attributes": [{"tag": "testAttribute","type": "32int","functionCode": 3,"registerCount": 2,"address": 0}]

配置测试：

在 tb 平台端可以看到对应属性：

timeseries

该模块主要用于配置网关向外转发的遥测数据，其配置内容与上一小节的 attributes 完全一致，此处不再赘述。

配置示例：

        "timeseries": [{"tag": "testTimeserie1","type": "32int","functionCode": 3,"registerCount": 2,"address": 0},{"tag": "testTimeserie2","type": "64uint","functionCode": 3,"registerCount": 4,"address": 2},{"tag": "testTimeserie3","type": "bytes","functionCode": 3,"registerCount": 1,"address": 6}]

配置测试：

在 tb 平台端可以看到对应遥测数据：

attributeUpdates

该模块主要用于配置 tb 平台修改设备的共享属性之后，平台主动推送更改至网关，网关回根据此处的设置将数据更改保存在指定的寄存器，其配置内容与 attributes 完全一致，此处不再赘述，不同的是tag属性配置的是共享属性的属性名。

配置示例：

        "attributeUpdates": [{"tag": "shared_attribute_write","type": "32int","functionCode": 16,"objectsCount": 2,"address": 29}]

配置测试：

rpc

该模块用于配置 tb 平台发送 rpc 指令以设置或获取对应寄存器的数据，其配置内容与 attributes 完全一致，此处不再赘述，不同的是此处的tag属性配置的是 tb 端发送请求的方法名。

配置示例：

        "rpc": [{"tag": "setValue","type": "16int","functionCode": 6,"objectsCount": 1,"address": 31},{"tag": "getValueBytes","type": "bytes","functionCode": 3,"objectsCount": 1,"address": 31}]

配置测试，可以通过 tb 部件库提供的 rpc debug 工具测试，也可以直接调接口测试：

参考 – Modbus functions

Modbus function code	Description
Read data
1	Read Coils
2	Read Discrete Inputs
3	Read Multiple Holding Registers
4	Read Input Registers
Write data:
5	Write Coil
6	Write Register
15	Write Coils
16	Write Registers

参考 – Data types

Type	Function code	Objects count	Note
string	3-4	1-…	Read bytes from registers and decode it (‘UTF-8’ coding).
bytes	3-4	1-…	Read bytes from registers.
bits	1-4	1-…	Read coils. If objects count 1 - result will be interpret as a boolean, else the result will be an array with bits.
16int	3-4	1	Integer 16 bit.
16uint	3-4	1	Unsigned integer 16 bit.
16float	3-4	1	Float 16 bit.
32int	3-4	2	Integer 32 bit.
32uint	3-4	2	Unsigned integer 32 bit.
32float	3-4	2	Float 32 bit.
64int	3-4	4	Integer 64 bit.
64uint	3-4	4	Unsigned integer 64 bit.
64float	3-4	4	Float 64 bit.

opcua 连接器

若需要使用 opcua 连接器连接下层设备，则需要配置 opcua.json 配置文件，并在 tb_gateway.json 启动相应的连接器（打开相应连接器的注释即可）。

opcua.json 配置文件可配置的内容如下。

server

该模块用于配置与 opcua server 的连接，其配置内容包括：

• name：配置 OPC-UA server 名称；

• url：配置 OPC-UA server 的 url 地址；

• timeoutInMillis：配置连接到 OPC-UA server 的超时时间；

• scanPeriodInMillis：配置扫描服务器的周期；

• disableSubscriptions：配置是否禁用订阅，默认为 false，开启后，网关将订阅感兴趣的节点并等待数据更新；如果为false，网关将以 scanPeriodInMillis 为周期重新扫描 OPC-UA 服务器；

• subCheckPeriodInMillis：配置检查订阅的周期；

• showMap：配置在扫描时是否展示节点；

• security：配置安全策略，可在 Basic128Rsa15、Basic256、Basic256Sha256 进行选择；

• identity：配置身份验证模式；

  • type: anonymous：匿名认证；

        "identity": {"type": "anonymous"}
    

  • type: username：用户名密码认证；

        "identity": {"username": "user","password": "5Tr0nG?@$sW0rD"}
    

  • type: cert.PEM：证书认证，其中mode字段可选择Sign或SignAndEncrypt；

        "identity": {"type": "cert.PEM","caCert": "etc/thingsboard-gateway/ca.pem","privateKey": "etc/thingsboard-gateway/private_key.pem", "cert": "etc/thingsboard-gateway/cert.pem","mode": "SignAndEncrypt","username": "user","password": "5Tr0nG?@$sW0rD"}
    

• mapping：进行设备以及数据上报相关信息；

配置示例：

  "server": {"name": "OPC-UA Default Server","url": "192.168.XX.XXX:53530/OPCUA/SimulationServer","timeoutInMillis": 5000,"scanPeriodInMillis": 5000,"disableSubscriptions": false,"subCheckPeriodInMillis": 100,"showMap": false,"security": "Basic128Rsa15","identity": {"type": "anonymous"},"mapping": [...]}

mapping

该模块主要用于配置点位与设备的对应关系，以及配置设备上报的属性、遥测等数据格式等。其配置内容包括：

• deviceNodePattern：配置设备节点的表达式，用于查找对应节点；

• deviceNamePattern：配置设备名称的表达式，用于在 tb 平台创建设备；

• attributes：配置属性上报消息内容；

• timeseries：配置遥测数据上报消息内容；

• rpc_methods：配置 rpc 指令相关内容；

• attributes_updates：配置属性更新订阅相关内容；

配置示例：

    "mapping": [{"deviceNodePattern": "Root\\.Objects\\.Simulation","deviceNamePattern": "OPC-UA Device","attributes": [...],"timeseries": [...],"rpc_methods": [...],"attributes_updates": [...]}]

attributes

该模块用于配置设备属性上报的相关内容，其配置内容包括：

• key：配置上报属性的名称；

• path：配置上报属性的值的存储路径；

配置示例：

        "attributes": [{"key": "Triangle","path": "${ns=3;i=1007}"}]

配置测试：

tb 平台可观察到设备创建并且属性上报成功：

timeseries

该模块用于配置设备遥测数据上报的相关内容，其配置内容与 attributes 相同，此处不再赘述。

配置示例：

        "timeseries": [{"key": "Counter","path": "${ns=3;i=1002}"},{"key": "Random","path": "${ns=3;i=1003}"}]

配置测试，此处配置方法与 attributes 完全相同，直接查看 tb 平台上报结果：

rpc_methods

该模块主要用于配置远程 rpc 的方法以及参数，可配置内容包括：

• method：配置 rpc 方法名供 tb 平台端调用；

• arguments：配置方法参数，若不配置则接收远程调用的传参；

该模块功能笔者未测试成功，此处给出官方提供的配置示例：

        "rpc_methods": [{"method": "multiply","arguments": [2,4]}]

官方提供的内置 rpc 方法 get\set 来获取\设置属性及遥测数据的方法：

attributes_updates

该模块用于配置 tb 端设备共享属性的更新订阅，配置内容包括：

• attributeOnThingsBoard：指定要订阅的 tb 平台设备的属性名称；

• attributeOnDevice：指定上述属性更新时最新值的存放节点；

配置示例：

        "attributes_updates": [{"attributeOnThingsBoard": "MyDeviceName","attributeOnDevice": "Root\\.Objects\\.Simulation\\.MyDeviceName"}]

配置测试：

opc server 模拟器查看相应节点值是否随之更新：

自定义连接器

自定义连接器官方示例

tb-gateway 提供了自定义连接器的示例，该示例允许网关从串口采集数据并将数据处理后形成属性或者遥测数据上报到 tb 平台。

测试使用 tb-gateway 版本为 3.4.2，使用本地源码启动，计算机串口采用虚拟串口工具进行模拟，采用串口调试工具进行数据的发送。

本地源码启动时，需注意：

• 应注释 tb_gateway_service.py 文件第 193 行的self.__modify_main_config()方法，该方法会读取当前计算机的名称作为连接到 tb 平台的 accessToken，导致主配置文件 tb_gateway.json 中配置的 accessToken 失效，造成鉴权失败问题；

• 官方提供的自定义连接器示例 custom_serial_connector.py 中，未实现父类的get_config(self)方法，需手动实现。如下配置即可：

      def get_config(self):return self.__config
  

• 官方提供的自定义连接器示例 custom_serial_connector.py 中，run()方法中第 132 行判断中止字符时，修改为下列字符，否则程序一直在此循环内执行：

  while not self.stopped and received_character != b'n':  # We will read until receive LF symbol
  

官方提供的示例测试如下：

首先修改主配置文件 tb_gateway.json，配置地址、端口、密钥以及 connectors 模块：

  "connectors": [{"name": "Custom Serial Connector","type": "serial","configuration": "custom_serial.json","class": "CustomSerialConnector"}]

设置自定义连接器的配置文件 custom_serial.json，其中的配置与自定义连接器的处理相关，后期都可以自定义使用，此处不展开讲解，可参考如下进行配置：

{"name": "Custom serial connector","devices": [{"name": "CustomSerialDevice1","type": "default","port": "COM2","baudrate": 9600,"converter": "CustomSerialUplinkConverter","telemetry": [{"type": "byte","key": "humidity","untilDelimiter": "\\r"}],"attributes": [{"key": "SerialNumber","type": "string","fromByte": 4,"toByte": -3}],"attributeUpdates": [{"attributeOnThingsBoard": "attr1","stringToDevice": "value = ${attr1}\n"}]}]
}

配置完成后，运行 tb_gateway.py 以启动网关。

配置测试：本地使用虚拟串口工具模拟两个串口 COM1 以及 COM2：COM1 连接串口调试工具，该串口与 COM2 串口连接，COM2 串口被网关占用。如下所示：

向端口发送数据48\r2430947595\n，自定义连接器将根据转换逻辑进行处理，并封装成标准的格式（由配置文件进行定义，转换逻辑实现）发送至 tb 平台：

自定义连接器还提供了设备共享属性更新主动的功能，如下所示：tb 平台对应设备的共享属性更新后，平台通过网关将数据推送至设备，即 COM2 串口，COM2 与 COM1 串口相连，故 COM1 串口收到相应的数据。

自定义连接器配置步骤

1. 编辑自定义连接器的配置文件，配置的内容与连接器以及转换器的处理逻辑有关，配置完成后将文件放置 config 文件夹；

2. 编辑连接器，连接器需要继承官方提供的 Connector 类，用于配置设备的连接；

3. 编辑转换器，转换器需要继承官方提供的 Converter 类，用于配置设备数据到网关转发数据的格式转换逻辑；

4. 在 extensions 文件夹中新建文件夹，将自定义的连接器、转换器放在该文件夹内，并添加带有 Licensed 头的__init__.py文件；

5. 在主配置文件 tb_gateway.json 的连接器模块中配置自定义的连接器，配置内容如下：

   • name：配置连接器名称；

   • type：配置连接器类型，需设置为 extensions 文件夹中存放自定义连接器、转换器的文件夹名称；

   • configuration：配置文件名称；

   • class：配置自定义转换器的类名；

   配置示例如下：

     "connectors": [{"name": "Custom Serial Connector","type": "serial","configuration": "custom_serial.json","class": "CustomSerialConnector"}]
   

6. 启动网关，进行测试验证即可；

感谢您阅读本文，如果您在阅读过程中发现了任何错误或不准确的内容，请与我联系并提供反馈，我将尽快进行更正和修正。