☰
Navigation :

智能家居接口V2.0参考

智能家居接口V2.0参考(预览版)

更新时间

2017/7/27 更新消息参考表中的传感器和错误消息

2017/8/3 增加设备发现响应说明 ​ 调整返回属性格式

2017/8/4 补充上一首消息

2017/10/27 设备发现增加options字段

介绍

本文档描述了BroadLink智能家居云端互通的接口规范。设备发现和控制接口只能通过云端IP白名单方式进行访问控制, 且可以与第三方平台帐号(OAuth 2.0)进行互通。

帐号互通的流程是在APP或者Web页面中嵌入BroadLink的Oauth 帐号登录页面，同时提供用来接收登录成功BroadLink生成的code回调URL。 当用户登录完成后，Oauth服务会跳转到回调URL并携带code参数。

整体的对接框架如下图所示：

image

接口格式说明

签名校验

所有接口的访问都需要在http的header中添加签名和时间戳 关键字: signature和timestamp

signature计算方法: sha1(body+timestamp+license).hexstring(),其中body，timestamp和license表示字符串拼接。

OAuth帐号关联接口

接口在调用之前，需要通过OAuth 2.0的Access Token模式与智慧星进行帐号关联来获取token。 在调用后续接口时，必须携带这个token。根据OAuth 2.0的标准，进行帐号互通时需要.在获取token之前还需要一些准备工作如下：

请单击注册企业开发者账号 在业务管理一栏申请license以及新增oauth应用；申请之后请及时联系与您对接的销售或售前或者BroadLink工程师替您进行审核审批。(审核通过后您可以拿到license和clientid/secretid进行后面的接口测试)

登录请求接口

  GET https://(OAuthLoginURL)/?redirect_uri=(callback_url)&client_id=(client_id)&state=(state)&response_type=code

成功后, OAuth服务器会跳转到回调地址，并携带code和state参数。

回调请求接口

  GET https://(callback_url)/?code=(code)&state=(state)

其中callback_url和state是第三方提供, callback_url参数需要使用url_encode

注意：callback_url中不能包括code和state参数，否则回调后，参数重名，会出现错误.

  POST https://(OAuthLoginURL)/oauth/v2/token?grant_type=authorization_code&client_id=(client_id)&client_secret=(client_secret)&code=(code)&redirect_uri=(callback_url)
  其中: OAuthLoginURL, client_id和client_secret为对接时从BroadLink DNAkit平台获取.
  code是OAuthServer在用户登录成功后，回调给第三方平台的URL中携带的。callback_url参数需要使用 url_encode, 必须提前注册, 当只注册一个callback_url时, 可以不带这个参数, 当 注册多个时, 必须携带这个参数.
  请求示例:
  
  POST https://(OAuthLoginURL)/oauth/v2/token?grant_type=authorization_code&client_id=(client_id)&client_secret=(client_secret)&code=(code) HTTP/1.1
  Host: OAuthLoginURL
  Accept: application/json, text/javascript
  响应示例:
  
  HTTP/1.1 200 OK
  Vary: Accept
  Content-Type: text/javascript
  
  {
   "access_token": "iM-nK1t_Sw6yyqBk3fAGyw",
   "expires_in": 7200,
   "refresh_token": "cwey5p6RTXa_PuasoLAhSw",
   "token_type": "Bearer"
  }
  Status Codes:	
  200 – 成功
  其他 – 失败

  POST https://(OAuthLoginURL)/oauth/v2/token?grant_type=refresh_token&client_id=(client_id)&client_secret=(client_secret)&refresh_token=(refresh_token)
  其中: OAuthLoginURL, client_id和client_secret为对接时从BroadLink DNAkit平台获取.
  refresh_token是OAuthServer在获取token是返回的。
  请求示例:
  POST https://(OAuthLoginURL)/oauth/v2/token?grant_type=authorization_code&client_id=(client_id)&client_secret=(client_secret)&refresh_token=(refresh_token) HTTP/1.1
  Host: OAuthLoginURL
  Accept: application/json, text/javascript
  
  响应示例:
  HTTP/1.1 200 OK
  Vary: Accept
  Content-Type: text/javascript
  {
   "access_token": "iM-nK1t_Sw6yyqBk3fAGyw",
   "expires_in": 7200,
   "refresh_token": "cwey5p6RTXa_PuasoLAhSw",
   "token_type": "Bearer"
  }
  Status Codes:	
  200 – 成功
  其他 – 失败
  刷新token 根据refresh_token 获取access_token

