Development Guide

This topic describes the communication specifications for connecting a Tuya-enabled gateway to a third-party system.

Communication model

1. When the integration with a third-party system is enabled, the gateway will send UDP packets every five seconds to advertise the device’s UUID and WebSocket port.
2. The third-party application stores the mapping between device UUIDs and keys. When it receives the advertising packet from the gateway without a WebSocket connection, it will establish one.
3. The gateway sends an identity authentication request to the third-party application.
4. The third-party application responds to the identity authentication request.
5. The gateway requests the result of identity authentication from the third-party application.
6. Both parties use their own randomly generated numbers and those of the other party to create a session key through the XOR operation. This key is then used for encrypting and decrypting data.

Protocol format

The WebSocket data is formatted in JSON, with each message containing a type key to indicate the type of message.

After successful identity authentication, there are two types of messages for bidirectional communication:

• The request message that requires the receiver to return a response.

• The event message that does not require the receiver to return a response.

Request message format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. See Protocol Details.
data	Object	No	The request data.

Response message format

Key value	Type	Required	Description
id	Integer	Yes	The message ID of the response.
type	String	Yes	The message type. Its value is result.
success	Boolean	Yes	Indicates whether the operation is successful. true: success. false: failure.
result	Object	No	When success is true, it indicates the response data.
error	Object	No	When success is false, it indicates the error message.

Event message format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is event.
event_type	String	Yes	The event type.
data	Object	No	The event data.

Protocol details

Authenticate identity

auth_required data format

Key value	Type	Required	Description
type	String	Yes	The message type. Its value is auth_required.
data	Object	Yes	The payload.
data.nonce	String	Yes	A 16-byte base64-encoded random number.

Example:

{
    "type": "auth_required",
    "data": {
        "nonce": "VOHiQDnXJatfv4fBPyHvEw=="
    }
}

auth data format

Key value	Type	Required	Description
type	String	Yes	The message type. Its value is auth.
data	Object	Yes	The payload.
data.nonce	String	Yes	A 16-byte base64-encoded random number.
data.hmac	String	Yes	A base64-encoded hash value generated by signing the gateway’s random number.

Example:

{
    "type": "auth",
    "data": {
        "nonce": "RIf328KU8EHKP1tH3XAtTw==",
        "hmac": "uZ3DiPiw3wFbb2w1lFZ/ZtzgzLuzK72xM95SGVIze3M="
    }
}

auth_ok data format

Key value	Type	Required	Description
type	String	Yes	The message type. Its value is auth_ok.
data	Object	Yes	The payload.
data.hmac	String	Yes	A base64-encoded hash value generated by signing the third-party application’s random number.

Example:

{
    "type": "auth_ok",
    "data": {
        "hmac": "+nThfHD+Ku/lWNMJJsoA+9ayrEgl/nlNtcokrFYTOQ8=",
    }
}

Get device list

Request data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is get_devices.

Example:

{
    "id": 1,
    "type": "get_devices",
}

Response data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID of the request.
type	String	Yes	The message type. Its value is result.
success	Boolean	Yes	Indicates whether the operation is successful. true: success. false: failure.
result	Array	Yes	The list of devices.

Example:

{
    "id": 1,
    "type: "result",
    "success": true,
    "result": [
        "000d6ffffe67e2ca",
        "a4c1380bb1d2f0d5",
        "a4c1385acafc01b5",
        "a4c138e72a0fb5a9",
        "a4c138807e3b1182"
    ]
}

Get device information

Request data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is get_schema.
data	Array	Yes	The list of devices.

Example:

{
    "id": 2,
    "type": "get_schema",
    "data": [
      "000d6ffffe67e2ca"
    ]
}

Response data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID of the request.
type	String	Yes	The message type. Its value is result.
success	Boolean	Yes	Indicates whether the operation is successful. true: success. false: failure.
result	Array	Yes	The payload.
result[0].devid	String	Yes	The device ID.
result[0].category	String	Yes	The category code of the device.
result[0].function	Array	Yes	The feature set.
result[0].function[0].code	String	Yes	The key value of the function DP code.
result[0].function[0].type	String	Yes	The type of the function DP code.
result[0].functions[0].values	String	Yes	The range of the function DP code.
result[0].status	Array	Yes	The status set.
result[0].status[0].code	String	Yes	The key value of the status DP code.
result[0].status[0].type	String	Yes	The type of the status DP code.
result[0].status[0].values	String	Yes	The range of the status DP code.

Example:

