Cloud Services API ReferenceSmart HomeSmart Home Basic ServiceDevice Control

Device Control

Last Updated on : 2024-01-24 06:04:56download

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/functions/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/functions

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	System error
1106	Illegal permission

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/functions?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	System error
1106	Illegal permission

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

Prev DocNetwork Pairing Management

Next DocDevice Management