Tuya Developer PlatformSmart IndustriesCommercial LightingValue-Added ServiceDevice In-situ Replacement

Device In-situ Replacement

Last Updated on : 2023-04-28 02:40:12download

Device in-situ replacement is a value-added service launched by Tuya’s commercial lighting system, helping you copy the configurations of a faulty device to a new device with one click. Device in-situ replacement allows you to easily replace gateways and sub-devices at lower repair costs. This way, you do not need to add the new device respectively to the existing group, scenes, and automated tasks.

API list

Request method	API	Description
GET	/v1.0/illumination/devices/{devId}/replaceability	Check the support for in-situ replacement
GET	/v1.0/illumination/devices/{devId}/replacements	Get a list of available devices under the project
POST	/v1.0/illumination/device/replace/record	Add a task of device in-situ replacement
POST	/v1.0/illumination/device/replace/record/retry	Retry a task of device in-situ replacement
GET	/v1.0/illumination/device/replace/records	Query records of device in-situ replacement
POST	/v1.0/illumination/device/gateway/copy	Copy a gateway
GET	/v1.0/illumination/devices/gateway-copy-info/{taskId}	Get the result of copying a gateway

Check the support for in-situ replacement

Functional description

Check whether a device supports in-situ replacement.

API endpoint

GET /v1.0/illumination/devices/{devId}/replaceability

Request parameters

Parameter	Type	Parameter type	Description	Required
devId	String	url	The device ID.	true

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error codes section. It is empty when the operation is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the operation failed. It is empty when the operation is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

/v1.0/illumination/devices/6cf53c7c494801bf72acch/replaceability

Sample response

{
    "result": true,
    "success": true,
    "t": 1681959047638,
    "tid": "26d4d5c8df2611edad582a6c806b923a"
}

Get a list of available devices under the project

Functional description

Get a list of devices under the project that can replace this device.

API endpoint

GET /v1.0/illumination/devices/{devId}/replacements

Request parameters

Parameter	Type	Parameter type	Description	Required
page	int	body	The page number.	false
pageSize	int	body	The number of entries to be returned per page.	false
devId	String	url	The device ID.	false
replaceType	int	body	The replacement type. Valid values: `1`: standard device `2`: gateway sub-device `3`: remote sub-device	false
gatewayId	String	body	The gateway ID.	false
roomId	String	body	The ID of the specified space.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error codes section. It is empty when the operation is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the operation failed. It is empty when the operation is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

{
  "total": "int",
  "list": [
    {
      "device_id": "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.",
      "device_name": "String // The device name.",
      "device_type": "String // The device type. For more information, see DeviceTypeEnum.",
      "device_type_value": "int // The value of a device type. For more information, see DeviceTypeEnum.",
      "top_category": "String // The major category of a product. For more information, see the type description of ProductCategoryEnum.
      "capability": "String // The device capabilities, separated with slashes (/).",
      "device_power": "double // The device power.",
      "device_status": "String // The device status. For more information, see DeviceAlarmTypeEnum.",
      "device_statuses": "String[] // The device status. For more information, see AlarmTypeEnum.",
      "install_time": "long // The installation time of a device.",
      "active_time": "long // The active time of a device.",
      "product_id": "String // The device category (product) ID.",
      "project_id": "String // The project ID.",
      "room_id": "String // The ID of the room to which a device belongs.",
      "room_name": "String // The name of the room to which a device belongs.",
      "point_id": "String // The ID of the location where a device is deployed.",
      "owner_id": "String // The ID of the home group to which a device belongs.",
      "category": "String // The level-2 category of a product.",
      "icon_url": "String // The icon of a device.",
      "uuid": "String // The universally unique identifier (UUID) of a device.",
      "category_code": "String // The level-3 category of a product",
      "uid": "String // The user ID.",
      "model": "String // The product model.",
      "device_mac": "String // The MAC address.",
      "is_online": "boolean // Indicates whether a device is online.",
      "space_name": "String // The space."
    }
  ]
}

Sample request

{
  "devId":"6cf53c7c494801bf72acch",
  "pageSize": "100",
  "replaceType": "1",
  "page": "1"
}

Sample response

{
    "result": {
        "list": [
            {
                "capability": "bluetooth/wifi",
                "category": "dj",
                "categoryCode": "wf_ble_dj",
                "currentBrightness": 0,
                "deviceId": "6c2757f2ec27f1dc93gclt",
                "deviceMac": "",
                "deviceName": "Test Device 2",
                "devicePower": 0,
                "deviceSaasId": "sa43836406370314240",
                "deviceType": "0",
                "id": 2114387,
                "online": true,
                "ownerId": "59457509",
                "pointId": "1648880505556303873",
                "productId": "naw6qa0nhwyfxzkt",
                "projectId": "1541976932755718144",
                "roomId": "1559640253681721",
                "topCategory": "zm",
                "uuid": "40505411da38feb1"
            }
        ],
        "total": 1
    },
    "success": true,
    "t": 1681960641878,
    "tid": "dd394ba8df2911edad582a6c806b923a"
}

