- CoAP接入
- CoAP DTLS接入
设备模型(元数据)定义
设备模型分为: 属性(properties),功能(function),事件(event).
设备模型使用场景:
- 前端通过模型定义动态展示设备运行状态或者设备操作界面
- 服务端可通过统一的API获取设备模型并进行相关操作,如: 在发送设备消息时进行参数校验,
在收到设备消息进行类型转换处理.
数据结构:
{
"id":"设备ID",
"name":"设备名称",
"properties":[...属性],
"functions":[...功能],
"events":[...事件]
}
属性
用于定义设备属性,运行状态等如: 设备SN,当前CPU使用率等.
平台可主动下发消息获取设备属性,设备也通过事件上报属性.
数据结构:
{
"id": "cpu_usage", //属性标识
"name": "CPU使用率",
"valueType": { //值类型
"type": "double", //类型标识,见类型表
"maxValue":100,
"minValue":0,
"unit":"percent", //单位
"expands":{"key1":"value1"} //其他自定义拓展定义
},
"expands":{"key1":"value1"} //其他自定义拓展定义
}
功能
用于定义设备功能,平台可主动调用,例如: 播放语音,开关操作等.
数据结构:
{
"id": "playVoice", //功能标识
"name": "播放声音", //名称
"inputs": [ //输入参数
{
"id": "text",
"name": "文字内容",
"valueType": { //参数类型
"type": "string"
},
"expands":{"key1":"value1"} //其他自定义拓展定义
}
],
"output": { //输出
"type": "boolean" //输出类型
},
"expands":{"key1":"value1"} //其他自定义拓展定义
}
事件
用于定义设备事件, 如: 定时上报设备属性, 设备报警等.
数据结构:
{
"id": "fire_alarm", //事件标识
"name": "火警",
"valueType": {
"type": "object", //对象(结构体)类型
"properties": [ //对象属性(结构与属性定义相同)
{
"id": "location",
"name": "地点",
"valueType": {
"type": "string"
}
},
{
"id": "lng",
"name": "经度",
"valueType": {
"type": "double"
},
"expands":{"gis":"lng"} //其他自定义拓展定义
},
{
"id": "lat",
"name": "纬度",
"valueType": {
"type": "double"
},
"expands":{"gis":"lat"} //其他自定义拓展定义
}
]
},
"expands":{"key1":"value1"} //其他自定义拓展定义
}
数据类型
所有类型共有属性:
- id 唯一标识
- name 名称
- description 描述
- expands 自定义配置
类型定义
- int 整型
- long 长整型
- float 单精度浮点型
- double 双精度浮点型
以上均为数字类型,共有属性:
- max 最大值
- min 最小值
- unit 单位
例:
{
"type":"double",
"max":100,
"min":0,
"unit":"percent",
"expands":{"readonly":true}
}
- boolean 布尔类型
属性
- trueText 为true时的文本,默认为
是
- falseText 为false时的文本,默认为
否
- trueValue 为true时的值,默认为
true
- falseValue 为false时的值,默认为
false
例:
{
"type":"boolean",
"trueText":"开启",
"falseText":"关闭",
"trueValue":"1",
"falseValue":"0"
}
- string 字符类型
例:
{
"type":"string",
"expands":{"maxLen","255"}
}
- enum 枚举类型
属性:
- elements (Element)枚举中的元素
Element:
- value 枚举值
- text 枚举文本
- description 说明
例:
{
"type":"enum",
"elements":[
{"value":"1","text":"正常"},
{"value":"-1","text":"警告"},
{"value":"0","text":"未知"}
]
}
- date 时间类型
属性:
- format 格式,如: yyyy-MM-dd
- tz 时区,如: Asia/Shanghai
例:
{
"type":"date",
"format":"yyyy-MM-dd",
"tz": "Asia/Shanghai"
}
- password 密码类型
与string类型相同
- file 文件类型
属性:
- bodyType 类型: url,base64,binary
例:
{
"type":"file",
"bodyType":"url"
}
- array 数组(集合)类型
属性:
- elementType 元素类型
例:
{
"type":"array",
"elementType":{
"type":"string"
}
}
- object 对象(结构体)类型
属性:
- properties 属性列表
例:
{
"type":"object",
"properties":[
{
"id": "location",
"name": "地点",
"valueType": {
"type": "string"
}
},
{
"id": "lng",
"name": "经度",
"valueType": {
"type": "double"
},
"expands":{"gis":"lng"}
},
{
"id": "lat",
"name": "纬度",
"valueType": {
"type": "double"
},
"expands":{"gis":"lat"}
}
]
}
MQTT(S)接入
目前支持MQTT3.1.1和3.1版本协议.
认证
CONNECT报文:
clientId: 设备实例ID
username: secureId+"|"+timestamp
password: md5(secureId+"|"+timestamp+"|"+secureKey)
说明: secureId
以及secureKey
在创建设备产品和设备实例时进行配置.
timestamp
为当前系统时间戳(毫秒),与系统时间不能相差5分钟.
Topic
- 读取设备属性:
topic:/{productId}/{deviceId}/properties/read
方向:下行
消息格式:
{
"messageId":"消息ID",
"deviceId":"设备ID",
"properties":["sn","model"] //要读取到属性列表
}
回复Topic: /{productId}/{deviceId}/properties/read/reply
回复消息格式:
//成功
{
"messageId":"与下行消息中的messageId相同",
"properties":{"sn":"test","model":"test"}, //key与设备模型中定义的属性id一致
"deviceId":"设备ID",
"success":true,
}
//失败. 下同
{
"messageId":"与下行消息中的messageId相同",
"success":false,
"code":"error_code",
"message":"失败原因"
}
- 修改设备属性:
topic:/{productId}/{deviceId}/properties/write
消息格式:
{
"messageId":"消息ID",
"deviceId":"设备ID",
"properties":{"color":"red"} //要设置的属性
}
回复Topic: /{productId}/{deviceId}/properties/wirte/reply
回复消息格式:
{
"messageId":"与下行消息中的messageId相同",
"properties":{"color":"red"}, //设置成功后的属性,可不返回
"success":true,
}
- 调用设备功能
topic:/{productId}/{deviceId}/function/invoke
消息格式:
{
"messageId":"消息ID",
"deviceId":"设备ID",
"function":"playVoice",//功能ID
"inputs":[{"name":"text","value":"播放声音"}] //参数
}
回复Topic: /{productId}/{deviceId}/function/invoke/reply
回复消息格式:
{
"messageId":"与下行消息中的messageId相同",
"output":"success", //返回执行结果
"success":true,
}
- 设备事件上报
topic: /{productId}/{deviceId}/event/{eventId}
消息格式:
{
"messageId":"随机消息ID",
"data":100 //上报数据
}
拓展:
定时上报属性:
{
"messageId":"随机消息ID",
"data":{"color":"red"},//属性列表
"headers":{"report-properties":true} //标记为上报属性事件
}
动态注册
暂不支持
CoAP接入
使用CoAP协议接入仅需要对数据进行加密即可.加密算法: AES/ECB/PKCS5Padding.
使用自定义Option: 2100:设备ID
来标识设备.
将请求体进行加密,密钥为在创建设备产品和设备实例时进行配置的(secureKey
).
请求地址(URI
)与MQTT Topic
相同.消息体(payload
)与MQTT相同.
DTLS接入
使用CoAP DTLS 协议接入时需要先进行认证:
发送认证请求:
POST /auth
Accept: application/json
Content-Format: application/json
2100: 设备ID
2110: 签名 md5(payload+secureKey)
payload: {"timestamp":"时间戳"}
响应结果:
2.05 (Content)
payload: {"token":"令牌"}
之后的请求中需要将返回的令牌携带到自定义Option:2111
例如:
POST /test/device1/event/fire_alarm
2100: 设备ID
2111: 令牌
...其他Option
payload: json数据