WebSocket 客户端

• Connections
  • 添加连接
  • 编辑连接
  • 删除连接
  • 连接设置
    • 连接详情
    • 高级设置
    • Last will
  • 连接状态
• Subscriptions
  • 添加订阅
  • 编辑订阅
  • 删除订阅
  • 订阅设置
• Messages
  • 消息筛选
  • 发布消息

TBMQ WebSocket Client是一款可在浏览器中访问的工具，旨在简化各类场景下的MQTT客户端调试与测试。 借助 MQTT over WebSocket 特性，以简洁易用为设计原则。 支持MQTT客户端管理、主题订阅、消息接收与发布的无缝操作。

TBMQ WebSocket Client使用 MQTT.js 库实现客户端与broker的通信。

Connections

TBMQ WebSocket Client支持同时管理多个MQTT客户端连接。 提供可便捷发起、监控和终止多个MQTT客户端的界面。

添加连接

添加新连接，请按以下步骤操作：

1. 进入 WebSocket Client 页面，点击以 expand more 图标表示的 Select Connection。
2. 点击 Add new connection 按钮。填写必要字段以创建并连接MQTT客户端，然后点击 Connect。

编辑连接

TBMQ支持在连接建立后修改WebSocket Client连接参数。 须注意对连接参数的修改会立即生效。

若修改时客户端已连接，TBMQ会先优雅断开当前会话，然后使用更新后的设置发起新会话。 这确保您的修改即时应用，在保持客户端正在进行的活动完整性的同时，实现无缝适配能力。

修改WebSocket Client连接，请按以下步骤操作：

1. 进入 WebSocket Client 页面，点击箭头图标展开连接列表。
2. 点击待修改连接的编辑图标。
3. 进行修改后点击Connect保存。

删除连接

删除WebSocket Client连接，请按以下步骤操作：

1. 进入 WebSocket Client 页面，点击箭头图标展开连接列表。
2. 点击待删除连接的垃圾桶图标。
3. 出现确认提示后，点击 Yes 完成删除。

连接设置

WebSocket连接允许用户建立并配置多种参数，包括客户端凭据、会话设置和Last Will设置。

连接详情

• Name。 WebSocket Client连接名称，必须唯一。
• URL。 通常包含协议（如 ‘ws’、’wss’）、MQTT broker的主机名和端口。/mqtt是MQTT over WebSockets的标准路径。示例：’ws://localhost:8084/mqtt’。
• Authentication。 TBMQ支持以不同方式处理clientID（必填）、username、password等凭据的WebSocket连接：
  • Auto-generated credentials。 随机Client ID、随机Username、空Password的凭据。请注意将创建对应的Credentials。
  • Custom authentication。 自定义Client ID、Username、Password的凭据。
  • Use existing credentials。 用户选择已有的 Basic 类型凭据，并按需输入Password。

当选定的凭据需要密码建立连接时，会显示Password输入框。

高级设置

• Clean start。 启用（true）时，broker将丢弃所有先前会话并启动新会话，即移除所有订阅并丢失所有未投递消息。
• Keep alive。 MQTT客户端愿意在发送给服务器的控制包（PUBLISH、PINGREQ等）之间等待的空闲时间，用于在无活动期间保持连接。
• Connect timeout。 客户端应等待MQTT CONNACK包以确认连接的最大等待时间。若在此时间内未收到确认，则视为连接失败。
• Reconnect period。 MQTT客户端与broker断开后，两次重连尝试之间的间隔。
• MQTT version。 指定使用的MQTT协议版本：MQTT3.1 (3)、MQTT3.1.1 (4) 或MQTT5.0 (5)。

若选择MQTT Version 5，将提供以下额外参数：

• Session Expiry Interval。 设置客户端断开后broker应保留会话的时间（秒）。
• Max Packet Size。 客户端愿意从broker接收的最大payload大小（字节）。
• Topic Alias Maximum。 客户端愿意接受的broker发送的Topic Alias最高值。
• Receive Maximum。 可并发处理的QoS 1和QoS 2消息的最大数量。
• Request Response Information。 设为true时，MQTT broker将在响应中返回发布操作的额外信息。

Last will

Last Will（可选）是MQTT的一项特性，允许用户在客户端非正常断开时，由MQTT broker代为发送指定消息。 以下是Last Will属性的说明：

• Topic。 Last Will消息将发布到的MQTT topic。
• QoS。 Last Will消息的Quality of Service级别。
• Payload。 Last Will消息内容。
• Retain。 控制broker在投递后是否保留Last Will消息。为true时，broker将存储will消息并投递给该topic的未来订阅者。

若选择MQTT Version 5，请配置以下额外特性：

• Payload Format Indicator。 为true时，表示payload为UTF-8编码字符数据。为false或未设置时，视为未指定的二进制数据。
• Content Type。 描述will消息所承载内容的格式。
• Will Delay Interval。 客户端非正常断开后，broker在发布will消息前需等待的时间。
• Message Expiry Interval。 自发布之日起will消息可被投递的有效期。
• Response Topic。 broker在广播will消息后可发布响应消息的topic。
• Correlation Data。 用于将broker广播will消息后的响应消息进行关联的二进制数据。
• User Properties。 允许客户端以key-value对形式为Will消息添加自定义元数据。

连接状态

