☰
Navigation :

音响fastcon对接接口

云端接口参考

2 云端接口

整体流程

整体框图

2.1 云端身份校验接口

POST https://(OpenproxyURL)/openproxy/v2/identity?license=(license)

请求：
{
    "directive": {
        "header": {
            "namespace": "DNA.CloudIdentity",
            "name": "Identity",
            "interfaceVersion": "2",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "payload": {
            "device": {
                "deviceId":""
                "deviceInfo":"xxxxx"//设备信息透传字段
                "challenge":""
            }
        }
    }
}

响应：
{
    "context": {},
    "event": {
        "header": {
            "namespace": "DNA.CloudIdentity",
            "name": "Response",
            "interfaceVersion": "2",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
        },
        "payload": {
          "device": {
              "deviceId":"",
              "deviceInfo":"xxxxx",
              "challenge":"",
              "signature":""
          }
        }
      }
}

ps:

challenge为设备和激活云端生成的加密签名，只有设备可以解析。

deviceInfo设备信息透传字段,结构体见结构体说明1.1

2.2 设备身份声明接口

POST https://(OpenproxyURL)/openproxy/v2/identity?license=(license)

请求：
{
    "directive": {
        "header": {
            "namespace": "DNA.DeviceIdentity",
            "name": "Identity",
            "interfaceVersion": "2",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "payload": {
            "device": {
                "deviceId":""
                "deviceInfo":"xxxxx",
                "signature":""
            }
        }
    }
}

响应：
{
    "context": {},
    "event": {
        "header": {
            "namespace": "DNA.DeviceIdentity",
            "name": "Response",
            "interfaceVersion": "2",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
        },
        "payload": {
          "device": {
              "deviceId":"",
              "deviceInfo":"xxxx",
              "shareKey":""
          }
        }
      }
}

2.3 设备注册接口

POST https://(OpenproxyURL)//openproxy/v3/register?license=(license)

请求：
{
    "directive": {
        "header": {
            "namespace": "DNA.Register",
            "name": "Register",
            "interfaceVersion": "2",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "payload": {
            "device": {
                deviceId:"xxx",
                deviceInfo:"xxx",
                tokenInfo:"xxx",//设备配网生成的token 可以为空，为空时返回基本播放信息，非空时返回设备落库信息
                cookie:{
                    "subDeviceInfo":subDeviceInfo //虚拟面板设备携带，其他设备不传，结构见透传字段
                }//设备额外信息，如面板、子设备信息,一般是h5或者sdk返回。
            }，
	    "scope"：{
         	"type": "BearerToken",
         	"token": "Yodst_WQRoS6LHyNyMLSZA",       //第三方oauth2.0 accesstoken
		"openId":"xxxxxxxx",                     //第三方userid
		"companyId":"xxxxx",                     //从DNAkit申请
		"platform":"xxxxxxx",                    //平台名称，从对接人员获取
		"nickname":"xxxxxxx"                     //第三方用户昵称
      		}          //需要添加设备到智慧星时使用此字段（智慧星通过第三方账号登录可以看到此设备）
        }
    }
}

响应：
{
    "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.4 设备控制接口

POST https://(OpenproxyURL)/openproxy/v3/opencontrol?license=(license)
请求：
{
  "directive": {
    "header": {
       "namespace": "DNA.PowerControl",//控制能力
       "name": "ChangePowerState",//控制动作
       "interfaceVersion": "2",//目前版本标识
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"//请求id,返回信息中会保持一致。
    },
    "endpoint": {
      "endpointId": "Some-Device-ID",//注册返回
      "cookie": {}//注册返回的cookie,第三方云端透传
    },
    "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.4.1 设备定时控制接口

POST https://(OpenproxyURL)/openproxy/v3/opencontrol?license=(license)
请求：
{
  "directive": {
    "header": {
       "namespace": "DNA.PowerControl",//控制能力
       "name": "ChangePowerState",//控制动作
       "interfaceVersion": "2",//目前版本标识
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"//请求id,返回信息中会保持一致。
    },
    "endpoint": {
      "endpointId": "Some-Device-ID",//注册返回
      "cookie": {}//注册返回的cookie,第三方云端透传
    },
    "payload": {
        "timer":{
            "type" : "xx",            //定时类型，目前使用delay标示延时定时
            "class" : "xx",           //所属类，可选，目前暂时为空即可
            "id" : xx,      //定时索引（由固件统一管理，添加的时候设为0或者为空）
            "en" : xx,      //定时使能：0 - 关闭，1 - 打开
            "name" : "xx" ,         //定时名称
            "time" : "xx",      //时间定义//0_1_22_26_2_*_2018
            "act":"xxx" 
        },//目前只是支持开关
        "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.5 设备在线状态查询接口

每次最多查询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",
      "cookie": {}
    }],
    "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.6 设备状态查询接口

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",
      "cookie": {}
    },
    "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.6 透传红码控制接口

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",
      "cookie": {}
    },
    "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.7 设备管理相关

2.7.1 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",
      "cookie": {}
    },
    "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"//查询返回数据
    }
  }
}

2.7.2 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",
      "cookie": {}
    },
    "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": {
	    
    }
  }
}

