Tuya MQTT Standard Protocol

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.

Gateway

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.

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

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

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.

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.

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.

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	Topology Management Sub-Device Goes Online or Offline
Device Management	OTA Firmware Update
Monitoring and Operations	Remote Configuration