Tuya MQTT Standard Protocol

Last Updated on : 2024-06-20 04:29:48download

The TuyaLink protocol is a data exchange standard in JSON for IoT development. It enables the bidirectional communication between devices and the Tuya Developer Platform efficiently.

TuyaLink supports a variety of connectivity technologies, including wireless technologies such as Bluetooth Low Energy (LE), Zigbee, Bluetooth mesh, and 433 MHz, wired technologies such as RS-485, RS-232, and Ethernet, as well as industrial protocols. Connectivity technologies build data channels. The communication data protocols determine how the data exchange works. They can be industrial communication protocols such as Open Charge Point Protocol (OCPP) and Modbus or proprietary protocols.

This topic describes the Tuya MQTT standard protocol, the underlying communication protocol adopted by the Tuya Developer Platform. This protocol can be integrated into any device, allowing you to develop embedded software as needed.

Device types

Directly connected device

Devices that can directly connect to the cloud over the internet, without a mediator device forwarding data. These devices use connectivity technologies such as Wi-Fi, Ethernet, and cellular.


A gateway is a physical device or software application that serves as a mediator between the cloud and end devices. It is also a directly connected device. A gateway, in a broad sense, is a device that can communicate with sub-devices and forward data.

Edge gateway

On top of the ordinary gateway, an edge gateway provides computing power on the edge of the network to perform local data analytics and statistics, data caching, and local automation.

Gateway sub-device

Devices that cannot directly access the internet can connect to the cloud through a gateway. These devices are called sub-devices to a gateway, such as Zigbee devices and Bluetooth devices.

Tuya MQTT Standard Protocol

What is MQTT?

Message Queuing Telemetry Transport (MQTT) is a lightweight client-server publish/subscribe messaging protocol based on TCP/IP developed in 1999 by IBM.

It is easy-to-implement, data-independent, bandwidth-saving, and QoS-supported. These characteristics make it ideal for constrained devices and low-bandwidth networks.

A device, acting as a client, can subscribe and publish to MQTT topics to send to and receive messages from the Tuya Developer Platform. MQTT has been widely used in IoT use cases thanks to its strengths.

How MQTT works

Tuya MQTT Standard Protocol

Support for MQTT

  • Quality of Service (QoS) in MQTT messaging is an agreement between the sender and the receiver on the guarantee of delivering a message. There are three levels of QoS, namely QoS 0, QoS 1, and QoS 2. Only QoS 0 and QoS 1 are supported.

    Quality of service (QoS) Description Support
    QoS 0 The message is delivered at most once. The message might be lost if the client is disconnected. Yes
    QoS 1 (Recommended) The message is always delivered at least once. Yes
    QoS 2 The message is always delivered exactly once. No
  • There are three MQTT versions, MQTT 3.1, MQTT 3.1.1, and MQTT 5. MQTT 3.1.1 is widely used in IoT environments. Tuya Developer Platform supports MQTT 3.1.1 only.

MQTT endpoints

Tuya Developer Platform can connect to devices deployed globally. Choose the endpoint based on where devices are deployed.

MQTT endpoints distributed in six global data centers.

Data center MQTT endpoint Port number
China Data Center m1.tuyacn.com 8883
Central Europe Data Center m1.tuyaeu.com 8883
Western America Data Center m1.tuyaus.com 8883
Eastern America Data Center m1-ueaz.tuyaus.com 8883
Western Europe Data Center m1-weaz.tuyaeu.com 8883
India Data Center m1.tuyain.com 8883

If your product is sold globally, make sure to choose the correct endpoint to meet the compliance requirements of the destination countries.

Device identity authentication

Before diving into the details of device identity authentication, you can familiarize yourself with device connectivity and control. For more information, see Quick Start.

When a device requests an MQTT connection to the Tuya Developer Platform, it carries its identity information to authenticate itself with the platform. If the device fails authentication, its request will be rejected.

Directly-connected device authentication

One-device-one-key authentication mechanism

Flash the unique certificate (ProductID, DeviceID, and DeviceSecre) to the device upfront. When a device connects to the Tuya Developer Platform, the Platform encrypts the certificate information carried by the device and authenticates the device’s identity using the username/password.

