Device Query
Last Updated on : 2023-01-12 07:14:57download
Device management APIs
| Request method | API | Description |
|---|---|---|
| GET | /v1.0/iot-02/building/device/secondary-menus | Query the level-2 menu |
| GET | /v1.0/iot-02/building/devices | Get the device list |
| GET | /v1.0/iot-02/building/device-running-detail | Get device running details |
| GET | /v1.0/iot-02/building/device-detail | Get device details |
| GET | /v1.0/iot-02/building/device/tendency-types | Get the indicator list of the trend chart supported by the devices |
| GET | /v1.0/iot-02/building/device/tendency | Get the trend chart of the specified indicator |
| POST | /v1.0/iot-02/building/device/actions/update-name | Rename a device |
Query the level-2 menu
Functional description
Query the level-2 menu.
API endpoint
GET /v1.0/iot-02/building/device/secondary-menus
Request parameters
| Parameter | Type | Parameter type | Description | Required |
|---|---|---|---|---|
| projectId | String | body | The project ID. | false |
Return parameters
| Parameter | Type | Description |
|---|---|---|
| code | Integer | The response code. For more information, see the error code section. It is empty if the request is successful. |
| success | Boolean | Indicates whether the operation is successful. Valid values:
|
| msg | String | The message that is returned if the request failed. The response is empty if the request is successful. |
| t | Long | The returned 13-digit timestamp. |
| result | Object | The returned result. |
Description of result
[
{
"code": "String // The category code",
"name": "String // The category name",
"order": "int // The order"
}
]
Sample request
{
"projectId": "1424615984265764***"
}
Sample response
{
"result": [
{
"code": "zm",
"name": "Lighting System",
"order": 1
},
{
"code": "lryxt",
"name": "Cold and Heat Source System",
"order": 2
},
{
"code": "spfxt",
"name": "Air Supply and Exhaust System",
"order": 3
}
],
"success": true,
"t": 1662708298644,
"tid": "8252c477301011edaf4dfa23c521f7ba"
}
Get the device list
Functional description
Get the device list.
API endpoint
GET /v1.0/iot-02/building/devices
Request parameters
| Parameter | Type | Parameter type | Description | Required |
|---|---|---|---|---|
| projectId | String | body | The project ID. | true |
| topCategories | String[] | body | The level-1 categories. | false |
| categories | String[] | body | The level-2 categories. | false |
| categoryCodes | String[] | body | The level-3 categories. | false |
| page | int | body | The total number of returned pages. | false |
| pageSize | int | body | The number of items returned on each page. | false |
| deviceStatus | String[] | body | The list of devices based on the status. | false |
| deviceTypes | int[] | body | The device type. | false |
| roomId | String | body | The room ID. | false |
| deviceName | String | body | The device name. | false |
| online | boolean | body | Indicate the online status of the device. | true |
Return parameters
| Parameter | Type | Description |
|---|---|---|
| code | Integer | The response code. For more information, see the error code section. It is empty if the request is successful. |
| success | Boolean | Indicates whether the operation is successful. Valid values:
|
| msg | String | The message that is returned if the request failed. The response is empty if the request is successful. |
| t | Long | The returned 13-digit timestamp. |
| result | Object | The returned result. |
Description of result
{
"total": "int",
"list": [
{
"deviceSaasId": "String // The unique ID of the SaaS.",
"deviceId": "String // The device ID. Each device ID corresponds with one hardware device. Because the device is re-bound to a new point, the device ID is not unique.",
"deviceName": "String // The device name.",
"deviceType": "String // The device type. For more information, see DeviceTypeEnum.",
"deviceTypeValue": "int // The device type. For more information, see DeviceTypeEnum.",
"topCategory": "String // The major category of the product. For more information, see ProductCategoryEnum.",
"capability": "String // The device capabilities, separated by a slash (/).",
"devicePower": "double // The device power.",
"deviceStatus": "String // The device status. For more information, see DeviceAlarmTypeEnum.",
"alarmDpValue": "String // The data point value of an alert.",
"deviceStatuses": "String[] // The device status. For more information, see AlarmTypeEnum.",
"installTime": "long // The installation time of the device.",
"activeTime": "long // The active time of the device.",
"productId": "String // The device category (product) ID.",
"roomId": "String // The ID of the room to which the device belongs.",
"roomName": "String // The name of the room to which the device belongs.",
"pointId": "String // The ID of the location where the device is deployed.",
"ownerId": "String // The ID of the home group to which the device belongs.",
"switchInfo": [
{
"deviceId": "String // The ID of a smart switch device.",
"dpCode": "String // The DP code of a smart switch device.",
}
],
"properties": [
{
"dpId": "String // The DP ID",
"dpCode": "String // The DP code",
"dpName": "String // The DP name",
"dpValue": "String // The current DP value",
"property": {
"range": "String[] // The value range of the property"
},
"propertyDetail": {},
"mode": "String // The mode such as ro and rw. This feature is added to v1.4.3",
"dpFrom": "String // The DP source"
}
],
"masterGroupJoinStatus": "int // Indicates whether the device has joined the main group. Valid values: 0: no. 1: yes. 2: a non-lighting device that has not joined the main group",
"currentBrightness": "int // The brightness threshold of the room to which the device belongs",
"supportGroup": "boolean // Check whether the device can be grouped",
"switchStatus": "boolean // The switch status",
"switchDpCode": "String // The DP code of the switch",
"colourValue": "String // The color value",
"brightPercentValue": "String // The brightness percentage value",
"pointDeviceType": "int // The device type on the point map",
"switchCount": "int",
"dpFrom": "String",
"devicePurpose": {
"id": "String //id",
"name": "string // The name",
"code": "String //code"
},
"industryPurpose": {
"id": "String //id",
"name": "string // The name",
"code": "String // The code"
},
"x": "String // The x-axis coordinate of the location",
"y": "String // The y-axis coordinate of the location",
"category": "String // The level-2 category of the product",
"categoryCode": "String // The level-3 category of the product",
"vasType": "String // The type of the value-added service"
}
]
}
Sample request
{
"pageSize": "The number of items to be returned on each page",
"online": "Indicates the online status of the device",
"categories": "The level-2 categories",
"page": "The total number of returned pages",
"projectId": "The project ID",
"topCategories": "The level-1 categories",
"categoryCodes": "The level-3 categories",
"deviceName": "The device name",
"roomId": "The room ID",
"deviceStatus": "The list of devices based on the status"
}
Sample response
{
"result": {
"list": [
{
"capability": "cable",
"category": "gpsxt",
"category_code": "gpsxt_8c_4",
"current_brightness": 0,
"device_id": "vdevo163722119778504",
"device_name": "Sewage Well (Double-Pump)-vdevo"
"device_power": 0,
"device_saas_id": "sa32108759772376064",
"device_status": "normal",
"device_statuses": [
"normal"
],
"device_type": "other",
"device_type_value": -1,
"install_time": 1637221198107,
"master_group_join_status": 2,
"owner_id": "38696291",
"point_id": "1496296555412570121",
"product_id": "khmasinj4tbc3qen",
"properties": [
{
"dp_code": "pump",
"dp_id": "1",
"dp_name": "Water Pump Switch 1",
"dp_value": "false",
"mode": "rw",
"property": {
"range": []
},
"property_detail": {
"type": "bool"
}
},
{
"dp_code": "fault",
"dp_id": "7",
"dp_name": "Fault Alert of Sewage Well",
"dp_value": "0",
"mode": "ro",
"property": {
"range": []
},
"property_detail": {
"label": [
"fault",
"pump_alarm_1",
"pump_alarm_2",
"water_low",
"water_low_max",
"water_high",
"water_high_max"
],
"maxlen": 7,
"type": "bitmap"
}
}
],
"room_id": "1424637504585277440",
"room_name": "Floor 8",
"switch_dp_code": "switch",
"switch_info": [],
"switch_status": true,
"top_category": "qt"
} ],
"total": 9
},
"success": true,
"t": 1662708352045,
"tid": "a22a2a8b301011edaf4dfa23c521f7ba"
}
Get device running details
Functional description
Get the running details of devices.
API endpoint
GET /v1.0/iot-02/building/device-running-detail
Request parameters
| Parameter | Type | Parameter type | Description | Required |
|---|---|---|---|---|
| projectId | String | body | The project ID. | false |
| deviceSaasId | String | body | The device ID. | false |
Return parameters
| Parameter | Type | Description |
|---|---|---|
| code | Integer | The response code. For more information, see the error code section. It is empty if the request is successful. |
| success | Boolean | Indicates whether the operation is successful. Valid values:
|
| msg | String | The message that is returned if the request failed. The response is empty if the request is successful. |
| t | Long | The returned 13-digit timestamp. |
| result | Object | The returned result. |
Description of result
{
"device": {
"deviceSaasId": "String // The unique ID of the SaaS.",
"deviceId": "String // The device ID. Each device ID corresponds with one hardware device. Because the device is re-bound to a new point, the device ID is not unique.",
"deviceName": "String // The device name.",
"deviceType": "String // The device type. For more information, see DeviceTypeEnum.",
"deviceTypeValue": "int // The device type. For more information, see DeviceTypeEnum.",
"topCategory": "String // The major category of the product. For more information, see ProductCategoryEnum.",
"capability": "String // The device capabilities, separated by a slash (/).",
"devicePower": "double // The device power.",
"deviceStatus": "String // The device status. For more information, see DeviceAlarmTypeEnum.",
"alarmDpValue": "String // The data point value of an alert.",
"deviceStatuses": "String[] // The device status. For more information, see AlarmTypeEnum.",
"installTime": "long // The installation time of the device.",
"activeTime": "long // The active time of the device.",
"productId": "String // The device category (product) ID.",
"roomId": "String // The ID of the room to which the device belongs.",
"roomName": "String // The name of the room to which the device belongs.",
"pointId": "String // The ID of the location where the device is deployed.",
"ownerId": "String // The ID of the home group to which the device belongs.",
"switchInfo": [
{
"deviceId": "String // The ID of a smart switch device.",
"dpCode": "String // The DP code of a smart switch device.",
}
],
"properties": [
{
"dpId": "String // The DP ID",
"dpCode": "String // The DP code",
"dpName": "String // The DP name",
"dpValue": "String // The current DP value",
"property": {
"range": "String[] // The value range of the property"
},
"propertyDetail": {},
"mode": "String // The mode such as ro and rw. This feature is added to v1.4.3",
"dpFrom": "String // The DP source"
}
],
"masterGroupJoinStatus": "int // Indicates whether the device has joined the main group. Valid values: 0: no. 1: yes. 2: a non-lighting device that has not joined the main group",
"currentBrightness": "int // The brightness threshold of the room to which the device belongs",
"supportGroup": "boolean // Check whether the device can be grouped",
"switchStatus": "boolean // The switch status",
"switchDpCode": "String // The DP code of the switch",
"colourValue": "String // The color value",
"brightPercentValue": "String // The brightness percentage value",
"pointDeviceType": "int // The device type on the point map",
"switchCount": "int",
"dpFrom": "String",
"devicePurpose": {
"id": "String //id",
"name": "string // The name",
"code": "String //code"
},
"industryPurpose": {
"id": "String //id",
"name": "string // The name",
"code": "String // The code"
},
"x": "String // The x-axis coordinate of the location",
"y": "String // The y-axis coordinate of the location",
"category": "String // The level-2 category of the product",
"categoryCode": "String // The level-3 category of the product",
"vasType": "String // The type of the value-added service"
},
"operationData": {
"cumulates": [
{
"dpId": "String // The DP ID",
"dpCode": "String // The DP code",
"dpName": "String // The DP name",
"needClean": "boolean // Indicates whether to clear the data",
"dpValue": "String // The DP value",
"unit": "String // The unit",
"value": {
"cumulateType": "String // The type of an accumulated value",
"cumulateName": "String // The name of an accumulated value",
"cumulateValue": "String // The accumulated value",
"unit": "String // The unit, such as hour"
}
}
],
"tendency": {
"dpId": "String // The DP ID",
"dpCode": "String // The DP code",
"dpName": "String // The DP name",
"unit": "String // The unit",
"values": [
{
"timestamp": "String // The timestamp",
"index": "int // The index",
"value": "String // The DP value",
"unit": "String // The unit"
}
]
}
}
}
Sample request
{
"projectId":"1424615984265764***",
"deviceSaasId":"sa32108760059423***"
}
Sample response
{
"result": {
"device": {
"category": "ktxt",
"category_code": "ktxt_8c_2",
"current_brightness": 0,
"device_id": "vdevo163722119881***",
"device_name": "Device A",
"device_power": 0,
"device_saas_id": "sa32108760059423***",
"device_status": "normal",
"device_statuses": [
"normal"
],
"device_type": "other",
"device_type_value": -1,
"install_time": 1637221199201,
"owner_id": "38696291",
"point_device_type": -1,
"point_id": "1554371132805677059",
"product_id": "ucd1j2d6masys2jq",
"properties": [
],
"room_id": "1424637349790294016",
"switch_dp_code": "switch",
"switch_info": [],
"switch_status": true,
"top_category": "qt"
},
"operation_data": {
"cumulates": [
{
"dp_code": "runtime_today",
"dp_name": "Today's Runtime",
"dp_value": "15.57",
"need_clean": false,
"unit": "h"
},
{
"dp_code": "runtime_all",
"dp_name": "Total Runtime",
"dp_value": "3046.60",
"need_clean": false,
"unit": "h"
},
{
"dp_code": "first_filter_switch",
"dp_name": "Total Usage Duration of Primary Filter",
"dp_value": "0.00",
"need_clean": true,
"unit": "h"
},
{
"dp_code": "fan_filter_switch",
"dp_name": "Total Usage Duration of Fan Filter",
"dp_value": "0.00",
"need_clean": true,
"unit": "h"
}
],
"tendency": {
"dp_id": "null",
"unit": "",
"values": [
{
"index": 10,
"timestamp": "2022-09-09 10:00",
"value": "0.00"
},
{
"index": 1,
"timestamp": "2022-09-09 01:00",
"value": "0.00"
},
{
"index": 12,
"timestamp": "2022-09-09 12:00",
"value": "0.00"
},
{
"index": 0,
"timestamp": "2022-09-09 00:00",
"value": "0.00"
},
{
"index": 11,
"timestamp": "2022-09-09 11:00",
"value": "0.00"
},
{
"index": 3,
"timestamp": "2022-09-09 03:00",
"value": "0.00"
},
{
"index": 14,
"timestamp": "2022-09-09 14:00",
"value": "0.00"
},
{
"index": 2,
"timestamp": "2022-09-09 02:00",
"value": "0.00"
},
{
"index": 13,
"timestamp": "2022-09-09 13:00",
"value": "0.00"
}
]
}
}
},
"success": true,
"t": 1662708591072,
"tid": "308b5c71301111edaf4dfa23c521f7ba"
}
Get device details
Functional description
Get the details of a single device.
API endpoint
GET /v1.0/iot-02/building/device-detail
Request parameters
| Parameter | Type | Parameter type | Description | Required |
|---|---|---|---|---|
| projectId | String | body | The project ID. | false |
| deviceSaasId | String | body | The device ID. | false |
Return parameters
| Parameter | Type | Description |
|---|---|---|
| code | Integer | The response code. For more information, see the error code section. It is empty if the request is successful. |
| success | Boolean | Indicates whether the operation is successful. Valid values:
|
| msg | String | The message that is returned if the request failed. The response is empty if the request is successful. |
| t | Long | The returned 13-digit timestamp. |
| result | Object | The returned result. |
Description of result
Refer to the device list.
Sample request
{
"deviceSaasId": "The device ID",
"projectId": "The project ID"
}
Sample response
Refer to the device list.
Get the indicator list of the trend chart supported by the devices
Functional description
Get the indicator list of the trend chart supported by the devices.
API endpoint
GET /v1.0/iot-02/building/device/tendency-types
Request parameters
| Parameter | Type | Parameter type | Description | Required |
|---|---|---|---|---|
| projectId | String | body | The project ID. | false |
| deviceId | String | body | The device ID. | false |
Return parameters
| Parameter | Type | Description |
|---|---|---|
| code | Integer | The response code. For more information, see the error code section. It is empty if the request is successful. |
| success | Boolean | Indicates whether the operation is successful. Valid values:
|
| msg | String | The message that is returned if the request failed. The response is empty if the request is successful. |
| t | Long | The returned 13-digit timestamp. |
| result | Object | The returned result. |
Description of result
{
"tendencies": [
{
"dpId": "String // The DP ID",
"dpCode": "String // The DP code",
"dpName": "String // The DP name",
"unit": "String // The unit",
"values": [
{
"timestamp": "String // The timestamp",
"index": "int // The index",
"value": "String // The DP value",
"unit": "String // The unit"
}
]
}
]
}
Sample request
{
"projectId":"1424615984265764***",
"deviceId":"vdevo163722119881***"
}
Sample response
{
"result": {
"tendencies": [
{
"dp_code": "fre_conversion_return",
"dp_id": "5",
"dp_name": "Frequency Feedback of Air Blower Frequency Converter",
"unit": "%"
},
{
"dp_code": "switch_state",
"dp_id": "6",
"dp_name": "Running Status of Air Blower",
"unit": ""
},
{
"dp_code": "hum_valve_return",
"dp_id": "9",
"dp_name": "Adjustment Feedback of Humidification Valve",
"unit": "%"
},
{
"dp_code": "water_valve_return",
"dp_id": "11",
"dp_name": "Openness Adjustment Feedback of Water Valve",
"unit": "%"
},
{
"dp_code": "ai_freshair_valve_return",
"dp_id": "13",
"dp_name": "Openness Adjustment Feedback of Fresh Air Valve",
"unit": "%"
},
{
"dp_code": "temp_fresh",
"dp_id": "14",
"dp_name": "Fresh Air Temperature Detection",
"unit": "℃"
},
{
"dp_code": "humidity_fresh",
"dp_id": "15",
"dp_name": "Fresh Air Humidity Detection",
"unit": "%"
},
{
"dp_code": "antifreeze",
"dp_id": "16",
"dp_name": "Anti-freeze Switch Detection",
"unit": ""
},
{
"dp_code": "first_filter_switch",
"dp_id": "17",
"dp_name": "Alert of Primary Filter",
"unit": ""
},
{
"dp_code": "fan_filter_switch",
"dp_id": "18",
"dp_name": "Alert of Fan Filter",
"unit": ""
},
{
"dp_code": "supply_temp",
"dp_id": "20",
"dp_name": "Air Supply Temperature",
"unit": "℃"
},
{
"dp_code": "humidity_supply",
"dp_id": "21",
"dp_name": "Air Supply Humidity",
"unit": "%"
},
{
"dp_code": "ico2_ndoor_value",
"dp_id": "22",
"dp_name": "CO2 Detection",
"unit": "ppm"
},
{
"dp_code": "voc_indoor_value",
"dp_id": "23",
"dp_name": "Indoor VOC",
"unit": "ppm"
},
{
"dp_code": "switch",
"dp_id": "1",
"dp_name": "Switch",
"unit": ""
},
{
"dp_code": "temp_set",
"dp_id": "2",
"dp_name": "Temperature Setting",
"unit": "℃"
},
{
"dp_code": "eco2_set",
"dp_id": "3",
"dp_name": "Setting of CO2 Detection Value",
"unit": "ppm"
},
{
"dp_code": "frequency_conversion",
"dp_id": "4",
"dp_name": "Air Blower Frequency",
"unit": "%"
},
{
"dp_code": "hum_valve_value",
"dp_id": "8",
"dp_name": "Adjustment of Humidification Valve",
"unit": "%"
},
{
"dp_code": "water_valve_value",
"dp_id": "10",
"dp_name": "Openness Adjustment of Water Valve",
"unit": "%"
},
{
"dp_code": "freshair_valve_value",
"dp_id": "12",
"dp_name": "Openness Adjustment of Fresh Air Valve",
"unit": "%"
}
]
},
"success": true,
"t": 1662708811310,
"tid": "b4068ad6301111edaf4dfa23c521f7ba"
}
Get the trend chart of the specified indicator
Functional description
Get the trend chart of the specified indicator of devices.
API endpoint
GET /v1.0/iot-02/building/device/tendency
Request parameters
| Parameter | Type | Parameter type | Description | Required |
|---|---|---|---|---|
| projectId | String | body | The project ID. | false |
| deviceId | String | body | The device ID. | false |
| dpId | String | body | The ID of a data point. | false |
| dpCode | String | body | The code of a data point. | false |
| dpName | String | body | The name of a data point. | false |
Return parameters
| Parameter | Type | Description |
|---|---|---|
| code | Integer | The response code. For more information, see the error code section. It is empty if the request is successful. |
| success | Boolean | Indicates whether the operation is successful. Valid values:
|
| msg | String | The message that is returned if the request failed. The response is empty if the request is successful. |
| t | Long | The returned 13-digit timestamp. |
| result | Object | The returned result. |
Description of result
{
"tendency": {
"dpId": "String // The DP ID",
"dpCode": "String // The DP code",
"dpName": "String // The DP name",
"unit": "String // The unit",
"values": [
{
"timestamp": "String // The timestamp",
"index": "int // The index",
"value": "String // The DP value",
"unit": "String // The unit"
}
]
}
}
Sample request
{
"projectId":"1424615984265764***",
"deviceId":"vdevo163722119881***",
"dpId": "5"
}
Sample response
{
"result": {
"tendency": {
"dp_id": "null",
"unit": "",
"values": [
{
"index": 10,
"timestamp": "2022-09-09 10:00",
"value": "0.00"
},
{
"index": 1,
"timestamp": "2022-09-09 01:00",
"value": "0.00"
},
{
"index": 12,
"timestamp": "2022-09-09 12:00",
"value": "0.00"
},
{
"index": 0,
"timestamp": "2022-09-09 00:00",
"value": "0.00"
},
{
"index": 11,
"timestamp": "2022-09-09 11:00",
"value": "0.00"
},
{
"index": 3,
"timestamp": "2022-09-09 03:00",
"value": "0.00"
},
{
"index": 14,
"timestamp": "2022-09-09 14:00",
"value": "0.00"
},
{
"index": 2,
"timestamp": "2022-09-09 02:00",
"value": "0.00"
},
{
"index": 13,
"timestamp": "2022-09-09 13:00",
"value": "0.00"
},
{
"index": 5,
"timestamp": "2022-09-09 05:00",
"value": "0.00"
},
{
"index": 4,
"timestamp": "2022-09-09 04:00",
"value": "0.00"
},
{
"index": 15,
"timestamp": "2022-09-09 15:00",
"value": "0.00"
},
{
"index": 7,
"timestamp": "2022-09-09 07:00",
"value": "0.00"
},
{
"index": 6,
"timestamp": "2022-09-09 06:00",
"value": "0.00"
},
{
"index": 9,
"timestamp": "2022-09-09 09:00",
"value": "0.00"
},
{
"index": 8,
"timestamp": "2022-09-09 08:00",
"value": "0.00"
}
]
}
},
"success": true,
"t": 1662708871291,
"tid": "d7d20c4c301111edaf4dfa23c521f7ba"
}
Rename a device
Functional description
Rename a device.
API endpoint
POST /v1.0/iot-02/building/device/actions/update-name
Request parameters
| Parameter | Type | Parameter type | Description | Required |
|---|---|---|---|---|
| projectId | String | body | The project ID. | false |
| deviceSaasId | String | body | The value of saasId for a device. |
false |
| deviceName | String | body | The device name. | false |
Return parameters
| Parameter | Type | Description |
|---|---|---|
| code | Integer | The response code. For more information, see the error code section. It is empty if the request is successful. |
| success | Boolean | Indicates whether the operation is successful. Valid values:
|
| msg | String | The message that is returned if the request failed. The response is empty if the request is successful. |
| t | Long | The returned 13-digit timestamp. |
| result | Object | The returned result. |
Description of result
boolean{}
Sample request
{
"projectId":"1424615984265764***",
"deviceSaasId":"sa32108760059423***",
"deviceName": "Device A"
}
Sample response
boolean{}
Error code
The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.
| Error code | Description |
|---|---|
| 500 | A system error has occurred while processing your request. |
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedbackMarketing Cooperation
Business Cooperation
Customer Service
Media Inquiry
© 2024 Tuya Inc.