TBMQ提供保存WebSocket Client状态临时日志的功能，便于您监控和排查客户端连接行为。 访问这些日志：将光标悬停在当前状态标签上，即可显示详细的状态更新历史，了解连接相关事件的时间顺序。

WebSocket Client的状态可能为以下之一：

1. Connected。 表示已成功与broker建立连接。
2. Disconnected。 表示WebSocket客户端已与broker关闭连接。
3. Reconnecting。 客户端正在尝试与broker重新建立连接时显示。点击右上角Cancel按钮可取消重连。
4. Connection failed。 表示客户端无法与broker建立连接。该状态可能附带失败原因，如认证问题、会话被接管等。

Subscriptions

MQTT subscriptions是MQTT发布-订阅消息协议的重要组成部分，允许客户端订阅一个或多个主题。 用户可通过创建、修改或删除来管理subscriptions。

添加订阅

添加Subscription步骤：

1. 进入 WebSocket Client 页面，点击以 plus 图标表示的 Add Subscription 按钮。
2. 进行修改后点击 Add 保存。

编辑订阅

修改订阅时，点击对应行的编辑图标打开 Edit subscription 对话框。 完成修改后，记得点击 Save 按钮确认。

请注意，若客户端已连接时修改现有订阅，TBMQ会先取消旧topic的订阅，再订阅更新后的topic。 成功重新订阅后，客户端将开始接收发布到新topic的消息。

删除订阅

删除订阅步骤：

1. 在Subscriptions列表中定位到要删除的订阅，点击对应行的删除图标。
2. 出现确认提示后，点击 Yes 完成删除。

订阅设置

订阅设置涵盖客户端如何订阅MQTT主题的相关配置。 通常包括topic filter、QoS (Quality of Service) 级别等参数，以及MQTT客户端或broker特有的额外选项。

• Topic filter。 要订阅的MQTT topic filter。每条连接内必须唯一。
• QoS。 订阅的Quality of Service。
• Retain as Published。 为true时，通过该订阅转发的消息保留发布时的RETAIN标志；为false时，消息的RETAIN标志设为0。
• Retain Handling。 该选项决定客户端订阅topic时broker如何处理retained消息。
  • 0-订阅时发送retained消息；
  • 1-若订阅尚不存在，则在订阅时发送retained消息；
  • 2-订阅时不发送retained消息。
• No local。 为true时，broker不会将该客户端发布的消息转发回建立该订阅的连接。
• Color。 用于在消息表中更好区分消息的颜色，可修改。
• Subscription Identifier。 分配给订阅的唯一标识符（大于0的数值），用于跟踪、管理和引用特定订阅，确保每条订阅可被唯一区分。

Messages

Messages表用作消息日志，显示最近的消息供查看和参考。 表中每行对应一条发布或接收的消息，并展示关键消息属性的快照：

1. Type。 标识消息是Received还是Published。
2. Topic。 消息关联的topic。
3. QoS。 消息关联的Quality of Service级别。
4. Retain。 显示发送方是否将消息标记为 Retain。
5. Payload。 消息内嵌内容的预览。 若消息包含payload，可点击Info图标按钮查看详情。该操作将打开对话框，除可阅读payload外，还可复制到剪贴板。
6. Properties 图标按钮可访问消息中的更多设置，如User properties、Content type、Topic Alias等。

消息筛选

消息表可按以下方式筛选：

• Type ‘All/Received/Published’-点击Messages表表头的type标签。
• Topic/QoS/Retain-点击 Clear messages 按钮旁的 filter 图标。

发布消息

WebSocket Client页面提供易于使用的发布消息界面。 使用TBMQ成功发布消息需满足：

• 客户端已连接。
• 已指定Topic。 使用Topic Alias特性时可不必指定。
• 消息格式有效，若选择JSON格式。

以下是发布消息的基本选项及简要说明：

• Topic。 消息将发布到的MQTT topic。
• QoS。 保证消息投递的Quality of Service级别：
  • 0-At most once（消息可能投递也可能不投递）；
  • 1-At least once（消息会投递，但可能重复）；
  • 2-Exactly once（消息Exactly once投递）。
• Retain。 为true时，broker存储该topic的最后一条消息及其QoS，该topic的未来订阅者将收到该topic的最后一条retained消息。
• Color。 用于在消息表中标记发布的消息以便区分。
• Format。 指定消息显示格式。
  • JSON。 对消息内容进行JSON格式校验。
  • String。 不进行校验。

填写必要信息和设置后，找到并点击Send图标发布消息。 消息将发送到broker并转发给订阅该topic的所有客户端。

使用 MQTT Version 5 的MQTT客户端还可使用额外参数进一步自定义消息发布。 这些特性组合提供了灵活的MQTT消息处理环境。

设置发布消息属性：点击左下角 Properties 按钮打开对话框。 以下为各设置简要说明：

• Payload Format Indicator。 为true时，表示payload为UTF-8编码字符数据。默认false表示未指定的二进制数据。
• Content Type。 描述应用消息数据的格式。
• Message Expiry Interval。 应用消息的有效期（秒）。
• Topic Alias。 可用作topic简写的整数值。若WebSocket连接的Topic Alias Max为0，则禁止使用topic alias。
• Correlation Data。 用作关联标识符的二进制数据。
• Response Topic。 用作响应消息Topic Name的字符串。
• User Properties。 允许以key-value对形式添加用户定义的元数据。