Overview of Third-Party Industry Device Capabilities

This topic describes how to use the general capabilities of third-party industry devices.

Network topology

1. Devices interact with the Tuya IoT Development Platform through direct connections or edge gateways.
2. The developer cloud requests Tuya’s APIs through HTTPS. For more information, see API Reference.
3. Tuya actively pushes various event data to the developer cloud through Pulsar. For more information, see Message Queue.
4. For more information about the integration of devices across categories, see the integration documents. For example, Smart Access Control Service, Vehicle Services, and Elevator Control Service.

Terms and definitions

Term	Description
Third-party industry device	Third-party industry devices include but are not limited to access control, camera, elevator control, vehicle service, firefighting, perimeter, building control, water meter, and circuit breaker.
Send a command	You can request Tuya’s open APIs to send a command from the cloud to a device.
Device message event	After an event is triggered on the device, the device reports the event to the Tuya IoT Development Platform. And then, the Tuya IoT Development Platform notifies you by using Pulsar messages.
ISV	Independent software vendor that is connected to the Tuya IoT Development Platform.
devId	The ID of a Tuya device. Same as deviceId.
productKey	The product ID of a Tuya device. Same as productId.
productType	The category code of a Tuya device.
SN	The globally unique identifier of a device command in the context session.

API description

Information

API name	API endpoint
Get device details	GET:/v1.0/expand/devices/{device_id}
Get a list of devices	GET:/v1.0/expand/devices

Commands

You can query the execution results of a specified command sent to the device. You can also get the result by Command execution result event.

API name	API endpoint
Query Command Record	GET:/v1.0/expand/cmds/{sn}

Permissions

This API operation is optional. If a device supports video talk capabilities, the following three API operations must be called: sync users, add device permissions, and delete device permissions. For example, if an access control device supports the video talk capabilities, you must create a Tuya developer account, get the user ID, and then grant permissions on the access control device to the user ID to implement the cloud-based video talk feature.

API name	API endpoint
Sync Users	POST: /v1.0/apps/{schema}/user
Add Device Permission	POST:/v1.0/expand/spaces/{device_id}/persons/{person_id}
Delete Device Permissions	DELETE:/v1.0/expand/spaces/{device_id}/persons/{person_id}

Data points

The data points vary depending on the device manufacturers and categories. You can query the supported data points as follows.

API name	API endpoint
Get Data Point List	GET:/v1.0/expand/devices/{device_id}/functions
Get Device Function Pool	GET:/v1.0/expand/devices/{device_id}/function-pool
Modify Data Point	PUT:/v1.0/expand/devices/{device_id}/functions

Device event format

Pairing event

API description

After a Tuya developer account is created, Tuya staff performs device pairing on the premises. You will be notified of pairing results by messages. If the device information changes, you will also be notified based on this event.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is bindUser here.	Yes
devId	String	The ID of a specified Tuya device.	Yes
productKey	String	The product ID (PID).	Yes
ts	Long	The 13-digit timestamp.	Yes
uuid	String	The universally unique identifier (UUID) of a specified device.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter name	Data type	Description	Required
devId	String	The ID of a specified Tuya device.	Yes
uid	String	The ID of a specified developer.	Yes
parentDevId	String	The ID of a specified gateway device.	Yes
ownerId	String	The ID of a specified home group.	Yes
uuid	String	The universally unique identifier (UUID) of a specified device.	Yes
deviceName	String	The name of a specified device.	Yes
productType	String	The category code of a specified Tuya device.	Yes
cid	String	The CID of a specified device.	Yes
projectId	String	The ID of a specified project to which the device belongs.	Yes

Example

{
    "bizCode": "bindUser",
    "bizData": {
        "devId": "6c0f9f75942945886b****",
        "uid": "bay1617693984346****",
        "parentDevId": "6c8508b09c431549fa****",
        "ownerId": "3406****",
        "uuid": "45106581bdee****",
        "deviceName": "Tuya Third-party Industry Device",
        "productType": "wf_znmj",
        "cid": "abc123****",
        "projectId": "abc123****"
    },
    "devId": "6c0f9f75942945886b****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637292810795,
    "uuid": "45106581bdee****"
}

Command execution result event

API description

You will be notified of command execution results by messages.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is cmdIssueResult here.	Yes
devId	String	The ID of a specified Tuya device.	Yes
productKey	String	The product ID (PID).	Yes
ts	Long	The 13-digit timestamp.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter name	Data type	Description	Required
sn	String	The ID of a specified command record.	Yes
processStatus	Integer	The execution status of a command. Valid values: 1: The command is being sent. 2: The command has already been sent. 3: The command is executed successfully. 4: Failed to execute the command.	Yes
message	String	The description of the command execution. In case of a failure, an error message will be returned.	No
happenTime	Long	The 13-digit timestamp when a command is executed.	Yes
dataFlag	Integer	The data flag. Valid values: 1: data sync command. 2: control command.	No
bizId	String	The business ID.	No
cmdBizType	String	The business type of the command.	No
data	String	The returned result.	No

Example

