TuyaMCU analyzer - UART packet decoder for Tuya devices - dpID detector

Here is a small program that allows you to analyze the content of TuyaMCU eavesdropped packets. The program shows the type, length and content of the packet, broken down into dpID variables, their types and values. The program allows you to quickly find out what the dpID we overheard contain - whether it is, for example, a dimmer value or, for example, a relay state, or maybe it is a voltage or current value. The program shown here is useful in the process of releasing a given IoT product from the cloud, because this process requires us to determine the available dpIDs for a given product, because these dpIDs are different for different products.

Related Topics
TuyaMCU is a UART-based protocol through which the WiFi module communicates with an additional microcontroller on board the device. In the case of devices with TuyaMCU, the WiFi module usually only reports data to the network, and the MCU itself supports relays, buttons, LCD or sensors and measuring systems.
For more details, I invite you to the topic about TuyaMCU itself: TuyaMCU protocol - communication between the microcontroller and the WiFi module
In addition, it is worth seeing examples of devices using TuyaMCU:
- WF-DS01 SmartLife/Tuya WiFi switch/dimmer for box - diagram
- EDM-01AA-EU 300W dimmer for BK7231 and TuyaMCU - configuration
- HomeMate Wi-Fi + Bluetooth Smart 4 Gang Touch Switch
- Tuya ATORCH AT4P(WP/BW) Smartlife Energy monitor (BK7231N) (C3BS) (CH573F) (BL0924)
- QIACHIP Universal WIFI Ceiling Fan Light Remote Control Kit - BK7231N - CB2S
- Energy-saving (?) battery door/window sensor for WiFi DS06

TuyaMCU packet capture
Capturing TuyaMCU packets is really very simple. One USB to UART converter is enough:

Just power from USB ( not from the web! everything should be unplugged ) our device, connect 5V from USB before the 3.3V LDO regulator on board, which will also provide a stable 3.3V for the WiFi module, and then solder with ground and signal wires on RX and TX. For example, for WB3S:

In the case of Tuya modules, the same UART is used to program the module via the bootloader and to communicate with TuyaMCU, which can sometimes be problematic. When changing the firmware, I often have to desolder the WiFi module in this case or break the path (and then reconstruct it).
UART is a bi-directional bus, so first we capture from the TuyaMCU TX line -> WiFi RX module, and then from the WiFi line TX module -> TuyaMCU RX

Capturing is easy to do in RealTerm:

It is best to choose hex with spaces (not binary):

Then you should enable writing to the file, so it's more convenient:

Capture Steps:
1. connect the USB to UART converter to the device, but do not connect the 5V from USB to its power yet (do not turn on the device)
2. start capturing, first e.g. from TuyaMCU TX line -> WiFi RX module
3. perform selected operations on the device
4. finish capturing
5. repeat points 1, 2, 3 and 4, but in point 2, connect to the WiFi line of the TX module -> TuyaMCU RX

I recommend doing separate packet captures for different operations, e.g.:
- separately for starting the device
- separately, e.g. for dimmer status changes (changes in brightness level)
- separately for on/off
- separately for other settings (if available), e.g. in the case of devices with energy measurement, it is worth doing a separate capture for different voltages and saving these voltages, then you can compare packets on this basis and look for where the voltage value is saved, etc. Same with power - do a capture when measuring the load 30W and then 100W, etc.

Using two USB to UART converters it could be improved, but it would also be nice to have some software that saves communication from two COM ports at once.

TuyaMCU analyzer
The program can be downloaded from Github, already in compiled form:
https://github.com/openshwprojects/TuyaMCUAnalyzer
After running the program, we already have a sample package entered:

To the field Raw packet data we can paste the hex record of packets captured by, for example, Realterm. The system allows spaces and transitions to the next line between hex codes, this is used to increase readability.
Field Tuya packets display shows each packet twice - first it breaks its bytes into divisions according to their role and colors them, and below it gives their roles and interpretations.
Plus a section List of automatically detected variable IDs contains a summary of detected dpIDs along with their captured values. This can help, for example, in determining which value is, for example, the brightness level of the dimmer, i.e. it usually has values from 0 to 1000. On the other hand, the relay states can only be 0 or 1.