Add a task of device in-situ replacement

Functional description

Add a task of replacing a device in situ.

API endpoint

POST /v1.0/illumination/device/replace/record

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
oldRoomId	String	body	The ID of the space where the device to be replaced is deployed.	false
oldDeviceId	String	body	The ID of the device to be replaced.	false
newDeviceId	String	body	The ID of the new device.	false
newRoomId	String	body	The ID of the space where the new device is deployed.	false
replaceType	int	body	The replacement type. Valid values: `1`: Replace a standard device `2`: Replace a gateway `3`: Replace a remote gateway	false
taskId	String	body	The task ID.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error codes section. It is empty when the operation is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the operation failed. It is empty when the operation is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

String{}

Sample request

{
  "oldDeviceId": "6cf53c7c494801bf72acch",
  "oldRoomId": "1559640253681721",
  "newDeviceId": "6c2757f2ec27f1dc93gclt",
  "newRoomId": "1559640253681721",
  "replaceType": "1",
  "projectId": "1541976932755718144"
}

Sample response

{
    "result": "1648890751519637504",
    "success": true,
    "t": 1681961165110,
    "tid": "14999fdcdf2b11edad582a6c806b923a"
}

Retry a task of device in-situ replacement

Functional description

You can retry the device replacement task after you fail to replace the device in situ.

API endpoint

POST /v1.0/illumination/device/replace/record/retry

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
roomId	String	body	The ID of the space where the device to be replaced is deployed.	false
recordId	String	body	The ID of the specified replacement record.	false
taskIds	String[]	body	The subtask ID. When the value is empty, all subtasks are retried by default.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error codes section. It is empty when the operation is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the operation failed. It is empty when the operation is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

{
  "recordId": "1648890751519637504",
  "projectId": "1541976932755718144",
  "roomId": "1559640253681721"
}

Sample response

{
  "success": true,
  "t": 1573441137,
  "result": false
}

Query records of device in-situ replacement

Functional description

Query the records of device in-situ replacement under the specified project.

API endpoint

GET /v1.0/illumination/device/replace/records

Request parameters

Parameter	Type	Parameter type	Description	Required
page	int	body	The page number.	false
pageSize	int	body	The number of entries to be returned per page.	false
projectId	String	body	The project ID.	false
roomIds	String[]	body	The room ID.	false
categories	String[]	body	The level-1 category.	false
recordStatuses	int[]	body	The current status of the specified record.	false
lang	String	body	The language.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error codes section. It is empty when the operation is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the operation failed. It is empty when the operation is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

{
  "total": "int",
  "list": [
    {
      "record_id": "String // The ID of a device replacement record.",
      "space_name": "String // The space name."
      "full_space_name": "String // The full name of a space, displayed when the mouse cursor hovers over it.",
      "old_device": {
        "category": "String // The level-1 device category.",
        "category_name": "String // The category name.",
        "device_id": "String // The device ID.",
        "device_name": "String // The device name.",
        "online": "boolean // Indicates whether a device is online.",
        "removed": "boolean // Indicates whether a device is removed.",
        "room_id": "String // The ID of the room to which a device belongs.",
        "space_name": "String // The location or space name."
        "icon_url": "String // The URL of an image.",
      },
      "new_device": {
        "category": "String // The level-1 device category.",
        "category_name": "String // The category name.",
        "device_id": "String // The device ID.",
        "device_name": "String // The device name.",
        "online": "boolean // Indicates whether a device is online.",
        "removed": "boolean // Indicates whether a device is removed.",
        "room_id": "String // The ID of the room to which a device belongs.",
        "space_name": "String // The location or space name."
        "icon_url": "String // The URL of an image.",
      },
      "record_status": "int // The record status. 0: failed, 1: successful, 2: partially successful, 3: executing.",
      "complete_time": "long // The completion time.",
      "progress_node": "int // The progress stage. 1: Copy a gateway, 2: Replace a device.",
      "delete_status": "boolean // Indicates whether a faulty device is deleted. The value is deleted or not deleted.",
      "local_type": "int // 0: default, 1: local, 2: remote.",
      "replace_type": "int //@see com.tuya.zhurong.biz.enums.ReplaceType",
      "old_gateway_name": "String // The gateway information of a faulty device.",
      "new_gateway_name": "String // The gateway information of a new device.",
      "is_allow_retry": "boolean // Indicates whether retry is allowed.",
      "gmt_create": "long // The creation time."
    }
  ]
}

