Integration with Firefighting Devices

Last Updated on : 2023-02-27 03:13:50download

This topic describes the protocol and solution used to integrate smart firefighting devices. Tuya provides the following solution to help brand owners connect smart firefighting devices to the Tuya IoT Development Platform.

Architecture

  • The architecture is shown as follows:

    Integration with Firefighting Devices

  • The commands are transferred as follows:

    Integration with Firefighting Devices

Before you start

A Tuya developer account is registered.

Cloud development project

A cloud development project is a collection of resources on the Tuya IoT Development Platform, including devices, APIs, and data assets. Resources distributed to different projects are isolated from each other. This section briefly describes cloud development projects. For more information about project creation and management steps, see Manage Projects.

A cloud development project is created to get AccessId (client_id) and AccessKey (secret) for device control, Tuya OpenAPI calls, and device event subscriptions. Keep them properly.

  1. Open the list of cloud development projects.

    Integration with Firefighting Devices

  2. Click your created project and get the Access ID and Access Secret on the Overview tab.

    Integration with Firefighting Devices

  3. Link devices.

    Integration with Firefighting Devices

Create a product

Each product created on the platform has a unique product ID (PID). The product contains all the property data of the smart device you deploy in the actual scenario, including the core and basic functional properties defined in product development.

In this step, you can define product functions and get the PID. For more information, see Create Products.

The specified product category will be determined by Tuya. Consult Tuya’s account manager.

Listener for device messages

A messaging mechanism is used to notify a third-party platform of a list of projects that meet the specified criteria. Therefore, you need to subscribe to Tuya’s message service on the third-party platform. For more information, see Message Queue.

Java SDK

Go to Tuya Java SDK GitHub repository to get tokens and common APIs. You only need to change the URL and parameters.

API specifications

Environment description

  • China: https://openapi.tuyacn.com
  • America: https://openapi.tuyaus.com
  • Europe: https://openapi.tuyaeu.com

Call the interfaces according to your region.

Request method

Request methods supported:

  • GET
  • PUT
  • POST
  • DELETE

When the request method is POST, the Content-Type must be set to application/json.

Set the request header

The following parameters must be added to the header of any API request:

Parameter Type Parameter location Description Required
client_id String header The client_id. Yes
lang String header The language. The default language is en. No
sign String header The signature that is generated by a specified signature algorithm: token-related interfaces and business-related interfaces. Yes
sign_method String header The signature digest algorithm. Set the value to HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes

Signature method

Tuya currently provides two signature algorithms for different application scenarios.

  • Token related interface (v1.0/token&v1.0/token/{refresh_token}):

    sign = HMAC-SHA256(client_id + t, secret).toUpperCase()
    
  • Other business interfaces:

    sign = HMAC-SHA256(client_id + access_token + t, secret).toUpperCase()
    
    • client_id: the above-mentioned Access ID.
    • secret: the above-mentioned Access Secret.
    • access_token: see Authorization in the subsequent sections.

The returned result

  • The returned result on success:

    {
    	"success": true,
    	"result": {
    		//object
    	}
    }
    
  • The returned result on failure:

    {
    	"success": false,
    	"code": 1010,
    	"msg": "Illegal token"
    }
    

Global error codes

Code Error message
500 System error.
1000 The data does not exist.
1001 The secret is illegal.
1002 The access_token cannot be empty.
1003 The grant_type is illegal.
1004 The signature is illegal.
1005 The client_id is illegal.
1010 The token has expired.
1011 The token is illegal.
1012 The status is illegal.
1013 The request time is illegal.
1100 The input parameter cannot be empty.
1101 The value range is illegal.
1102 The parameter is null.

Features

Feature Description
Request for authorization Get authorization from Tuya for data communication.
Bind a third-party device A third-party device is registered to Tuya’s ecosystem after an API request is made to bind the device. This allows the device to be controlled throughout Tuya’s ecosystem, and the device status and other related information can be visualized.
Unbind a third-party device Remove a third-party device from Tuya’s ecosystem.
Update a third-party device Update the information about a third-party device in the cloud.
Go online Notify Tuya of the third-party device going online.
Go offline Notify Tuya of the third-party device going offline.
Send alerts Send alerts of the third-party device to Tuya.

Authorization APIs

Get a token

