Device Management

Last Updated on : 2024-06-05 03:15:10download

Get device list by user ID

API endpoint

action: device.getDeviceList

Request parameter

Parameter name Type Description Required
uid String The user ID assigned by Tuya. Yes

Sample request

{
	"action": "device.getDeviceList",
	"params": {
		"uid": "ay1578921339405Lr3au"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
id String The device ID.
uid String The user ID.
local_key String The secret key.
category String The product category.
product_id String The product ID.
sub Boolean Indicates whether the device is sub-device. Valid values:
  • true: yes.
  • false: no.
uuid String The universally unique identifier (UUID) of a specified device.
owner_id String The ID of the device owner.
online Boolean Indicates whether the device is online.
name String The name of the device.
ip String The IP address of the device.
time_zone String The time zone.
create_time Long The time when the device is first paired.
update_time Long The time when the device status was last updated.
active_time Long The time when the device is last paired.
status List The status of a DP.

Description of status

Parameter name Type Description
code String The identifier of a data point (DP).
value String The value of a DP.

Get device list by app schema

API endpoint

action: device.getListBySchema

Request parameter

Parameter name Type Description Required
schema String The schema of a specified application. Yes
page_no Integer The start page number. This is the first page by default. Yes
page_size Integer The maximum number of entries returned on each page. By default, up to 20 entries can be returned on each page. No

Sample request

{
	"action": "device.getListBySchema",
	"params": {
		"schema": "testApp"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
total Long The total number of entries.
devices List The list of devices.

Description of devices

Parameter name Type Description
id String The device ID.
uid String The user ID.
local_key String The secret key.
category String The product category.
product_id String The product ID.
sub Boolean Indicates whether the device is sub-device. Valid values:
  • true: yes.
  • false: no.
uuid String The UUID of a specified device.
owner_id String The ID of the device owner.
online Boolean Indicates whether the device is online.
name String The name of the device.
ip String The IP address of the device.
time_zone String The time zone.
create_time Long The time when the device is first paired.
update_time Long The time when the device status was last updated.
active_time Long The time when the device is last paired.
status List The status of a DP.

Sample response

{
  "success": true,
  "result": {
  "id": "vdevo153490924188132",
  "uid": "ay1485177979114baBn2",
  "category": "pc",
  "sub": false,
  "uuid": "vdevo153490924188132",
  "online": true,
  "status": [
   {
   "code": "switch_1",
   "value": "false",
   "mode": "rw"
   },
   {
   "code": "countdown_led",
   "value": "0",
   "mode": "rw"
   }
  ],
  "local_key": "aeb4ddbcc34cf26a",
  "product_id": "5T63equBYIDPmGXH",
  "owner_id": "703028"
  }
}

Get device list by product ID

API endpoint

action: device.getListByProduct

Request parameter

Parameter name Type Description Required
product_id String The product ID. Yes
page_no Integer The start page number. This is the first page by default. No
page_size Integer The maximum number of entries returned on each page. By default, up to 20 entries can be returned on each page. No

Sample request

{
	"action": "device.getListByProduct",
	"params": {
		"product_id": "xxxxx"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
total Long The total number of entries.
devices List The list of devices.

Description of devices

Parameter name Type Description
id String The device ID.
uid String The user ID.
local_key String The secret key.
category String The product category.
product_id String The product ID.
sub Boolean Indicates whether the device is sub-device. Valid values:
  • true: yes.
  • false: no.
uuid String The UUID of a specified device.
owner_id String The ID of the device owner.
online Boolean Indicates whether the device is online.
name String The name of the device.
ip String The IP address of the device.
time_zone String The time zone.
create_time Long The time when the device is first paired.
update_time Long The time when the device status was last updated.
active_time Long The time when the device is last paired.
status List The status of a DP.

Sample response

{
  "success": true,
  "result": {
  "id": "vdevo153490924188132",
  "uid": "ay1485177979114baBn2",
  "category": "pc",
  "sub": false,
  "uuid": "vdevo153490924188132",
  "online": true,
  "status": [
   {
   "code": "switch_1",
   "value": "false",
   "mode": "rw"
   },
   {
   "code": "countdown_led",
   "value": "0",
   "mode": "rw"
   }
  ],
  "local_key": "aeb4ddbcc34cf26a",
  "product_id": "5T63equBYIDPmGXH",
  "owner_id": "703028"
  }
}

Get device list by device ID

API endpoint

action: device.getListByIds

Request parameter

Parameter name Type Description Required
device_ids String A list of device IDs. Yes

Sample request

{
	"action": "device.getListByIds",
	"params": {
		"device_ids": "vdevo15xxxx88132,vdevo1xxx188132"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
total Long The total number of entries.
devices List The list of devices.

Description of devices

Parameter name Type Description
id String The device ID.
uid String The user ID.
local_key String The secret key.
category String The product category.
product_id String The product ID.
sub Boolean Indicates whether the device is sub-device. Valid values:
  • true: yes.
  • false: no.
uuid String The UUID of a specified device.
owner_id String The ID of the device owner.
online Boolean Indicates whether the device is online.
name String The name of the device.
ip String The IP address of the device.
time_zone String The time zone.
create_time Long The time when the device is first paired.
update_time Long The time when the device status was last updated.
active_time Long The time when the device is last paired.
status List The status of a DP.

Sample response

{
  "success": true,
  "result": {
  "id": "vdevo153490924188132",
  "uid": "ay1485177979114baBn2",
  "category": "pc",
  "sub": false,
  "uuid": "vdevo153490924188132",
  "online": true,
  "status": [
   {
   "code": "switch_1",
   "value": "false",
   "mode": "rw"
   },
   {
   "code": "countdown_led",
   "value": "0",
   "mode": "rw"
   }
  ],
  "local_key": "aeb4ddbcc34cf26a",
  "product_id": "5T63equBYIDPmGXH",
  "owner_id": "703028"
  }
}

Send instructions to device

API endpoint

action:  device.control

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
commands Object The instruction set. Yes

Sample request

{
	"action": "device.control",
	"params": {
		"device_id": "vdevo158132564936223",
		"commands": [
		{
			"code": "switch_led",
			"value": true
		}
		]
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Boolean Indicates whether the operation is successful.

Get latest device status

API endpoint

action:  device.status

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes

Sample request

{
	"action": "device.status",
	"params": {
		"device_id": "vdevo158346027181013"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Boolean Indicates whether the operation is successful.

Sample response

{
	"result": [{
		"code": "switch_led",
		"value": true
	}, {
		"code": "work_mode",
		"value": "white"
	}, {
		"code": "bright_value_v2",
		"value": 370
	}, {
		"code": "temp_value_v2",
		"value": 216
	}, {
		"code": "scene_data_v2",
		"value": ""
	}, {
		"code": "countdown_1",
		"value": 0
	}, {
		"code": "control_data",
		"value": "{\"bright\":370,\"change_mode\":\"gradient\",\"h\":0,\"s\":0,\"temperature\":216,\"v\":0}"
	}],
	"success": true,
	"t": 1583740617030
}

Get instruction set by category

API endpoint

action:  device.functionsByCategory

Request parameter

Parameter name Type Description Required
category String The name of the target category. Example: kg, cz, and dj. Yes

Sample request

{
	"action": "device.functionsByCategory",
	"params": {
		"category": "dj"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
category String The product category.
functions List The instruction set.

Description of functions

Parameter name Type Description
code String The DP code.
type String The type of DP.
values String The range of DP values.
name String The name of the DP.
desc String The description of the DP.

Sample response

{
  "success": true,
  "t": 1571293457435,
  "result": {
  "category": "kg",
  "functions": [
   {
   "name": "Switch",
   "desc": "The main switch. true: turns all on. false: turns all off.",
   "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": "Countdown of Switch 1",
   "desc": "Countdown of Switch 1",
   "code": "countdown_1",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 2",
   "desc": "Countdown of Switch 2",
   "code": "countdown_2",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 3",
   "desc": "Countdown of Switch 3",
   "code": "countdown_3",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 4",
   "desc": "Countdown of Switch 4",
   "code": "countdown_4",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 5",
   "desc": "Countdown of Switch 5",
   "code": "countdown_5",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 6",
   "desc": "Countdown of Switch 6",
   "code": "countdown_6",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of USB 1",
   "desc": "Countdown of USB 1",
   "code": "countdown_usb1",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of USB 2",
   "desc": "Countdown of USB 2",
   "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": "{}"
   }
  ]
  }
}

Get instruction set supported by device

API endpoint

action:  device.functions

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes

Sample request

{
	"action": "device.functions",
	"params": {
		"device_id": "vdevo158132564936223"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
category String The product category.
functions List The instruction set.

Description of functions

Parameter name Type Description
code String The DP code.
type String The type of DP.
values String The range of DP values.
name String The name of the DP.
desc String The description of the DP.

Sample response

{
    "success": true,
    "t": 1571293457435,
    "result": {
        "category": "kg",
        "functions": [
             {
                "name": "Switch",
                "desc": "The main switch. true: turns all on. false: turns all off.",
                "code": "switch",
                "type": "Boolean",
                "values": "{}"
             },
             {
                "name": "Switch 1",
                "desc": "Switch 1",
                "code": "switch_1",
                "type": "Boolean",
                "values": "{}"
             }
        ]
    }
}

Get instruction set and status set supported by device

API endpoint

action:  device.specifications

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes

Sample request

{
	"action": "device.specifications",
	"params": {
		"device_id": "vdevo158132564936223"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
category String The product category.
functions List The instruction set.
status List The status set.

Description of functions

Parameter name Type Description
code String The DP code.
type String The type of DP.
values String The range of DP values.

Description of status

Parameter name Type Description
code String The status code.
type String The type of DP.
values String The range of DP values.

Sample response

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

Get device details

API description

Query the details of a device, including the properties and latest status of the device.

API endpoint

action:  device.details

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes

Sample request

{
	"action": "device.details",
	"params": {
		"device_id": "vdevo158132564936223"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
id String The device ID.
uid String The user ID.
local_key String The secret key.
category String The product category.
product_id String The product ID.
sub Boolean Indicates whether the device is sub-device. Valid values:
  • true: yes.
  • false: no.
uuid String The UUID of a specified device.
owner_id String The home ID.
online Boolean Indicates whether the device is online.
status Object The status of a DP.

Description of status

Parameter name Type Description
code String The identifier of a DP.
value String The value of a DP.
type String The type of DP.