跳到主要内容
版本:开发版

设备 API 一览

设备接入 DeviceChain 的所有方式,每种都附有一条可直接粘贴到终端的命令。本页是一张地图,而不是规范:每一行都链接到解释该传输方式的页面,设备协议参考列出每个字段和每种拒绝情形。各传输方式能做什么、不能做什么,见传输能力矩阵。

示例使用本地 kind 安装(租户 acme,实例 devicechain)。请把主机、租户和凭据替换成你自己的。

传输方式方向认证方式前往
MQTT遥测上行,命令下行每次连接使用凭据 ID 和密钥连接设备
HTTP遥测上行,可选命令拉取事件使用请求体凭据;命令拉取使用 bearer 访问令牌连接设备
LwM2M遥测上行,写入下行DTLS 预共享密钥LwM2M
Sparkplug B遥测上行,命令下行数据源的 broker 凭据Sparkplug B
X.509 证书同 MQTT客户端证书证书设备
自注册获取设备和凭据预配密钥和密文自注册

MQTT​

把一个设备事件发布到平台 broker 上该设备的事件主题。用户名是 {tenant}:{credentialId},事件正文不带凭据。

mosquitto_pub --cafile instance-ca.crt -h <mqtt-host> -p 1883 \
-i 'devicechain:acme:sensor-001' -u 'acme:<credentialId>' -P '<credentialSecret>' \
-t 'devicechain/acme/devices/sensor-001/events' \
-m '{"device":"sensor-001","eventType":"Measurement","payload":{"entries":[{"measurements":{"temperature":"21.5"}}]}}'

命令会到达设备订阅的主题:

mosquitto_sub --cafile instance-ca.crt -h <mqtt-host> -p 1883 \
-i 'devicechain:acme:sensor-001' -u 'acme:<credentialId>' -P '<credentialSecret>' \
-t 'devicechain/acme/device-commands/sensor-001'

HTTP​

用 POST 把同样的事件正文发送到 event-sources 服务。HTTP 方式下凭据放在正文中,事件被接受时返回 202。429,或带 Retry-After 的 503,表示稍后重发。

curl -i -X POST http://localhost:8081/devicechain/acme/events \
-H 'Content-Type: application/json' \
-d '{"device":"sensor-001","eventType":"Measurement","credentialType":"ACCESS_TOKEN","credentialId":"<token>","payload":{"entries":[{"measurements":{"temperature":"21.5"}}]}}'

要使用 HTTP 命令拉取,请将设备类型的 commandChannel 设为 HTTP_PULL。设备使用自身的访问令牌,通过 Authorization: Bearer <access-token> 轮询命令、确认接收并提交响应。默认的 PUBLISH 通道不支持轮询。HTTP 命令拉取不传递配置或托管更新分配。请将 8081 端口置于网络控制之后。

LwM2M​

LwM2M 客户端通过 DTLS 上的 CoAP(UDP 5684)注册,并出示一个预共享密钥身份,平台会把它解析为租户和设备。任何支持 PSK 的 LwM2M 客户端都可以;例如使用 Leshan 的演示客户端:

./leshan-client-demo -u coaps://<lwm2m-host>:5684 -n sensor-001 -i <pskIdentity> -p <pskKeyHex>

随后平台会观察设备的传感器对象,并把每次通知存为一条测量。在线状态、写入以及不支持的内容见 LwM2M。

Sparkplug B​

平台是 Sparkplug 主机:它订阅你自己的 broker,不接受边缘节点的连接。把一个已配置的数据源指向该 broker,然后像往常一样先发布节点 birth,再发布数据。主题名称就是 Sparkplug 的主题名称;载荷是 Protobuf,因此由 Sparkplug 库构造。用普通 MQTT 客户端可以确认该主题可达:

mosquitto_sub -h <your-broker> -p 1883 -u <user> -P <password> -t 'spBv1.0/plant-a/#' -v

每个 {group}/{node} 会成为该数据源所属租户中一台设备的外部 ID。

X.509 证书​

持有受信任 CA 签发证书的设备,使用用户名 {tenant}:@x509 且不带密码连接。

mosquitto_pub --cafile instance-ca.crt --cert device.crt --key device.key \
-h <mqtt-host> -p 1883 -i 'devicechain:acme:<deviceToken>' -u 'acme:@x509' \
-t 'devicechain/acme/devices/<deviceToken>/events' \
-m '{"device":"<deviceToken>","eventType":"Measurement","payload":{"entries":[{"measurements":{"temperature":"21.5"}}]}}'

自注册​

持有预配密钥和密文的设备可以自行创建设备及其凭据。发送前先生成并保存凭据,然后注册:

curl -sS https://<instance-host>/api/device-management/provisioning/acme/register \
-H 'Content-Type: application/json' \
-d '{"provisionKey":"acme-sensors-2026","provisionSecret":"<secret>","externalId":"SN-000123","credentialSecret":"<credential you saved>"}'

响应会给出设备令牌和用于连接的 MQTT 客户端 ID。重复发送同一请求是安全的,返回 REPLAYED。参见重试约定。