接入文档

设备怎么把数据发上来(MQTT / HTTP / Topic 规范),以及第三方系统怎么把数据拿走(Open API、Webhook、MQTT 订阅出口)。

在控制台「注册设备」后,会得到已填好 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}]}

Open API

控制台里的每个动作都是同一套 REST API。用 API Key(Authorization: Bearer <accessKey>.<secret>)调用,权限与范围和成员一致。完整参考与在线调试台:/docs/api,规范文件 openapi.json(OpenAPI 3.1,可导入 Postman / Apifox)。

python
# 20 行 Python 拉昨日读数(API Key 在控制台「设置 → API Key」创建,readonly 模板即可)
import requests, csv, io
BASE = "https://<你的域名>"
KEY = "mck_xxx.yyy"
r = requests.get(f"{BASE}/api/v1/telemetry/export",
                 params={"range": "yesterday", "agg": "1h", "props": "energy,voltage_a"},
                 headers={"Authorization": f"Bearer {KEY}"}, timeout=60)
r.raise_for_status()
for row in csv.DictReader(io.StringIO(r.content.decode("utf-8-sig"))):
    print(row["bucket"], row["device"], row["prop"], row["avg"])

Webhook

在「设置 → Webhook」订阅设备上下线、属性上报、事件、指令状态与告警;每次推送带 HMAC-SHA256 签名,10 秒超时,失败按 10 秒 / 1 分钟 / 5 分钟重试 3 次,连续失败 100 次自动停用。请用 X-MControl-Delivery 做幂等。

text
# 推送体(POST JSON)
{ "id": "<投递 id>", "event": "alarm.fired", "ts": 1726800000000, "workspaceId": "…", "attempt": 1,
  "data": { "alarmId": "…", "ruleId": "…", "deviceId": "…", "deviceKey": "d_…", "severity": "critical", "status": "ACTIVE", "title": "泳池余氯偏低" } }

# 请求头
X-MControl-Event: alarm.fired
X-MControl-Delivery: <投递 id>            # 幂等键:重试会带同一个 id
X-MControl-Signature: t=<毫秒时间戳>,v1=<hex(HMAC-SHA256(secret, "<t>.<原始请求体>"))>

# 校验(Python)
import hmac, hashlib, time
def verify(secret, body: bytes, header: str) -> bool:
    p = dict(x.split("=", 1) for x in header.split(","))
    if abs(time.time() * 1000 - int(p["t"])) > 300_000: return False
    expect = hmac.new(secret.encode(), f"{p['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expect, p["v1"])

MQTT 订阅出口

不想轮询也不想开公网地址收 Webhook?直接用 API Key 作为 MQTT 凭证订阅设备的原始上报(只能订阅、不能发布;只限本 Workspace 的产品,Key 的范围为产品 / 空间 / 设备时只能订阅范围内的具体设备)。

python
# 用 API Key 直接订阅 MQTT(只读;username 固定 key:<accessKey>,password 为 secret)
# 订阅本 Workspace 任一产品的属性上报:/{productKey}/+/thing/property/post
# 事件:/{productKey}/+/thing/event/+/post   指令应答:/{productKey}/+/thing/service/+_reply
import paho.mqtt.client as mqtt
c = mqtt.Client(client_id="my-subscriber-1")
c.username_pw_set("key:mck_xxx", "yyy")
c.on_message = lambda cl, u, m: print(m.topic, m.payload.decode())
c.connect("mqtt.<你的域名>", 1883, 60)
c.subscribe("/{productKey}/+/thing/property/post", qos=1)
c.loop_forever()
解析脚本(Codec)与寄存器映射向导的说明在控制台产品页的「解析脚本」Tab 里。