概述
MQTT（消息队列遥测传输）是一种轻量级的发布-订阅式机器对机器网络协议，广泛用于资源受限或网络传输速率有限的远程设备连接。本文档将帮助您为ThingsBoard IoT网关设置MQTT连接器。我们将用简单的术语解释配置参数，使您易于理解和操作。 使用通用配置启用此连接器。
如果您是ThingsBoard IoT网关的新用户，建议先阅读快速入门指南，了解ThingsBoard IoT网关的基本概念及其与MQTT协议的工作方式。
该连接器可通过用户界面表单进行配置，帮助您建立与MQTT代理的连接，并通过订阅/发布MQTT主题来读写数据，主题可以静态定义或动态生成。 让我们查看所有可用设置并逐一说明。 这将帮助您了解各项功能的工作原理。
请注意： 要访问网关的实际UI，您需要在添加连接器之前已连接网关。否则，您将看到旧版UI。
配置模式
MQTT连接器可以在两种模式下配置：Basic和Advanced。
- Basic模式专为ThingsBoard IoT网关新用户设计，可通过最少的配置快速设置连接器。它提供简化的界面和基本设置。
- Advanced模式适用于需要更多配置控制权的有经验用户。它提供额外的选项和灵活性，适合高级用例。
请注意： 如果您是IoT网关新用户，请使用”Basic”配置模式。如果您熟悉IoT网关的配置， 可以使用”Advanced”配置模式。
您可以使用配置页面顶部的切换按钮在这两种模式之间切换：
通用设置
本配置部分包含 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 的信息请参见此处。
通用设置选项卡在基本配置和高级配置中是相同的。
连接设置
MQTT连接器如何与MQTT代理建立和维护通信。 这些设置用于配置基本连接参数、使用的MQTT协议版本以及相应的安全和认证模式。
连接到代理
此子部分指定目标MQTT代理以及网关如何与其交互。包括代理的主机地址、 端口、MQTT协议版本和客户端ID。
本配置部分包含 MQTT Broker 连接相关设置，例如：
- Host（主机） - MQTT Broker 的主机名或 IP 地址；
- Port（端口） - MQTT Broker 上用于建立连接的监听端口；
- MQTT version（MQTT 版本） - MQTT 协议版本（网关当前支持 3.1、3.11、5 三个版本）；
- Client ID（客户端 ID） - 每个客户端在 Broker 上会话的唯一标识符；
- Security（安全） - 在 MQTT Broker 端配置客户端认证（匿名、基本认证或证书）。
请注意： Broker（或 Broker 集群）不允许使用相同 Client ID 的两个会话同时存在。若第二个连接使用了该 ID， Broker 会关闭已有会话并接受新连接（会话接管）。Client ID 可为任意有效 UTF-8 字符串； 若暂无描述性 ID，可在 MQTT connector 配置界面中生成——见本小节下方的最后几张截图。
所有配置参数列表及其详细说明参见 高级配置 章节。
若希望由界面生成 Client ID，请将 Client ID 字段留空并点击 Generate Client ID（见下方截图）。 网关会创建唯一的标识符。
生成 Client ID 后的界面表单，例如 tb_gw_rfpev——仅为示例，您的实际值会不同。
安全设置
MQTT代理连接提供三种不同的安全类型：匿名（Anonymous）、基本认证（Basic）、证书（Certificates）。
Anonymous 是最简单的选项：在 MQTT broker 上发布/订阅无需凭据。 适合测试使用（例如公共测试 broker）， 但不建议用于生产环境，因其允许不受控访问。  |
Basic 认证使用 MQTT broker 上配置的 username 和 password。 适合大多数场景——只需使用强且唯一的凭据。若需更强身份验证和双向认证，可考虑基于证书的认证。  |
基于证书的认证使用 TLS，使网关和 broker 相互验证。 将CA 证书文件路径设为 CA 证书（用于信任 broker），客户端证书文件路径设为网关的客户端证书，私钥文件路径设为其私钥（以便 broker 认证网关）。 使用 broker 的 TLS 端口（通常为 8883）以获得加密的生产级安全。  |
每种认证模式的所有配置参数列表及其详细描述可在 高级配置部分找到。
数据映射
数据映射允许您配置网关订阅的主题，用于设备创建和传入数据处理。 您可以动态生成主题和设备名称，并选择哪些数据作为设备属性或遥测数据发送。本节提供了灵活的设备和数据管理的基本设置。
以下参数用于配置网关订阅的数据源主题、设备创建（名称和配置文件）及上报策略：
- Topic filter -网关将订阅的用于数据源的主题。Topic filter支持特殊符号：’#’和’+’ 通配符（关于如何使用它们进行主题模式匹配的更多信息请参见附加信息部分）。
- MQTT连接器还支持共享订阅，创建共享订阅需要在Topic filter前添加
$share/前缀和共享订阅组名（关于如何使用它的更多信息请参见附加信息部分）以及使用它们时可能出现的问题共享订阅限制。 - QoS - MQTT服务质量是消息发送者和接收者之间的协议，定义了特定消息的传递保证级别。（0-至多一次，1-至少一次，2-恰好一次）
- 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发送数据（默认策略）。
数据转换
- Payload type -将被处理的传入数据类型，可为
JSON、Bytes、Custom（关于支持的有效载荷类型的更多信息请参见附加信息转换器类型部分）。 - Device Name - ThingsBoard中的设备名称。可从
Message、Topic、Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。 - Device Profile name - ThingsBoard中的设备配置文件。可从
Message、Topic、Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。
要添加新设备，请按以下步骤操作：
属性和时序数据
本子节的配置提供了处理来自MQTT主题数据的设置。这些设置将在ThingsBoard平台实例中被解释为设备的属性/时序数据。
以下参数用于配置设备属性和时序数据：
- Key - ThingsBoard中属性/时序数据的键名。可以指定为静态值。
- Type -属性/时序数据字段的类型（可以是以下之一：
string、boolean、integer、double，或当Payload type为Bytes时为Raw）： - Value -将发送到平台设备的属性/时序数据值。应根据所选Payload type（
Bytes、JSON、CUSTOM）来指定。
添加新的 time series 或 attribute key 时，请按以下步骤操作：
-
点击”Attributes“部分的”铅笔“图标以添加新 attribute key；
-
在打开窗口中点击”Add attribute“；
-
填写”Key“字段，选择”Type“（可为
string、boolean、integer、double，若 Payload type 为Bytes则可为Raw），填写”Value“并点击”Apply“； -
点击”Time series“部分的”铅笔“图标以添加新 time series key；
-
在打开窗口中点击”Add time series“；
-
填写”Key“字段，选择”Type“（可为
string、boolean、integer、double，若 Payload type 为Bytes则可为Raw），填写”Value“并点击”Apply“。
点击”Attributes“部分的”铅笔“图标以添加新 attribute key；
在打开窗口中点击”Add attribute“；
填写”Key“字段，选择”Type“（可为 string、boolean、integer、double，若 Payload type 为 Bytes 则可为 Raw），填写”Value“并点击”Apply“；
点击”Time series“部分的”铅笔“图标以添加新 time series key；
在打开窗口中点击”Add time series“；
填写”Key“字段，选择”Type“（可为 string、boolean、integer、double，若 Payload type 为 Bytes 则可为 Raw），填写”Value“并点击”Apply“。
可为每个 time series 或 attribute 启用特定的上报策略。该策略定义数据发送到 ThingsBoard 服务器的频率。可用策略如下：
- On report period（按上报周期） - 在上报周期后向 ThingsBoard 发送数据；
- On value change（按值变化） - 值变化时向 ThingsBoard 发送数据；
- On value change or report period（按值变化或上报周期） - 值变化或到达上报周期时向 ThingsBoard 发送数据；
- On received（按接收） - 从设备接收数据后向 ThingsBoard 发送数据（默认策略）。
更多关于 report strategy 的信息请参见此处。
使用示例
注意：如果您在Docker中运行网关并使用我们在快速入门中的MQTT演示代理，必须使用host.docker.internal作为主机地址。
设备名和配置文件可从入站消息中提取。本示例使用 json path 指定设备名和配置文件。 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 代理运行于 我们还希望从
 在左侧边栏进入“实体”→“网关”并选择您的网关。  点击右侧菜单中的“连接器配置”按钮。  选择已创建的 MQTT 连接器，选择“基本”并点击“数据映射”，再点击“+ 添加映射”按钮。  在打开的窗口中，“主题过滤器”填  指向包含设备名的字段。](/images/gateway/mqtt-connector/examples/device-name-and-profile-message-json-5.png) 在“设备”子部分，“名称”字段选“Message”，填  指向包含设备配置的字段。](/images/gateway/mqtt-connector/examples/device-name-and-profile-message-json-6.png) 在“配置文件名称”子部分，“名称”字段选“Message”，填  还需要至少添加一个属性/时序数据，因为连接器不会添加无可读数据的设备。点击“时序数据”旁的“铅笔”图标。  在打开的窗口中，点击“添加时序数据”按钮并按对应图片填写字段。不要忘记保存更改。 可以检查设备名和配置文件是否正确设置。进入“实体”→“设备”，设备名应为
