You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
430 lines
9.8 KiB
430 lines
9.8 KiB
# JetLinks 消息协议 v1.0
|
|
|
|
- [设备模型定义](#设备模型(元数据)定义)
|
|
- [属性](#属性)
|
|
- [功能](#功能)
|
|
- [事件](#事件)
|
|
- [数据类型](#数据类型)
|
|
- [MQTT接入](#MQTT(S)接入)
|
|
- [认证](#认证)
|
|
- [Topic](#Topic)
|
|
- [CoAP接入](#CoAP接入)
|
|
- [CoAP DTLS接入](#DTLS接入)
|
|
|
|
## 设备模型(元数据)定义
|
|
|
|
设备模型分为: 属性(properties),功能(function),事件(event).
|
|
|
|
设备模型使用场景:
|
|
1. 前端通过模型定义动态展示设备运行状态或者设备操作界面
|
|
2. 服务端可通过统一的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 自定义配置
|
|
|
|
类型定义
|
|
|
|
1. int 整型
|
|
2. long 长整型
|
|
3. float 单精度浮点型
|
|
4. double 双精度浮点型
|
|
|
|
以上均为数字类型,共有属性:
|
|
- max 最大值
|
|
- min 最小值
|
|
- unit 单位
|
|
|
|
例:
|
|
|
|
{
|
|
"type":"double",
|
|
"max":100,
|
|
"min":0,
|
|
"unit":"percent",
|
|
"expands":{"readonly":true}
|
|
}
|
|
|
|
5. boolean 布尔类型
|
|
|
|
属性
|
|
- trueText 为true时的文本,默认为`是`
|
|
- falseText 为false时的文本,默认为`否`
|
|
- trueValue 为true时的值,默认为`true`
|
|
- falseValue 为false时的值,默认为`false`
|
|
|
|
例:
|
|
|
|
{
|
|
"type":"boolean",
|
|
"trueText":"开启",
|
|
"falseText":"关闭",
|
|
"trueValue":"1",
|
|
"falseValue":"0"
|
|
}
|
|
|
|
6. string 字符类型
|
|
|
|
例:
|
|
|
|
{
|
|
"type":"string",
|
|
"expands":{"maxLen","255"}
|
|
}
|
|
|
|
7. enum 枚举类型
|
|
|
|
属性:
|
|
- elements (Element)枚举中的元素
|
|
|
|
Element:
|
|
- value 枚举值
|
|
- text 枚举文本
|
|
- description 说明
|
|
|
|
例:
|
|
|
|
{
|
|
"type":"enum",
|
|
"elements":[
|
|
{"value":"1","text":"正常"},
|
|
{"value":"-1","text":"警告"},
|
|
{"value":"0","text":"未知"}
|
|
]
|
|
}
|
|
|
|
8. date 时间类型
|
|
|
|
属性:
|
|
- format 格式,如: yyyy-MM-dd
|
|
- tz 时区,如: Asia/Shanghai
|
|
|
|
例:
|
|
|
|
{
|
|
"type":"date",
|
|
"format":"yyyy-MM-dd",
|
|
"tz": "Asia/Shanghai"
|
|
}
|
|
|
|
9. password 密码类型
|
|
|
|
与string类型相同
|
|
|
|
10. file 文件类型
|
|
|
|
属性:
|
|
- bodyType 类型: url,base64,binary
|
|
|
|
例:
|
|
|
|
{
|
|
"type":"file",
|
|
"bodyType":"url"
|
|
}
|
|
|
|
11. array 数组(集合)类型
|
|
|
|
属性:
|
|
- elementType 元素类型
|
|
|
|
例:
|
|
|
|
{
|
|
"type":"array",
|
|
"elementType":{
|
|
"type":"string"
|
|
}
|
|
}
|
|
|
|
12. 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 协议接入时需要先进行认证:
|
|
|
|
发送认证请求:
|
|
```text
|
|
POST /auth
|
|
Accept: application/json
|
|
Content-Format: application/json
|
|
2100: 设备ID
|
|
2110: 签名 md5(payload+secureKey)
|
|
payload: {"timestamp":"时间戳"}
|
|
```
|
|
|
|
响应结果:
|
|
```text
|
|
2.05 (Content)
|
|
payload: {"token":"令牌"}
|
|
```
|
|
|
|
之后的请求中需要将返回的令牌携带到自定义Option:2111
|
|
|
|
例如:
|
|
```text
|
|
POST /test/device1/event/fire_alarm
|
|
2100: 设备ID
|
|
2111: 令牌
|
|
...其他Option
|
|
payload: json数据
|
|
``` |