Development Guide

Last Updated on : 2024-05-16 08:03:32download

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.