Before making API requests, you need to get the access_token in the first place and access the business interface using the acess_token. According to the provided client_id and secret signature, the /v1.0/token interface is called to get access_token from the server. When you request a business interface, for the calculation of sign, see Signature algorithm for requesting a business interface.

  • sign signature algorithm

    To get a token, the signature is generated based on the following rules:

    sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()
    

    The token is valid for five minutes after it is generated for each request URL. For more information about token management, see Sign Requests.

  • API endpoint

    GET /v1.0/token
    
  • header parameter

    Parameter Type Parameter type Description Required
    client_id String header The client_id. Yes
    sign String header The signature that is generated by the above-mentioned signature algorithm. Yes
    nonce String header The universally unique identifier (UUID) generated for each API request. Combined with the timestamp, the UUID ensures the uniqueness of API requests. No
    stringToSign String header The signature string. Yes
    sign_method String header The signature type. Default value: HMAC-SHA256. Yes
    t Long header The 13-digit standard timestamp. Yes
  • Request parameter

    Parameter Type Parameter type Description Required
    grant_type Integer URL The authorization type. Valid values:
    • 1: simple mode.
    • 2: license mode.
    Yes
  • stringToSign signature string

    String stringToSign=
    HTTPMethod + "\n" +
    Content-SHA256 + "\n" +
    Headers + "\n" +
    Url
    
  • Sample request

    GET /v1.0/token?grant_type=1
    
  • Sample SDK for Java

    TuyaClient tuyaClient = new TuyaClient(accessId, accessKey, RegionEnum.CN);
    String url = ServerEnum.CN_ONLINE.getUrl() + "/v1.0/token";
    HashMap<String, String> hashMap = new HashMap<String, String>();
    hashMap.put("grant_type", "1");
    tuyaClient.commonHttpRequest(url, HttpMethod.GET, hashMap, null);
    
  • Response parameter

    Parameter Type Description
    Code Integer The response code. For more information, see the global error codes section.
    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 information about the user’s device.
  • Description of result

    Parameter Type Description
    access_token String The access token.
    expire_time Integer The time when the token expires. Unit: seconds.
    refresh_token String It is used to refresh the access_token.
  • Sample response

    • Returned result on success:

      {
      "success": true,
      "t": 1575699977724,
      "result": {
      	"uid": "ay1573712013719u5***",
      	"access_token": "6a5629b9285703a1f05f667757dd6***",
      	"expire_time": 7200,
      	"refresh_token": "adbc6363ef181dcc244769e4237d9***"
      }
      }
      
    • Returned result on failure:

      {
      	"success": false,
      	"code": 100323,
      	"msg": "Illegal token"
      }
      

Refresh a token

The access_token is valid for 2 hours. After the expiration, you need to call the token refresh interface to get a new access_token, and use the new access_token to access the business interface.

  • sign signature algorithm

    To get a token, the signature is generated based on the following rules:

    sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()
    

    The token is valid for five minutes after it is generated for each request URL. For more information about token management, see Sign Requests.

  • stringToSign signature string

    String stringToSign=
    HTTPMethod + "\n" +
    Content-SHA256 + "\n" +
    Headers + "\n" +
    Url
    
  • API endpoint

    GET /v1.0/token/{refresh_token}
    
  • header parameter

    Parameter Type Parameter type Description Required
    client_id String header The client_id. Yes
    sign String header The signature that is generated by the above-mentioned signature algorithm. Yes
    nonce String header The universally unique identifier (UUID) generated for each API request. Combined with the timestamp, the UUID ensures the uniqueness of API requests. No
    stringToSign String header The signature string. Yes
    sign_method String header The signature type. Default value: HMAC-SHA256. Yes
    t Long header The 13-digit standard timestamp. Yes
  • Request parameter

    Parameter Type Parameter type Description Required
    refresh_token String URI The returned result of /v1.0/token. Yes
  • Sample request

    GET /v1.0/token/35e0dd4b0f9dfb87c320414a4c190***
    
  • Sample SDK for Java

    String url = ServerEnum.CN_ONLINE.getUrl() + "/v1.0/token/"+ token;
    TuyaClient tuyaClient = new TuyaClient(accessId, accessKey, RegionEnum.CN);
    tuyaClient.commonHttpRequest(url, HttpMethod.GET, null, null);
    
  • Response parameter

    Parameter Type Description
    Code Integer The response code. For more information, see the global error codes section.
    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 information about the user’s device.
  • Description of result

    Parameter Type Description
    access_token String The access token.
    expire_time Integer The time when the token expires. Unit: seconds.
    refresh_token String It is used to refresh the access_token.
  • Sample response

    	{
    	"success": true,
    	"t": 1575701937231,
    	"result": {
    		 "uid": "ay1573712013719u5***",
    		 "access_token": "4bbdc25b6f360b8e31125ed1e3653***",
    		 "expire_time": 7200,
    		 "refresh_token": "adbc6363ef181dcc244769e4237d9***"
    	}
    	}
    

Device connection

Bind a third-party device