{
    "bizCode": "cmdIssueResult",
    "bizData": {
        "processStatus": 3,
        "data": "{}",
        "dataFlag": 2,
        "sn": 146153748529231****,
        "message": "success",
        "deviceId": "6ce23ee0de009667c0****",
        "happenTime": 1637292665335
    },
    "devId": "6ce23ee0de009667c0****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637292665405
}

Going online event

API description

You will be notified by messages when a device goes online.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is online here.	Yes
devId	String	The ID of a specified Tuya device.	Yes
productKey	String	The product ID (PID).	Yes
ts	Long	The 13-digit timestamp.	Yes
uuid	String	The universally unique identifier (UUID) of a specified device.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter name	Data type	Description	Required
uid	String	The user ID.	Yes
time	Long	The 13-digit timestamp when a device goes online.	Yes

Example

{
    "bizCode": "online",
    "bizData": {
        "uid": "bay161769398434****",
        "time": 1637216002196
    },
    "devId": "6c0b7b2ac7b6c1eb5e****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637216002224,
    "uuid": "4991ffc40430****"
}

Going offline event

API description

You will be notified by messages when a device goes offline.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is offline here.	Yes
devId	String	The ID of a specified Tuya device.	Yes
productKey	String	The product ID (PID).	Yes
ts	Long	The 13-digit timestamp.	Yes
uuid	String	The universally unique identifier (UUID) of a specified device.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter name	Data type	Description	Required
uid	String	The user ID.	Yes
time	Long	The 13-digit timestamp when a device goes offline.	Yes

Example

{
    "bizCode": "offline",
    "bizData": {
        "uid": "bay1617693984346****",
        "time": 1637215931403
    },
    "devId": "6ce23ee0de009667c0****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637215931555,
    "uuid": "a3c7ecc1ada4****"
}

Report device unbinding event

API description

You will be notified when a device is unbound.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is delete here.	Yes
devId	String	The ID of a specified Tuya device.	Yes
productKey	String	The product ID (PID).	Yes
ts	Long	The 13-digit timestamp.	Yes
uuid	String	The universally unique identifier (UUID) of a specified device.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter name	Data type	Description	Required
devId	String	The device ID.	Yes
uid	String	The user ID.	Yes
ownerId	String	The ID of a specified home group.	Yes

Example

{
    "bizCode": "delete",
    "bizData": {
        "devId": "6c0f9f75942945886b****",
        "uid": "bay1617693984346****",
        "ownerId": "3406****"
    },
    "devId": "6c0f9f75942945886b****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637303082416,
    "uuid": "45106581bdee****"
}

Report device message event

API description

You will be notified when a device event is reported. For more information about the specified event messages of devices across categories, see the integration documents.

Parameters

Parameter name	Data type	Description	Required
dataId	String	The unique identifier of the data.	Yes
devId	String	The ID of a specified Tuya device.	Yes
productKey	String	The product ID (PID).	Yes
status	List	The object of device messages.	Yes

Description of status

Parameter name	Data type	Description	Required
code	String	The code of a specified device event.	Yes
t	Long	The timestamp.	Yes
value	String	The content of a specified device event.	Yes

Example

{
  "dataId": "AAXRV4BrtW9BRB9A2JYW****",
  "devId": "6cac703763f7653deb8****",
  "productKey": "iyktmr3hd2qp****",
  "status": [
    {
      "126": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}",
      "code": "event_pass",
      "t": 1637548630455,
      "value": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}"
    }
  ]
}

Device event format v1.0

Device event messages are compatible with v1.0 format. If you want to subscribe to the v1.0 format, please contact Tuya’s staff. For more information, see Message Queue.

Integration procedure

Sample code of receiving messages

String url = "";
String accessId = "";
String accessKey = "";
MqConsumer mqConsumer = MqConsumer.build()
    .serviceUrl(url)
    .accessId(accessId)
    .accessKey(accessKey)
    .maxRedeliverCount(3)
    .messageListener(new MqConsumer.IMessageListener() {
     @Override
     public void onMessageArrived(Message message) throws Exception {
        String content = new String(message.getData());
     }
    });
mqConsumer.start();

Description of content

Parameter name	Data type	Description	Required
encryptPayload	String	The encrypted data.	Yes
encryptType	String	The data encryption type. Default value: aes_ecb.	Yes
sign	String	The signature.	Yes
t	Long	The 13-digit timestamp.	Yes
v	Long	The version number of the data. Default value: 1.0.	Yes

Data sample of content

{
  "encryptPayload": "Cl6rUppuwmjUJZRZNdwJdfs2NpGyqYSyVlXjgdiLLbeb6/UvWSZa972jFl+6q3Q8QyNZnOluC9VQeUh7BosdD7p/NcJYLYDknFPqpTD1R7sIg0HZgag3W+YCQtL8b+SKE5UwDEWg0toy1mCmTg5qyrYad+uGWLY98yrT9et/ePj/7FP9g9zGOHAmnytrcCS7a/4j5bARkROHiDzYnQt1lA==",
  "encryptType": "aes_ecb",
  "sign": "3f2b0dbe19119806f8f7f884653dca5d",
  "t": 1611221228800,
  "v": "1.0"
}