需要在token失效之前对token进行刷新，失效时间参考expires_in,单位是秒

  POST https://(OAuthLoginURL)/oauth/v2/server/getlogindata？access_token=xx
  请求示例:
  
  POST http://(OAuthLoginURL)/oauth/v2/server/getlogindata?access_token=xx
  Host: OAuthLoginURL
  Accept: application/json, text/javascript
  响应示例:
  
  HTTP/1.1 200 OK
  Vary: Accept
  Content-Type: text/javascript
  
  {
   "status" : "0",
   "msg" : "ok",
   "userid" : "xx",
   "loginsession" : "xx",
   "nickname" : "xx"
  }
  Status Codes:	
  200 – 成功
  其他 – 失败

设备发现和控制接口

用于从用户的帐号和家庭中获取设备列表,同时会订阅该设备的设备上报信息。具体消息格式请查看 智能家居消息参考表

   POST https://(DnaproxyURL)/dnaproxy/v2/discover?license=(license)
   其中: DnaproxyURL和license为对接时从BroadLink DNAkit平台获取.
   
   license需要使用 url_encode。
   
   请求示例:
   
   其中只需修改token（该token为上面oauth认证中刷新token接口获取到的access_token）
   
   POST https://(DnaproxyURL)/dnaproxy/v2/discover?license=(license)
   
   Host: DnaproxyURL
   
   Accept: application/json, text/javascript
   
   signature: 你的签名 Signature
   
   timestamp: 你的unix时间戳

{
	"directive": {
		"header": {
			"namespace": "DNA.Discovery",
			"name": "Discover",
			"interfaceVersion": "2",
			"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
		},
		"payload": {
			"scope": {
				"type": "BearerToken",
				"token": "some-access-token"
			},
			"options": {
				"enableIntent": false,
				"additionals": {
				    "familyids":["xx","xx"]//只从某几个家庭中发现设备
				},
				"ignoreDevReachable":false //该字段为true时，不查询设备在线情况,提高设备列表返回速度
			}

		}
	}
}

响应示例: 
{
​      "context": {},
​      "event": {
​          "header": {
​              "namespace": "DNA.Discovery",
​              "name": "Response",
​              "interfaceVersion": "2",
​              "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
​          },
​          "payload": {
​          },
​          "scenes": [{
​              "sceneId":"",
​              "friendlyName":"",
​              "manufacturerName": "Sample Manufacturer",
​              "description":"",
​              "displayCategories":["SCENE_TRIGGER"],
​              "cookie":{},
​              "capabilities":[
​                  {
​                      "type":"DNAInterface",
​                      "interface":"DNA.SceneControl",
​                      "version":"2",
​                      "supportsDeactivation":false,
​                      "proactivelyReported":true
​                  }
​              ]
​          }],
​          "endpoints": [
​              {
​                  "endpointId": "appliance-001",
​                  "parentId":"",//空代表普通设备或网关设备
​                  "friendlyName": "智能遥控",
​                  "isReachable":true,
​                  "description": "由BroadLink生产的智能遥控",
​                  "manufacturerName": "Sample Manufacturer",
​                  "icon":"产品图片URL",
​                  "brand":"品牌",
                   "CustomizeCategory":"xxx", //APP设置的品类
​                  "displayCategories": [
​                      "TELECONTROLLER"//万能遥控品类
​                  ],
​                  "familyName": "用户设置的家庭名称",
​                  "roomName": "用户设置的房间名称",
​                  "cookie": {
​                      "extraDetail1": "某些设备可能会用到这个cookie，需要在控制时原样返回",
​                      "extraDetail2": "某些设备可能会用到这个cookie，需要在控制时原样返回",
​                      "extraDetail3": "某些设备可能会用到这个cookie，需要在控制时原样返回",
​                      "extraDetail4": "某些设备可能会用到这个cookie，需要在控制时原样返回"
​                  },
​                  "capabilities": [
​                  ]
​              },
​              {
​                  "endpointId": "appliance-002",
​                  "parentId":"appliance-001",//非空代表该设备是子设备，parentId为网关设备endpointId
​                  "friendlyName": "电视面板",
​                  "isReachable":true,
​                  "description": "BroadLink　电视面板",
​                  "manufacturerName": "Sample Manufacturer",
​                  "icon":"产品图片URL",
​                  "brand":"品牌",
​                  "displayCategories": [
​                      "TV"
​                  ],
​                  "familyName": "用户设置的家庭名称",
​                  "roomName": "用户设置的房间名称",
​                  "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"
​                              }
​                             ]
​                         }
​                      }
​                  ]
​              },
​              {
​                  "endpointId": "appliance-003",
​                  "parentId":"",//空代表普通设备或网关设备
​                  "friendlyName": "灯",
​                  "isReachable":true,
​                  "description": "BroadLink　灯",
​                  "manufacturerName": "Sample Manufacturer",
​                  "icon":"产品图片URL",
​                  "brand":"品牌",
​                  "displayCategories": [
​                      "LIGHT",
​                      "SMARTPLUG"
​                  ],
​                  "familyName": "用户设置的家庭名称",
​                  "roomName": "用户设置的房间名称",
​                  "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"
​                              }
​                             ]
​                         }
​                      }
​                  ]
​              }
​          ]
​      }
  }