In addition, the program offers a set of sample packages loaded from the folder samples , they are available in this menu:

The .bin extension means a binary file, with packets as bytes, while .txt means a text file, where packets are already saved as hex codes (already in ASCII, human readable).

Also, there is a bookmark Compare tool , which is a tiny tool useful for determining what has changed in the packages when, for example, we changed the color of the lamp (e.g. the Miboxer led strip controller uses TuyaMCU):

The program treats each line as a separate packet. If the given byte in each line is the same, it is highlighted in green, otherwise it is in red.


Some examples
Examples are included in the samples directory. Here is a short presentation of some of them.
Dimmer from TuyaMCU:

The above packets were intercepted on the line WiFi module TX -> TuyaMCU RX. Here in the summary you can see that dpID 1 of type bool has values 1 and 0, that is, the state of the switch, on or off. In turn, dpID 2, of the value type, has values from 0 to 570, which is probably a dimmer. 570 is the maximum value recorded during the tests, while you can guess from this that the full brightness of the light is 1000, as usual.
Thermometer/Hygrometer/Clock/Calendar TH06:

This set of packets shows how the WiFi module sends time to the main MCU from TH06. On the other hand, broadcast by the MCU we have:

The MCU supports the thermometer and hygrometer, so it sends these measurements to the WiFi module. The temperature is multiplied by 10, because the values here must be integers, and the manufacturer wanted to support up to one digit after the decimal point.

What does the program not help with?
Basically, there is one situation where this program cannot help. Some of the more advanced Tuya electricity meters (higher-end, already DIN rail, in the price range of PLN 100 or more) use TuyaMCU to report measurements, but often report a group of measurements in one dpID. Then such a dpID is of the Raw type (no longer Value) and contains several bytes in which (depending on the device) data such as the current value of voltage, current, power, sometimes frequency are stored. Such a raw package has a device-dependent format and it is difficult to decode it more universally.
Cheaper products with energy measurement, in turn, do not use TuyaMCU, rather BL0937 or BL0942 are directly connected to the WiFI module there.

Application for OpenBeken
This analyzer allows you to set up quickly OpenBeken to work on your device with TuyaMCU. Here it is autoexec.bat from the OBK. These scripts map values from TuyaMCU (those dpID) to OBK variables and allow further processing of these values, determine how values are displayed on the web panel, etc.:


- EDM-01AA-EU dimmer

dpID 1 is a bool type, it is the on/off state of the light. dpID 2 is value, value from 1 to 1000 is dimmer level.


- QIACHIP Universal WIFI Ceiling Fan Light (fan and light)

Here dpID 1 is bool, it turns the fan on and off. dpID 9 is the state of the light - on or off, also boolean. dpID 3 is the fan speed - three possible values, 0, 1, 2, low, mid or high. Next, dpID 6 is the setting of the timer (countdown) after which the device will turn off, this timer already supports the MCU. Then dpID 7 is the read only variable, the current value of the countdown timer. There is also dpID 17, which controls the sound signal when configured, e.g. from the RF remote control (on or off)


- configuration TH06 hygrometer/LCD/calendar

Here, dpID 2 is the humidity level, and dpID 1 is the temperature, where the temperature is multiplied by 10 because val is an integer type and the manufacturer wanted to transfer values of the type 20.5 degrees


- BlitzWolf BW-AF1 fryer:

About the fryer topic is here:
https://www.elektroda.pl/rtvforum/topic3958909.html#20448156


- ATORCH AT4P(WP/BW) energy monitor meter:

Without much comment, but here it is clear how many different variables can be available, usually in the form multiplied by 10 or 100 (or even 1000) to push numbers with a decimal point as integers.

Summary
The program was written quickly, even "on the knee" but turned out to be really very useful. Thanks to it, I can quickly analyze the captured data from Tuya products, see what dpIDs are used and what their values look like. Syntax coloring (specific bytes) from the package also speeds up the whole process, and for me it greatly increases their readability.