Sample of decrypted data

For more information about signature verification and decryption process, see Data Signature.

Decrypt encryptPayload, and the result looks like this:

{
  "data": "{\"deviceId\":\"6c280fdff93c18e45ben6i\",\"status\":1,\"happenTime\":1611221228433}",
  "bizCode": "edge_device",
  "eventType": "dev_online_status"
}

V1.0 messages only define the data format of decrypted encryptPayload.

Pairing event

API description

After a Tuya developer account is created, Tuya staff performs device pairing on the premises. You will be notified of pairing results by messages. If the device information changes, you will also be notified based on this event.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is edge_device here.	Yes
eventType	String	The type of a specified event. Default value: activate_device.	Yes
deviceId	String	The ID of a specified Tuya device.	Yes
cid	String	The unique identifier of a specified device, such as device SN, MAC address, or IMEI.	Yes
gatewayId	Integer	The ID of a specified gateway device.	No
projectId	String	The project ID. You can customize the project ID during device pairing.	Yes
uid	String	The ID of a specified developer.	Yes
deviceName	String	The name of a specified device.	Yes
deviceIp	Long	The IP address of a specified device.	Yes
macAddress	String	The MAC address of a specified device.	No
supplierCode	String	The code of a specified supplier.	Yes
productType	String	The category of a specified product.	Yes
productId	String	The product ID (PID).	Yes
installLocation	String	The location where the device is installed.	No
extendData	String	The extension data in the JSON format.	No
activeStatus	Integer	Indicates whether a device is activated. Valid values: 0: The device is not activated. 1: The device is activated.	Yes
onlineStatus	Integer	Indicates whether a device is online. Valid values: 0: The device is offline. 1: The device is online.	Yes
createTime	Long	The time when a device is created.	Yes

Example

{
  "bizCode": "edge_device",
  "eventType": "activate_device",
  "data": "{\"cid\": \"120759236001223****\",\"deviceId\":
  \"002dj00118fe34d9****\",\"deviceName\": \"East Entrance Access Control\",\"deviceIp\":
  \"192.168.16.111\",\"macAddress\": \"00-55-52-24-01-65\",\"productType\":
  \"wf_znmj\",\"productId\": \"0vbrvxonnjsxi****\",\"supplierCode\":
  \"tuya\",\"installLocation\": \"East Entrance\",\"extendData\":
  \"\",\"activeStatus\": 1,\"onlineStatus\": 1,\"createTime\": 1591693362843}"
}

Command execution result event

API description

You will be notified of command execution results by messages.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is edge_device here.	Yes
eventType	String	The type of a specified event. Default value: cmd_issue_result.	Yes
deviceId	String	The ID of a specified Tuya device.	Yes
sn	String	The ID of a specified command record.	Yes
processStatus	Integer	The execution status of a command. Valid values: 1: The command is being sent. 2: The command has already been sent. 3: The command is executed successfully. 4: Failed to execute the command. 5: The command status is unknown.	Yes
message	String	The description about the command execution. In case of a failure, an error message will be returned.	No
happenTime	Long	The 13-digit timestamp when a command is executed.	Yes

Example

{
  "bizCode": "edge_device",
  "eventType": "cmd_issue_result",
  "data": "{\"sn\": \"1212581947449081856\",\"deviceId\": \"002dj00118fe34d9**** \",\"processStatus\":2,\"message\":\"The command is sent\",\"happenTime\":1591693362843}"
}

Going online/offline event

API description

You will be notified by messages when a device goes online or offline.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is edge_device here.	Yes
eventType	String	The type of a specified event. Default value: dev_online_status.	Yes
deviceId	String	The ID of a specified Tuya device.	Yes
status	Integer	The device status. Valid values: 0: The device is offline. 1: The device is online.	Yes
happenTime	Long	The 13-digit timestamp when a device goes online or offline.	Yes

Example

{
  "bizCode": "edge_device",
  "eventType": "dev_online_status",
  "data": "{\"deviceId\": \"002dj00118fe34d9****\",\"status\": 1,\"happenTime\": 1591693362843}"
}

Report device unbinding event

API description
You will be notified when a device is unbound.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is edge_device here.	Yes
eventType	String	The type of a specified event. Default value: edge_report_data.	Yes
mode	String	The mode of a specified event. The value device-unbind indicates device unbinding.	Yes
deviceId	String	The ID of a specified Tuya device.	Yes

Example

{
  "data": "{\"mode\":\"device-unbind\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\"}",
  "bizCode": "edge_device",
  "eventType": "edge_report_data"
}

Report gateway unbinding event

API description

You will be notified when a gateway is unbound.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. The value is edge_device here.	Yes
eventType	String	The type of a specified event. Default value: edge_report_data.	Yes
mode	String	The mode of a specified event. The value gateway-unbind indicates gateway unbinding.	Yes
deviceId	String	The ID of a specified Tuya device.	Yes

Example

{
  "data": "{\"mode\":\"gateway-unbind\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\"}",
  "bizCode": "edge_device",
  "eventType": "edge_report_data"
}