After the device is paired with the third-party cloud service, call this interface to register the device information with Tuya.

  • Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya IoT Development Platform, and the product ID (PID) has been generated. For more information, see Create Products.
  • Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
  • Bind the device: After the device is paired with the third-party cloud service, the cloud service calls this interface to register the device information with Tuya. This interface is used to register a device connected to the third-party cloud without a gateway, as well as a gateway and its sub-devices.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/bind

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
3rd_cloud_device_id String URI The unique ID of a third-party device. 3rd_cloud_device_id can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. Yes
tuya_product_id String BODY The ID of a Tuya product. Yes
app_schema String BODY The identifier of a Tuya application. No
tuya_username String BODY The unique username in Tuya’s ecosystem to identify a user. No
properties Object BODY The property of a Tuya device. No
ext_properties List BODY The extension information depending on the specified business. Yes
  • properties parameter:

    Parameter Type Parameter type Description Required
    Name String BODY The device name. No
    lon Double BODY The longitude. No
    lat Double BODY The latitude. No
    ip String BODY The IP address. No
  • ext_properties parameter:

    Parameter Type Parameter type Description Required
    Code String BODY The identifier. Yes
    value String BODY The value. Yes

    The ext_properties field is described as follows:

    [{"code":"cid","value":"123123***"},
    {"code":"vendorCode","value":"nite"},
    {"code":"deviceIp","value": "192.168.*.*"},
    {"code":"macAddress","value": "MAC address"},
    {"code":"commType","value":"HTTP"},
    {"code":"lat","value": "30.20***"},
    {"code":"lon","value": "120.21***"},
    {"code":"installLocation","value":"Installation location"},
    {"code":"outProjectId","value":"Community ID"},
    {"code":"deviceDesc","value":"Device description"},
    {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\"}"},
    {"code":"deviceName","value":"Device name"},
    {"code":"isGateway","value":true}
    ]
    

