直连设备上报数据

直连设备（未挂网关的普通设备）自己连接平台，把采集到的数据直接上报。本章介绍连接方式、上报主题、报文格式与常见问题。

一、准备：拿到设备令牌

上报前，设备端需要两样东西：

项目	从哪里获得	说明
Access Token	创建设备后弹出的提示框；或设备详情页 →「设备信息」	设备身份凭证，填入 MQTT 的用户名
MQTT 接入地址与端口	如使用云服务请填写cloudbridge.qiuhuasoft.top；私有部署由平台部署方提供	默认端口为 1883

连接要点：

• 用户名 = Access Token，密码留空（平台只校验用户名，密码不参与校验）。
• 每台设备请使用唯一的客户端标识（Client ID），建议直接用设备令牌或平台设备 ID，避免多台设备互相顶线。
• 令牌错误、设备未在平台建档、租户被停用这三种情况，平台返回的失败提示完全相同，统一定位为"用户名或密码错误"。遇到连不上时，请按这三种可能逐一排查，不要只看其中一种。

二、上报主题

直连设备使用固定的上报主题：

用途	主题
上报遥测数据	v1/devices/me/telemetry

设备连上平台后，直接向该主题发布报文即可，不需要额外订阅。

⚠️ 请勿使用属性上报主题。 平台当前的属性上报通道尚未落库，数据发出去不会出现在页面上。所有采集数据请统一走上面的遥测主题。

三、报文格式

报文为 JSON，支持以下三种写法，任选其一即可：

格式一：带时间戳（推荐）

{
  "ts": 1735689600000,
  "values": {
    "temperature": 25.3,
    "humidity": 60
  }
}

格式二：一组数据点

[
  { "temperature": 25.3 },
  { "humidity": 60 }
]

格式三：扁平键值

{ "temperature": 25.3, "humidity": 60 }

说明：

• ts 为毫秒级时间戳，可省略；省略时平台按收到报文的服务器时间记录。
• 字段名由设备端决定：平台不做指标名转换，上报的 temperature 就是页面上的 temperature。它会成为实时数据卡片的指标名、历史曲线的图例名，以及配置告警规则时可选择的属性名。因此字段名一旦定下就不要随意更改，否则历史数据会被切成两条曲线。
• 支持数字、文本、布尔值等类型；同一字段名的类型要保持一致（例如 temperature 一直上报数字，不要一会儿数字一会儿文本），否则平台会按不同类型分开存储，曲线会出现断点。
• 同一条报文里的多个字段会作为同一时刻的多个数据点入库。

四、上报示例（Python）

import json, time
import paho.mqtt.client as mqtt          # pip install paho-mqtt>=2.0

TOKEN  = "在设备详情页复制的 Access Token"
BROKER = "平台 MQTT 地址"
PORT   = 1883

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=TOKEN)
client.username_pw_set(TOKEN)            # 只需用户名，密码留空
client.connect(BROKER, PORT, keepalive=60)
client.loop_start()

payload = {
    "ts": int(time.time() * 1000),
    "values": {"temperature": 25.3, "humidity": 60},
}
client.publish("v1/device/me/telemetry", json.dumps(payload), qos=1)

time.sleep(1)
client.loop_stop()
client.disconnect()

五、怎么确认上报成功

1. 设备台账：该设备「状态」列显示在线，「最后活跃」时间随上报不断刷新。
2. 实时监控：能看到该设备的实时数据卡片，指标名与上报字段一致。
3. 历史数据：选中设备与时间区间，即可查到刚才上报的数据点。

如果数据没出现，按顺序检查：

现象	常见原因
设备显示离线	令牌填写错误、MQTT 地址/端口不通、客户端标识冲突被顶线
在线但页面无数据	主题写错（漏了 me、devices 没写成复数）；报文体不是合法 JSON
部分字段没显示	同一字段名的数据类型前后不一致（数字／文本混用）；或字段名被改过，历史数据被拆成了两条
上报一段时间后全部丢失	租户的消息量已达到每日上限，超限的报文会被直接丢弃，请联系平台管理员

---

下一步：网关及子设备的数据上报方式不同，请参考《网关设备上报数据》。