若使用高级配置模式并需用主题和 json path 设置设备名和配置文件，可使用以下配置： |
设备名和配置文件可从主题中提取。本示例使用 正则表达式 指定设备名和常量配置文件。 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 代理运行于 匹配该主题时，可在主题过滤器中填 配置 MQTT 连接器，使设备名从主题获取，配置文件使用常量（如
在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择已创建的 MQTT 连接器，选择“基本”并点击“数据映射”，再点击“+ 添加映射”按钮。  在打开的窗口中，“主题过滤器”填 。](/images/gateway/mqtt-connector/examples/device-name-and-profile-topic-constant-json-5.png) 在“设备”子部分，“名称”字段选“Topic”，填  在“配置文件名称”子部分，“名称”字段选“Constant”，填  还需要至少添加一个属性/时序数据，因为连接器不会添加无可读数据的设备。点击“时序数据”旁的“铅笔”图标。 在打开的窗口中，点击“添加时序数据”按钮并按对应图片填写字段。不要忘记保存更改。 可以检查设备名和配置文件是否正确设置。进入“实体”→“设备”，设备名应为
若使用高级配置模式并需用主题和 json path 设置设备名和配置文件，可使用以下配置： |
设备名和配置文件可从消息源和字节负载中提取。本示例使用 切片 指定设备名和常量配置文件。 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 代理运行于
假设要从该负载创建设备。前四个字节表示设备名，其余字节表示温度值。 配置 MQTT 连接器，从原始字节提取设备名，并使用常量作为设备配置（例如 按以下步骤操作：
在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择已创建的 MQTT 连接器，选择“基本”并点击“数据映射”，再点击“+ 添加映射”按钮。  在打开的窗口中，“主题过滤器”填 ![在“设备”子部分，“名称”字段选“Message”，填 `[0:4]`，这些是用于提取设备名的 [切片](/docs/iot-gateway/config/mqtt/#slices)。](/images/gateway/mqtt-connector/examples/device-name-and-profile-message-and-constant-bytes-5.png) 在“设备”子部分，“名称”字段选“Message”，填  在“配置文件名称”子部分，“名称”字段选“Constant”，填  还需要至少添加一个属性/时序数据，因为连接器不会添加无可读数据的设备。前四个字节表示设备名，其余字节表示温度值。点击“时序数据”旁的“铅笔”图标。  在打开的窗口中，点击“添加时序数据”按钮并按对应图片填写字段。不要忘记保存更改。 可以检查设备名和配置文件是否正确设置。进入“实体”→“设备”，设备名应为
若使用高级配置模式并需用主题和 json path 设置设备名和配置文件，可使用以下配置： |
在 MQTT 连接器中，可使用 json-path 获取属性和时序数据，
从订阅主题收到的 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 代理运行于 将
在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择 MQTT 连接器，点击“数据映射”标签。选择要添加时序数据的数据映射（若不清楚如何添加新设备，请参阅入门指南或本指南的数据映射及相应示例）。  在打开的数据映射窗口中，点击“属性”旁的“铅笔”图标。 。](/images/gateway/mqtt-connector/examples/attributes-time-series-json-path-3.png) 点击“添加属性”按钮。“键”填  记得点击相应按钮保存更改。  在打开的数据映射窗口中，点击“时序数据”旁的“铅笔”图标。  `${temp}`。](/images/gateway/mqtt-connector/examples/attributes-time-series-json-path-6.png) 点击“添加时序数据”按钮。“键”填  记得点击相应按钮保存更改。 可以检查属性数据是否正确设置。进入“实体”→“设备”，选择已创建设备，可在“属性”部分看到湿度数据：
可以检查温度数据是否发送正确。进入“实体”→“设备”，选择已创建设备，可在“最新遥测”部分看到湿度数据：
若使用高级配置模式并需用 json-path 设置 |
在 MQTT 连接器中，可使用切片获取属性和时序数据，
从订阅主题收到的 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 代理运行于
前四个字节表示设备名，其余字节表示温度值。
配置 MQTT 连接器，将原始负载存入 按以下步骤操作：
在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择 MQTT 连接器，点击“数据映射”标签。选择要添加时序数据的数据映射（若不清楚如何添加新设备，请参阅入门指南或本指南的数据映射及相应示例）。  在打开的数据映射窗口中，点击“属性”旁的“铅笔”图标。 ![点击“添加属性”按钮。“键”填 `rawData`，“类型”选 `Raw`，“值”填 `[:]`。这来自[切片](/docs/iot-gateway/config/mqtt/#slices)。](/images/gateway/mqtt-connector/examples/attributes-time-series-bytes-3.png) 点击“添加属性”按钮。“键”填  记得点击截图中的相应按钮保存更改。  在打开的数据映射窗口中，点击“时序数据”旁的“铅笔”图标。 ![点击“添加时序数据”按钮。“键”填 `temp`，“类型”选 `Raw`，“值”填 `[4:]`。这来自[切片](/docs/iot-gateway/config/mqtt/#slices)。](/images/gateway/mqtt-connector/examples/attributes-time-series-bytes-6.png) 点击“添加时序数据”按钮。“键”填  记得点击截图中的相应按钮保存更改。 可以检查属性数据是否正确设置。进入“实体”→“设备”，选择已创建设备，可在“属性”部分看到湿度数据：
可以检查温度数据是否发送正确。进入“实体”→“设备”，选择已创建设备，可在“最新遥测”部分看到湿度数据：
若使用高级配置模式并需用 json-path 设置 |
某些场景下，时序数据和属性的键名需要直接从 MQTT 主题结构中提取。这在处理动态主题或主题结构包含重要元数据时尤其有用。本示例演示如何配置 MQTT 连接器，用正则表达式从主题提取时序数据的键名。 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 代理运行于 因此主题形式如下：
我们将把主题中的 将以下配置复制粘贴到 MQTT 连接器高级配置模式中： 配置要点如下：
应用该配置后，MQTT 连接器会从主题提取传感器名并用作时序数据的键名，您应能看到对应时序数据正确更新：
|
Requests mapping
请求映射部分允许您配置ThingsBoard平台实例如何与设备交互，即平台如何向设备请求数据、如何更新/请求设备属性，以及如何向设备发送RPC命令。
MQTT连接器支持以下请求映射：
- Connect requests -通过发布网关监听的”connect”消息，告知ThingsBoard平台设备已在MQTT代理上线。
- Disconnect requests -通过向配置的主题发布断开消息，通知ThingsBoard（通过网关）设备已离线。
- Attribute updates -通过网关向配置的主题发布更新消息，将共享属性从ThingsBoard推送到设备。
- Attribute requests -设备通过向特定主题发布请求来向ThingsBoard请求属性；网关在响应主题上回复属性值。
-
RPC methods -允许向设备发送RPC命令。 MQTT连接器支持不同类型的RPC方法，例如：
-
Reserved GET/SET methods -这些方法为每个属性和时序数据参数自动创建。您可以使用它们获取或设置设备的值。对于每个配置的属性或时序数据键，连接器会暴露内置RPC：
get-读取当前值（由连接器提供/解析）set-设置/更新值（连接器应用或转发）
这些方法不需要额外映射，因为它们由连接器管理，结果直接返回给ThingsBoard。命令将由连接器处理，结果将发送回ThingsBoard平台实例。
-
Configurable RPC methods to device -这些方法允许您在连接器配置中配置可发送到设备的自定义RPC命令。
-
One Way and Two Way RPC methods -所有RPC可以是两种类型：
One Way-如果您不需要从设备获取响应Two Way-如果您需要从设备获取响应
-
Connect request
连接请求用于向网关发送消息，表明设备已连接，以便平台将设备标记为在线。
假设有这样一个场景：设备连接到MQTT代理但不发送任何遥测数据。默认情况下，10分钟不活动后，设备对ThingsBoard平台实例来说变为离线状态。 然而，即使设备不发送任何遥测数据，我们可能仍然希望能够向该设备发送RPC/属性更新。 在这种情况下，平台需要知道目标设备是否已连接，以及当前使用哪个网关或会话来连接该设备。 如果您的设备持续发送遥测数据，可以跳过本节——ThingsBoard已经知道如何推送通知。
以下参数用于配置连接请求：
- Request type -发送到ThingsBoard的请求类型（设置为”Connect request”）。
- Topic filter -网关将订阅并等待设备发布连接请求的主题。Topic filter支持特殊符号：
#和+通配符（关于如何使用它们匹配主题模式的更多信息请参见附加信息部分）。 - Name - ThingsBoard中将发送请求的设备名称。可从
Message、Topic、Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。 - Profile name - ThingsBoard中将发送请求的设备配置文件名称。可从
Message、Topic、Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。
要添加新的 connect request 映射，请按以下步骤操作：
-
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 connect request 映射。
-
在 Request type 字段选择 “Connect request“，输入 “Topic filter“，并为 Name 和 Profile name 字段选择来源类型（
Message、Constant或Topic）。根据所选来源类型输入对应的 json path、regex 或常量值。
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 connect request 映射。
、[regex](/docs/iot-gateway/config/mqtt/#regular-expressions) 或常量值。](/images/gateway/mqtt-connector/mqtt-gateway-configuring-12-ce.png)
在 Request type 字段选择 “Connect request“，输入 “Topic filter“，并为 Name 和 Profile name 字段选择来源类型（Message、Constant 或 Topic）。根据所选来源类型输入对应的 json path、regex 或常量值。
断开请求
断开请求用于向网关发送设备已断开连接的消息，以便在平台上将设备标记为离线。
当设备从MQTT代理断开连接时，需要通知ThingsBoard更新设备状态和最后断开时间。 断开请求允许网关在设备从MQTT代理断开连接时通知ThingsBoard。此信息作为服务器属性存储，可用于监控设备连接模式、排查连接问题或触发基于断开事件的工作流。 如果您的设备使用干净的断开流程（而不是仅仅超时），配置断开请求可以在ThingsBoard中提供更及时和准确的状态更新。
以下参数用于配置断开请求：
- Request type -发送到ThingsBoard的请求类型（设置为”Disconnect request”）。
- Topic filter -网关将订阅并等待设备发布断开通知的主题。Topic filter支持特殊符号：’#’和’+’ 通配符（关于如何使用它们进行主题模式匹配的更多信息请参见附加信息部分）。
- Name - ThingsBoard中将应用断开状态的设备名称。可从
Message、Topic或Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。
要添加新的 disconnect request 映射，请按以下步骤操作：
-
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 disconnect request 映射。
-
在 Request type 字段选择 “Disconnect request“，输入 “Topic filter“，并为 Name 字段选择来源类型（
Message、Topic或Constant）。根据所选来源类型输入对应的 json path、regex 或常量值。
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 disconnect request 映射。
、[regex](/docs/iot-gateway/config/mqtt/#regular-expressions) 或常量值。](/images/gateway/mqtt-connector/mqtt-gateway-disconnect-configuring-12-ce.png)
在 Request type 字段选择 “Disconnect request“，输入 “Topic filter“，并为 Name 字段选择来源类型（Message、Topic 或 Constant）。根据所选来源类型输入对应的 json path、regex 或常量值。
属性请求
属性请求用于通过网关从TingsBoard请求设备的客户端属性或共享属性的值。
当设备需要从TingsBoard检索属性值时，可以发送属性请求。这允许设备请求存储在ThingsBoard平台上的共享属性或客户端属性。 当设备向特定主题发布请求时，网关从TingsBoard获取请求的共享/客户端属性，并将响应发布到响应主题。
以下参数用于配置属性请求：
- Request type -发送到ThingsBoard的请求类型（设置为”Attribute request”）。
- Topic filter -网关订阅用于接收传入请求的主题。Topic filter支持特殊符号：
#和+通配符（关于如何使用它们进行主题模式匹配的更多信息请参见附加信息部分）。 - Device name expression - ThingsBoard中要请求属性的设备名称。可从
Message、Topic或Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。 - Attribute name expression - ThingsBoard中要请求的属性名称。可从
Message、Topic或Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。 - Response value expression -响应消息中属性值的格式。可从
Message、Topic或Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。 - Response topic expression -网关将发布属性响应消息的主题。可从
Message、Topic或Constant解析（关于数据源的更多信息和截图示例可在使用示例部分找到）。 - Retain -属性响应消息是否应由MQTT代理保留。
要添加新的 attribute request 映射，请按以下步骤操作：
-
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 attribute request 映射。
-
在 Request type 字段选择 “Attribute request“，输入 “Topic filter”
-
配置 Device name expression、Response topic expression 和 Attribute name expression 字段。 为每个字段选择来源类型（
Message、Topic或Constant）并输入对应值。 还可设置 Retain 选项以决定 attribute 响应消息是否由 MQTT broker 保留。
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 attribute request 映射。
在 Request type 字段选择 “Attribute request“，输入 “Topic filter”
配置 Device name expression、Response topic expression 和 Attribute name expression 字段。 为每个字段选择来源类型（Message、Topic 或 Constant）并输入对应值。 还可设置 Retain 选项以决定 attribute 响应消息是否由 MQTT broker 保留。
属性更新
属性更新用于通过网关在ThingsBoard上配置或更新设备的客户端属性或共享属性。
您可以将其视为设备的远程配置，使设备能够从ThingsBoard请求共享属性。更多详情请参见用户指南。
以下参数用于配置属性更新：
- Request type -发送到ThingsBoard的请求类型（设置为”Attribute updates”）。
- Device name filter -正则表达式设备名称过滤器，用于确定哪些设备应接收属性更新，参见regex（更多信息和截图示例可在使用示例部分找到）。
- Attribute filter -正则表达式属性名称过滤器，用于确定哪些属性应被更新，参见regex（更多信息和截图示例可在使用示例部分找到）。
- Response value expression -响应消息中属性值的格式。可从json-path解析（更多信息和截图示例可在使用示例部分找到）。
- Response topic expression -网关将发布属性响应消息的主题。可从json-path解析（更多信息和截图示例可在使用示例部分找到）。
- Retain -属性响应消息是否应由MQTT代理保留。
要添加新的 attribute update 映射，请按以下步骤操作：
-
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 attribute 更新映射。
-
在 Request type 字段选择 “Attribute update“，输入 “Device name filter”
-
配置 Attribute filter、Response value expression 和 Response topic expression 字段。 还可设置 Retain 选项以决定 attribute 响应消息是否由 MQTT broker 保留。
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的 attribute 更新映射。
在 Request type 字段选择 “Attribute update“，输入 “Device name filter”
配置 Attribute filter、Response value expression 和 Response topic expression 字段。 还可设置 Retain 选项以决定 attribute 响应消息是否由 MQTT broker 保留。
服务端RPC命令
服务端RPC命令用于将远程过程调用（RPC）命令从ThingsBoard传递到通过网关连接的设备。
ThingsBoard允许向直接连接到ThingsBoard或通过网关连接的设备发送RPC命令。 以下参数用于配置RPC方法：
- Request type -设置为RPC命令。可以有响应（
Two Way）或无响应（One Way）。 - Device name filter -正则表达式设备名称过滤器，用于确定哪些设备应接收RPC命令。
- Method filter -正则表达式方法名称过滤器，用于确定哪些RPC方法应被处理。
- Request topic expression - JSON-path表达式，用于创建发送RPC请求的主题地址。
- Value expression - JSON-path表达式，用于创建发送到代理的数据。
- Response topic expression（仅适用于
Two Way）- JSON-path表达式，用于创建订阅响应消息的主题地址。 - Response topic QoS（仅适用于
Two Way）-响应主题订阅的服务质量级别。 - Response timeout（仅适用于
Two Way）-超时时间（毫秒）。如果在发送请求后在此时间段内没有响应，网关将取消订阅响应主题。
单向和双向RPC概览：
要添加新的 RPC 方法，请按以下步骤操作：
-
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的服务端 RPC 命令。
-
选择 “Request type“：
With response或Without response。 -
填写必填字段：”Device name filter“、”Method filter“、”Request topic expression” 和 “Value expression“。
-
对于双向 RPC，还需配置 “Response topic expression“、”Response topic QoS” 和 “Response timeout“。完成后点击 “Add“。
在 “Requests mapping” 部分点击 “Add mapping” 以添加新的服务端 RPC 命令。
选择 “Request type“：With response 或 Without response。
填写必填字段：”Device name filter“、”Method filter“、”Request topic expression” 和 “Value expression“。
对于双向 RPC，还需配置 “Response topic expression“、”Response topic QoS” 和 “Response timeout“。完成后点击 “Add“。
此外，每个遥测和属性参数都内置了GET和SET RPC方法，无需手动配置。参见指南。
使用示例
注意：如果您在Docker中运行网关并使用我们在快速入门中的MQTT演示代理，必须使用host.docker.internal作为主机地址。
对于连接请求，网关需要知道目标设备名。可使用 json-path 从 设备
按以下步骤操作：
在左侧边栏进入“实体”→“网关”并选择您的网关。  点击右侧菜单中的“连接器配置”按钮。  选择 MQTT 连接器，点击“基本”。在“请求映射”下点击“添加映射”以添加新的连接请求映射。  在请求类型中选择  名称来源选  记得点击相应按钮保存更改。  在请求类型中选择  名称来源选  记得点击相应按钮保存更改。 10 分钟无遥测后，设备
为重新激活设备以接收 RPC 命令，需发送连接请求。下面用两个示例演示： 示例 1：设备名来自消息负载在终端模拟设备向 MQTT 代理发送包含设备名的 JSON 负载消息： 发送后，ThingsBoard 会更新设备
示例 2：设备名来自主题使用第二种映射配置也可实现同样效果，设备名从主题而非消息负载中提取： 若使用高级配置模式，可使用以下配置： |
对于断开连接请求，网关需要知道目标设备名。可使用 json-path 从 假设希望让设备 请注意： 断开连接请求会立即告知平台设备已离线，并停止向其路由 RPC 和 属性更新。 它不会阻断 MQTT 流量：若设备（或网关）继续发布，新消息仍会到达，设备可能根据 10 分钟不活跃超时再次被标记为活跃。 界面中的“活跃”标志遵循最后活动时间；除非不再有消息到达，否则超时前可能仍显示活跃。 . 在 MQTT 连接器中配置断开连接请求，以在设备断开时通知平台。演示两种提取设备名的方式：
按以下步骤操作：
在左侧边栏进入“实体”→“网关”并选择您的网关。  点击右侧菜单中的“连接器配置”按钮。 选择 MQTT 连接器，点击“基本”。在“请求映射”下点击“添加映射”以添加新的断开连接请求映射。  在请求类型中选择“断开连接请求”，将“主题过滤器”填为  名称字段的来源类型选  记得点击相应按钮保存更改。  在请求类型中选择“断开连接请求”，将“主题过滤器”填为  名称字段的来源类型选  记得点击相应按钮保存更改。 下面用两个示例演示如何使用这些断开连接请求配置：
示例 1：设备名来自消息负载当设备名包含在消息负载中时，可按以下方式发送断开连接请求： 此消息的设备名在 JSON 负载中，通过
示例 2：设备名来自主题当设备名编码在主题路径中时，可按以下方式发送断开连接请求： 此情况下，设备名通过正则表达式 若使用高级配置模式，可使用以下配置： |
对于属性请求，网关需要知道目标设备名和要请求的属性。可使用 json-path 从 假设要为设备 请注意： 属性请求允许设备从 ThingsBoard 获取属性值，适用于：
网关作为桥梁，接收设备的属性请求，从 ThingsBoard 获取属性，并将响应返回给设备。 在 MQTT 连接器中配置属性请求，使设备能从 ThingsBoard 请求属性值。演示两种提取设备名的方式：
按以下步骤操作：
在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择 MQTT 连接器，点击“基本”，在“请求映射”下点击“添加映射”以添加新的属性请求映射。  在请求类型中选择“属性请求”，将“主题过滤器”填为  配置设备名和属性。设备名表达式选择来源类型  将响应主题配置为  记得点击相应按钮保存更改。 下面用两个示例演示如何使用这些属性请求配置： 示例 1：设备名和属性来自消息负载假设某设备在ThingsBoard 中有共享属性 先在ThingsBoard 中为设备
此消息的设备名在 JSON 负载中，通过 响应将发布到主题 在另一终端模拟设备向 MQTT 代理发送包含设备名和属性名的 JSON 负载消息： 此消息的设备名在 JSON 负载中，通过
若使用高级配置模式，可使用以下配置： |
对于属性更新，网关需要知道哪些设备应接收哪些属性的更新。通过设备名和属性名的正则表达式配置。当 ThingsBoard 中某属性更新时，网关会将新值发布到配置的 MQTT 主题。 假设希望 ThingsBoard 将固件版本更新自动推送到设备。在ThingsBoard 中更新 请注意： 属性更新允许 ThingsBoard 将共享属性变更推送到设备，适用于：
网关作为桥梁，检测 ThingsBoard 中的属性变更并发布到设备可订阅的 MQTT 主题。 在 MQTT 连接器中配置属性更新，使 ThingsBoard 能将属性变更推送到设备。 按以下步骤操作：
在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择 MQTT 连接器，点击“基本”。在“请求映射”下点击“添加映射”以添加新的属性更新映射。  在请求类型中选择“属性更新”，将“设备名过滤器”填为  将属性过滤器配置为  记得点击相应按钮保存更改。  进入“设备”→选择设备  添加  找到 下面演示如何使用该属性更新配置： 示例：在ThingsBoard 中更新设备属性
订阅
若使用高级配置模式，可使用以下配置： |
保留 RPC 方法
假设有设备 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 代理运行于 请注意： RPC 调试终端仅用于示例，您可使用任何支持 RPC 调用的其他部件。 自定义 MQTT 发布器仅用于模拟设备行为，不适用于实际生产场景。 示例 1：获取当前光照（双向 RPC 带响应）在 RPC 调试终端部件中执行以下命令发送双向 RPC 请求： 网关将：
示例 2：获取当前光照（单向 RPC 无响应）在 RPC 调试终端部件中执行以下命令发送单向 RPC 请求： 网关将：
示例 3：SET 新光照（单向 RPC）在 RPC 调试终端部件中执行以下命令设置新的光照值： 网关将：
示例 4：检查更新后的光照（双向 RPC 带响应）设置新光照后，可执行以下命令验证更新值： 网关将按示例 1 处理该请求，响应中应能看到更新后的光照值。
若使用高级配置模式，可使用以下配置： |
RPC 到设备允许向直接或通过网关连接至 ThingsBoard 的设备发送 RPC 命令。 假设有设备 以下示例使用 ThingsBoard MQTT 演示代理，可通过 Docker 及以下命令运行： 演示代理运行于 请注意： RPC 调试终端仅用于示例，您可使用任何支持 RPC 调用的其他部件。 自定义 MQTT 发布器仅用于模拟设备行为，不适用于实际生产场景。 在 MQTT 连接器中配置 RPC 命令，使 ThingsBoard 能向设备发送命令。 按以下步骤操作：
在左侧边栏进入“实体”→“网关”并选择您的网关。 点击右侧菜单中的“连接器配置”按钮。 选择 MQTT 连接器，点击“基本”。在“请求映射”下点击“添加映射”以添加新的 RPC 映射。  在请求类型中选择“RPC 命令”。双向 RPC（需要响应）时。  设备名过滤器填  记得点击相应按钮保存更改。  单向 RPC（无需响应）时，点击“无响应”标签。设备名过滤器填  记得点击相应按钮保存更改。 下面演示如何使用该 RPC 配置： 示例 1：双向 RPC（有响应）在 RPC 调试终端部件中执行以下命令发送双向 RPC 请求： 网关将：
示例 2：单向 RPC（无响应）在 RPC 调试终端部件中执行以下命令发送单向 RPC 请求： 网关将：
若使用高级配置模式，可使用以下配置： |
高级配置
高级配置部分提供了MQTT连接器所有可用参数的详细概述。
连接到代理
代理部分定义了目标MQTT代理以及网关如何与其交互。
| Parameter | Default value | Description |
|---|---|---|
| broker | broker对象指定目标MQTT代理以及网关如何与其交互。 | |
| broker.host | 用于建立与MQTT代理连接的主机名或IP地址。 | |
| broker.port | 1883 | 代理上接受客户端连接的MQTT监听端口。 |
| broker.version | 5 | MQTT协议版本（网关目前支持三个版本- 3.1、3.11、5）。 |
| broker.clientId ** | ThingsBoard_gateway | 代理上每个客户端会话的唯一标识符。 |
| broker.maxMessageNumberPerWorker | 10 | （可选）单个Worker（处理排队消息的后台助手）在一轮中处理的最大MQTT消息数，超过后让其他Worker运行。更多信息请参见工作线程设置。 |
| broker.maxNumberOfWorkers | 100 | （可选）网关可并行运行以处理MQTT流量的最大Worker数（处理排队消息的后台助手）。更多信息请参见工作线程设置。 |
| broker.keepAlive (in seconds) | 60 | （可选）ping之间的秒数；例如默认60秒，代理期望在给定间隔*1.5内有流量，否则关闭连接。 |
| broker.cleanSession | true | （可选）告知代理是重新开始还是保留先前会话。如果需要离线消息队列请使用false；如果总是干净重连且不需要持久化请使用true（仅适用于3.1、3.11，详见MQTT参数版本差异）。 |
| broker.cleanStart | true | （可选）类似于broker.cleanSession，但仅决定连接开始时的行为；如果要丢弃旧会话请使用true；如果要尝试恢复请使用false（仅适用于MQTT 5.0，详见MQTT参数版本差异）。 |
| broker.sessionExpiryInterval (in seconds) | 0 | （可选）断开连接后代理应保留您的会话多长时间（仅适用于MQTT 5.0，详见MQTT参数版本差异）。 |
请注意： ** –代理（或代理集群）不允许两个同时使用相同broker.clientId的会话。如果第二个连接使用该ID， 代理将关闭现有会话并接受新会话（会话接管）。客户端ID可以是任何有效的UTF-8字符串； 如果您没有描述性名称，可以在MQTT连接器配置UI中生成——参见连接到代理子部分下的最后几张截图。
服务器配置示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
"broker": {
"host": "127.0.0.1",
"port": 1883,
"version": 5,
"clientId": "ThingsBoard_gateway",
"maxMessageNumberPerWorker": 10,
"maxNumberOfWorkers": 100,
"keepAlive": 60,
"cleanSession": true,
"cleanStart": true,
"sessionExpiryInterval": 0,
"security": {
"type": "anonymous"
}
}
安全设置
MQTT代理连接提供三种不同的安全类型：匿名、 基本认证、证书。
匿名
匿名是最简单的选项：在MQTT代理上发布/订阅无需任何凭据。 不建议用于生产环境，因为它允许无人值守的访问。
| Parameter | Default value | Description |
|---|---|---|
| broker.security | 代理安全对象指定建立与MQTT代理连接的认证类型。 | |
| broker.security.type | anonymous | 认证类型。 |
匿名认证选项的安全配置示例。
1
2
3
"security": {
"type": "anonymous"
}
基本认证
基本认证选项使用在MQTT代理上配置的用户名和密码。 这是大多数设置的默认选择——只需使用强密码和唯一凭据。
| Parameter | Default value | Description |
|---|---|---|
| broker.security | 代理安全对象指定建立与MQTT代理连接的认证类型。 | |
| broker.security.type | basic | 认证类型。 |
| broker.security.username | username | 用于建立与MQTT代理连接的用户名。 |
| broker.security.password | password | 用于建立与MQTT代理连接的密码。 |
基本认证选项的安全配置示例：
1
2
3
4
5
"security": {
"type": "basic",
"username": "username",
"password": "password"
}
证书
基于证书的认证使用TLS证书，使网关和代理相互验证。 这是最安全的认证模式，设置时使用代理的TLS端口（通常为8883）以获得加密的生产级安全性。
| Parameter | Default value | Description |
|---|---|---|
| broker.security | 代理安全对象指定建立与MQTT代理连接的认证类型。 | |
| broker.security.type | certificates | 认证类型。 |
| broker.security.pathToCACert | /etc/thingsboard-gateway/ca.pem | pathToCACert的路径，您的CA证书，MQTT客户端使用它在TLS期间检查代理的证书，确保您连接到可信服务器。’s certificate during TLS, ensuring you’re connecting to a trusted server. |
| broker.security.pathToPrivateKey | /etc/thingsboard-gateway/privateKey.pem | pathToPrivateKey的路径，该密钥证明客户端的身份并启用安全的TLS握手。’s identity and enables secure TLS handshakes. |
| broker.security.pathToClientCert | /etc/thingsboard-gateway/certificate.pem | pathToClientCert的路径，您的证书在TLS握手期间向MQTT代理标识网关。它与网关的私钥配对，通常由受信任CA签署。It’s paired with the gateway’s private key and is usually signed by a trusted CA. |
证书认证选项的安全配置示例：
1
2
3
4
5
6
"security": {
"type": "certificates",
"pathToCACert": "/etc/thingsboard-gateway/ca.pem",
"pathToPrivateKey": "/etc/thingsboard-gateway/privateKey.pem",
"pathToClientCert": "/etc/thingsboard-gateway/certificate.pem"
}
映射
映射允许您配置网关订阅的主题，用于设备创建和传入数据处理。 您可以动态生成主题和设备名称，并选择哪些数据作为设备属性或遥测数据发送。本节提供了灵活的设备和数据管理的基本设置。
设备映射
| Parameter | Description |
|---|---|
| mapping[].topicFilter | 网关将订阅的用于数据源的主题。可使用通配符创建主题。 |
| mapping[].subscriptionQos | 消息发送者和接收者之间的协议，定义特定消息的传递保证级别。（0-至多一次，1-至少一次，2-恰好一次）。 |
| mapping[].convertor.type | 说明连接器如何解析MQTT有效载荷并提取设备信息，可以是json、bytes、custom。 |
| mapping[].deviceInfo.convertor.deviceNameExpressionSource | 设备名称的来源（可以是message、topic或constant）。 |
| mapping[].deviceInfo.convertor.deviceNameExpression | 用于从所选来源（Message/Topic/Constant）提取设备名称的表达式。支持JSON路径、正则表达式、字节切片或字面量-参见表达式。 |
| mapping[].deviceInfo.convertor.deviceProfileSource | 设备配置文件的来源（可以是message、topic或constant）。 |
| mapping[].deviceInfo.convertor.deviceProfileExpression | 用于从所选来源（Message/Topic/Constant）提取设备配置文件的表达式。支持JSON路径、正则表达式、字节切片或字面量-参见表达式。 |
| mapping[].reportStrategy | （可选）用于配置设备上报策略的上报策略对象。 |
| mapping[].timeout | （可选）触发“设备断开”事件的超时时间，默认为60000（毫秒）。 |
设备映射配置示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"mapping": [
{
"topicFilter": "sensor/data",
"subscriptionQos": 1,
"converter": {
"type": "json",
"deviceInfo": {
"deviceNameExpressionSource": "message",
"deviceNameExpression": "${serialNumber}",
"deviceProfileExpressionSource": "message",
"deviceProfileExpression": "${sensorType}"
},
"attributes": [],
"timeseries": []
}
}
]
设备属性和时序数据
| Parameter | Description |
|---|---|
| mapping[].attributes[] | 将发送到ThingsBoard平台实例的属性列表。 |
| mapping[].attributes[].keySource | （可选，自网关v.3.8.1起可用）属性键名的来源。可以是：message（默认）或topic。更多信息请参见使用示例。 |
| mapping[].attributes[].key | ThingsBoard中属性的键名。可以指定为静态值、JSON路径或正则表达式。 |
| mapping[].attributes[].type | 属性字段的类型（可以是以下之一：string、boolean、integer、double，或当Payload type为Bytes时为Raw）。 |
| mapping[].attributes[].value | 将发送到平台设备的属性值。应根据所选的Payload type（Bytes、JSON、CUSTOM）来指定。 |
| mapping[].attributes[].reportStrategy | （可选）属性数据的上报策略。如果未指定，将使用设备上报策略。 |
| mapping[].timeseries[] | 将发送到ThingsBoard平台实例的遥测数据列表。 |
| mapping[].timeseries[].keySource | （可选，自网关v.3.8.1起可用）时序数据键名的来源。可以是：message（默认）或topic。更多信息请参见使用示例。 |
| mapping[].timeseries[].key | ThingsBoard中遥测数据的键名。可以指定为静态值。 |
| mapping[].timeseries[].type | 遥测字段的类型（可以是以下之一：string、boolean、integer、double，或当Payload type为Bytes时为Raw）。 |
| mapping[].timeseries[].value | 将发送到平台的遥测数据值。应根据所选类型（json path、regular expressions或slices）来指定。 |
| mapping[].timeseries[].tsField | （可选）json-path表达式，用于携带日期时间字符串的字段。如果不存在，将使用传入消息的ts或timestamp属性作为数据条目的时间戳。 |
| mapping[].timeseries[].dayfirst | （可选）指出第一个数字是日(DD.MM.YY HH:mm:ss.SSS).• false → 10.11.24 10:10:10.252 → 11 Oct 2024 10:10:10.252• true → 10.11.24 10:10:10.252 → 10 Nov 2024 10:10:10.252. |
| mapping[].timeseries[].yearfirst | （可选）指出第一个数字是年 (DD.MM.YY HH:mm:ss.SSS). • false → follows dayfirst rule• true → 10.11.24 10:10:10.252 → 24 Nov 2010 10:10:10.252. |
| mapping[].timeseries[].reportStrategy | （可选）时序数据的上报策略。如果未指定，将使用设备上报策略。 |
属性和遥测数据配置示例：
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
"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}",
"tsField": "${timestampField}",
"dayfirst": true
},
{
"type": "string",
"key": "combine",
"value": "${hum}:${temp}"
}
]
请求映射
设备连接请求
| Parameter | Description |
|---|---|
| requestsMapping.connectRequests[].topicFilter | 网关将订阅并等待设备发布连接请求的主题。可使用通配符创建主题。 |
| requestsMapping.connectRequests[].deviceInfo.deviceNameExpressionSource | 请求将发送到的设备名称的来源（可以是message、topic或constant）。 |
| requestsMapping.connectRequests[].deviceInfo.deviceNameExpression | 用于从所选来源（Message/Topic/Constant）提取设备名称的表达式。支持JSON路径、正则表达式、字节切片或字面量-参见表达式。 |
| requestsMapping.connectRequests[].deviceInfo.deviceProfileExpressionSource | 请求将发送到的设备配置文件的来源（可以是message、topic或constant）。 |
| requestsMapping.connectRequests[].deviceInfo.deviceProfileExpression | 用于从所选来源（Message/Topic/Constant）提取设备配置文件的表达式。支持JSON路径、正则表达式、字节切片或字面量-参见表达式。 |
连接请求配置示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
"requestsMapping": {
"connectRequests": [
{
"topicFilter": "sensor/connect",
"deviceInfo": {
"deviceNameExpressionSource": "message",
"deviceNameExpression": "${serialNumber}",
"deviceProfileExpressionSource": "constant",
"deviceProfileExpression": "Thermometer"
}
}
]
}
设备断开请求
| Parameter | Description |
|---|---|
| requestsMapping.disconnectRequests[].topicFilter | 网关将订阅并等待设备发布断开请求的主题。可使用通配符创建主题。 |
| requestsMapping.disconnectRequests[].deviceInfo.deviceNameExpressionSource | 请求将发送到的设备名称的来源（可以是message、topic或constant）。 |
| requestsMapping.disconnectRequests[].deviceInfo.deviceNameExpression | 用于从所选来源（Message/Topic/Constant）提取设备名称的表达式。支持JSON路径、正则表达式、字节切片或字面量-参见表达式。 |
断开请求配置示例：
1
2
3
4
5
6
7
8
9
10
11
"requestsMapping": {
"disconnectRequests": [
{
"topicFilter": "sensor/disconnect",
"deviceInfo": {
"deviceNameExpression": "${serialNumber}",
"deviceNameExpressionSource": "message"
}
}
]
}
设备属性请求
| Parameter | Description |
|---|---|
| requestsMapping.attributeRequests[].scope | （可选）确定从哪个范围获取属性，如果要请求客户端属性请使用client |
| requestsMapping.attributeRequests[].retain | 属性响应消息是否应由MQTT代理保留，可以是true或false。 |
| requestsMapping.attributeRequests[].topicFilter | 网关订阅用于接收传入请求的主题。Topic filter支持特殊符号：#和+ |
| requestsMapping.attributeRequests[].deviceInfo.deviceNameExpressionSource | 请求将发送到的设备名称的来源（可以是message、topic或constant）。 |
| requestsMapping.attributeRequests[].deviceInfo.deviceNameExpression | 用于从所选来源（Message/Topic/Constant）提取设备名称的表达式。支持JSON路径、正则表达式、字节切片或字面量-参见表达式。 |
| requestsMapping.attributeRequests[].attributeNameExpressionSource | 请求将发送到的属性名称的来源（可以是message、topic或constant）。 |
| requestsMapping.attributeRequests[].attributeNameExpression | 用于从所选来源（Message/Topic/Constant）提取属性名称的表达式。支持JSON路径、正则表达式、字节切片或字面量-参见表达式。 |
| requestsMapping.attributeRequests[].topicExpression | 用于格式化响应主题的表达式。可以从message、topic或constant解析。 |
| requestsMapping.attributeRequests[].valueExpression | 用于格式化响应值的表达式。可以从message、topic或constant解析。 |
属性请求配置示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"requestsMapping": {
"attributeRequests": [
{
"retain": false,
"topicFilter": "v1/devices/me/attributes/request",
"deviceInfo": {
"deviceNameExpressionSource": "message",
"deviceNameExpression": "${serialNumber}"
},
"attributeNameExpressionSource": "message",
"attributeNameExpression": "${versionAttribute}",
"topicExpression": "devices/${deviceName}/attrs",
"valueExpression": "${attributeKey}: ${attributeValue}"
}
]
}
设备属性更新
| Parameter | Description |
|---|---|
| requestsMapping.attributeUpdates[].retain | 属性响应消息是否应由MQTT代理保留。 |
| requestsMapping.attributeUpdates[].deviceNameFilter | 正则表达式设备名称过滤器，用于确定哪些设备应接收属性更新，参见表达式 |
| requestsMapping.attributeUpdates[].attributeFilter | 正则表达式属性名称过滤器，用于确定哪些属性应被更新，参见表达式 |
| requestsMapping.attributeUpdates[].topicExpression | JSON-path表达式，用于创建发送消息的主题地址。支持${deviceName}和${attributeKey}等变量，参见表达式。 |
| requestsMapping.attributeUpdates[].valueExpression | JSON-path表达式，用于创建将发送到主题的消息数据。支持${attributeKey}和${attributeValue}等变量，参见表达式。 |
属性更新配置示例：
1
2
3
4
5
6
7
8
9
10
11
"requestsMapping": {
"attributeUpdates": [
{
"retain": true,
"deviceNameFilter": ".*",
"attributeFilter": "firmwareVersion",
"topicExpression": "sensor/${deviceName}/${attributeKey}",
"valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
}
]
}
设备RPC方法
设备RPC（远程过程调用）方法允许您通过MQTT连接器从ThingsBoard向设备发送命令。网关充当中间人，将ThingsBoard RPC调用转换为设备可以理解的MQTT消息。
MQTT连接器支持两种类型的RPC请求：
- 双向（有响应） -网关向设备发送请求并等待响应。当您需要从设备获取数据时，这很有用。
- 单向（无响应） -网关向设备发送请求，不期望响应。这适用于不需要确认的简单命令。
| Parameter | Description |
|---|---|
| requestsMapping.serverSideRpc[].deviceNameFilter | 正则表达式设备名称过滤器，用于确定此RPC配置适用于哪些设备。参见表达式 |
| requestsMapping.serverSideRpc[].methodFilter | 正则表达式方法名称过滤器，用于确定此配置适用于哪些RPC方法。参见表达式 |
| requestsMapping.serverSideRpc[].requestTopicExpression | JSON-path表达式，用于创建发送RPC请求的主题地址。支持${deviceName}和${attributeKey}等变量。参见表达式 |
| requestsMapping.serverSideRpc[].responseTopicExpression | JSON-path表达式，用于创建订阅响应消息的主题地址。支持${deviceName}和${attributeKey}等变量。参见表达式 |
| requestsMapping.serverSideRpc[].responseTopicQoS | 响应主题订阅的服务质量级别。 |
| requestsMapping.serverSideRpc[].responseTimeout | 以毫秒为单位的值。如果在发送请求后在此时间段内没有响应，网关将取消订阅响应主题。 |
| requestsMapping.serverSideRpc[].valueExpression | JSON-path表达式，用于创建发送到代理的数据。支持${deviceName}和${attributeKey}等变量。参见表达式 |
设备RPC方法的配置在MQTT连接器配置的”serverSideRpc”部分中定义：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
"requestsMapping": {
"serverSideRpc": [
{
"type": "twoWay",
"deviceNameFilter": ".*",
"methodFilter": "echo",
"requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
"responseTopicExpression": "sensor/${deviceName}/response/${methodName}/${requestId}",
"responseTopicQoS": 1,
"responseTimeout": 10000,
"valueExpression": "${params}"
},
{
"type": "oneWay",
"deviceNameFilter": ".*",
"methodFilter": "no-reply",
"requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
"valueExpression": "${params}"
}
]
}
此外，每个遥测和属性参数都内置了GET和SET RPC方法，无需手动配置。
有关使用内置GET和SET RPC方法的更多信息，请参见指南。
工作线程设置
此配置设置提供了用于配置连接器性能和消息读取/格式化速度的字段：
-
Max messages queue per worker（每个 worker 的最大消息队列）
单个 worker 在一次轮转中处理的 MQTT 消息数量，然后才让其他 worker 运行。 数值越大吞吐越高；越小延迟越低。例如：大量 telemetry 约 ~100，快速 RPC 约 ~10–20。 -
Max number of workers（最大 worker 数量）
同时运行的 worker 数量。worker 越多占用越多 CPU 核心，过多会导致竞争。 建议从接近 CPU 核心数起步，根据积压和 CPU 情况调整。
附加信息
通配符用法
Wildcards允许网关使用一个模式订阅多个主题，或订阅您不知道确切名称但知道其结构的主题。
-
(
#) - wildcard(
#) -通配符匹配此级别及所有后续级别。只能放在末尾。表达式：
sensor/data/#匹配示例：
sensor/data/room1sensor/data/room1/tempsensor/data/ -
(
+) - wildcard(
+) -通配符恰好匹配一个级别，可在主题的任何级别使用。Expression:
sensor/+/dataMatching examples:
sensor/A/datasensor/B/data不匹配示例：
sensor/A/lab/data
共享订阅
共享订阅允许多个网关实例“共享”单个订阅，因此每条消息只被其中一个实例处理——这对于在多个网关之间分配负载非常有用。
使代理在它们之间进行消息负载均衡。
不是每个订阅者都接收每条消息（扇出），而是组中只有一个成员接收每条匹配的
发布。
例如，要在workers组中订阅sensor/+/data，可以将主题过滤器设置为。
示例：
$share/workers/sensor/+/data
转换器类型
转换器类型部分说明连接器如何解析MQTT有效载荷 并提取设备信息（名称、配置文件）和数据（属性/遥测）； 根据您的有效载荷格式和首选提取方法选择转换器。
JSON
如果传入数据是json格式，请使用此类型的转换。
Example:
{"serialNumber": "SN-001", "sensorType": "Thermometer", "sensorModel": "T1000", "temp": 42, "hum": 58}
BYTES
如果传入数据是bytes字节序列，请使用此类型的转换。
Example:
b'AM-120'
CUSTOM
当传入数据既不是BYTES也不是JSON时，使用CUSTOM转换器。实现您的自定义转换器并在MQTT连接器中配置它（参见使用示例获取带截图的示例）。
表达式类型
表达式类型部分说明如何从不同来源—Message, Topic或Constant——使用JSON路径、正则表达式或字节切片提取设备信息（名称、配置文件）。
Json路径
当Name和/或Profile Name必须从Message来源提取且 Payload type为JSON时，使用Json路径。 换句话说，这些值直接从传入JSON有效载荷的字段中读取。
表达式：
${serialNumber}
${sensorType}
有效载荷示例：
{"serialNumber": "SN-001", "sensorType": "Thermometer", "sensorModel": "T1000", "temp": 42, "hum": 58}
转换后数据：
SN-001
Thermometer
正则表达式
正则表达式 当Name和/或Profile Name必须从Topic提取时，使用正则表达式。 换句话说，这些值将根据您编写的正则表达式从主题中提取。
Expression:
(?<=sensor/)(.*?)(?=/data)
匹配示例：
sensor/Thermo-A/data
Converted data:
Thermo-A
切片
切片（Bytes来源）
当Name和/或Profile Name必须从字节序列中提取且 Payload type为BYTES时，使用切片。切片使用Python风格的索引遍历原始字节序列。示例规则：设备名称=前4个字节； 温度=其余部分。
Expressions:
[0:4]
[4:]
Payload example:
b'AM-120'
Converted data:
AM-1
20
故障排除
MQTT参数版本差异
-
broker.cleanSession 仅适用于MQTT 3.1、3.11；在MQTT 5.0中被broker.cleanStart（连接时行为）加broker.sessionExpiryInterval（断开后会话保留时长）取代。
-
broker.sessionExpiryInterval 仅适用于MQTT 5.0；如果为
0则在断开连接时丢弃会话，如果大于0则保留该秒数。 -
broker.cleanStart 仅适用于MQTT 5.0；控制连接时的行为：
true丢弃任何先前的会话，false尝试恢复它。
共享订阅限制
1.不要在同一个连接器中同时订阅sensor/+/data和$share/workers/sensor/+/data，否则会有重复处理的风险。
2.确保您的代理支持共享订阅，因为有些代理不支持。
下一步
探索与ThingsBoard主要功能相关的指南：