Status Codes:
200 – 成功 其他 – 失败

license需要使用 url_encode。

“scope”中的“type”和“token”用于权限校验，支持三种校验方式：

  1. accesstoken “type”:“BearerToken”, “token”:“accesstoken”
  2. loginsession “type”:“Session”, “token”:“Session info” //{“userId”:“”, ​ “session”:“”}对象的base64编码后的字符串
  3. tikcet “type”:“Ticket”, “token”:“Ticket info” //{“userid”:“”,“did”:“”,“ticket”:“”,“familyid”:“”}对象的base64编码后的字符串

不同功能消息格式请查看 智能家居消息参考表

请求示例:

   POST https://(DnaproxyURL)/dnaproxy/v2/control?license=(license)
   Host: DnaproxyURL
   Accept: application/json, text/javascript
   signature: 你的签名 Signature
   timestamp: 你的unix时间戳
 {
   "directive": {
     "header": {
        "namespace": "DNA.PowerControl",
        "name": "ChangePowerState",
        "interfaceVersion": "2",
        "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
     },
     "endpoint": {
       "scope": {
          "type": "BearerToken",
          "token": "Yodst_WQRoS6LHyNyMLSZA"
       },
       "endpointId": "Some-Device-ID",
       "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": {
       "scope": {
         "type": "BearerToken",
         "token": "some-access-token"
       },
       "endpointId": "appliance-001"
     },
     "payload": {
     }
   }
 }

控制时，body中的cookie内容，从设备发现返回的endpoint信息中获取，需要确保一致。

消息格式说明

设备控制消息由两个对象构成：header,payload和endpoint。其中header描述请求的功能和参数，endpoint用来描述某个用户的某个设备,payload承载各类数据， 和具体消息接口相关。 header包括如下内容

字段 说明 备注
namespace 接口名称
name 接口的动作名称
interfaceVersion 接口版本 固定为2
messageId 随机生成消息Id

endpoint包括如下内容

字段 说明
scope 用户身份数据
endpointId 设备唯一ID
cookie 设备发现时返回，需要在控制时原样携带

scope包含的字段说明

type固定填写：”BearerToken”

token是指通过OAuth2.0获取的access_token

消息通知接口

消息通知接口用来主动通知第三方平台设备或者数据变化事件，第三方平台需要按如下形式设计接口

变化通知包括两种：家庭信息变化通知和设备状态变化通知，设备状态变化通知目前尚未正式开放。 家庭信息变化通知ｖ１格式如下：

 header:userid (discover header中返回相同userid)
 body:
 {
   "context":{
​       "properties":null
   },
   "event":{
​       "header":{
​           "namespace":"DNA",
​           "name":"ChangeReport",
​           "interfaceVersion":"2",
​           "messageId":"nyjq-kl269q3j93u33sxo"
​       },
​       "payload":{
​           "reportType":"ENDPOINT_CHANGE",
​           "change":{
​               "cause":{
​                   "type":""
​               }
​           },
​           "scenes":[
​               {
​                   "sceneId":"sceneId",
​                   "friendlyName":"scenename",
​                   "manufacturerName":"",
​                   "description":"",
​                   "displayCategories":[
​                       "SCENE_TRIGGER"
​                   ],
​                   "cookie":{
​                       "key":"value"
​                   },
​                   "capabilities":[
​                       {
​                           "type":"DNAInterface",
​                           "interface":"DNA.SceneControl",
​                           "version":"2",
​                           "supportsDeactivation":false,
​                           "proactivelyReported":true
​                       }
​                   ]
​               }
​           ],
​           "endpoints":[
​               {
​                   "endpointId":"endpointId",
​                   "parentId":"",
​                   "friendlyName":"tv",
​                   "description":"BroadLink 智能遥控",
​                   "manufacturerName":"BroadLink",
​                   "icon":"https://ihcv0.ibroadlink.com/ec4appsysinfo/category2/TV.png",
​                   "brand":"BroadLink",
​                   "roomName":"roomName",
​                   "displayCategories":[
​                       "TV"
​                   ],
​                   "cookie":{
​                       "did":"did",
​                       "pid":"10002",
​                       "param":"val"
​                   },
​                   "isReachable":true,
​                   "capabilities":[
​                       {
​                           "type":"DNAInterface",
​                           "interface":"DNA.ChannelControl",
​                           "version":"2",
​                           "properties":{
​                               "supported":[
​                                   {
​                                       "name":"channelNumber"
​                                   },
​                                   {
​                                       "name":"channelName"
​                                   },
​                                   {
​                                       "name":"channelSteps"
​                                   }
​                               ],
​                               "proactivelyReported":false,
​                               "retrievable":false
​                           },
​                           "actions":{
​                               "supported":null
​                           }
​                       },
​                       {
​                           "type":"DNAInterface",
​                           "interface":"DNA.PlaybackController",
​                           "version":"2",
​                           "properties":{
​                               "supported":null,
​                               "proactivelyReported":false,
​                               "retrievable":false
​                           },
​                           "actions":{
​                               "supported":null
​                           }
​                       },
​                       {
​                           "type":"DNAInterface",
​                           "interface":"DNA.PowerControl",
​                           "version":"2",
​                           "properties":{
​                               "supported":[
​                                   {
​                                       "name":"powerState"
​                                   }
​                               ],
​                               "proactivelyReported":false,
​                               "retrievable":false
​                           },
​                           "actions":{
​                               "supported":null
​                           }
​                       },
​                       {
​                           "type":"DNAInterface",
​                           "interface":"DNA.VolumeControl",
​                           "version":"2",
​                           "properties":{
​                               "supported":[
​                                   {
​                                       "name":"volumeSteps"
​                                   },
​                                   {
​                                       "name":"mute"
​                                   }
​                               ],
​                               "proactivelyReported":false,
​                               "retrievable":false
​                           },
​                           "actions":{
​                               "supported":null
​                           }
​                       }
​                   ],
​                   "additional":{
​                       "channellist":[
​                           {
​                               "name":"Demo",
​                               "extend":"12"
​                           }
​                       ]
​                   }
​               }
​           ],
​           "extend":""
​       }
   }
 }

取消设备消息上报订阅接口

第三方云用户调用discover接口发现设备后，会订阅相关设备的上报信息，broadlink云会将设备上报信息以标准格式上报到第三方云．第三方云需要取消用户订阅时，调用该接口

url:

 POST https://(DnaproxyURL)/dnaproxy/v2/disconnect?license=(license)

body:

 {
​     "directive": {
​     "header": {
​       "namespace": "DNA.Disconnect",
​       "name": "disconnect",
​       "interfaceVersion": "2",
​       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
​     },
​     "payload": {
​       "scope": {
​         "type": "BearerToken",
​         "token": "some-access-token"
​       },
​       "options": {
​         "enableIntent": false,
​         "additionals":{}
​       }
​     }
   }
 }

返回：

{
  "event": {
​    "header": {
​       "namespace": "DNA.Disconnect",
​       "name": "Response",
​       "interfaceVersion": "2",
​       "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
​    },
​    "endpoint": {
​      "scope": {
​        "type": "BearerToken",
​        "token": "some-access-token"
​      },
​      "endpointId": "appliance-001"
​    },
​    "payload": {
​    }
  }
}

详细参考表

智能家居消息参考表

智能家居接口属性参考表

接口错误消息参考表

品类参考表

当前支持的产品列表