4. 设备遥测数据发布：v1/devices/me/telemetry 主题与 JSON 数据格式
设备遥测数据（Telemetry）是 IoT 平台中最核心的实时数据流，包括温度、湿度、电压、GPS 坐标等时序型键值对。ThingsBoard 通过 MQTT 主题 v1/devices/me/telemetry 接收设备上报的遥测数据，并自动存入时序数据库（Cassandra / TimescaleDB / SQL 等）。本章将深入讲解该主题的发布模式、JSON 数据格式规范以及上传频率控制策略。
4.1 遥测数据发布主题与 QoS
| 属性 | 值 |
|---|---|
| 主题 | v1/devices/me/telemetry |
| MQTT 操作 | PUBLISH（发布） |
| 推荐 QoS | 0（最多一次）或 1（至少一次） |
| 保留消息 | 不适用（遥测数据不保留） |
| 权限要求 | 设备已通过 Access Token 或 X.509 证书认证 |
实践建议：对于高频传感器（如每秒上报一次），使用 QoS 0 可减少网络开销和 Broker 负载；对于关键告警数据（如设备故障），使用 QoS 1 确保至少一次送达。
4.2 JSON 数据格式规范
ThingsBoard 要求遥测数据以 JSON 格式发布，支持三种结构：
4.2.1 单层键值对（最常用）
{
"temperature": 23.5,
"humidity": 68.2,
"voltage": 3.31
}4.2.2 带时间戳的键值对
{
"ts": 1712345678000,
"values": {
"temperature": 23.5,
"humidity": 68.2
}
}ts 为 Unix 毫秒时间戳，若不提供则使用服务器接收时间。
4.2.3 批量数据（数组形式）
[
{
"ts": 1712345678000,
"values": { "temperature": 23.5, "humidity": 68.2 }
},
{
"ts": 1712345679000,
"values": { "temperature": 23.6, "humidity": 68.0 }
}
]
常见错误：JSON 键名不能包含空格或特殊字符（建议使用小写字母和下划线）；数值类型必须为数字（不加引号），布尔值使用
true/false，字符串使用双引号。
4.3 数据上传频率控制策略
高频上传会导致网络拥塞、数据库写入压力增大以及设备电量快速消耗。以下是三种常用控制策略：
| 策略 | 描述 | 适用场景 |
|---|---|---|
| 固定间隔上报 | 设备按固定时间间隔（如 5 秒、30 秒）发布一次遥测数据 | 环境监测、温湿度传感器 |
| 变化阈值上报 | 仅当数据变化超过设定阈值（如温度变化 > 0.5°C）时才上报 | 工业控制、电池供电设备 |
| 自适应频率 | 根据数据变化率动态调整上报间隔（变化剧烈时高频，平稳时低频） | 车辆追踪、运动检测 |
4.3.1 固定间隔上报示例（ESP32 伪代码）
// 每 10 秒发布一次遥测数据
void loop() {
float temp = readTemperature();
float hum = readHumidity();
String payload = "{\"temperature\":";
payload += String(temp, 1);
payload += ",\"humidity\":";
payload += String(hum, 1);
payload += "}";
client.publish("v1/devices/me/telemetry", payload.c_str());
delay(10000); // 10 秒间隔
}4.3.2 变化阈值上报示例（Python 伪代码）
last_temp = None
THRESHOLD = 0.5
while True:
current_temp = read_temperature()
if last_temp is None or abs(current_temp - last_temp) > THRESHOLD:
payload = json.dumps({"temperature": current_temp})
client.publish("v1/devices/me/telemetry", payload)
last_temp = current_temp
time.sleep(2) # 采样间隔 2 秒
频率控制最佳实践：
- 电池供电设备：优先使用变化阈值上报，间隔不低于 30 秒
- 市电供电设备：固定间隔 5~15 秒，配合批量数组减少 MQTT 报文数量
- 高精度场景：自适应频率，变化剧烈时 1 秒一次，平稳时 60 秒一次
4.4 遥测数据发布流程（SVG 架构图）
4.5 频率控制对比与选型
| 控制策略 | 网络流量 | 数据实时性 | 设备功耗 | 实现复杂度 |
|---|---|---|---|---|
| 固定间隔 | 高（恒定） | 中等 | 高 | 低 |
| 变化阈值 | 低（按需） | 高（变化时即时） | 低 | 中 |
| 自适应 | 动态优化 | 高 | 中 | 高 |
选型建议：对于大多数物联网项目，推荐从“固定间隔 10 秒 + 变化阈值 0.5°C”的组合策略开始，既保证基础数据流，又能在关键变化时快速响应。后期可根据实际数据量和业务需求调整参数。
4.6 验证遥测数据是否成功发布
发布后可通过以下方式验证：
- ThingsBoard 仪表板：在设备详情页的“最新遥测”选项卡中查看最近上报的键值对。
- MQTT 客户端日志：检查 PUBLISH 报文是否返回 PUBACK（QoS 1）或直接成功（QoS 0）。
- REST API 查询：调用
/api/plugins/telemetry/{entityType}/{entityId}/values/timeseries获取历史数据。
// 使用 curl 验证设备遥测数据
curl -X GET "http://your-thingsboard-server/api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature,humidity&startTs=1712345678000&endTs=1712345778000" \
-H "Authorization: Bearer {JWT_TOKEN}"
注意：如果设备发布后遥测数据未显示，请检查：① Access Token 是否正确；② JSON 格式是否合法（可使用 JSON 校验工具）；③ 主题字符串是否完全匹配（区分大小写）；④ 设备是否处于“活动”状态。