3. ThingsBoard MQTT 接入方式：设备凭证、访问令牌、基础 Topic 结构、MQTT 端口配置

设备接入 ThingsBoard 平台的第一步是理解其身份验证机制与通信协议栈。本章将深入剖析 MQTT 接入的四大核心要素：设备凭证体系、访问令牌（Access Token）、基础 Topic 结构以及MQTT 端口配置。掌握这些内容，是后续实现数据上报与指令下发的基础。

3.1 设备凭证体系

ThingsBoard 支持多种设备凭证类型，用于验证 MQTT 客户端的身份。平台根据凭证类型决定是否允许设备建立连接并发布/订阅消息。

3.2 访问令牌（Access Token）详解

访问令牌是 ThingsBoard 最常用的设备凭证。它是一个由平台生成的唯一字符串，设备在 MQTT CONNECT 报文中将其作为密码字段发送。平台验证通过后，设备即可获得对应权限。

• 获取方式： 在 ThingsBoard Web UI 中，进入 设备 → 选择设备 → 凭据 标签页，即可查看或复制访问令牌。
• 格式示例： YOUR_DEVICE_ACCESS_TOKEN（通常为 32 位十六进制字符串）。
• 连接示例（使用 Mosquitto 客户端）：

mosquitto_pub -d -h localhost -p 1883 \
  -t "v1/devices/me/telemetry" \
  -u "YOUR_DEVICE_ACCESS_TOKEN" \
  -m '{"temperature": 25.5}'

3.3 基础 Topic 结构

ThingsBoard 为 MQTT 接入定义了标准化的 Topic 层级。设备通过特定的 Topic 发布遥测数据、属性更新，或订阅 RPC 指令与属性获取响应。

下表列出了最核心的 Topic 及其用途：

3.4 MQTT 端口配置

ThingsBoard 默认提供三个 MQTT 接入端口，分别对应不同的安全级别。正确配置端口是设备网络连通性的前提。

3.5 接入流程总览

下图展示了设备通过 MQTT 接入 ThingsBoard 的完整流程，涵盖凭证验证、Topic 发布/订阅与数据流转：

3.6 端口与 Topic 映射关系

不同端口对应不同的接入场景，但 Topic 结构保持一致。设备只需更改连接地址与端口，无需修改 Topic 字符串即可切换安全模式。

• 明文 MQTT（1883）： 适用于局域网内部设备，传输速度快，无加密开销。
• TLS 加密 MQTT（8883）： 适用于公网或跨网络设备，需配置客户端证书或信任平台 CA 证书。
• WebSocket（8083/8084）： 适用于浏览器或 Node.js 环境，通过 WebSocket 代理实现 MQTT 通信。

import paho.mqtt.client as mqtt

client = mqtt.Client()
client.tls_set(ca_certs="thingsboard.crt")  # 平台 CA 证书路径
client.username_pw_set("YOUR_DEVICE_ACCESS_TOKEN")
client.connect("thingsboard.cloud", 8883, 60)
client.publish("v1/devices/me/telemetry", '{"temperature": 25.5}')

3.7 常见接入错误排查