跳至主要内容

诊断、日志、信号与位置

大约 3 分钟

诊断、日志、信号与位置

本文覆盖网络诊断、本地日志、日志配置、信号强度、位置上报与自定义 Topic。

网络诊断

Topic：/sys/{pk}/{dn}/_thing/diag/post

{
  "id": "diag-0001",
  "version": "1.0",
  "sys": { "ack": 1 },
  "params": {
    "p": {
      "_time": 1700000000000,
      "wifi": { "rssi": -55, "snr": 20, "per": 10, "err_stats": "10,02,01;10,05,01" }
    }
  }
}

规则：

  • 代码读取的时间字段名是 _time（不是 time），缺失则用服务端时间。
  • wifi.rssi、wifi.snr、wifi.per 缺一不可，err_stats 可为空字符串。
  • 成功时把 rssi 与网络类型写入 Redis（保留 30 分钟）供后台展示，并写入诊断记录。
  • sys.ack=1 时回复 /sys/{pk}/{dn}/_thing/diag/post_reply：
{ "id": "diag-0001", "code": 200, "version": "1.0", "data": {}, "message": "success" }

本地日志上报

Topic：/sys/{pk}/{dn}/thing/log/post

{
  "id": "log-0001",
  "version": "1.0",
  "sys": { "ack": 1 },
  "params": [
    {
      "utcTime": "2026-10-25T10:00:00.000+0800",
      "logLevel": "ERROR",
      "module": "net",
      "code": "E1001",
      "traceContext": "trace-abc",
      "logContent": "connect timeout"
    }
  ],
  "method": "thing.log.post"
}

说明：

  • params 必须是数组。
  • utcTime 支持三种格式：13 位毫秒数、10 位秒数、字符串 yyyy-MM-dd'T'HH:mm:ss.SSSZ 或 yyyy-MM-dd HH:mm:ss.SSS；无法解析时按服务端时间入库。
  • 平台侧不强制校验后台的「设备本地日志上报」开关——上报始终入库。该开关用于通过日志配置向设备同步 mode（见下节），建议设备遵循该配置决定是否上报，避免流量浪费。

回复（默认需要回复，sys.ack 缺省即 1）Topic /sys/{pk}/{dn}/thing/log/post_reply：

{ "id": "log-0001", "code": 200, "data": {}, "message": "success" }

日志配置

设备主动获取日志配置：Topic /sys/{pk}/{dn}/thing/config/log/get，payload 可只带 id：

{ "id": "cfg-0001", "version": "1.0", "params": { "configScope": "device", "getType": "content" } }

回复 Topic /sys/{pk}/{dn}/thing/config/log/get_reply：

{ "id": "cfg-0001", "code": 200, "message": "success",
  "data": { "getType": "content", "content": { "mode": 1 } } }

mode：1 打开本地日志上传，0 关闭。

后台修改「设备本地日志上报」开关时，平台主动下发 /sys/{pk}/{dn}/thing/config/log/push（QoS1）：

{ "id": "123456789012", "version": "1.0",
  "params": { "getType": "content", "content": { "mode": 1 } } }

信号强度上报

Topic（平台按 signal/report 后缀匹配）：/{pk}/{dn}/signal/report

{ "timestamp": 1700000000000, "rssi": -67, "networkType": 1 }

实现说明：rssi 缺失会返回错误码 2013000005；timestamp 缺失不会报错且该时间戳不会被持久化 —— 平台只把 rssi 与 networkType 写入 Redis（保留 30 分钟）供后台展示信号强度，不写历史表。为便于后续扩展，设备仍应按上述格式携带毫秒 timestamp。该 Topic 无回复。

位置上报

Topic（平台按 location/upload 后缀匹配）：/{pk}/{dn}/location/upload

{ "location": "120.123456,30.654321" }

格式 经度,纬度，成功后写入设备档案的经纬度字段。当前校验只接受非负数且必须带小数点：经度 0–180、纬度 0–90，小数点后最多 6 位；120,30 这类整数写法会返回 2013000000，字段缺失或分隔错误返回 2013000006。南纬/西经等负值不支持，请自行换算。

自定义 Topic

后台在产品详情「Topic类列表 → 自定义Topic」中配置后缀 {topicShortName} 后：

  • 设备发布 /{pk}/{dn}/user/{topicShortName}：平台不做业务解析、不触发规则引擎、也不回复，只会写入消息流水和一条 code=200 的云端日志，因此后台「消息记录」能看到原始报文。
  • 平台下发同 Topic，QoS0，包装格式：
{ "id": "123456789012345678", "timestamp": 1700000000000, "messageContent": "{\"any\":\"raw\"}" }

messageContent 是字符串（可能是 JSON 字符串），设备需自行二次解析。产品未配置该自定义 Topic 时下发返回 2012000000。

小李子科技