接入文档

这是 S0 阶段的精简版：足够让一台设备把数据发上来。完整文档（SDK、解析脚本、Open API 参考）随 S5 发布。

在控制台「注册设备」后，会得到已填好 Key 的 mqtt.js / Python / AT / HTTP 示例，直接复制运行即可。

MQTT 接入

推荐方式。MQTT 3.1.1，支持 TCP / TLS / WebSocket。用户名固定为productKey&deviceKey，密码为设备 Secret（或 HMAC 签名）。保持长连接时平台按 $SYS 断开事件即时判定离线；低功耗设备按产品的「离线判定」秒数兜底。

mqtt

# 连接参数
host     : mqtt.<你的域名>      port: 1883 (TLS 8883)
clientId : {deviceKey}
username : {productKey}&{deviceKey}
password : {secret}            # 或 HMAC 签名 "sig:<ts>:<hmac>"

# 上报属性（QoS 1）
topic    : /{productKey}/{deviceKey}/thing/property/post
payload  : {"id":"1","params":{"temperature":24.5,"voltage":225.7},"ts":1726800000}

HTTP 接入

适合抄表器、只会发 HTTP 的模组。一次 POST 一条属性报文，鉴权走请求头。HTTP 设备没有长连接，离线只按上报间隔判定。

bash

curl -X POST "https://<你的域名>/api/device/v1/property" \
  -H "Content-Type: application/json" \
  -H "X-Device-Key: {deviceKey}" \
  -H "X-Device-Secret: {secret}" \
  -d '{"id":"1","params":{"temperature":24.5,"voltage":225.7},"ts":1726800000}'

Topic 规范

命名兼容阿里云物联网平台，方便已有固件迁移。所有 Topic 以 productKey / deviceKey 开头。

用途	Topic	方向	说明
属性上报	/{productKey}/{deviceKey}/thing/property/post	设备 → 平台	payload: {id, params:{k:v}, ts}
事件上报	/{productKey}/{deviceKey}/thing/event/{event}/post	设备 → 平台	payload: {id, params:{…}, ts}；{event} 为物模型事件标识符
原始报文	/{productKey}/{deviceKey}/raw/up	设备 → 平台	二进制 / 私有协议，由产品解析脚本转成属性
服务调用	/{productKey}/{deviceKey}/thing/service/{service}	平台 → 设备	payload: {id, params:{…}}；设备订阅后执行
服务应答	/{productKey}/{deviceKey}/thing/service/{service}_reply	设备 → 平台	payload: {id, code, data}；id 与调用一致
期望值下发	/{productKey}/{deviceKey}/shadow/desired	平台 → 设备	影子期望值，设备上线后补发
子设备拓扑	/{productKey}/{deviceKey}/topo/add	网关 → 平台	网关注册子设备：{subDevices:[{deviceKey}]}