简体中文
简体中文
English
联系我们
注册
登录
layout空间导航

设备控制

更新时间:2022-02-10 03:48:36下载pdf

本文介绍了获取设备控制相关的指令集、规格属性、最新状态,以及下发设备指令的接口。

请求方式 API 描述
GET /v1.0/functions/{category} 按品类获取指令集
GET /v1.0/devices/{device_id}/functions 按设备获取指令集
GET /v1.0/devices/functions 批量获取设备支持的指令集
GET /v1.0/devices/{device_id}/specifications 获取设备规格属性(包含指令集和状态集)
POST /v1.0/devices/{device_id}/commands 下发设备指令
GET /v1.0/devices/{device_id}/status 获取设备最新状态

获取指令集(按品类)

接口描述

按品类来查询指令集,该指令集为涂鸦公版品类下最丰富的指令集,可供开发者参考使用。如果是平台类开发者,建议可按照此类进行开发对接。

接口地址

GET /v1.0/functions/{category}

请求参数

参数名 类型 参数类型 必填 说明
category String URI 类别名,例如:kg、cz、dj

返回参数

参数名 类型 说明
code Integer 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
category String 产品类别
functions List<funnctions> 指令集

functions 说明

参数名 类型 说明
code String 指令
type String 指令类型
values String 指令入参范围
name String 指令名称
desc String 描述

请求示例

GET /v1.0/functions/kg

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
CategoryFunctions categoryFunctions = client.getFunctionByCategory("kg");
System.out.println("根据category获取function列表: ");
System.out.println(JSONObject.toJSONString(categoryFunctions));

响应示例

{
    "success": true,
    "t": 1571293457435,
    "result": {
        "category": "kg",
        "functions": [
            {
                "name": "开关",
                "desc": "总开关,true:打开所有;false:关闭所有",
                "code": "switch",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关1",
                "desc": "开关1",
                "code": "switch_1",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关2",
                "desc": "开关2",
                "code": "switch_2",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关3",
                "desc": "开关3",
                "code": "switch_3",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关4",
                "desc": "开关4",
                "code": "switch_4",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关5",
                "desc": "开关5",
                "code": "switch_5",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关6",
                "desc": "开关6",
                "code": "switch_6",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关1倒计时",
                "desc": "开关1倒计时",
                "code": "countdown_1",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "开关2倒计时",
                "desc": "开关2倒计时",
                "code": "countdown_2",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "开关3倒计时",
                "desc": "开关3倒计时",
                "code": "countdown_3",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "开关4倒计时",
                "desc": "开关4倒计时",
                "code": "countdown_4",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "开关5倒计时",
                "desc": "开关5倒计时",
                "code": "countdown_5",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "开关6倒计时",
                "desc": "开关6倒计时",
                "code": "countdown_6",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "USB1倒计时",
                "desc": "USB1倒计时",
                "code": "countdown_usb1",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "USB2倒计时",
                "desc": "USB2倒计时",
                "code": "countdown_usb2",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            },
            {
                "name": "USB1",
                "desc": "USB1",
                "code": "switch_usb1",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "USB2",
                "desc": "USB2",
                "code": "switch_usb2",
                "type": "Boolean",
                "values": "{}"
            }
        ]
    }
}

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
2015 该品类暂不支持

获取指令集(按设备)

接口描述

查询设备支持的功能,获取到的指令可用于下发控制。

接口地址

GET /v1.0/devices/{device_id}/functions

请求参数

参数名 类型 参数类型 是否必填 说明
device_id String URI 设备 ID

返回参数

参数名 类型 说明
code Integer 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
category String 产品类别
functions List<funtion> 指令集

functions 说明

参数名 类型 说明
code String 指令
type String 指令类型
values String 指令入参范围
name String 指令名称
desc String 描述

请求示例

GET /v1.0/devices/vdevo155XXXX83954683/functions

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
categoryFunctions = client.getFunctionsByDevId(DEV_ID);
System.out.println("根据设备id 获取function列表: ");
System.out.println(JSONObject.toJSONString(categoryFunctions));

响应示例

{
    "success": true,
    "t": 1571293776551,
    "result": {
        "category": "cz",
        "functions": [
            {
                "name": "开关",
                "desc": "开关",
                "code": "switch_1",
                "type": "Boolean",
                "values": "{}"
            },
            {
                "name": "开关1倒计时",
                "desc": "开关1倒计时",
                "code": "countdown_1",
                "type": "Integer",
                "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
            }
        ]
    }
}

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
1106 权限非法

批量获取指令集(按设备)

接口描述

批量获取设备列表指令集合,设备ID列表,多个ID逗号分隔,最多支持20个设备

接口地址

GET  /v1.0/devices/functions

请求参数

参数名 类型 参数类型 必填 说明
device_ids String BODY 设备 ID集合

返回参数

参数名 类型 说明
code Integer 全局错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result List<result> 返回结果。

result 说明

参数名 类型 说明
category String 产品类别
functions List<funtion> 指令集
devices List 设备列表

functions 说明

参数名 类型 说明
code String 指令
type String 指令类型
values String 指令入参范围
name String 指令名称
desc String 描述

请求示例

GET /v1.0/devices/functions?device_ids=06200286dc4f22c8418c,6c8beb2fa517fbc901dtln

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
categoryFunctions = client.getFunctionsByDevsList(DEV_ID);
System.out.println("根据设备id列表 获取function列表: ");
System.out.println(JSONObject.toJSONString(categoryFunctions));

