openproxy云端接口参考
1.整体流程
最终客户使用流程包含:设备配网、发现、配对,设备注册,设备状态查询,设备控制,设备数据上报,RM面板添加等几个流程。
客户使用时序图如下:
2.接口文档
阅前须知:
1.接口中的devicePairedInfo是从配网sdk中获取到的结构,需要第三方云端储存,控制时携带。
2.控制设备具体功能参数请参见控制消息接口枚举。
2.1 设备注册接口(非必须)
ps:该接口是非必须接口,当第三方查询设备类别描述信息时可以调用。
POST https://(OpenproxyURL)//openproxy/v2/register?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.Register",
"name": "Register",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"payload": {
"device": {
"devicePairedInfo": {
"mac":"",
"did":"",
"pid":"",
"cookie":base64(cookieStu) sdk透传字段
}
},
"uploadinfo":{
"lid":"xxxxxxxxx",//license对应的lid
}//有设备上报订阅需求时增加该字段,否则不带该字
}
}
}
响应:
{
"context": {},
"event": {
"header": {
"namespace": "DNA.Register",
"name": "Response",
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
},
"endpoints": [
{
"endpointId": "appliance-001",//设备的,一般为sdk设备发现的did
"friendlyName": "卧室灯",//设备的默认名称
"description": "由BroadLink生产的灯",
"manufacturerName": "Sample Manufacturer",
"icon":"产品图片URL",
"brand":"品牌",
"displayCategories": [
"LIGHT"
],
"cookie": {
"extraDetail1": "某些设备可能会用到这个cookie,需要在控制时原样返回",
"extraDetail2": "某些设备可能会用到这个cookie,需要在控制时原样返回",
"extraDetail3": "某些设备可能会用到这个cookie,需要在控制时原样返回",
"extraDetail4": "某些设备可能会用到这个cookie,需要在控制时原样返回"
},
"capabilities": [
{
"type": "DNAInterface",
"interface": "DNA.PowerControl",
"version": "2",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
},
"actions": {
"supported": [
{
"name": "ChangePowerState"
}
]
}
}
]
}
]
}
}
2.2 设备控制接口
POST https://(OpenproxyURL)/openproxy/v2/opencontrol?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.PowerControl",//控制能力
"name": "ChangePowerState",//控制动作
"interfaceVersion": "2",//目前版本标识
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"//请求id,返回信息中会保持一致。
},
"endpoint": {
"endpointId": "Some-Device-ID",//注册返回
"devicePairedInfo":{}
},
"payload": {
"powerState":"OFF"//控制属性和属性值
}
}
}
响应:
{
"context": {//控制参数
"properties": [ {
"namespace": "DNA.PowerControl",
"name": "powerState",
"value": “ON”,
"timeOfSample": "2017-02-03T16:20:50.52Z",
} ]
},
"event": {
"header": {
"namespace": "DNA.PowerControl",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001"//控制设备
},
"payload": {
}
}
}
2.3 批量设备在线状态查询接口
每次最多查询32个设备的在线状态.
POST https://(OpenproxyURL)/openproxy/v3/querystate?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.QueryState",
"name": "QueryState",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoints": [{
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
}],
"payload": {
}
}
}
响应:
{
"context": {
"properties": []
},
"event": {
"header": {
"namespace": "DNA.QueryState",
"name": "Response",
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoints": [{
"endpointId": "appliance-001",
"state": "online"
}],
"payload": {
}
}
}
2.4 设备属性状态查询接口
POST https://(OpenproxyURL)/openproxy/v3/opencontrol?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA",
"name": "ReportState",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
}
}
}
响应:
{
"context": {
"properties": [
{
"namespace": "DNA",
"name": "powerState",
"value":{
"value":"ON",
"scale":"",
"attributeName":"开关"
"scaleName":"",
"valueName":"打开"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
}
]
},
"event": {
"header": {
"namespace": "DNA.QueryState",
"name": "Response",
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001",
},
"payload": {
}
}
}
2.5 透传红码控制接口
POST https://(OpenproxyURL)/openproxy/v3/opencontrol?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.FreeControl",
"name": "DnaCodeControl",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
"dnaCode":"b445sdfafad112224sdf"
}
}
}
响应:
{
"context": {//控制参数
"properties": [ {
"namespace": "DNA.FreeControl",
"name": "DnaCodeControl",
"value": "b445sdfafad112224sdf",//控制指令
"timeOfSample": "2017-02-03T16:20:50.52Z",
} ]
},
"event": {
"header": {
"namespace": "DNA.FreeControl",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001"//控制设备
cookie:{}
},
"payload": {
}
}
}
2.6 设备管理相关
- OTA查询版本接口
POST https://(OpenproxyURL)/openproxy/v3/firmware?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.ManagerControl",
"name": "QueryVersion",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
}
}
}
响应:
{
"context": {
},
"event": {
"header": {
"namespace": "DNA.ManagerControl",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"scope": {
},
"endpointId": "appliance-001"//控制设备
},
"payload": {
"version":"xxxxxx"//查询返回数据
}
}
}
- OTA版本升级
POST https://(OpenproxyURL)/openproxy/v3/firmware?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.ManagerControl",
"name": "OTAUpgrade",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
"url":"xxxx"
}
}
}
响应:
{
"context": {//控制参数
"properties": [ {
"namespace": "DNA.ManagerControl",
"name": "OTAUpgrade",
"value": "b445sdfafad112224sdf",//控制指令
"timeOfSample": "2017-02-03T16:20:50.52Z",
} ]
},
"event": {
"header": {
"namespace": "DNA.ManagerControl",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001"//控制设备
}
"payload": {
}
}
}
- 远程复位接口
POST https://(OpenproxyURL)/openproxy/v3/firmware?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.ManagerControl",
"name": "Reset",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
}
}
}
响应:
{
"context": {
},
"event": {
"header": {
"namespace": "DNA.ManagerControl",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001"//控制设备
},
"payload": {
"version":"xxxxxx"//查询返回数据
}
}
}
2.7 设备数据上报结构
POST https://YOURURL 安全性:使用ED25519对数据进行签名 HTTP HEADER: BLSignature:签名
1.上线离线
{
"context": {},
"event": {
"header": {
"namespace": "DNA",
"name": "ChangeReport",
"payloadVersion": "3",
"messageId": "qlo4-vr2mjbygqx9hymif"
},
"endpoint": {
"endpointId": "00000000000000000000780f7781087d",
"devtype": "32013"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION",
"msgtype": 10003
},
"properties": [{
"namespace": "DNA.EndpointHealth",
"name": "connectivity",
"value": {
"value": "UNREACHABLE"
},
"timeOfSample": "2018-09-06T11:46:55.52Z",
"uncertaintyInMilliseconds": 0
}]
}
}
}
}
2.开关(34消息)
{
"context": {},
"event": {
"header": {
"namespace": "DNA",
"name": "ChangeReport",
"payloadVersion": "3",
"messageId": "8kua-vviwdgkmxutb5s3r"
},
"endpoint": {
"devtype": "32009",
"endpointId": "00000000000000000000780f774fc726"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION",
"msgtype": 34
},
"properties": [{
"namespace": "DNA.PowerControl",
"name": "powerState",
"value": "ON",
"timeOfSample": "2019-01-17T11:39:11.52Z",
"uncertaintyInMilliseconds": 0
}]
}
}
}
}
3.心跳
{
"context": {},
"event": {
"header": {
"namespace": "DNA",
"name": "HeartBeat",
"payloadVersion": "3",
"messageId": "smrn-xr615ouot38qd431"
},
"endpoint": {
"endpointId": "00000000000000000000780f7751ecfb",
"devtype": "10178"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION",
"msgtype": 10007
},
"properties": [{
"namespace": "DNA.HeartBeat",
"name": "HeartBeat",
"value": {
"ip": [67, 193, 1, 69],
"port": 49161,
"res": 0
},
"timeOfSample": "2019-01-17T11:38:05.52Z",
"uncertaintyInMilliseconds": 0
}]
}
}
}
}
4.透传上报,适用于设备消息其他类型
{
"context": {},
"event": {
"endpoint": {
"endpointId": "00000000000000000000c411e004a2b1",
"devtype": "32512"
},
"header": {
"namespace": "DNA.TransmissionReport",
"name": "Report",
"payloadVersion": "3",
"messageId": "nupp-xge3vtpwgy22fn6y"
},
"payload": {
"data": "7b22707772223a302c226d6178776f726b74696d65223a302c22706964223a223030303030303030303030303030303030303030303030303030376630303030222c22646964223a223030303030303030303030303030303030303030633431316530303461326231227d",
"change": {
"cause": {
"msgtype": 54
}
}
}
}
}
ps:其中payload.data中的内容是设备上报的body数据经过hex.EnCodeTostring编码而成
5.产品属性上报(设备54消息)举例
{
"context": {},
"event": {
"header": {
"namespace": "DNA",
"name": "ChangeReport",
"payloadVersion": "3",
"messageId": "5ike-psu4w0f2ounvpqkg"
},
"endpoint": {
"endpointId": "00000000000000000000b4430d96b522",
"devtype": "20010"
},
"payload": {
"change": {
"cause": {
"type": "54"
},
"properties": [{
"namespace": "DNA",
"name": "temperatureAmbient",
"value": 23,
"timeOfSample": "2019-02-28T06:40:40.89Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "DNA",
"name": "mode",
"value": "DEHUMI",
"timeOfSample": "2019-02-28T06:40:40.89Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "DNA",
"name": "windSpeed",
"value": "LOW",
"timeOfSample": "2019-02-28T06:40:40.89Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "DNA",
"name": "fixedTargetTemperature",
"value": 24,
"timeOfSample": "2019-02-28T06:40:40.89Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "DNA",
"name": "powerState",
"value": "ON",
"timeOfSample": "2019-02-28T06:40:40.89Z",
"uncertaintyInMilliseconds": 0
}]
}
}
}
}
2.8 红码学习相关接口
- RM进入学习功能接口
POST https://(OpenproxyURL)/openproxy/v2/learncode?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.RMControl",
"name": "StudyIrCode",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
}
}
}
响应:
{
"context": {
},
"event": {
"header": {
"namespace": "DNA.RMControl",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001"//控制设备
},
"payload": {
}
}
}
- RM查询红码学习结果
POST https://(OpenproxyURL)/openproxy/v3/opencontrol?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.RMControl",
"name": "GetIrCode",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
}
}
}
响应:
{
"context":{
},
"event":{
"header":{
"namespace":"DNA.RMControl",
"messageId":"30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",//新生成
"name":"GetIrCode",
"interfaceVersion":"2"
},
"endpoint":{
"endpointId":"appliance-001"
},
"payload":{
"code":"2600ac000700059e0001158911121211"
}
}
}
2.9 设备上报订阅相关接口
- 取消上报订阅
POST https://(OpenproxyURL)/openproxy/v2/devsubscribe?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.DevSubscribe",//
"name": "Unsubscribe",//取消订阅
"interfaceVersion": "2",//目前版本标识
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"//请求id,返回信息中会保持一致。
},
"endpoint": {
"endpointId": "Some-Device-ID",//注册返回
"devicePairedInfo":{},
"cookie":{}//注册返回
},
"payload": {
"lid":"xxxxxxxxx"// 开发者申请的lid
}
}
}
响应:
{
"event": {
"header": {
"namespace": "DNA.DevSubscribe",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001"//设备ID
},
"payload": {
}
}
}
2.10 透传控制接口
POST https://(OpenproxyURL)/openproxy/v3/opencontrol?license=(license)
请求:
{
"directive": {
"header": {
"namespace": "DNA.TransmissionControl",
"name": "commonControl",
"interfaceVersion": "2",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"endpoint": {
"endpointId": "Some-Device-ID",
"devicePairedInfo":{}
},
"payload": {
"data":"b445sdfafad112224sdf", //base64编码
"notpadding":0//默认为0,特殊控制如定时等为1
}
}
}
响应:
{
"context": {//控制参数
"properties": [ {
"namespace": "DNA.TransmissionControl",
"name": "commonControl",
"value": "b445sdfafad112224sdf",//控制指令
"timeOfSample": "2017-02-03T16:20:50.52Z",
} ]
},
"event": {
"header": {
"namespace": "DNA.TransmissionControl",
"name": "Response",//成功返回标识
"interfaceVersion": "2",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
},
"endpoint": {
"endpointId": "appliance-001"//控制设备
},
"payload": {
"data":"b445sdfafad112224sdfsdfad"//设备返回数据
}
}
}
2.11 接口错误响应
- 错误响应格式
返回消息中
event.name="ErrorResponse",
payload中是具体错误类型和原因。
举例:
{
"context": {},
"event": {
"header": {
"namespace": "DNA.PowerControl",
"messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
"name": "ErrorResponse",
"payloadVersion": "2"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "some-access-token"
},
"endpointId": "appliance-001"
},
"payload": {
"type": "ENDPOINT_UNREACHABLE",
"status":-3,
"message":"xxx"
}
}
- 错误码表
字段 | 说明 | 备注 |
---|---|---|
ENDPOINT_UNREACHABLE | 设备离线 | |
NO_SUCH_ENDPOINT | 设备不存在 | |
INVALID_REQ | 请求格式不对 | |
DEVICE_RESET | 设备已经复位 | |
INVALID_DIRECTIVE | 指令错误 | |
INVALID_ACCESSTOKEN | token失效 | |
INVALID_SIGNATURE | 签名非法 | |
INTERNAL_ERROR | 其他错误 | |
VALUE_OUT_OF_RANGE | 值越界 | |
FUNCTION_NOT_SUPPORT | 功能不支持 | |
UNDERSTAND_FAILURE | 无法理解 | |
SERVICE_UNAVAILABLE | 服务器不可用 | 当服务处理超时或者异常时返回 |
NETWOEK_TIME_OUT | 网络超时 | 控制设备超时返回 |
- status表
字段 | 说明 | 备注 |
---|---|---|
0 | 成功 | |
-49001 | 设备网络超时 | |
-49002 | 服务器错误 | |
-3 | 设备离线 | |
-49004 | 参数错误 | |
-5 | 设备无响应 | |
-49006 | 请求错误 | |
-7 | 设备已经复位 | |
-49008 | 请求命令错误 | |
-49010 | 设备不存在 | |
-49011 | 请求内容错误 | |
-49039 | 服务器缓存错误 | |
-49019 | ip白名单错误 | |
-49024 | 空调红码文件不存在 | |
-49037 | 数值超出界限 | |
-49103 | 功能不支持 | |
-49022 | 功能参数不支持 | |
-49026 | 请求长度超出限制 | |
-49021 | 红码过长 | |
-49018 | Signature校验失败 |