1.1.1. 目录

1.1.2. HTTP 远程驱动（旧版协议）

HTTP 远程驱动是接入 Homebase 推荐的方式，云对云驱动也使用此协议。

你可以通过 开发者驱动， 或 rhome 命令 来开发和调试 HTTP Driver

开发一个 HTTP 远程驱动你可能需要以下 3 个接口

  • /list 获取设备列表
  • /execute 在设备上执行动作
  • /command （可选）用于处理用户授权，绑定，初始化等命令；相对于使用这个授权方式，我们更加推荐使用标准 OAuth2.0 接入

通用格式

HTTP 远程驱动使用 JSON 作为数据交换格式， 执行成功会返回如下字段：

成功返回

  • status {int} 成功返回必须为 0
  • data {any} 执行结果, 根据接口类型返回不同的结果
{
  "status": 0,
  "data": {
    "some": "data"
  }
}

错误返回

  • status {int} 必须 大于0 的正整数
  • errorName {string} 可选， 若琪定义的错误名
  • vendorErrorCode {string} 可选， 厂家自有错误码
  • message {string} status > 0 时必选；错误描述, 对错误的简短描述
  • debugInfo {string} 可选， 调试信息
{
  "status": 1,
  "errorName": "E_DRIVER_ERROR",
  "vendorErrorCode": "10001",
  "message": "time out",
  "debugInfo": "some info for debug"
}

标准接口

POST /list 设备搜索

搜索给定用户账号下的所有设备， 包括虚拟设备， 子设备

参数：

  • userAuth {Object} 用户授权信息
{
  "userAuth": {
    "userId": "",
    "userToken": ""
  }
}

返回值

标准化后的 Device 列表 { Array }：

示例

{
  "status": 0,
    "data": [
      {
        "type": "light",
        "deviceId": "demoDevcie1",
        "name": "灯灯灯灯",
        "roomName": "客厅",
        "homeName": "我的家",
        "actions": {
          "switch": ["on", "off"]
        },
        "state": {
          "switch": "off"
        }
      },
      {
        "type": "light",
        "deviceId": "demoDevcie2",
        "name": "灯灯灯灯",
        "roomName": "办公室",
        "homeName": "公司",
        "actions": {
          "switch": ["on", "off"]
        },
        "state": {
          "switch": "off"
        }
      }
    ]
}
POST /execute 执行操作指令， 并返回可确定的最新状态

设备执行操作， 将返回最新状态

参数

  • device {Object}
  • device.deviceId {String}, 厂商设备ID， 可以包含不可变数据， 与厂商ID一起，可以唯一确认一台设备
  • device.state {Object}, 获取设备当前状态
  • device.userAuth {Object}, 用户授权信息
  • action {Object} 需要执行的操作， 参考文档 actions and state

request

{
  "device": {
     "deviceId": "xxx",
     "state": {
        "switch": "on"
     },
     "userAuth": {
        "userId": "",
        "userToken": ""
     }
  },
  "action": {
    "property": "switch",
    "name": "on"
  }
}

response


{
  "status": 0,
  "data": {
    "switch": "on"
  }
}

返回值

Object 设备最新状态， 如果无法确定设备的状态， 返回字段可以置空， 返回的设备状态将被缓存到虚拟设备中去

POST /command 执行特定指令

执行自定义指令

说明：

  • 如果是用户名，密码登录的 Driver 必须提供 login command，返回 userId,userToken
  • 如果是 OAuth 登录的， 必须提供 OAuth command, 返回 OAuth loginUrl

参数

  • command {String}
  • params {Object}

request sample

{
  "command": "login",
  "params": {
    "username": "superman",
    "password": "xxxxxx"
  }
}

response sample


{
  "status": 0,
  "data": {
    "userId": "superman",
    "userToken": "DFGHJKLCVBNMFGHJKL"
  }
}
常用指令 Command

command OAuth

OAuth 授权方式必须提供 OAuth Command， 输入回调地址， 返回 OAuth 登陆地址

  • 返回的地址必须可以在浏览器里面打开
  • 地址里面包含 callbackURL ， 注意需要 encode
  • 用户授权完成， 需要重定向到 callbackURL, url 中添加 OAuthRefresh

params:

  • callbackURL 授权成功后的回调页面

request

{
  "command": "OAuth",
  "params": {
    "callbackURL": "https://homebase.rokid.com/bar?a=1"
  }
}

returns { String } 登录跳转 URL

response

{
  "status": 0,
  "data": "https://oauth.yourbrand.com?redirect=http%3A%2F%2Fhomebase.rokid.com%2Fbar%3Fa%3D1"
}

command OAuthRefresh

OAuth 授权方式必须要有， 输入回调地址， 返回 OAuth 登陆地址

params:

  • userId 用户Id
  • userToken 用户Token
  • refreshToken 用户的 refreshToken， 可选
{
    "userId": "superman",
    "userToken": "fjfjfjfjfjfj"
}

returns result

  • result.userId {可选}
  • result.userToken 新的用户Token
  • result.expiredTime 更新过期时间， 秒为单位， UTC 时间戳
  • result.refreshToken 可选， 更新 refreshToken
{
  "status": 0,
  "data": {
    "userToken": "",
    "expiredTime": ""
  }
}

command login

params:

  • username 用户Id
  • password 密码
{
    "username": "superman",
    "password": "superman_password"
}

returns result

  • result.userToken
{
  "status": 0,
  "data": {
    "userToken": "userToken"
  }
}
如何描述你的设备？

请参考： 设备定义

可以参考我们的示例程序

Rokid/homebase-nodejs-http-remote-driver-sample

results matching ""

    No results matching ""