响应示例

{
  "result": [
    {
      "category": "cz",
      "devices": [
        "06200286dc4f22c8418c"
      ],
      "functions": [
        {
          "code": "switch",
          "desc": "开关",
          "name": "开关",
          "type": "Boolean",
          "values": "{}"
        },
        {
          "code": "countdown_1",
          "desc": "开关1倒计时",
          "name": "开关1倒计时",
          "type": "Integer",
          "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
        }
      ]
    }
  ],
  "success": true,
  "t": 1618822009199
}

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
1106 权限非法

获取设备规格属性(包含指令集、状态集)

接口描述

根据设备 ID 获取设备支持的指令集和状态集。

接口地址

GET  /v1.0/devices/{device_id}/specifications

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 设备 ID

返回参数

参数名 类型 说明
code Integer 全局错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
category String 产品类别
functions List<functions> 指令集
status List<status> 状态集

functions 说明

参数名 类型 说明
code String 指令码
type String 类型
values String 参数范围

status 说明

参数名 类型 说明
code String 状态码
type String 类型
values String 参数范围

请求示例

GET /v1.0/devices/vdevoXXXXXXXXXXXXXXX/specifications

SDK 示例

N/A

返回参数

{
    "success":true,
    "t":1571201730542,
    "result":{
        "category":"dj",
        "functions":[
            {
                "code":"switch_led",
                "type":"Boolean",
                "values":"{}"
            },
            {
                "code":"work_mode",
                "type":"Enum",
                "values":"{\"range\":[\"colour\"]}"
            },
            {
                "code":"bright_value",
                "type":"Integer",
                "values":"{\"min\":0,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}"
            },
            {
                "code":"colour_data",
                "type":"Json",
                "values":"{\"h\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":360,\"step\":1},\"s\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1},\"v\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}}"
            }
        ],
        "status":[
            {
                "code":"switch_led",
                "type":"Boolean",
                "values":"{}"
            },
            {
                "code":"work_mode",
                "type":"Enum",
                "values":"{\"range\":[\"colour\"]}"
            },
            {
                "code":"bright_value",
                "type":"Integer",
                "values":"{\"min\":0,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}"
            },
            {
                "code":"colour_data",
                "type":"Json",
                "values":"{\"h\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":360,\"step\":1},\"s\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1},\"v\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}}"
            }
        ]
    }
}

下发设备指令

接口描述

根据获取到的指令集,可按一组或多组指令集进行下发,是否同时支持多指令同时执行依具体产品而定。

接口地址

POST /v1.0/devices/{device_id}/commands

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 设备 ID
commands Object body 命令集

返回参数

参数名 类型 说明
code Integer 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Boolean 是否成功。

请求示例

POST /v1.0/devices/vdevo1552XXXX3954683/commands
{
    "commands":[
        {
            "code":"switch_led",
            "value":true
        },
        {
            "code":"bright",
            "value":30
        }
    ]
}

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
JSONObject temp = new JSONObject();
temp.put("v", 0);
temp.put("s", 1);
temp.put("h", 1);
Command command = new Command("colour_data", temp);
List<Command> list = new ArrayList<Command>(1);
list.add(command);
Boolean isSuccess = client.postDeviceCommand("vdevo155013689282523", list);
System.out.println("下发设备控制指令: ");
System.out.println(isSuccess);

响应示例

{
    "success":true,
    "t":1551851043862,
    "result":true
}

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
2008 指令不支持,请确认指令或值是否正确

获取设备最新状态

接口描述

根据设备 ID 来查询设备最新状态。

接口地址

GET /v1.0/devices/{device_id}/status

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 设备 ID

返回参数

参数名 类型 说明
code Integer 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Boolean 是否成功。

请求示例

GET /v1.0/devices/{device_id}/status

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
List<Status> deviceStatus= client.getDeviceStatus(DEV_ID);
System.out.println("获取设备状态信息: ");
System.out.println(JSONObject.toJSONString(deviceStatus));

响应示例

{
      "success": true,
      "t": 1545447665981,
      "result": [
          {
              "code": "switch_led",
              "value": true
          },
          {
              "code": "work_mode",
              "value": "scene_2"
          },
          {
              "code": "bright_value",
              "value": 25
          },
          {
              "code": "temp_value",
              "value": 0
          },
          {
              "code": "colour_data",
              "value": "{\"h\":37.0,\"s\":255.0,\"v\":189.0}"
          },
          {
              "code": "scene_data",
              "value": ""
          },
          {
              "code": "flash_scene_1",
              "value": ""
          },
          {
              "code": "flash_scene_2",
              "value": ""
          },
          {
              "code": "flash_scene_3",
              "value": ""
          },
          {
              "code": "flash_scene_4",
              "value": "{\"bright\":255,\"frequency\":80,\"hsv\":[{\"h\":0.0,\"s\":255.0,\"v\":255.0},{\"h\":120.0,\"s\":255.0,\"v\":255.0},{\"h\":240.0,\"s\":255.0,\"v\":255.0},{\"h\":300.0,\"s\":255.0,\"v\":255.0},{\"h\":240.0,\"s\":255.0,\"v\":255.0},{\"h\":0.0,\"s\":255.0,\"v\":255.0}],\"temperature\":255}"
          }
      ]
  }

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误