Sample request

{
  "pageSize": "100",
  "page": "1",
  "projectId": "1541976932755718144"
}

Sample response

{
    "result": {
        "list": [
            {
                "completeTime": 1681961164747,
                "deleteStatus": false,
                "gmtCreate": 1681961164747,
                "newDevice": {
                    "category": "zm",
                    "deviceId": "6c2757f2ec27f1dc93gclt",
                    "deviceName": "Test Device 2",
                    "roomId": "1559640253681721"
                },
                "oldDevice": {
                    "category": "zm",
                    "deviceId": "6cf53c7c494801bf72acch",
                    "deviceName": "Test Device 1",
                    "iconUrl": "https://images.tuyacn.com/smart/icon/bay1606528390981YiDN/4199481d5d32874980313cb387df095b.png",
                    "roomId": "1559640253681721",
                    "spaceName": "Test Space"
                },
                "progressNode": 2,
                "recordId": "1648890751519637504",
                "recordStatus": 2,
                "replaceType": 1,
                "spaceName": "Test Space",
                "subTasks": [
                    {
                        "relativeName": "",
                        "taskCode": "",
                        "taskId": "1648890752782123008",
                        "taskMessage": "",
                        "taskName": "Replace Basic Device Information",
                        "taskStatus": 1,
                        "taskType": "6"
                    }
                ]
            }
        ],
        "total": 1
    },
    "success": true,
    "t": 1681961893353,
    "tid": "c72adc06df2c11edad582a6c806b923a"
}

Copy a gateway

Functional description

Copy and put a device under a new gateway.

API endpoint

POST /v1.0/illumination/device/gateway/copy

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
oldDeviceId	String	body	The ID of the device to be replaced.	false
newGatewayId	String	body	The ID of the new gateway.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error codes section. It is empty when the operation is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the operation failed. It is empty when the operation is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

String{}

Sample request

{
  "newGatewayId": "6cb42aa94f3db52884w6ix",
  "projectId": "1541976932755718144",
  "oldDeviceId": "6c4794741ec4f88c993ast"
}

Sample response

{
  "success": true,
  "t": 1573441137,
  "result": "juJxURqDkZ"
}

Get the result of copying a gateway

Functional description

Get the result of copying a gateway.

API endpoint

GET /v1.0/illumination/devices/gateway-copy-info/{taskId}

Request parameters

Parameter	Type	Parameter type	Description	Required
taskId	String	url	The task ID.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error codes section. It is empty when the operation is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the operation failed. It is empty when the operation is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

{
  "old_device": {
    "category": "String // The level-1 device category.",
    "category_name": "String // The category name.",
    "device_id": "String // The device ID.",
    "device_name": "String // The device name.",
    "online": "boolean // Indicates whether a device is online.",
    "removed": "boolean // Indicates whether a device is removed.",
    "room_id": "String // The ID of the room to which a device belongs.",
    "space_name": "String // The location/space name."
    "icon_url": "String // The URL of an image.",
  },
  "new_device": {
    "category": "String // The level-1 device category.",
    "category_name": "String // The category name.",
    "device_id": "String // The device ID.",
    "device_name": "String // The device name.",
    "online": "boolean // Indicates whether a device is online.",
    "removed": "boolean // Indicates whether a device is removed.",
    "room_id": "String // The ID of the room to which a device belongs.",
    "space_name": "String // The location/space name."
    "icon_url": "String // The URL of an image.",
  },
  "task_id": "String",
  "record_id": "String"
}

Sample request

{
  "taskId": ""
}

Sample response

{
  "success": true,
  "t": 1573441137,
  "result": {
    "old_device": {
      "category": "wg2",
      "device_id": "6dx43c8f321821bg71avvb",
      "device_name": "Gateway Test",
      "online": true,
      "room_id": "1559640253681721",
      "space_name": "Test Space",
      "icon_url": "https://images.tuyacn.com/smart/icon/ay1567409560124sa2O6/9c782c7782c6f4f3e3d989554ae6d49c.png"
    },
    "new_device": {
      "category": "wg2",
      "deviceId": "6cf53c7c494801bf72acch",
      "deviceName": "Gateway Test 2",
      "iconUrl": "https://images.tuyacn.com/smart/icon/ay1567409560124sa2O6/9c782c7782c6f4f3e3d989554ae6d49c.png",
      "roomId": "1559640253681721",
      "spaceName": "Test Space"
      "online": true,
      "space_name": "Test Space",
    },
    "task_id": "xxxx",
    "record_id": "xxxxx"
  }
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	The error message is returned because you are unauthorized to make the API request.

Prev DocAI Adaptive Sensing

Next DocSolution: Smart Classroom