Tuya MQTT Standard Protocol

On the page of Activation and Verification, you can get the device certificate, which is made up of three elements.

Parameter name Description
ProductID The PID of the product you create.
DeviceID The device ID that is used for cloud authentication and communication.
DeviceSecret The device secret that is used for cloud authentication and communication.

The following table describes how the username and password are derived.

Parameter name Description Example
user name ${DeviceID}|signMethod=hmacSha256,timestamp=${10-digit current timestamp},secureMode=1,accessType=1; For example, 6c828cba434ff40c074wF2|signMethod=hmacSha256,timestamp=1607837283,secureMode=1,accessType=1
password hmacSha256(content, DeviceSecret)
content format: deviceId=${DeviceID},timestamp=${10-digit current timestamp},secureMode=1,accessType=1.
The plaintext of content is a string concatenated with deviceId, timestamp, secureMode, and accessType in sequence. The password is a 64-character hexadecimal value. Pad the left-most bits with zero if necessary.
For example, if the content is deviceId=6c828cba434ff40c074wF2,timestamp=1607635284,secureMode=1,accessType=1 and the DeviceSecret is ffad8eb66ae8c717, the password would be 9088f1608df4744e2a933ff905ffdde58dc7213510f25ad786a89896a5ea1104.

We recommend you turn on automatic reconnection when one-device-one-key authentication is run. If a device is disconnected due to network jitter, it will be automatically reconnected when the network is restored.

  • One device certificate can only be used for one MQTT connection. If multiple physical devices use the same device certificate to connect to the Tuya Developer Platform, they are considered one device. One device going online will force the currently connected device offline. With automatic reconnection turned on, the device will be repeatedly forced offline and then become unavailable.
  • Make sure to keep the device certificate safe and do not flash one device certificate to more than one device.

X.509 certificate authentication

This feature is not generally available currently. If you are interested in it, submit a service ticket.

One-model-one-key authentication mechanism

This feature is not generally available currently. If you are interested in it, submit a service ticket.

Gateway sub-device authentication

A sub-device must be connected to a gateway before it authenticates itself with the Tuya Developer Platform.

A gateway is a physical device or software application. Basically, there are two types of gateway, ordinary gateway devices as well as smart devices with built-in gateway capability such as smart speakers, TVs, and sockets.

A gateway can enable messaging in two directions:

  • Messaging between gateway and cloud: A gateway can directly connect to the Tuya Developer Platform.
  • Messaging between gateway and sub-device: A gateway can translate the data sent by the sub-device and forward that data to the Tuya Developer Platform.

To help you deal with different use cases, three sub-device authentication methods are available. For more information, see Topology Management.

MQTT keep-alive

MQTT keep-alive is the maximum time interval that can elapse between the point a client finishes transmitting a control packet and when it starts to send the next packet. It is used to determine if the connection is still up.

You can set the keep-alive interval to 60 seconds. An interval of less than 60 seconds is not recommended. A timer starts when the device sends a CONNECT packet. When the Tuya Developer Platform receives a PING message, the timer is reset. If the Platform does not receive a message within 2.5 times the keep-alive interval, it will close the connection and declare the device offline.

For example, if the keep-alive interval is set to 60 seconds, the device is declared offline when it is not reachable within 150 seconds.

MQTT keep-alive does not apply to sub-devices because the connection status of sub-devices is determined by the keep-alive mechanism between the gateway and the sub-device.

Secure connection

TLS 1.2 is used for secure communication between the Tuya Developer Platform and devices. The SDK comes with the TLS implementation. However, resource-constrained devices may not run the TLS kit even though they are Ethernet-capable. In this case, you can connect them to the Tuya Developer Platform as a sub-device to the gateway.

If you want to implement the TLS protocol on your own, you need to download the root certificate. For more information about the usage of the root certificate, see Demo for C and Demo for Java.

MQTT standard protocol

The following table lists the MQTT topics by features. For more information, see MQTT Topics Overview.

Feature Topic
Messaging Properties, Actions, and Events
Device Connectivity
Device Management OTA Firmware Update
Monitoring and Operations Remote Configuration