Push Message

Message Subscription

The Tuya Intelligent Business Platform uses Pulsar to push event data to external partners, meeting the requirements of partners for instant and persistent messages.

Method for Enabling This Function

Developers can submit their accounts and authorization keys (clientId or accessId) to the technical support center of the Tuya Intelligent Business Platform for subscribing to messages.

Pulsar Overview

Pulsar is a solution for message exchange between servers, supporting multiple tenants and featuring high performance. Pulsar is developed by Yahoo and managed by the Apache Software Foundation now. Tuya customizes the open-source Pulsar system. The Pulsar SDK provided by Tuya enables message access. As a message broker, Pulsar uses the design pattern of publish-subscribe, also known as pub-sub. In this pattern, producers publish messages to topics. Then consumers can subscribe to the topics, process incoming messages, and send acknowledgment messages when the processing is complete. Once a subscription request is created, Pulsar saves all messages even when the consumer is disconnected. The messages are discarded only after the consumer confirms that the messages are successfully processed.

Multiple consumers can subscribe to one topic. After successfully processing a message, the consumer needs to send an acknowledgment message to Pulsar so that Pulsar can discard the message. The Tuya Pulsar broker allocates multiple partitions to each topic, and routes messages based on partitions and consumers.

Security

• Authentication security: The Tuya Pulsar system provides in-depth customization for identity authentication to meet the requirement of high security. It uses dynamic tokens to enhance security. Developers can use the SDK provided by Tuya to complete authentication, without considering the implementation details.
• Data security:

1. Transmission security: The Tuya Pulsar system transmits data based on Secure Socket Layer (SSL).
2. Business security: All business data is encrypted by AES-128. Each request is attached with a signature.

Request Method

For details, see the ConsumerExample code in the example part in open-mq-sdk. The following data must be provided for access:

Username: clientId applied for under Cloud API Authorization on the Tuya IoT platform

Password: secret applied for under Cloud API Authorization on the Tuya IoT platform

URL for partners:

• China: pulsar+ssl://mqe.tuyacn.com:7285/
• US: pulsar+ssl://mqe.tuyaus.com:7285/
• Europe: pulsar+ssl://mqe.tuyaeu.com:7285/

Data Format

Message Format

Parameter	Type	Description
encryptPayload	String	Cipher text of a message body.
sign	String	Signature calculated based on a specified signature algorithm.
encryptType	String	Encryption type.
t	Long	13-digit standard timestamp.
v	String	Version.

Message Example

{
  "encryptType": "aes_ecb",
  "v": "1.0",
  "t": 1588918073598,
  "encryptPayload":"4FDEE3FE59FCD76E26150******",
  "sign": "4b7084b3b87b550c0d967f77******"
}

Message Body Format

Parameter	Type	Description
bizCode	String	Business ID.
eventType	String	Event type.
data	JSON	Message data.

Message Body Example

{
  "bizCode": "device",
  "eventType": "dp_report",
  "data": {}
}

Data Signature

Before obtaining real data, you need to perform the anti-tampering MD5 signature verification. The algorithm is as follows: Convert each JSON parameter (excluding the parameters whose signs and values are null) into the key=val format, and assemble the parameters (in ascending order of keys). After assembling, the string format is similar to k1=v1||k2=v2. Then add the key, for example, k1=v1||k2=v2…kn=vn||key, to add an MD5 signature to the entire string. If the MD5 value is the same as that of the sign in the received data, the data does not tamper. Otherwise, the data tampering.

After signature verification is passed, perform BASE64 decoding for data. Then use the 16 digits in the middle of accessKey to perform AES decryption (ECB mode), thus obtaining the actual device status data.

Business Types

bizCode	Description
device	Device event pushing.
voice	Voice business pushing.
construction	Construction business push.

Device Event Types

eventType	Description
bind	Device binding.
unbind	Device unbinding.
reset	Device resetting.
online	Device going online.
offline	Device going offline.
dp_report	Device status reporting.
name_update	Device renaming.

Example of a Device Binding Message

