设备 CoAP 接入协议

@cz 最后修改于 2020-07-13 10:43:08 rev.5230 - 最近修改

设备 CoAP 接入协议

概述

本文主要描述了如何注册和管理基于 NB-IoT/CoAP 协议通信的设备.

前端设备主要通过消息订阅/发布模式和云端消息队列进行通信.

本文定义的接口主要供前端设备调用.

系统前缀

API:

coap://[domain-name]:5683/mqtt/

版本

V4.0

作者

@author ChengZhen

修改历史

2020/2/14

更新 CoAP 服务器地址和路径

2019/9/21

修改 CoAP 协议为非订阅模式

2019/5/9

修改 CoAP 服务器地址

2019/4/18

整理和完善文档

2019/2/13

重写 API

2018/10/9

修改注册消息内容, 添加事物描述等信息
删除设备状态 API
修改边缘节点管理 API 名称
添加新的签名算法

CoAP 服务器

前端设备和应用程序可以通过 CoAP 协议访问云端消息队列服务器

消息最大长度不能超过 1 KB, 最好控制在 200 字节以内

消息队列服务器地址:

coap://[domain-name]:5683/mqtt/path/to/topic

path/to/topic MQTT 消息主题

设备端 CoAP API

CoAP 协议和 MQTT 协议共享相同的主题

如 coap://host:5683/mqtt/actions/:did 对应的 MQTT 主题为 actions/:did

CoAP 协议概述

关于 CoAP 协议请查询参考文档或搜索在线文章，这里不再具体介绍

订阅服务端消息

必须订阅指定的消息主题才能接收云端操作命令等

发起订阅

GET coap://host:5683/mqtt/actions/:did?c=:clientId&u=:username&p=:password OBSERVE=0

前端设备通过观察 actions/:did 路径来接收所有云端发送给设备的消息

actions/:did必须提供，要订阅的消息主题
- did 必需，设备的唯一 ID，由设备端定义，如可使用 MAC 地址等
clientId 必需，客户端 ID，可以同 did
username 可选，用户名
password 可选，密码
OBSERVE 要订阅消息，必须添加 OBSERVE 选项，并且值为 0

取消订阅

GET coap://host:5683/mqtt/actions/:did?c=:clientId&u=:username&p=:password OBSERVE=1

actions/:did必须提供，要取消订阅的消息主题
OBSERVE 要取消息订阅，必须添加 OBSERVE 选项，并且值为 1
clientId 必需，客户端 ID，可以同 did
username 可选，用户名
password 可选，密码

心跳消息

设备必须定期发送心跳 (Keep Alive) 消息来保持和云端的会话

GET coap://host:5683/mqtt/actions/:did?c=:clientId&u=:username&p=:password

actions/:did 必须提供
- did 必需，设备的唯一 ID，由设备端定义，如可使用 MAC 地址等
clientId 必需，客户端 ID，可以同 did
username 可选，用户名
password 可选，密码

特别是设备处于 NAT 网络之后, 必须定时发送心跳消息, 否则会导致设备收不到订阅的事件通知消息

建议每隔 60 到 90 秒发送一次

发布消息

设备可以通过 PUT 请求主动向云端发布数据

PUT coap://host:5683/mqtt/messages/:did?c=:clientId&u=:username&p=:password (0.03) Content-Type: application/json :payload

messages/:did 必须提供, 要发布的消息主题
- did 必需，设备的唯一 ID，由设备端定义，如可使用 MAC 地址等
clientId 必需，客户端 ID，可以同 did
username 可选，用户名
password 可选，密码
payload 必需，消息内容，JSON 格式

设备注册

设备->服务器: 发布注册请求 messages/:did
服务器->设备: 注册结果

设备通过发送注册请求消息向服务器注册

发布注册请求

发布地址:

PUT coap://host:5683/mqtt/messages/:did?c=:clientId (0.03)

host 服务器地址
port 服务器端口
did 设备的 ID
clientId 必需，客户端 ID，可以同 did

注册消息:

