设备控制

更新时间：2023-06-20 13:08:22下载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	系统错误

上一篇配网管理