★ FEATURED ARTICLE 最近在折腾 ThingsBoard 设备接入时我遇到了一个特别基础但特别容易卡壳的问题设备明明已经连上 MQTT 了消息也发出去了可在 ThingsBoard 页面上就是看不到任何数据。排查了半天才发现我是把“属性数据”和“遥测数据”的上报 topic 混为一谈属性内容发到了telemetry自然在属性页里什么都刷不出来。后来把 topic 切换成v1/devices/me/attributes数据立马出来了整个过程就像打开了一扇门。这篇内容就把 ThingsBoard 通过 MQTT 发送属性数据的完整链路讲透从 MQTT topic 怎么定、payload 怎么组织到用命令行和 Python 脚本快速上报再到平台侧怎么查看、怎么用 REST API 读取以及最容易踩的几个坑。无论你是用 ESP32、树莓派、STM32还是只在电脑上跑一个模拟器只要你需要往 ThingsBoard 上报设备型号、固件版本、运行模式、配置参数这类“属性信息”这篇文章都能直接照着做。1. 为什么说属性数据是设备接入的第一道门槛1.1 属性数据和遥测数据到底有什么区别ThingsBoard 的数据模型里有两类最常见的的数据一类叫 Telemetry遥测一类叫 Attributes属性。很多人第一次接触时都会混淆包括我自己也犯过这个错误。简单来说遥测数据是“随着时间不断变化”的采样值比如温度、湿度、电压、经纬度它天生就是一条时间序列平台会把它存成带时间戳的历史记录并在“最新遥测”页面展示曲线。而属性数据是“描述设备当前状态或配置”的键值对比如设备序列号、固件版本、安装位置、运行模式、报警阈值它更像是一张设备档案卡片存的是最新的“结果”而不是一段“过程”。对比项Telemetry 遥测数据Attributes 属性数据上报 topicv1/devices/me/telemetryv1/devices/me/attributes数据形态时间序列可带 ts 时间戳键值对 JSON 对象存储方式追加存储保留历史覆盖存储只保留最新值典型用途温度、电量、信号强度、位置轨迹固件版本、序列号、配置项、状态开关页面位置设备详情 - 最新遥测设备详情 - 属性如果你把属性数据发到 telemetry topic平台会正常接收但只会把它当成普通时间序列处理不会出现在“属性”页面里。反之把遥测数据发到 attributes topic平台只保留最后一次上报值历史曲线就丢了。所以搞清楚“你现在到底要传什么”是接入 ThingsBoard 的第一道门槛。从业务角度再打个比方遥测数据像人的“体温、心率”需要持续记录变化属性数据像人的“姓名、工号、部门”是相对固定的档案。一套设备接入流程里通常先上报属性让平台认识设备再持续上报遥测数据做监控。你不能把档案当成体检报告也不能把体检报告当成档案存。1.2 MQTT 在 ThingsBoard 接入链路中扮演什么角色ThingsBoard 本身不是一个 MQTT Broker但它内置了 MQTT Transport 模块对外暴露标准的 MQTT 端口默认 1883启用 TLS 的话是 8883。设备可以把 MQTT 消息直接发到 ThingsBoard也可以先发到自己的 EMQX、Mosquitto 这类 Broker再通过规则链转发给 ThingsBoard。对于大多数中小型项目来说直接用平台内置的 MQTT 接入就够了省去一层消息中间件架构也简单很多。MQTT 协议本身是一种轻量级发布/订阅协议特别适合资源受限的设备端。它基于 topic 做消息路由支持 QoS 0/1/2 三种投递级别连接占用带宽很小非常适合弱网环境。在 ThingsBoard 里topic 不只是消息分类的标签还是 API 的“路由地址”。你在哪个 topic 上发什么内容直接决定了平台会把它归为遥测、属性还是 RPC 响应。这也是为什么我强调“topic 错了数据就进错门”。很多初学者喜欢先去搭一个“自己的 MQTT 服务器”再把 ThingsBoard 接上去这其实绕了远路。正确思路是ThingsBoard 已经帮你把 MQTT 服务端和业务解析层打通了你只需要用任何一款 MQTT 客户端把自己伪装成一台设备连接到 ThingsBoard 的 1883 端口然后按它规定的 topic 格式上报数据即可。消息到了平台后会被自动解析成设备数据并落库不需要你再写任何解析逻辑。2. 发送属性数据前必须搞清楚的三个关键点2.1 设备凭证和 Access Token 的正确用法在 ThingsBoard 里一台设备要接入平台必须先通过认证。最常见的认证方式是 Access Token你可以把它理解成设备的“身份证号”。在设备列表中创建一个设备后进入设备详情页点击“管理凭证”就能看到一串唯一的访问令牌。这串 token 在整个 MQTT 连接过程中起着决定性作用。使用标准 MQTT 客户端连接 ThingsBoard 时认证机制和普通 MQTT Broker 有点不一样。大多数情况下ThingsBoard 要求把 Access Token 填到 Client ID 字段用户名和密码可以留空也可以任意填。也就是说MQTT 客户端连接的client_id必须是设备 token而不是你自己随便起的“esp32-client”。如果你用mosquitto_pub对应参数就是-i如果用 Python 的 paho-mqtt就是Client(client_id...)如果用 ESP32 的 PubSubClient就是setClient里的 client id。这里有个容易忽略的细节如果设备被禁用或者 token 被重置即使 Client ID 填对了服务端也会拒绝连接或者不让消息通过。遇到NOT_AUTHORIZED或bad user name or password时先不要怀疑网络而是去设备详情里重新复制一遍 token检查有没有多复制空格或换行。另外如果同一个 token 被多个连接同时使用后一个连接可能把前一个踢下线导致消息一会儿能发一会儿不能发排查时要留意是不是有多个进程或者多个工具在同时竞争同一个凭证。2.2 属性上报的 MQTT 主题和 Payload 格式发送属性数据在 ThingsBoard 里对应的 topic 是v1/devices/me/attributes。在这个 topic 上发布一条 JSON 对象平台就会把里面的每个键值对作为属性保存下来。常见的 payload 格式看起来是这样的{deviceName:air-conditioner-01,firmwareVersion:2.0.1,signal:-65,settings:{mode:cool,fanSpeed:3}}发送时注意三件事。第一payload 必须是合法的 JSON 对象最外层一定是{和}不能是数组也不能是裸字符串。属性上报不支持类似[{ts:..., values:{...}}]这种遥测批量格式如果你把一个数组发到这个 topic平台大概率会直接丢弃或者返回错误。第二字符串值必须用双引号不能用单引号。在命令行里实测的时候很多人会被 shell 转义坑到我后面会专门写。第三属性值可以是嵌套 JSON比如上面例子里的settings是一个子对象平台会把它当成一个独立的属性值存起来读取时拿到的就是整体对象。要特别注意的是属性上报没有时间戳字段平台只保存最新上报的键值对。同一条属性如果被重复上报新值会覆盖旧值并且更新时间会刷新。如果你需要保留属性变化的历史记录就必须自己在规则链里做配置比如把属性变化写入遥测或者在平台外部单独存一份日志。这个“只留最新值”的特性也是属性数据和遥测数据最本质的区别。功能topicpayload 要求客户端属性上报v1/devices/me/attributesJSON 对象键值对形式遥测数据上报v1/devices/me/telemetryJSON 对象或数组可带时间戳RPC 响应v1/devices/me/rpc/response/{requestId}JSON 对象响应具体命令共享属性订阅v1/devices/me/attributes订阅后接收平台下发内容2.3 属性上报用 QoS 0 还是 QoS 1MQTT 有 QoS 0、1、2 三种投递级别分别对应“最多一次”“至少一次”“仅一次”。ThingsBoard 的 MQTT Transport 是支持 QoS 0 和 QoS 1 的但我不建议在属性上报时使用 QoS 2因为属性数据本身是“只保留最新值”的逻辑为了它付出两次确认的带宽和延迟成本并不划算。那到底选哪个我的经验是属性数据通常包含设备身份、固件版本、关键配置等“必须别丢”的信息所以优先用 QoS 1。QoS 1 保证消息至少送达一次即使网络临时抖动客户端会在重连后把未确认的报文重新投递这对关键属性来说相当重要。如果是一天上报一次配置、上线时上报一次固件版本这种低频场景直接 QoS 1 就够了。反过来遥测数据如果上报频率很高比如每秒一条温度用 QoS 0 会更轻盈因为丢掉一秒的数据可能不影响整体趋势。属性数据不是这样的它本身就是低频高价值的信息丢了可能就要等设备下次重启才能再拿到。我之前调试一台设备时因为图省事把所有消息都发成 QoS 0结果网络抽风正好把固件版本上报这条消息丢了平台侧一直显示旧版本排查了很久才意识到是 QoS 级别太低导致消息没送达。从那以后属性上报我统一用 QoS 1宁可多一点网络开销也要让设备“身份信息”可靠到达。3. 手把手实现用命令行与脚本发送属性数据3.1 最快验证用 mosquitto_pub 一条命令发布属性如果你只是想快速验证 ThingsBoard 的属性上报链路是否通不要急着写代码先用命令行工具跑通再说。推荐安装mosquitto-clients工具里面包含mosquitto_pub和mosquitto_sub。在 Ubuntu/Debian 上执行sudo apt install mosquitto-clientsmacOS 上执行brew install mosquittoWindows 用户可以用安装包或 WSL。假设 ThingsBoard 服务地址是localhost端口是默认的 1883设备 token 是abcd1234那么发布一条属性数据的命令如下mosquitto_pub -d -q 1 -h localhost -p 1883 -i abcd1234 -t v1/devices/me/attributes -m {firmwareVersion:2.0.1,active:true}这里-d打开调试日志你会看到完整的 MQTT 交互报文包括连接确认、PUBLISH 报文等-q 1指定 QoS 级别-h和-p指定服务地址与端口-i abcd1234是关键必须把设备的 Access Token 作为 Client ID-t是属性上报 topic-m是 payload 内容。执行之后打开 ThingsBoard 设备详情页切到“属性”页签如果能看到firmwareVersion2.0.1和activetrue两个键值说明整个链路已经通了。如果你的 ThingsBoard 不在本机把localhost换成服务器 IP 或域名即可。这里最常见的错误是-m里的 JSON 用了双引号包整体然后里面属性名也想用双引号结果被 shell 解构了所以我在命令里特意用了单引号包整体属性名双引号保内层这个习惯能从根源上避开转义问题。3.2 用 Python paho-mqtt 编写属性上报脚本命令行工具适合验证但真正接入设备或做模拟测试时还是要写脚本。Python 生态里最常用的 MQTT 客户端库是paho-mqtt安装只需pip install paho-mqtt。下面这个脚本是属性上报的最小可用版本我在多个版本上实测过直接改 token 和设备信息就能跑起来。import json import time import paho.mqtt.client as mqtt BROKER localhost PORT 1883 DEVICE_TOKEN abcd1234 client mqtt.Client(client_idDEVICE_TOKEN, protocolmqtt.MQTTv311) client.connect(BROKER, PORT, 60) payload { deviceName: air-conditioner-01, firmware: 2.0.1, signal: -65, settings: {mode: cool, fanSpeed: 3} } client.publish(v1/devices/me/attributes, json.dumps(payload), qos1) time.sleep(1) client.disconnect()脚本的思路很简单创建客户端时把client_id设为设备 token连接 ThingsBoard然后把一个字典用json.dumps序列化成字符串发布到属性上报 topic。发布之后sleep(1)是为了给底层网络一点时间把消息推送出去否则立刻disconnect()可能导致数据没发完就断开了。如果你的 ThingsBoard 版本比较老或者连接时遇到认证问题可以在connect之前加一行client.username_pw_set(DEVICE_TOKEN, )把 token 同时填到用户名里密码留空。这种兼容性写法在对接不同 MQTT Transport 版本时很有用。跑完脚本后再到“属性”页签刷新看到的数据应该和代码里定义的键值完全一致。如果你习惯用 MQTTX 这类图形化工具思路一模一样新建连接时 Client ID 填 tokentopic 填v1/devices/me/attributespayload 填 JSON点发送即可。3.3 从设备端上报到平台侧校验的完整链路在实际项目里我们不只在电脑上模拟还要让真实设备上报属性。不管你是用 ESP32、树莓派还是 STM32 加 4G 模块核心逻辑都是一样的调用 MQTT 库用 token 作为 Client ID 连接 ThingsBroker然后 publish 到v1/devices/me/attributes。比如 ESP32 上的 PubSubClient 代码片段大概是这样client.setServer(your-thingsboard-ip, 1883); client.connect(abcd1234); char payload[] {\firmwareVersion\:\2.0.1\}; client.publish(v1/devices/me/attributes, payload);设备端上报后建议经过这样一条“自检链路”来确认数据真的被平台收到第一步检查设备端 MQTT 日志里有没有PUBLISH成功回执重点是看有没有出现qos1的PUBACK。第二步到 ThingsBoard 设备详情页的“属性”页签确认键值已经出现。第三步如果你在平台侧配置了规则链再看消息是否进入了规则引擎。第四步通过 REST API 拉取属性值与设备端上报内容做一次一致性核对。很多问题都出在第二步和第四步之间比如数据明明在页面上看到了但规则链没触发或者外部系统读不到这时候你就要往规则链和 API 权限上排查。一个很容易被忽略的细节是设备上报属性后如果你在同一个连接里紧接着上报遥测这两个请求是相互独立的不要把它们写进同一条消息里。属性归属性遥测归遥测topic 不同解析路径也不同。把这条链路走通之后你再去看 ThingsBoard 的 RPC 下发命令、共享属性更新会发现它们都是同一套 MQTT 通道上的不同主题而已思路完全可以复用。4. 平台侧如何查收和二次使用这些属性数据4.1 在设备详情页面定位属性数据很多用户上报成功后去页面找半天找不到数据不是因为传输失败而是没找对位置。ThingsBoard 设备详情页默认展示的是“最新遥测”页签里面只能看到带时间戳的遥测值。你要切到“属性”页签才能看到客户端上报的属性。在“属性”页签里通常还能切换client、shared、server三种作用域设备自己上报的属性属于client作用域平台主动配置下发的属于shared服务端内部记录的是server。如果你上报的数据在“属性”页签下没有立刻刷新可以手动刷新一下浏览器或者把“属性”页签关掉重新打开。还是看不到的话再用 REST API 查一次确认是不是 UI 缓存问题。另外属性页签里的键值可以是字符串、数字、布尔值或嵌套对象页面会根据 JSON 类型自动展示但不一定会做漂亮的图表因为它本身就不是为曲线图设计的。如果你需要把属性变化画成图表就得额外配置规则链把它落到遥测存储里。这里我再分享一个工作习惯给设备做属性上报时尽量用一套固定的命名规范比如fwVersion、serialNumber、hwModel避免同一个设备一会儿上报firmwareVersion一会儿上报firmware_version导致平台侧属性键混乱。属性键一旦脏了后期做规则链筛选和数据治理会非常痛苦。4.2 通过 REST API 读取客户端属性值在页面查看很方便但自动化运维或集成场景下我们更希望用 REST API 直接拉取属性。ThingsBoard 提供了GET /api/plugins/telemetry/{entityType}/{entityId}/values/attributes/{scope}这个接口。其中entityType一般是DEVICEentityId是设备在平台里的 UUID不是设备名称scope填CLIENT_SCOPE、SHARED_SCOPE或SERVER_SCOPE。调用这个接口时必须带 Authorization 请求头。最方便的方式是先用账号密码调用登录接口拿到 JWT token再带着 token 去查属性。用一个简单的 curl 示例说明# 1. 登录获取 token curl -X POST -H Content-Type: application/json \ -d {username:tenantthingsboard.org,password:your-password} \ http://localhost:8080/api/auth/login # 2. 用 token 查询设备属性把 {deviceId} 替换成设备 UUID curl -X GET \ -H X-Authorization: Bearer YOUR_JWT_TOKEN \ http://localhost:8080/api/plugins/telemetry/DEVICE/{deviceId}/values/attributes/CLIENT_SCOPE返回结果是一组包含 key、value、lastUpdateTs 的数组比如[{key:firmwareVersion,value:2.0.1,lastUpdateTs:1710000000000}]。这个接口很适合对接外部系统比如设备资产管理系统可以定时同步设备固件版本运维平台可以拉取所有设备的配置项。另一个常用接口是GET /api/plugins/telemetry/{entityType}/{entityId}/values/timeseries这个是查遥测数据的不要混了。需要注意的是用 REST API 读取属性时token 的生命周期有限过期后需要重新登录获取。如果你在脚本里定时拉取建议先做一次403判断发现 token 失效就自动重新登录。否则本地缓存着一把过期 token会白白多出很多 401 请求。4.3 属性变化事件与规则链联动属性数据不仅仅是“存起来看看”它更重要的作用是驱动规则链。每次设备上报属性ThingsBoard 会生成一条类型为POST_ATTRIBUTES的消息进入规则引擎。你可以利用这条消息做很多事情比如判断设备是否在线、检查固件版本是否需要升级、把属性变化同步到另一个实体、或者触发告警。我举一个实际用过的场景设备启动后会上报一条属性{online:true,ip:192.168.1.100}。我在规则链里加了一个“消息类型筛选器”筛选POST_ATTRIBUTES接着用“脚本”节点判断消息里的online是否为true如果为真就把设备的另一个属性lastSeenAt更新成当前时间。这样一来即使设备不上报遥测平台也能通过属性变化知道设备最后一次活跃时间后续做离线判定就方便多了。属性变化和规则链联动还有一个常见用途配置漂移检测。假设设备当前上报的fanSpeed是 2但平台希望所有设备都运行在 3 档你可以在规则链里做一个比较发现不一致时自动下发新的共享属性给设备或者生成一条告警让运维介入。这种“设备上报属性 - 规则链判断 - 平台下发新配置”的闭环是 ThingsBoard 最典型的自动化场景之一。要强调的是属性上报频率不能太高否则规则引擎压力和被触发的动作都会成倍增加后面我会专门说频率控制的问题。5. 常见问题与排查技巧实录5.1 数据发了但页面就是没有任何变化这个问题出现频率最高原因也最多。首先检查 topic 是不是v1/devices/me/attributes很多同学会把属性数据发到v1/devices/me/telemetry结果页面“最新遥测”有数据但“属性”页签一片空白看起来像“数据没发出去”其实是数据进错了门。其次检查设备 token 有没有设置成 Client ID如果连接时随意写了一个 client idThingsBoard 会直接拒绝连接或者连接后无法通过设备认证消息自然上不去。还有一种情况是消息已经发成功了但你看的是设备组层面的聚合页面而不是设备详情页。属性数据是挂在具体设备下面的你得先进入设备详情再切到“属性”页签。如果你在浏览器里开了开发者工具可以顺手看一下设备详情页发起的 API 请求正常情况下会请求values/attributes/CLIENT_SCOPE响应里应该能看到刚刚上报告的数据。如果 API 响应没有那就是服务端没收到重点回到 MQTT 连接和 topic 上排查。5.2 JSON 格式和特殊字符引起的诡异问题命令行里发属性时shell 解析规则经常会让人抓狂。比如我在 Windows 的 CMD 和 PowerShell 下用 mosquitto_pub单双引号的处理方式和 Linux 完全不一样稍不注意 JSON 就被拆成了多段平台收到的根本不是合法 JSON。最简单的办法是在 Linux 上用单引号包整个 JSON在 CMD 下用双引号包整个 JSON然后内部的属性名和字符串值用反斜杠转义。如果你觉得转义麻烦干脆把 JSON 内容写进一个文件用mosquitto_pub -f payload.json指定文件这样最不容易出错。除了转义问题属性值类型也容易出错。比如{active: true}会被解析成布尔值{active: true}会被解析成字符串二者在规则链里判断时的写法完全不同。如果你在脚本里用 Python 发送json.dumps会自动处理好类型但如果你在调试工具里手写 JSON务必检查数字、布尔值不要加引号字符串必须加双引号。另外如果你上报的属性值里包含中文最好确保 MQTT 客户端使用 UTF-8 编码否则平台侧可能显示乱码。5.3 属性上报频率与平台存储压力怎么平衡属性数据虽然“只保留最新值”但每次上报都会触发网络传输、数据解析、规则链处理如果频率控制不好照样会对平台产生压力。有些开发者误以为属性上报和遥测一样可以每秒一次结果几千台设备同时高频上报属性直接把规则引擎和数据库的连接池打满。属性数据的本质是“低频、高价值”正确的上报策略是“变化时上报”比如设备启动时上报一次、配置变更时上报一次、状态切换时上报一次而不是定时每秒上报。实际项目中我通常会给属性上报加一个“变化判断”的过滤器只有当前值和上次值不同才真正发布消息。这样既能保证平台侧属性始终是最新值又能大幅减少无效消息。如果你确实需要高频记录某些状态那应该走遥测通道而不是属性通道。记住一个判断口诀需要画历史曲线、需要保留过程的走 telemetry只需要知道最新状态、需要被配置系统读取的走 attributes。二者配合使用才能让 ThingsBoard 在数据量上来之后依然保持流畅。我个人的习惯是刚开始接入 ThingsBoard 时不要急着写大段代码先用 mosquitto_pub 手动把一条属性刷上去页面确认能看到数据再写脚本、再集成设备。这个“先手动后自动”的习惯帮我节省了大量调试时间尤其当你需要同时排查网络、鉴权、数据格式等多层问题时一次只验证一个环节是最有效率的。等属性上报这条链路彻底跑顺了再去看 RPC 下发命令、共享属性双向同步你会发现整个 ThingsBoard 的 MQTT 接入体系都是互通的一通百通。
阅读完成 · 觉得有帮助？