{
    "id": 2,
    "type": "result",
    "success": true,
    "result": [
      {
          "devid":"000d6ffffe67e2ca",
          "category": "kg",
          "function":[
             {
                "code":"switch_1",
                "type":"Boolean",
                "values":"{}"
             },
             {
                "code":"countdown_1",
                "type":"Integer",
                "values":"{\"unit\":\"s\",\"min\":0,\"max\":43200,\"scale\":0,\"step\":1}"
             }
          ],
           "status":[
             {
                "code":"switch_1",
                "type":"Boolean",
                "values":"{}"
             },
             {
                "code":"countdown_1",
                "type":"Integer",
                "values":"{\"unit\":\"s\",\"min\":0,\"max\":43200,\"scale\":0,\"step\":1}"
             }
          ]
      }
    ]
}

Get device status

Request data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is get_status.
data	Array	Yes	The list of devices.

Example:

{
    "id": 3,
    "type": "get_status",
    "data": [
      "000d6ffffe67e2ca"
    ]
}

Response data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID of the request.
type	String	Yes	The message type. Its value is result.
success	Boolean	Yes	Indicates whether the operation is successful. true: success. false: failure.
result	Array	Yes	The payload.
result[0].devid	String	Yes	The device ID.
result[0].online	Boolean	Yes	Indicates whether the device is online. true: online. false: offline.
result[0].value	Array	Yes	The status set.
result[0].value[0].k	String	Yes	The key value of the status DP code.
result[0].value[0].v	Boolean/Integer/String/Object	Yes	The value of the status DP code.

Example:

{
    "id": 3,
    "type": "result",
    "success": true,
    "result": [
        {
            "devid": "000d6ffffe67e2ca",
              "online": true,
            "value": [
              {
                  "k": "switch_1",
                "v": true
              }
            ]
        }
    ]
}

Control device

Request data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is set_value.
data	Array	Yes	The payload.
data[0].device	String	Yes	The device ID.
data[0].value	Array	Yes	The feature set.
data[0].value[0].k	String	Yes	The key value of the function DP code.
data[0].value[0].v	Boolean/Integer/String/Object	Yes	The value of the function DP code.

Example:

{
    "id": 4,
    "type": "set_value",
    "data": [
        {
            "devid": "000d6ffffe67e2ca",
            "value": [
                {
                    "k": "switch_1",
                    "v": true
                }
            ]
        }
    ]
}

Response data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID of the request.
type	String	Yes	The message type. Its value is result.
success	Boolean	Yes	Indicates whether the operation is successful. true: success. false: failure.

Example:

{
    "id": 4,
    "type": "result",
    "success": true
}

Update device registration status

Event data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is event.
event_type	String	Yes	The event type. Its value is registry_updated.
data	Object	Yes	The payload.
data.devid	String	Yes	The device ID.
data.state	Integer	Yes	The status. 1: bound 2: unbound 3: unbound with data cleared

Example:

{
    "id": 100,
    "type": "event",
    "event_type": "registry_updated",
    "data": {
        "devid": "000d6ffffe67e2ca",
        "state": 1
    }
}

Update device online status

Event data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is event.
event_type	String	Yes	The event type. Its value is online_updated.
data	Object	Yes	The payload.
data.devid	String	Yes	The device ID.
data.state	Boolean	Yes	true: online. false: offline.
data.value[0].k	String	Yes	The DP code.
data.value[0].v	Boolean/Integer/String/Object	Yes	The value of the DP code.

Example:

{
    "id": 102,
    "type": "event",
    "event_type": "online_updated",
    "data": {
        "devid": "000d6ffffe67e2ca",
        "state": true
    }
}

Update feature status

Event data format

Key value	Type	Required	Description
id	Integer	Yes	The message ID.
type	String	Yes	The message type. Its value is event.
event_type	String	Yes	The event type. Its value is state_changed.
data	Object	Yes	The payload.
data.devid	String	Yes	The device ID.
data.value	Array	Yes	The status set.
data.value[0].k	String	Yes	The key value of the status DP code.
data.value[0].v	Boolean/Integer/String/Object	Yes	The value of the status DP code.

Example:

{
    "id": 101,
    "type": "event",
    "event_type": "state_changed",
    "data": {
        "devid": "000d6ffffe67e2ca",
        "value": [
            {
                "k": "switch_1",
                "v": true
            }
        ]
    }
}

Things to note

• Identity authentication is done using the key shown on the app panel.
• After successful identity authentication, the session key will be used.
• Be sure to keep the device key safe.