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 设备管理相关

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"//查询返回数据
    }
  }
}
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 红码学习相关接口

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": {
    }
  }
}
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 网络超时 控制设备超时返回
字段 说明 备注
0 成功
-49001 设备网络超时
-49002 服务器错误
-3 设备离线
-49004 参数错误
-5 设备无响应
-49006 请求错误
-7 设备已经复位
-49008 请求命令错误
-49010 设备不存在
-49011 请求内容错误
-49039 服务器缓存错误
-49019 ip白名单错误
-49024 空调红码文件不存在
-49037 数值超出界限
-49103 功能不支持
-49022 功能参数不支持
-49026 请求长度超出限制
-49021 红码过长
-49018 Signature校验失败