{
  "data":{
    "devId":"02200434dc4*******",
    "deviceName":"Socket(wifi)_0",
    "gwId":"",
    "location":{
      "child":{
        "id":"12561526665*******",
        "name":"Test room"
      },
      "id":"1256148753241358336",
      "name":""
    },
    "namespace":"BgdBXzUhIg5x77770LL1Of*******",
    "ownerId":"139960*******",
    "position":"Home office",
    "productId":"qCY4YFq0*******",
    "sub":false,
    "uid":"bay1588324079*******",
    "uuid":"02200434dc4f*******"
  },
  "bizCode":"device",
  "eventType":"bind"
}

Example of a Device Unbinding Message

{
  "data":{
    "devId":"02200434dc4f2*******",
    "namespace":"Developer namespace"
  },
  "bizCode":"device",
  "eventType":"unbind"
}

Example of a Device Resetting Message

{
  "data":{
    "devId":"02200434dc4f22*******",
    "namespace":"Developer namespace"
  },
  "bizCode":"device",
  "eventType":"reset"
}

Example of a Device Going-Online Message

{
  "data":{
    "devId":"02200434dc4f22*******",
    "namespace":"Developer namespace",
    "time":1589019224062
  },
  "bizCode":"device",
  "eventType":"online"
}

Example of a Device Going-Offline Message

{
  "data":{
    "devId":"02200434dc4*******",
    "namespace":"Developer namespace",
    "time":1589019224062
  },
  "bizCode":"device",
  "eventType":"offline"
}

Example of a Device Status Reporting Message

{
  "data":{
    "devId": "002dj00118f*******",
    "productId": "PID of the product",
    "dataId": "145*****************",
    "namespace":"Developer namespace",
    "status": [
      {
        "code": "switch_1",
        "value": "true",
        "time": 1589767589137
      }
    ]
  },
  "bizCode":"device",
  "eventType":"dp_report"
}

Example of a Device Renaming Message

{
  "data":{
    "devId":"02200434dc4*******",
    "deviceName":"Socket",
    "namespace":"Developer namespace"
  },
  "bizCode":"device",
  "eventType":"name_update"
}

Voice Event Types

bizCode	Description
voice_nlu	Voice recognition result pushing.
voice_room_bind	Speaker-room binding result pushing.

Example of a Voice Recognition Result Message

{
  "data":{
    "devId":"6cd40b4ed084a*******",
    "namespace":"BgdBXzUhIg5x77770*******",
    "nlu":"[{\"entities\":[{\"value\":\"TV\",\"entity\":\"deviceName\"}],\"domain\":\"mediaControl\",\"confidence\":1,\"text\":\"Can I pause the TV playing?\",\"intent\":\"pause\"}]",
    "productId":"fabz****",
    "uid":"bay1588324079*******",
    "uuid":"f572ecc09e19d8c1"
  },
  "bizCode":"voice",
  "eventType":"voice_nlu"
}

Example of a Speaker-Room Binding Result Message

{
  "data":{
    "voice_id":"6cd40b4ed084ac*******",
    "namespace":"BgdBXzUhIg5x77770LL1*******"
  },
  "bizCode":"voice",
  "eventType":"voice_room_bind"
}

Construction Event Types

eventType	description
task_status_change	Task status change push.

Example of a Construction task status change Message

{
  "data":{
    "namespace":"BgdBXzUhIg5xLL1O*******",
    "taskId":"125614875324*******",
    "taskType":"CONSTRUCTION",
    "taskStatus":"PENDING_ACCEPTANCE",
    "sendTime":"1607220008843"
  },
  "bizCode":"construction",
  "eventType":"task_status_change"
}

parameter	description
taskId	Unique ID of a task.
taskType	Type: CONSTRUCTION MAINTENANCE
taskStatus	Construction status: IN_CONSTRUCTION IN_MAINTENANCE PENDING_ACCEPTANCE ACCEPTANCE_COMPLETE
sendTime	Message sending time, which is a 13-digit timestamp.