Development Guide

Last Updated on : 2023-11-10 08:56:38download

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

Communication model

The gateway and third-party applications communicate using the WebSocket API. The gateway functions as a WebSocket server, while the third-party applications act as clients and initiate a connection request.

WebSocket connections are secured through token authentication, ensuring that only authenticated clients can connect. The transport layer is encrypted using TLS for enhanced security.

The process of a third-party application communicating with the gateway through the WebSocket API:

  1. The third-party application obtains an access token by using a unique identity credential through the HTTPS API.
  2. The third-party application uses the WebSocket Secure (wss) protocol to establish a secure WebSocket connection.
  3. The third-party application uses the access token for authentication when establishing a WebSocket connection.

Endpoint

Protocol URL Purpose
wss wss://:8433 Bidirectional communication
HTTPS https:///api/v1 Get the access token

HTTP APIs

Get the access token

  • Request URL: /api/v1/token

  • Request method: GET

  • Request header:

    • Content-Type: application/json
    • Autorization: Bearer <OPENAPI_KEY>
  • Request parameter: None

  • Response:

    Name Description
    access_token The access token, used for WebSocket authentication.
    refresh_token Refresh the token.
    expires_in The expiration time of the token, in seconds.

Refresh the token

  • Request URL: /api/v1/token/{refresh_token}

  • Request method: GET

  • Request header:

    • Content-Type: application/json
  • Request parameter: None

  • Response:

    Name Description
    access_token The access token, used for WebSocket authentication.
    refresh_token Refresh the token.
    expires_in The expiration time of the token, in seconds.

Protocol format

The JSON format is used for data transmission because it offers easy readability, making implementation more efficient. Messages are divided into requests, responses, and events based on their directions. Requests and responses have a one-to-one relationship, while events are unidirectional.

Request data format

Name Type Required Description
method String Yes The method. For more information, see Communication Protocol.
action String Yes request
version String Yes The protocol version.
sequence Integer Yes The sequence number of the message.
devid String No The device ID.
payload JSON No The payload data, depending on the method.

Response data format

Name Type Required Description
method String Yes The method. For more information, see Communication Protocol.
action String Yes response
version String Yes The protocol version, which must be consistent with that of the request.
sequence Integer Yes The sequence number of the message, which must be consistent with that of the request.
code Integer Yes The error code. 0: Success. Other values: Failure.
result JSON No The payload data, depending on the method.

Event data format

Name Type Required Description
method String Yes The method. For more information, see Communication Protocol.
action String Yes event
version String Yes The protocol version.
sequence Integer Yes The sequence number of the message.
devid String No The device ID.
payload JSON Yes The payload data, depending on the method.

Protocol details

getDeviceList

Description

Get the list of activated devices under the gateway.

Sample request

{
    "method": "getDeviceList",
    "action": "request",
    "version": 0,
    "sequence": 1
}

Sample response

{
    "method": "getDeviceList",
    "action": "response",
    "version": 0,
    "sequence": 1,
    "code": 0,
    "result": [
        "000d6ffffe67e2ca",
        "a4c1380bb1d2f0d5",
        "a4c1385acafc01b5",
        "a4c138e72a0fb5a9",
        "a4c138807e3b1182"
    ]
}

getDeviceSpecification

Description

Get the standard instruction set for a single device.

Sample request

{
    "method": "getDeviceSpecification",
    "action": "request",
    "version": 0,
    "sequence": 1,
    "devid": "000d6ffffe67e2ca"
}

Sample response

{
   "method": "getDeviceSpecification",
   "action": "response",
   "version": 0,
   "sequence": 1,
   "code": 0,
   "result": {
      "devid":"000d6ffffe67e2ca",
      "category": "kg",
      "functions":[
         {
            "code":"switch_1",
            "type":"Boolean",
            "values":"{}"
         },
         {
            "code":"countdown_1",
            "type":"Integer",
            "values":"{\"unit\":\"s\",\"min\":0,\"max\":43200,\"scale\":0,\"step\":1}"
         }
      ]
   }
}

getDeviceStatus

Description

Get the status of a single device.

Sample request

{
    "method": "getDeviceStatus",
    "action": "request",
    "version": 0,
    "sequence": 1,
    "devid": "000d6ffffe67e2ca"
}

Sample response

{
    "method": "getDeviceStatus",
    "action": "response",
    "version": 0,
    "sequence": 1,
    "code": 0,
    "result": {
        "devid": "000d6ffffe67e2ca",
          "online": true,
        "status": [
          {
              "code": "switch_1",
            "v": true
          }
        ]
    }
}

setDeviceProperty

Description

Set the property of a single device.

Sample request

{
    "method": "setDeviceProperty",
    "action": "request",
    "version": 0,
    "sequence": 1,
    "devid": "000d6ffffe67e2ca",
    "payload":[
        {
            "k": "switch_1",
            "v": true
        }
    ]
}

Sample response

{
   "method": "setDeviceProperty",
   "action": "response",
   "version": 0,
   "sequence": 1,
   "code": 0
}

onDeviceOnlineOffline

Description

Device online or offline event.

Example

{
    "method": "onDeviceOnlineOffline",
    "action": "event",
    "version": 0,
    "sequence": 1,
    "devid": "000d6ffffe67e2ca",
    "payload": {
        "online": true
    }
}

onDeviceBindUnbind

Description

Device binding or unbinding event.

Example

{
    "method": "onDeviceBindUnbind",
    "action": "event",
    "version": 0,
    "sequence": 1,
    "devid": "000d6ffffe67e2ca",
    "payload": {
        "bind": true
    }
}

onDeviceProperty

Description

Device property change event.

Example

{
    "method": "onDeviceProperty",
    "action": "event",
    "version": 0,
    "sequence": 1,
    "devid": "000d6ffffe67e2ca",
    "payload": [
        {
            "code": "switch_1",
            "v": true
        }
    ]
}

Things to note

  • The gateway’s TLS certificate is self-signed. Verifying the domain name is unnecessary when a third-party application verifies the certificate of the gateway.
  • Get the token with OPENAPI_KEY for the initial connection. When a token expires, refresh the token to get a new one and try to reduce the exposure of OPENAPI_KEY.
  • A Bearer Token is used for WebSocket authentication. Before a connection, the third-party application requests an access token through the HTTP API. To establish a connection, it carries the access token with Autorization: Bearer <access_token> in the request header to authenticate with the server.
  • A device must be activated before it can be used.