English
English
简体中文
Contact Us
Register
Log In
Language
English
English
简体中文
Contact Us
Log In
Register
Go to main website
App Develop

App Development Platform

App development platform provides multiple development methods such as no-code or IoT App SDK development to maximize the monetization of IoT apps.
layoutIndex

Device Control

Last Updated on : 2021-10-16 09:07:36download

This topic describes the APIs related to device control, including getting instruction set, specifications, properties, the latest statuses, and sending instructions.

Request method API Description
GET /v1.0/functions/{category} Get the instruction set by category
GET /v1.0/devices/{device_id}/functions Get the instruction set by device
GET /v1.0/devices/{device_id}/specifications Get the device’s specifications and properties (including instruction set and status set)
POST /v1.0/devices/{device_id}/commands Send instructions to the device
GET /v1.0/devices/{device_id}/status Get the latest device status

Get the instruction set by category

API description

Query the instruction set by category. This instruction set has the biggest amount of instructions in the category of the all-in-one apps, which can be used and referred to by developers. If you are a platform developer, you can develop applications according to this instruction set.

API address

GET /v1.0/functions/{category}

Request parameter

Parameter name Data type Parameter type Required Description
category String URI Yes Category name, such as kg, cz, and dj.

Return parameter

Parameter name Data type Description
code Integer Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> The returned result.

Description of result

Parameter name Category Description
category String Product category
functions List<funnctions> Instruction set

Description of functions

Parameter name Category Description
code String Instruction
values String The range of input parameter values
name String Instruction name
desc String Description

Request example

GET /v1.0/fucntions/kg

SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN); CategoryFunctions categoryFunctions = client.getFunctionByCategory("kg"); System.out.println("Get the function list by category: "); System.out.println(JSONObject.toJSONString(categoryFunctions));

Response example

{ "success": true, "t": 1571293457435, "result": { "category": "kg", "functions": [ { "name": "Switch", "desc": "The master switch. true: Open all sub switches. false: Close all sub switches", "code": "switch", "type": "Boolean", "values": "{}" }, { "name": "Switch 1", "desc": "Switch 1", "code": "switch_1", "type": "Boolean", "values": "{}" }, { "name": "Switch 2", "desc": "Switch 2", "code": "switch_2", "type": "Boolean", "values": "{}" }, { "name": "Switch 3", "desc": "Switch 3", "code": "switch_3", "type": "Boolean", "values": "{}" }, { "name": "Switch 4", "desc": "Switch 4", "code": "switch_4", "type": "Boolean", "values": "{}" }, { "name": "Switch 5", "desc": "Switch 5", "code": "switch_5", "type": "Boolean", "values": "{}" }, { "name": "Switch 6", "desc": "Switch 6", "code": "switch_6", "type": "Boolean", "values": "{}" }, { "name": "The countdown of switch 1", "desc": "The countdown of switch 1", "code": "countdown_1", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "The countdown of switch 2", "desc": "The countdown of switch 2", "code": "countdown_2", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "The countdown of switch 3", "desc": "The countdown of switch 3", "code": "countdown_3", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "The countdown of switch 4", "desc": "The countdown of switch 4", "code": "countdown_4", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "The countdown of switch 5", "desc": "The countdown of switch 5", "code": "countdown_5", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "The countdown of switch 6", "desc": "The countdown of switch 6", "code": "countdown_6", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "The countdown of USB 1", "desc": "The countdown of USB 1", "code": "countdown_usb1", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "The countdown of USB 2", "desc": "The countdown of USB 2", "code": "countdown_usb2", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" }, { "name": "USB1 ", "desc": "USB 1", "code": "switch_usb1", "type": "Boolean", "values": "{}" }, { "name": "USB 2", "desc": "USB 2", "code": "switch_usb2", "type": "Boolean", "values": "{}" } ] } }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error
2015 This category is not supported at present

Get the instruction set by device

API description

Query the functions supported by the device. You can send control by the obtained instructions.

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
device_id String URI Yes Device ID

Return parameter

Parameter name Data type Description
code Integer Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> The returned result.

Description of result

Parameter name Category Description
category String Product category
functions List<function> Instruction set

Description of functions

Parameter name Category Description
code String Instruction
type String Instruction type
values String The range of input parameter values
name String Instruction name
desc String Description

Request example

GET /v1.0/devices/vdevo155XXXX83954683/fucntions

SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN); categoryFunctions = client.getFunctionsByDevId(DEV_ID); System.out.println("Get the function list by device ID: "); System.out.println(JSONObject.toJSONString(categoryFunctions));

Response example

{ "success": true, "t": 1571293776551, "result": { "category": "cz", "functions": [ { "name": "Switch", "desc": "Switch", "code": "switch_1", "type": "Boolean", "values": "{}" }, { "name": "The countdown of switch 1", "desc": "The countdown of switch 1", "code": "countdown_1", "type": "Integer", "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}" } ] } }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code description
500
1106

Get the instruction set by devices

API description

Query the functions supported by the devices List. You can send control by the obtained instructions. support up to 20 devices

API address

GET /v1.0/devices/functions

Request parameter

Parameter name Data type Parameter type Required Description
device_ids String URI Yes Devices List

Return parameter

Parameter name Data type Description
code Integer Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> The returned result.

Description of result

Parameter name Category Description
category String Product category
functions List<function> Instruction set
devices List device Id List

Description of functions

Parameter name Category Description
code String Instruction
type String Instruction type
values String The range of input parameter values
name String Instruction name
desc String Description

Request example

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

SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN); categoryFunctions = client.getFunctionsByDevsList(DEV_ID); System.out.println("Get the function list by devices List: "); System.out.println(JSONObject.toJSONString(categoryFunctions));

Response example

{ "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 }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code description
500
1106

Get the specifications and properties of the device, including the instruction set and status set

API description

This interface is used to get the instruction set and status set supported by the device according to the device ID.

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
device_id String URI Yes Device ID

Return parameter

Parameter name Data type Description
code Integer Error Code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> The returned result.

Description of result

Parameter name Category Description
category String Product category
functions List<functions> Instruction set
status List<status> Status set

Description of functions

Parameter name Category Description
code String command
type String Type
values String The range of parameter values

Description of status

Parameter name Category Description
code String status code
type String Type
values String The range of parameter values

Request example

GET /v1.0/devices/vdevoXXXXXXXXXXXXXXX/specifications

SDK example

N/A

Return parameter

{ "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}}" } ] } }

Send instructions to the device

API description

This interface is used to send one or more obtained instruction sets. Whether instruction sets can be sent simultaneously depends on the product.

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
device_id String URI Yes Device ID
commands Object body Yes Command set

Return parameter

Parameter name Data type Description
code Integer Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Boolean Determine whether the request succeeded or not.

Request example

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

SDK example

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("Send device control instructions: "); System.out.println(isSuccess);

Response example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error
2008 Instruction not supported. Confirm whether the instruction or value is correct

Get the latest device status

API description

Get the latest device status by the device ID

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
device_id String URI Yes Device ID

Return parameter

Parameter name Data type Description
code Integer Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Boolean Determine whether the request succeeded or not.

Request example

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

SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN); List<Status> deviceStatus= client.getDeviceStatus(DEV_ID); System.out.println("Get device status: "); System.out.println(JSONObject.toJSONString(deviceStatus));

Response example

{ "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}" } ] }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error