Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
涂鸦 Cube（私有云）
search
根据文档目录筛选
涂鸦 Cube（私有云）智慧私有云 2.0应用开发服务API 网关API 参考IoT Core 服务全屋设备体系设备控制

设备控制

更新时间：2023-07-20 02:00:21下载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 下发设备指令
PUT /v1.0/devices/{device_id}/functions/{function_code} 修改功能点名称

获取指令集（按品类）

接口描述

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

接口地址

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 指令不支持，请确认指令或值是否正确

修改功能点名称

接口描述

满足多路子设备，可以进行子设备名称修改。

接口地址

PUT /v1.0/devices/{device_id}/functions/{function_code}

请求参数

参数名 类型 参数位置 必填 说明
device_id String URI 是 设备 ID
function_code String URI 是 功能点
name String Body 是 功能点名称

请求示例

PUT /v1.0/devices/vdevo156083035305868/functions/switch_1

{
  "name":"lalal"
}

返回参数

参数名 类型 说明
code Integer 响应码，详见 全局错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Object 返回结果
t Long 时间戳

返回示例

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

错误码

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

错误码 说明
500 系统错误
上一篇获取用户列表
下一篇应用管理
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2024 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English