2.7.3 远程复位接口

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",
      "cookie": {}
    },
    "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.8 数据上报结构

POST https://YOURURL
上报结构：
{
    "context":{

    },
    "event":{
        "header":{
            "namespace":"DNA",
            "name":"ChangeReport",
            "payloadVersion":"3",
            "messageId":"yfwf-pnpu4uc5ax7xcxia"
        },
        "endpoint":{
            "endpointId":"34ea34183f4a", //设备唯一标识
            "devtype":"32016" //标示设备型号
        },
        "payload":{
            "change":{
                "cause":{
                    "type":"PHYSICAL_INTERACTION",
		     "msgtype":10005  //10001:上线；10003：下线；10005：fastcon配网上线
                },
                "properties":[
                    {
                        "namespace":"DNA.EndpointHealth",
                        "name":"connectivity",
                        "value":{
                            "value":"OK" or "UNREACHABLE"
                        },
                        "timeOfSample":"2018-05-14T23:24:04.52Z",
                        "uncertaintyInMilliseconds":0
                    }     //离线在线
                ]
            }
        }
    }
}

2.9 红码学习相关接口

2.9.1 RM进入学习功能接口

POST https://(OpenproxyURL)/openproxy/v3/opencontrol?license=(license)
请求：
{
  "directive": {
    "header": {
       "namespace": "DNA.RMControl",
       "name": "StudyIrCode",
       "interfaceVersion": "2",
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "endpoint": {
      "endpointId": "Some-Device-ID",
      "cookie": {}
    },
    "payload": {
    }
  }
}
响应：
{
  "context": {
  },
  "event": {
    "header": {
       "namespace": "DNA.RMControl",
       "name": "Response",//成功返回标识
       "interfaceVersion": "2",
       "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    },
    "endpoint": {
      "endpointId": "appliance-001"//控制设备
    },
    "payload": {
    }
  }
}

2.9.2 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",
      "cookie": {}
    },
    "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.10 接口错误响应

2.10.1 错误响应格式

返回消息中
    event.name="ErrorResponse",
    payload中是具体错误类型和原因。
举例：
{
  "context": {},
  "event": {
      "header": {
      "namespace": "DNA.PowerControl",
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "name": "ErrorResponse",
      "payloadVersion": "2"
    },
    "endpoint": {
      "endpointId": "appliance-001"
    },
    "payload": {
        "type": "ENDPOINT_UNREACHABLE",
        "message":"xxx",
        "status":-3
    }
  }
字段 说明 备注
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校验失败

3 控制接口参考表 Go to 控制接口参考表.

4 接口属性参考表 Go to 接口属性参考表.

5 品类参考表 Go to 品类参考表.