{
  "did": String,
  "type": "register",
  "sign": String,
  "data": {
    "expires": Number,
    "version": {
      "firmware": String
    },
    "supported": []
  }
}

更新注册:

设备可以定期发送一个空的注册消息来更新注册状态:

{
  "did": String,
  "type": "register",
  "sign": String
}

删除注册:

{
  "did": String,
  "type": "register",
  "sign": String,
  "data": {
    "expires": -1
  }
}

expires 值为 -1，表示注册马上失效
did 设备的 ID
type 消息类型总是为 register
sign 消息签名
data 设备描述
- @context 描述上下文路径
- @type 云端注册的设备类型

由于 CoAP 消息长度有限，设备描述必须在服务端配置

消息签名

<data>:<method>

method 表示签名算法名称, 如 md5
data 表示签名内容, HEX 字符串格式，大小写不敏感

签名算法:

有时间戳的模式: data = md5(did + ":" + deviceSecret + ":" + timestamp).toHexString()
没有时间戳的模式: data = md5(did + ":" + deviceSecret).toHexString()

示例:

did: 'aa1234567890'
deviceSecret: '1234567890abcdef'
sign = 'bd530e3fd5138955ced7f3b851b0309d:md5'

注册结果

2.04 Changed

{
  "did": String,
  "type": "register",
  "result": {
      "expires": Number,
      "token": String
  }
}

expires 注册有效期
token 设备访问令牌，只在注册有效期内可用

设备属性

主动上报数据流

PUT coap://host:5683/mqtt/messages/:did?c=:clientId

设备主动上报属性和数据流给云端采集服务器.

host 服务器地址
port 服务器端口
did 设备的唯一 ID，由设备端定义，如可使用 MAC 地址等
clientId 必需，客户端 ID，可以同 did

设备端将数据流消息通过这个主题上报到云端, 来上报设备属性状态

注意: 上报数据流也会同时更新设备影子的状态

请求内容:

Content-Type 为 application/octet-stream 或者 application/json:

MIME-Type	ID	Reference
application/octet-stream	40	-
application/json	50	[RFC4627]

JSON 格式请求内容:

{
    "did": String, 
    "type": "stream",
    "token": String,
    "data": {
        "<name>": <value>
    }
}

did 设备的 ID
type 消息类型总是为 stream
token 设备访问令牌
data 属性
- <name> 属性的名称
  - <value> 属性的值

示例:

PUT coap://host:5683/mqtt/messages/aabbcc112233?c=aabbcc112233

{
    "did": "aabbcc112233",
    "type": "stream",
    "token": "11223344556677889900",
    "data": {
        "rssi": -49
    }
}

接收读取请求

云端可以通过这个接口主动读取设备的属性

应用程序->服务器: 发布请求
服务器->设备: NOTIFY actions/:did
设备->服务器: PUT 应答消息
服务器->应用程序: 应答消息

由云端发送给设备

消息内容:

{
    "did": String,
    "mid": String,    
    "type": "action",
    "data": {
        "read": ["<name>"]
    }
}

did 设备的 ID
mid 消息 ID
type 消息类型总是为 action
data 要读取的属性
- read 读取操作
  - name 要读取的属性的名称

应答消息:

PUT coap://host:5683/mqtt/messages/:did?c=:clientId

{
    "did": String,
    "mid": String,    
    "type": "action",
    "result": {
        "read": {
          "<name>": <value>
        }
    }
}

接收修改请求

云端可以通过这个接口主动修改设备的属性

应用程序->服务器: 发布请求
服务器->设备: NOTIFY actions/:did
设备->服务器: PUT 应答消息
服务器->应用程序: 应答消息

由云端发送给设备

消息内容:

{
    "did": String, 
    "mid": String,    
    "type": "action",
    "data": {
        "write": {
          "<name>": <value>
        }
    }
}

did 设备的 ID
mid 消息 ID
type 消息类型总是为 action
data 要修改的属性
- write 修改操作
  - <name> 要修改的属性的名称
    - <value> 要修改的属性的值

应答消息:

PUT coap://host:5683/mqtt/messages/:did?c=:clientId

{
    "did": String,
    "mid": String,    
    "type": "action",
    "result": {
        "write": {
          "code": 0
        }
    }
}

设备操作

云端可以通过设备操作消息调用设备的操作

应用程序->服务器: 发布请求
服务器->设备: NOTIFY actions/:did
设备->服务器: PUT 应答消息
服务器->应用程序: 应答消息

操作请求消息

由云端发送给设备

消息内容:

{
    "did": String,
    "mid": String,
    "type": "action",
    "data": {
        "<name>": <input>
    }
}

did 设备的 ID
mid 消息 ID, 不同消息不可重复
type 消息类型总是为 action
data 操作数据
- <name> 操作的名称
  - input 操作的输入参数值

调用结果

PUT coap://host:5683/mqtt/messages/:did?c=:clientId

{
  "did": String,
  "mid": String,
  "type": "action",
  "result": {
    "<name>": <output>
  }
}

did 设备的 ID
mid 消息 ID, 不同消息不可重复
type 消息类型总是为 action
result 操作结果
- <name> 操作的名称
  - <output> 操作的输出参数值

示例

请求:

PUT coap://host:5683/mqtt/actions/aabbcc112233?c=112233445500

{
  "did": "aabbcc112233",
  "mid": "1234",
  "type": "action",
  "data": {
    "fade": {
      "level": 50,
      "duration": 2000
    }
  }
}

应答:

{
  "did": "aabbcc112233",
  "mid": "abcdef123456",
  "type": "action",
  "result": {
    "fade": {
      "level": 50
    }
  }
}

设备事件

设备->消息队列: 发布事件 messages/:did
消息队列->应用程序: 事件信息

发布事件

发布地址:

PUT coap://host:5683/mqtt/messages/:did?c=:clientId

host 服务器地址
port 服务器端口
messages/:did 是消息队列主题名
did 设备的唯一 ID，由设备端定义，如可使用 MAC 地址等
clientId 必需，客户端 ID，可以同 did

设备通过这个接口将事件消息上报到云端

{
  "did": String,
  "type": "event",
  "token": String,
  "data": {
    "<event>": <data>
  }
}

did 设备的 ID
type 消息类型总是为 event
token 设备访问令牌
data 事件数据
- name 事件的名称
  - data 事件数据

示例

PUT coap://host:5683/mqtt/messages/112233445500?c=112233445500

{
  "did": "112233445500",
  "type": "event",
  "token": "11223344556677889900",
  "data": {
    "status": {
      "level": 50
    }
  }
}

设备影子

查询设备影子

设备->服务器: 发布查询请求 messages/:did
服务器->设备: 查询结果

更新设备影子

应用程序->服务器: 发布修改请求 messages/:did
服务器->应用程序: 修改结果

待完善...

设备管理 CoAP API

固件下载

注意：这个接口暂时没有实现

GET coap://host:5683/mqtt/firmware/:did?c=:clientId

前端设备通过这个 URI 地址以块传输的方式下载固件文件

did 设备的 ID

前端设备需自行验证下载的固件文件的合法性

参数配置

应用程序可以通过下面的流程修改前端设备的属性

config 是设备管理保留属性名，用来读写设备配置参数

设备->消息队列: 订阅
设备管理服务器->消息队列: 发布修改配置参数请求
消息队列->设备: NOTIFY 修改配置参数
设备->设备: 应用新的参数
设备->消息队列: PUT 请求结果
消息队列->设备管理服务器: 请求结果

请求消息:

{
    "did": String,
    "mid": String,    
    "type": "action",
    "data": {
        "config": {
            "write": {
                "<name>": <value>,
            }
        }
    }
}

应答内容

发布主题:

PUT coap://host:5683/mqtt/actions/:did?c=:clientId

消息内容:

{
    "did": String,
    "mid": String,
    "timestamp": Number,    
    "type": "action",
    "result": {
        "config": {
            "write": {
                "code": 0
            }
        }
    }    
}