Overview of Third-Party Industry Device Capabilities

Last Updated on : 2023-06-15 05:22:17

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

Network topology

Overview of Third-Party Industry Device Capabilities

  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();

content refers to the content of the message received by the Pulsar client.

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