The third-party device name shall be placed in the ext field, and the key is deviceName, rather than the name field in the request. The key is lat for the latitude and lon for the longitude.

  • app_schema: the channel identifier. For more information, see Cloud development project.

  • tuya_username: the code of a manufacturer.

  • tuya_product_id: the product ID of a specified device in Tuya. For more information, see Create a product.

  • isGateway: indicates whether it is a gateway device. Default value: false. This value is true for a user data transmission device. In the extendData field, enter {\"userTransUnitNum\":\"000.000.000.000.000.155\"}, . userTransUnitNum is the number of a user data transmission device.

    For a user data transmission device, the 3rd_cloud_device_id field is generated in form of manufacturer code_device number, and uses MD5 conversion.

The fields are described as follows:

ext_properties code Description Required
cid The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. Yes
vendorCode The code of a specified third-party supplier. Yes
outProjectId The ID of a specified community where the third-party device is located. Yes
deviceIp The IP address of a specified device. Example: 192.168.1.1. No
macAddress The MAC address of a specified device. No
commType The communication type, such as HTTP, MQTT, and RS-485 electric signal. No
lat The latitude. Yes
lon The longitude. Yes
installLocation The readable installation location. Yes
deviceName The readable device name. Yes
deviceDesc The readable device description. Example: wireless pressure transmitter. Yes
extendData The extension information in form of a JSON string and others. No
isGateway A Boolean value indicating whether it is a user data transmission device. Enter true for a user data transmission device. You can enter nothing for other devices. No

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/bind
{
    "app_schema":"tencentiot",
    "tuya_username": "0123456***",
    "tuya_product_id": "nr1k9ptidpov***",
    "ext_properties":[{"code":"deviceName","value":"Device name"},{"code":"installLocation","value":"Huace***, Jiangdun Road, Xihu District, Hangzhou"}]

}

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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 Type Description
tuya_device_id String The ID of a Tuya device.
tuya_user_id String Tuya user ID.

Sample request

{
    "success": true,
    "t": 1561456817168,
    "result": {
      "tuya_device_id":"",
      "tuya_user_id":""
    }
}

Bind third-party devices in bulk

After the devices are paired with the third-party cloud service, call this interface to register the devices with Tuya in bulk.

  • Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya IoT Development Platform, and the PID has been generated. For more information, see Create Products.
  • Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
  • Bind the devices: After the devices are paired with the third-party cloud service, the third-party cloud service calls this interface to register the devices with Tuya in bulk. This interface is used to register multiple devices directly connected to the third-party cloud, as well as gateway devices.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/devices/actions/bind

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
tuya_product_id String BODY The ID of a Tuya product. Yes
app_schema String BODY The identifier of a Tuya application. No
tuya_username String BODY The username in Tuya’s ecosystem. The unique identifier assigned when a third-party device is bound. No
devices List BODY The property of a Tuya device. Up to 20 devices can be called at one operation. Yes
  • devices properties:

    Parameter Type Description Required
    id String The ID of a specified third-party device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. Yes
    lon String The longitude of a specified device. No
    lat String The latitude of a specified device. No
    Name String The device name. No
    ip String The IP address of a specified device. No
    ext String The extension information about a specified device. See the following table. Yes
  • ext properties:

    Parameter Type Parameter type Description Required
    Code String BODY The identifier. Yes
    value String BODY The value. Yes

    The ext_properties field is described as follows:

    [{"code":"cid","value":"123123***"},
    {"code":"vendorCode","value":"nite"},
    {"code":"deviceIp","value": "192.168.1.*"},
    {"code":"macAddress","value": "MAC address"},
    {"code":"commType","value":"HTTP"},
    {"code":"lat","value": "30.2***"},
    {"code":"lon","value": "120.21***"},
    {"code":"installLocation","value":"Installation location"},
    {"code":"outProjectId","value":"Community ID"},
    {"code":"deviceDesc","value":"Device description"},
    {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\"}"},
    {"code":"deviceName","value":"Device name"},
    {"code":"isGateway","value":true}
    ]
    

The third-party device name shall be placed in the ext field, and the key is deviceName, rather than the name field in the request. The key is lat for the latitude and lon for the longitude.

  • app_schema: the channel identifier. For more information, see Cloud development project.

  • tuya_username: the code of a manufacturer. Confirm the specific value of this field with your Tuya account manager.

  • tuya_product_id: the product ID of a specified device in Tuya. For more information, see Create a product.

  • isGateway: indicates whether it is a gateway device. Default value: false. This value is true for a user data transmission device. In the extendData field, enter {\"userTransUnitNum\":\"000.000.000.000.000.155\"}, . userTransUnitNum is the number of a user data transmission device.

    For a user data transmission device, the 3rd_cloud_device_id field is generated in form of manufacturer code_device number, and uses MD5 conversion.

The fields are described as follows:

ext_properties code Description Required
cid The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. Yes
vendorCode The code of a specified third-party supplier. Yes
outProjectId The ID of a specified community where the third-party device is located. Yes
deviceIp The IP address of a specified device. Example: 192.168.1.1. No
macAddress The MAC address of a specified device. No
commType The communication type, such as HTTP, MQTT, and RS-485 electric signal. No
lat The latitude. Yes
lon The longitude. Yes
installLocation The readable installation location. Yes
deviceName The readable device name. Yes
deviceDesc The readable device description. Example: wireless pressure transmitter. Yes
extendData The extension information in form of a JSON string and others. No
isGateway A Boolean value indicating whether it is a user data transmission device. Enter true for a user data transmission device. You can enter nothing for other devices. No

Sample request

POST /v1.0/3rdcloud/devices/actions/bind
{
    "tuya_product_id": "wazil4rsq7cl***",
    "devices": [
        {
            "id": "qinfengte***",
            "ext": "[{\"code\": \"cid\",\"value\": \"**********\"},{\"code\": \"vendorCode\",\"value\": \"****\"},{\"code\": \"deviceIp\",\"value\": \"1*********3\"},{\"code\": \"macAddress\",\"value\": \"MAC address\"},{\"code\": \"commType\",\"value\": \"HTTP\"},{\"code\": \"lat\",\"value\": \"30.2084\"},{\"code\": \"lon\",\"value\": \"120.21201\"},{\"code\": \"installLocation\", \"value\": \"Installation location\"},{\"code\": \"outProjectId\",\"value\": \"a***********3\"},{\"code\": \"deviceDesc\",\"value\": \"Test device\"},{\"code\": \"extendData\",\"value\": \"\"},{\"code\": \"deviceName\",\"value\": \"Test device\"}]"
        }
    ]
}

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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 Type Description
failed_bind_result List The list of devices failed in pairing.
success_bind_result List The list of paired devices.
  • Description of success_bind_result

    Parameter Type Description
    3rd_device_id String The ID of a specified third-party device.
    tuya_device_id String The ID of a Tuya device.
  • Description of failed_bind_result

    Parameter Type Description
    3rd_device_id String The ID of a specified third-party device.
    failed_reason String The reason for failure.

Sample request

{
    "result": {
        "failed_bind_result": [],
        "success_bind_result": [
            {
                "3rd_device_id": "",
                "tuya_device_id": ""
            }
        ]
    },
    "success": true,
    "t": 1635845117***
}

Bind a third-party sub-device

After the sub-device is successfully paired with the third-party cloud service, call this interface to register the sub-device information with Tuya.

  • Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya IoT Development Platform, and the product ID (PID) has been generated. For more information, see Create Products.
  • Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
  • Bind the sub-device: After the sub-device is successfully paired with the third-party cloud service, this cloud service calls this interface to register the sub-device information with Tuya.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/sub/bind

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
3rd_cloud_device_id String URI The sub-device ID in a third-party cloud. Yes
tuya_product_id String BODY The ID of a Tuya product. Yes
app_schema String BODY The identifier of a Tuya application. No
tuya_username String BODY The username in Tuya’s ecosystem. The unique identifier assigned when a third-party device is bound. No
properties Object BODY The property of a Tuya device. No
ext_properties List BODY The extension information depending on the specified business. No
  • properties parameter:

    Parameter Type Parameter type Description Required
    Name String BODY The name of a specified sub-device. No
    lon Double BODY The longitude. No
    lat Double BODY The latitude. No
    ip String BODY The IP address. No
    gatewayId String BODY The same as 3rd_cloud_device_id of a user data transmission device. Yes
  • ext_properties properties:

    Parameter Type Parameter type Description Required
    Code String BODY The identifier. Yes
    value String BODY The value. Yes

    The ext_properties field is described as follows:

    [{"code":"cid","value":"123123***"},
    {"code":"vendorCode","value":"nite"},
    {"code":"deviceIp","value": "192.168.*.*"},
    {"code":"macAddress","value": "MAC address"},
    {"code":"commType","value":"HTTP"},
    {"code":"lat","value": "30.2***"},
    {"code":"lon","value": "120.21***"},
    {"code":"installLocation","value":"Installation location"},
    {"code":"outProjectId","value":"Community ID"},
    {"code":"deviceDesc","value":"Device description"},
    {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\",\"fireControlUnitNum\":\"000.000\",\"deviceUnitNum\":\"000.001.001.000\"}"},
    {"code":"deviceName","value":"Device name"}
    ]
    

The third-party device name shall be placed in the ext field, and the key is deviceName, rather than the name field in the request. The key is lat for the latitude and lon for the longitude.

  • app_schema: the channel identifier. For more information, see Cloud development project.

  • tuya_username: the code of a manufacturer.

  • tuya_product_id: the product ID of a specified device in Tuya. For more information, see Create a product.

  • 3rd_cloud_device_id: the ID of a specified third-party device. The field generation rule is vendorCode_the number of a user data transmission device_host number_device number, and MD5 conversion is performed.

  • Pass in extendData as follows:

    {
       "userTransUnitNum": "000.000.000.000.000.155", // The number of a user data transmission device
       "fireControlUnitNum": "000.000", // The host number
       "deviceUnitNum": "000.001.001.000" // The sub-device number
    }
    

The fields are described as follows:

ext_properties code Description Required
cid The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. Yes
vendorCode The code of a specified third-party supplier in English. Enter the fixed value neat. Yes
outProjectId The ID of a specified community where the third-party device is located. The unit ID of a third-party manufacturer can be entered. Yes
deviceIp The IP address of a specified device. Example: 192.168.1.1. No
macAddress The MAC address of a specified device. No
commType The communication type, such as HTTP, MQTT, and RS-485 electric signal. No
lat The latitude. Yes
lon The longitude. Yes
installLocation The readable installation location. Yes
deviceName The readable device name. Yes
deviceDesc The readable device description. Example: wireless pressure transmitter. Yes
extendData The extension information in form of a JSON string and others. No

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/sub/bind
{
    "app_schema":"tencentiot",
    "tuya_username": "012345***",
    "tuya_product_id": "nr1k9ptidpov***",
    "ext_properties":[
       {"code":"deviceName","value":"Device name"},
       {"code":"installLocation","value":"Huace Center***, Jiangdun Road, Xihu District, Hangzhou"}
    ]
}

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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 Type Description
tuya_device_id String The ID of a Tuya device.
tuya_user_id String Tuya user ID.

Sample request

{
    "success": true,
    "t": 1561456817***,
    "result": {
      "tuya_device_id":"",
      "tuya_user_id":""
    }
}

Bind third-party sub-devices in bulk

After the sub-devices are paired with the third-party cloud service, call this interface to register the sub-devices with Tuya in bulk.

  • Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya IoT Development Platform, and the PID has been generated. For more information, see Create Products.
  • Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
  • Bind the sub-devices: After the sub-devices are paired with the third-party cloud service, thicloud service calls this interface to register the sub-devices with Tuya in bulk.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/sub-devices/actions/bind

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
tuya_product_id String BODY The ID of a Tuya product. Yes
app_schema String BODY The identifier of a Tuya application. No
tuya_username String BODY The username in Tuya’s ecosystem. The unique identifier assigned when a third-party device is bound. No
devices List BODY The property of a Tuya device. Up to 20 devices can be called at one operation. Yes
  • properties parameter:

    Parameter Type Parameter type Description Required
    Name String BODY The name of a specified sub-device. No
    lon Double BODY The longitude. No
    lat Double BODY The latitude. No
    ip String BODY The IP address. No
    gatewayId String BODY The same as 3rd_cloud_device_id of a user data transmission device. Yes
    ext String BODY The extension information about a specified device. See the following table. Yes
  • ext parameter:

    Parameter Type Parameter type Description Required
    Code String BODY The identifier. Yes
    value String BODY The value. Yes

    The ext_properties field is described as follows:

    [{"code":"cid","value":"123123***"},
    {"code":"vendorCode","value":"nite"},
    {"code":"deviceIp","value": "192.168.*.*"},
    {"code":"macAddress","value": "MAC address"},
    {"code":"commType","value":"HTTP"},
    {"code":"lat","value": "30.2***"},
    {"code":"lon","value": "120.21***"},
    {"code":"installLocation","value":"Installation location"},
    {"code":"outProjectId","value":"Community ID"},
    {"code":"deviceDesc","value":"Device description"},
    {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\",\"fireControlUnitNum\":\"000.000\",\"deviceUnitNum\":\"000.001.001.000\"}"},
    {"code":"deviceName","value":"Device name"}
    ]
    

The third-party device name shall be placed in the ext field, and the key is deviceName, rather than the name field in the request. The key is lat for the latitude and lon for the longitude.

  • app_schema: the channel identifier. For more information, see Cloud development project.

  • tuya_username: the code of a manufacturer.

  • tuya_product_id: the product ID of a specified device in Tuya. For more information, see Create a product.

  • 3rd_cloud_device_id: the ID of a specified third-party device. The field generation rule is vendorCode_the number of a user data transmission device_host number_device number, and MD5 conversion is performed.

  • Pass in extendData as follows:

    {
        "userTransUnitNum": "000.000.000.000.000.155", // The number of a user data transmission device             
        "fireControlUnitNum": "000.000", // The host number
       "deviceUnitNum": "000.001.001.000" // The sub-device number
    }
    

The fields are described as follows:

ext_properties code Description Required
cid The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. Yes
vendorCode The code of a specified third-party supplier in English. Enter the fixed value neat. Yes
outProjectId The ID of a specified community where the third-party device is located. The unit ID of a third-party manufacturer can be entered. Yes
deviceIp The IP address of a specified device. Example: 192.168.1.1. No
macAddress The MAC address of a specified device. No
commType The communication type, such as HTTP, MQTT, and RS-485 electric signal. No
lat The latitude. Yes
lon The longitude. Yes
installLocation The readable installation location. Yes
deviceName The readable device name. Yes
deviceDesc The readable device description. Example: wireless pressure transmitter. Yes
extendData The extension information in form of a JSON string and others. No

Sample request

POST /v1.0/3rdcloud/sub-devices/actions/bind
{
    "tuya_product_id": "123***",
    "devices": [
        {
            "id": "1223***",
            "gatewayId": "123***",
            "lon": "",
            "lat": "",
            "name": "",
            "ip": "",
            "ext":"[{\"code\": \"cid\",\"value\": \"123***\"},{\"code\": \"vendorCode\",                    \"value\": \"123***\"},{\"code\": \"deviceIp\",\"value\": \"\"},{\"code\": \"macAddress\",\"value\": \"MAC address\"},{\"code\": \"commType\",\"value\": \"HTTP\"},{\"code\": \"lat\",\"value\": \"30.2084\"},{\"code\": \"lon\",\"value\": \"120.21201\"},{\"code\": \"installLocation\",\"value\": \"\"},{ \"code\":\"outProjectId\",\"value\": \"a123***\"},{\"code\": \"deviceDesc\",\"value\": \"Test sub-device\"},{\"code\": \"extendData\",\"value\": \"\\\"userTransUnitNum\\\":\\\"000.000.000.000.000.001\\\",\\\"fireControlUnitNum\\\":\\\"000.000\\\",\\\"deviceUnitNum\\\":\\\"000.001.001.000\\\"}\"},{\"code\": \"deviceName\",\"value\": \"Test third-party sub-device\"}]"
        }
    ]
}

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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 Type Description
failed_bind_result List The list of devices failed in pairing.
success_bind_result List The list of paired devices.
  • Description of success_bind_result

    Parameter Type Description
    3rd_device_id String The ID of a specified third-party device.
    tuya_device_id String The ID of a Tuya device.
  • Description of failed_bind_result

    Parameter Type Description
    3rd_device_id String The ID of a specified third-party device.
    failed_reason String The reason for failure.

Sample request

{
    "success": true,
    "t": 156145681***,
    "result": {
      "failed_bind_result":[],
      "success_bind_result":[
      	"3rd_device_id":"123***",
        "tuya_device_id":"123***"
      ]
    }
}

Update a third-party device

After a third-party device is registered, you can update the device information as needed.

API endpoint

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
3rd_cloud_device_id String URI The device ID in a third-party cloud. Yes
tuya_product_id String BODY The ID of a Tuya product. Yes
properties Object BODY The property of a Tuya device. No
ext_properties List BODY The extended device properties. No
  • properties parameter:

    Parameter Type Parameter type Description Required
    Name String BODY The device name. No
    lon Double BODY The longitude. No
    lat Double BODY The latitude. No
    ip String BODY The IP address. No
  • ext_properties parameter:

    Parameter Type Parameter type Description Required
    Code String BODY The identifier. Yes
    value String BODY The value. Yes
    Name String BODY The name. No

    The ext_properties field is described as follows:

    [{"code":"vendorCode","value":"neat","name":"The code of a specified third-party supplier"},
    {"code":"deviceName","value":"Third-party device name","name":"Third-party device name"},
    {"code":"deviceIp","value": "192.168.1.1","Device ID"},
    {"code":"deviceDesc","value":"Device description","name":"Device description"},
    {"code":"macAddress","value": "MAC address","name":"MAC address"},
    {"code":"commType","value":"HTTP","name":"Communication type (HTTP, MQTT, RS-485 electric signal)"},
    {"code":"installLocation","value":"Installation location","name":"Installation location"},
    {"code":"lat","value": "30.2084","name":"Latitude"},
    {"code":"lon","value": "120.21201","name":"Longitude"},
    {"code":"extendData","value":"Extension information if any","name":"Extension information"}
    ]
    

The third-party device name shall be placed in the ext field, and the key is deviceName, rather than the name field in the request. The key is lat for the latitude and lon for the longitude.

  • app_schema: the channel identifier. For more information, see Cloud development project.
  • tuya_username: the fixed value is neat.
  • tuya_product_id: the product ID of a specified device in Tuya. For more information, see Create a product.

The fields are described as follows:

ext_properties code Description Required
vendorCode The code of a specified third-party supplier in English. Enter the fixed value neat. Yes
deviceIp The IP address of a specified device. Example: 192.168.1.1. No
macAddress The MAC address of a specified device. No
commType The communication type, such as HTTP, MQTT, and RS-485 electric signal. No
lat The latitude. Yes
lon The longitude. Yes
installLocation The readable installation location. Yes
deviceName The readable device name. Yes
deviceDesc The readable device description. Example: wireless pressure transmitter. Yes
extendData The extension information in form of a JSON string and others. No

Sample request

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200
{
    "properties":{
        "name":"Test device",
        "lon":39.904***,
        "lat":116.407***,
        "ip":"124.156.99.***"
    },
    "ext_properties":[
        {
            "code":"vendorCode",
            "value":"neat",
            "name":"Code of a third-party supplier"
        },
        {
            "code":"installLocation",
            "value":"Huace Center***, Jiangdun Road, Xihu District, Hangzhou",
            "name":"Address"
        }
    ]
}

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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 The returned result.

Sample response

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

Unbind a third-party device

Unbind a third-party device from Tuya based on the following scenarios:

  • The device is reset.
  • The device is removed from an app in Tuya’s ecosystem or third-party cloud service.

API endpoint

DELETE /v1.0/3rdcloud/devices/{third_party_device_id}/unbind

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
3rd_cloud_device_id String URI The device ID in a third-party cloud. Yes

Sample request

DELETE /v1.0/3rdcloud/devices/27511006b4e62d4bd200/unbind

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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.

Sample request

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

Go online

The third-party cloud service synchronizes the going-online event of a specified device to Tuya based on the network connection of the device. Tuya’s app updates the online status of the device accordingly.

API endpoint

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/online

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
3rd_cloud_device_id String URI The device ID in a third-party cloud. Yes

Sample request

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200/online

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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.

Sample response

{
    "success": true,
    "t": 156145681***,
    "result": true
}

Go offline

The third-party cloud service synchronizes the going-offline event of a specified device to Tuya based on the network connection of the device. Tuya’s app updates the offline status of the device accordingly.

API endpoint

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/offline

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
3rd_cloud_device_id String URI The device ID in a third-party cloud. Yes

Sample request

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200/offline

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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.

Sample request

{
    "success": true,
    "t": 156145681***,
    "result": true
}

Report events of a third-party device

When an event occurs in a device of the third-party cloud, this API is called to notify Tuya.

API endpoint

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/status

header parameter

Parameter Type Parameter type Description Required
access_token String header The access token. Yes
client_id String header The client_id. Yes
sign String header See Signature algorithm for requesting a business interface. Yes
sign_method String header The signature type. Default value: HMAC-SHA256. Yes
t Long header The 13-digit standard timestamp. Yes
Content-Type String header Default value: application/json. Yes

Request parameter

Parameter Type Parameter type Description Required
3rd_cloud_device_id String URI The device ID in a third-party cloud. Yes
timestamp Long BODY The time when the third-party device status is changed, which is accurate to seconds. Yes
status List BODY The data of device status. Yes
  • Description of status

    Parameter Type Description
    Code String The code of a specified device function.
    value String The value of a specified device function.
  • status content

    Code value Function Data type Description
    alarm_trace_id Unique event ID (productId + snowflake algorithm) Alarm event ID String It is used to update the event processing result alarm_result_content after an alarm is triggered.
    alarm_event_content Description of content such as smoke concentration exceeding threshold Alarm content description String Describe the content of an alarm.
    fire_alarm_type Alarm type of firefighting device Alarm type Enum {“range”:[“fire_alarm”,“device_fault”,“device_alarm”,“others”]}. Fire alarm, device failure (low battery), and device alarm.
    alarm_trace_time 13-digit timestamp in milliseconds Event occurrence time String The timestamp when the event occurs. Unit: in milliseconds.
    alarm_result_content Processed/device failure Event result String Describe the event processing result. The specific content is defined by the third-party platform. This document only provides an example.
    alarm_value Data type Event value float The value at the time of the alarm. Note: All values need to be multiplied by 10,000 and converted to integers. Example: 36.5 is passed to Tuya as 365,000, and 37.55 is passed to Tuya as 375,500. The value is multiplied by 10,000 and rounded up.) Value range: -1,000,000,000 to 1,000,000,000.
    alarm_unit Unit description Event unit String The unit of an alarm. It is related to the event value, such as degree Celsius.
    alarm_process_time 13-digit timestamp in milliseconds Alarm processing time String The timestamp when an alarm is processed. Unit: in milliseconds.
  • Multiple different events of the same alarm can include list type data.
  • To report the event processing result, make sure the alarm_trace_id is the same as that of reporting the alarm event. Meanwhile, upload other fields of the alarm event and alarm processing. Do not pass in the processing result only.

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/status
{
    "timestamp":1592920221,
    "status": [
        {
            "code": "alarm_trace_id",
            "value": "productId+snowflake algorithm"
        },
        {
            "code": "alarm_event_content",
            "value": "Reach temperature threshold"
        },
        {
            "code": "fire_alarm_type",
            "value": "fire_warning"
        },
        {
            "code": "alarm_trace_time",
            "value": "1592722282***"
        },
        {
            "code": "alarm_result_content",
            "value": "Processed"
        },
        {
            "code": "alarm_value",
            "value": 50
        },
        {
            "code": "alarm_unit",
            "value": "Degree Celsius"
        },
        {
            "code": "alarm_process_time",
            "value": "1592722282***"
        }
    ]
}

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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.

Sample response

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

Definition of testing data dpcode (status content)

Code value Function Data type Description
monitor_data Code of test item Code of test item String The code of a specified test item to be defined by the manufacturer. Simple and easy-to-read English words or phrases are preferred.
monitor_name Name of test item Name of test item String The name of a specified test item in Chinese.
monitor_value Value of test data Test value Int Valid values: -10000 to 100000. No more than 4 decimal places.
monitor_unit Unit of test data Test unit String The unit name of a specified test item.
monitor_time_data 13-digit timestamp in milliseconds Test time String The time when the data of a specified test item is generated.
  • Multiple items of data reported from the same device can use the list type data.
  • The data reporting cannot be mixed with the alarm dpcode. Make sure the same element of the list contains only one of the two types.

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/status
{
    "timestamp":1592920221,
    "status": [
        {
            "code": "monitor_data",
            "value": "voltage"
        },
        {
            "code": "monitor_name",
            "value": "Voltage"
        },
        {
            "code": "monitor_value",
            "value": "220"
        },
        {
            "code": "monitor_unit",
            "value": "V"
        },
        {
           "code": "monitor_time_data",
           "value": "1592722282***"
        }
    ]
}

Response parameter

Parameter Type Description
Code Integer The response code. For more information, see the global error codes section.
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.

Sample response

{
    "success": true,
    "t": 156145681***,
    "result": true
}