" %}
### Software Development
In the process of hardware debugging, the user saw that the module and the MCU have a series of serial protocol protocol interaction data. For the understanding of these data, please refer to the protocol document in the development kit.
The agreement is mainly divided into two parts: the basic agreement and the functional agreement. The basic protocol has nothing to do with the product. It is a common protocol of the module, including module initialization instructions and some extended function instructions. The function protocol part is mainly based on the command word of the report of the basic protocol, and has explained the DP data content format in detail. The complete content of the basic protocol, the document center is kept updated in real time, you can click the link to view: [Tuya Cloud Universal Serial Port Access Protocol](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/software-reference-wifi/tuya-cloud-universal-serial-port-access-protocol)
There are two ways for MCU to interface with Tuya module: transplant the MCU SDK or connect the protocol by yourself.
* Self-docking agreement
When MCU resources are limited or the MCU SDK is not suitable for porting, customers can choose to connect the serial port protocol by themselves. The detailed explanation of serial port protocol can refer to: [Protocol Analysis](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/protocol-reference-wifi/mcu-protocol)
* Porting MCU SDK
If the MCU resources are sufficient, it is generally recommended that users directly port the MCU SDK for efficient and convenient development. The MCU SDK in the development kit is a C-based protocol application code provided by Tuya, which can be directly added to the MCU project. The MCU SDK requires MCU hardware resources: 4K bytes of Flash; RAM is related to the length of the DP point data, about 100 bytes (if OTA function is required, it must be greater than 260 bytes); the number of function nesting levels is 9 levels. If users with insufficient resources can connect the protocol by themselves, the functions in the SDK package can still be used as a reference.
MCU SDK Porting Tutorial: [Overview of migrating Tuya's MCU SDK](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/software-reference-wifi/overview-of-migrating-tuyas-mcu-sdk)
### Functional debugging
After porting the MCU SDK code development, you can use the Tuya module debugging assistant-module simulation mode to verify the correctness of the MCU code. The usage method is similar to the MCU simulation mode. In the simulation module mode, the assistant will automatically send the initialization data stream to verify that the MCU response is correct and give corresponding prompts for the incorrect data. After the initial interaction is passed, you can manually click to test other extended functions.
**Note:** Tuya module debugging assistant module simulation mode, without networking function, only used to verify the correctness of MCU serial protocol transmission and reception. After the test is completed, the MCU can be connected to the actual module and network.
Debugging common tool links:
[Background log query entry](https://docs.tuya.com/en/iot/guidelines-for-platform/operation-center/operation#Log%20query%3A%20Use%20Behavior%20Query%20on%20a%20Single-Device%20Basis): IoT Workbench-Operation Center. You can query related device background log data based on the device ID.
[Tuya Online Support Portal](https://docs.tuya.com/en/iot/guidelines-for-platform/support-center/troubleshooting): Tuya provides online support services. If the problem documents cannot be answered, you can Ask questions directly online, and the professional and technical team will answer your questions.
[FAQ collection for open platform](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/faqs-wifi/tuya-question): develop common problems, understand them in advance, and avoid stepping into the pit.
## Appendix
### Video Tutorial
[Using Tuya MCU Scheme to Create Products](https://www.youtube.com/watch?v=oHU-Ry417Ys\&feature=youtu.be)
# Hardware Design Reference Wi-Fi
## TYWE1S Module & MCU serial communication instructions
### 1.Typical Application diagram
Diagram 1 Module self-processing mode
Diagram 2 MCU & Module cooperative processing mode
### 2.Design specification
1. Module power supply consumption: 3.3V/100mA, instantaneous current(5us) 450mA. Proposed supply current≥300mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3V3 pin as possible.
3. Serial port U1TX & U1RX are user interface. Default setting Baud rate: 9600, Data level: 8 bit, Stop bit: 1 bit, No check bit, No flow control. **If you need to use serial port 1 as a common IO port, please contact with the business.**
4. Serial port U0TX & U0RX are the interface related module printing, please don't link to user serial port
**U0TX pin can't be used as an ordinary IO port, please suspend.** **if need to use U0RX pin as an ordinary IO port, please contact with the business.**
5. TOUT pin is voltage collection pin, can't be used as an ordinary IO port. **If idle, plesase suspend.**
6. IO 0 participates in the module for normal startup, when the power is on, this pin's level needs the high level for normal startup. For the export, a pull-up resistor is recommended. For the import, the input level should be considered. If idle, it can be suspended processing.
7. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
8. The module also needs the button and Wi-Fi status indicator. The button is used to clear network information of the module. The indicator is used to indicate the current status of the Wi-Fi module. If choose the module self-processing mode, refer to Diagram 1. If choose MCU & Module cooperative processing mode, refer to Diagram 2. Mode instructions can refer to "3.3 Query module work mode of MCU settings" in "Tuya general serial communication protocol".
9. If MCU supply voltage is 3.3V, circuit section about the signal level conversion in the reference diagram can be omitted.
10. Other idle pins can be suspended processing.
11. For Diagram 3, the antenna is susceptible to the shadow part of the package, don't wire and cover with copper, so as not to affect the antenna performance.
12. The exposed measuring point is located on the back of the module, as shown in Diagram 3 - The purple ring of TYWE1S recommended packaging. Please pay attention to avoidance when wiring. **Note: if need to recommend package, download it online or achieve it from the business.**
### 3.Antenna area instructions
Diagram 3 The shadow part is susceptible area for antenna, please don't wire and cover with copper. If the structure allows, please empty this area of PCB, so as not to affect the antenna performance.
## TYWE3S Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 Module self-processing mode
Diagram 2 MCU & Module cooperative processing mode
### Design specification
1. Module power supply consumption：3.3V/100mA, instantaneous current(5us) 450mA. Proposed supply current≥300mA.
2. Power filter capacitor C1 & C2 should be distributed as close to VCC pin as possible.
3. Serial port TXD & RXD are communication ports. At startup, there will be a lot of module information data output. Default setting Baud rate: 9600, Data level: 8 bit, Stop bit: 1 bit, No check bit, No flow control.
4. ADC pin is voltage collection pin, can't be used as normal IO function. If idle, it needs to be suspended.
5. IO 0 participates in the module for normal startup, when the power is on, this pin's level needs the high level for normal startup. For the export, a pull-up resistor is recommended. For the import, the input level should be considered. If idle, it can be suspended processing.
6. IO 2 participates in the module for normal startup, when the power is on, this pin's level needs the high level for normal startup. The default mode is module debugging port, and data output is available on the upper current. If idle, it can be suspended processing.
7. IO 15 participates in the module for normal startup, When the power is on, the pin's level needs the low level for normal startup. You need to add a pull-down resistor to your pin.
8. RST pin is module hardware reset pin, reset under the low level. For use, it can be directly connected to MCU's IO port without external circuit.
9. **Please note that there is no pull-up resistor inside of IO16 when used**
10. The module also needs the button and Wi-Fi status indicator. The button is used to clear network information of the module. The indicator is used to indicate the current status of the Wi-Fi module. If choose the module self-processing mode, refer to Diagram 1. If choose MCU & Module cooperative processing mode, refer to Diagram 2. Mode instructions can refer to "3.3 Query module work mode of MCU settings" in "Tuya general serial communication protocol".
11. If MCU supply voltage is 3.3V, circuit section about the signal level conversion in the reference diagram can be omitted.
12. The pins 9-14 need to be suspended, and other idle pins also need to be suspended.
13. Figure 3 the ANTENNA part is the position of antenna, which is forbidden to cover the copper & wire. It's better to empty this area of PCB, so as not to affect the antenna performance.
### Packaging instructions
Diagram 3 TYWE3S boundary dimension
**Note：if need recommended packaging, download from Internet or contact with the business.**
## Serial Port Communication Between the TYLC4 Module and MCU
### Typical Application Diagram
Figure 1-1 and Figure 1-2 show communication between the TYLC4 module and MCU in Wi-Fi module processing mode. Figure 1-3 and Figure 1-4 show communication between the module and MCU in cooperative processing mode.
S1 indicates the Wi-Fi module reset button, and LED1 indicates the Wi-Fi module status indicator. The following table lists the default mAppings between the LED1 status and working status of the Wi-Fi module.
| **LED1 Status** | **LED1 Display** | **Wi-Fi Module Status** |
| --------------- | --------------------------------------- | -------------------------- |
| Blinks quickly | Flashes on and off at 250 ms intervals | SmartConfig mode |
| Blinks slowly | Flashes on and off at 1500 ms intervals | AP mode |
| Steady on | Steady on | Connected to a router |
| Steady off | Steady off | Disconnected from a router |
Figure 1-1 Communication between the TYLC4 module and a 5 V MCU in Wi-Fi module processing mode
Figure 1-2 Communication between the TYLC4 module and a 3.3 V MCU in Wi-Fi module processing mode
Figure 1-3 Communication between the TYLC4 module and a 5 V MCU in cooperative processing mode
Figure 1-4 Communication between the TYLC4 module and a 3.3 V MCU in cooperative processing mode
### Design Description
1. The voltage and current for the Wi-Fi module to work properly are 3.3 V and 100 mA, respectively. It is recommended that the current be 300 mA or higher and that the total capacitance of external filter capacitors be more than 10 μF when the voltage is 3.3 V. When the Wi-Fi module is transmitting or receiving RF signals at 3.3 V, the current is increased by over 50%.
2. When designing the PCB layout, ensure that the filter capacitors C1 and C2 are as close to the VCC pin as possible.
3. The default settings for connections between the serial ports (TXD and RXD) and MCU are as follows:
Baud rate: 9600
Data bit: 8
Stop bit: 1
Parity bit: none
Flow control: none
For details, see *Tuya General Serial Port Communication Protocols*. When the Wi-Fi module is powered on, the TXD pin prints the module startup information. Skip the information during module startup. To use the serial port as a common I/O port, contact Tuya R\&D personnel.
4. The RST pin resets the module at low level. To use the RST pin, connect it to the I/O port of the MCU and low level input.
5. To use the module, you need a button and Wi-Fi status indicator.
The button (S1 in Figure 1-1 and Figure 1-2) is used to clear the module's network configuration. You can use the smart product's network connection button.
The indicator (LED1 in Figure 1-1 and Figure 1-2) indicates the working status of the Wi-Fi module or smart product.
For details about the processing modes, see section 3.3 in *Tuya General Serial Port Communication Protocols*.
6. If the input voltage of the MCU is 3.3 V, skip signal level conversion in Figure 1-1 and Figure 1-3.
7. Other idle pins can be vacant.
## TYWE2S Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V, instantaneous current (5us) 451mA. Proposed supply current≥600mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYJW1 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
!\[image.png]
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 5V, instantaneous current(5us) 451mA. Proposed supply current≥600mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 5V pin as possible.C1 & C2≥10uF.
3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYJW2.0 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 5V, instantaneous current(5us) 451mA. Proposed supply current≥600mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 5V pin as possible.C1 & C2≥10uF.
3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYJW2.1 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 5V, instantaneous current(5us) 451mA. Proposed supply current≥600mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 5V pin as possible.C1 & C2≥10uF.
3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYJW2S-3.3V Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V, instantaneous current(5us) 451mA. Proposed supply current≥600mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYJW2S-5V Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 5V, instantaneous current(5us) 451mA. Proposed supply current≥600mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 5V pin as possible.C1 & C2≥10uF.
3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## WR1 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WR1E Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WR2 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WR2E Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WR3 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WR3E Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WR4 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WRG1 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum constant current295mA. Proposed supply current≥400mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WBR1 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum instant current is 324mA. Proposed supply current≥500mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WBR1D Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum instant current is 392mA. Proposed supply current≥500mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WBR2 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specificationi
1. Module power supply consumption: 3.3V,the maximum instant current is 324mA. Proposed supply current≥500mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WBR2D Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum instant current is 392mA. Proposed supply current≥500mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WBR3 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum instant current is 324mA. Proposed supply current≥500mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## WBR3D Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1. Module power supply consumption: 3.3V,the maximum instant current is 392mA. Proposed supply current≥500mA.
2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
# Software Reference Wi-Fi
###
# Tuya Cloud Universal Serial Port Access Protocol
| Protocol version | Date |
| ---------------- | -------- |
| 1.2.3 | 20200521 |
### 1、Serial communication conventions
Baud rate: 9600/115200
Data bits: 8
Parity: None
Stop bits: 1
Data flow control: None
MCU: User control board control chip, connected with Tuya module through serial port.
### 2、Frame Format Description
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | Fixed at 0x55aa |
| Version | 1 | Upgrade and Expansion |
| Command word | 1 | Specific frame type |
| Data Length | 2 | Big Endian |
| Data | N | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Explanation:
* All data larger than 1 byte is transmitted in big-endian mode.
* Under normal circumstances, the same command word is used to send and receive synchronization mechanism, that is, one party sends a command and the other responds. If the sender does not receive the correct response packet after timeout, the timeout is transmitted, as shown in the figure below:
Note: The specific communication method is subject to the "Protocol Details" section.
* The module control command is issued and the MCU status is reported in asynchronous mode. Assuming that the module control command is issued with the "command word" as x and the MCU status is reported with the "command word" as y, as follows:
* Module control command is issued:
* MCU status report:
### 3、Protocol details
### 3.1、Heartbeat detection
Explanation:
1. After the WIFI module is powered on, it periodically sends heartbeats at 15s intervals. If no response is received from the MCU within the timeout period (3s), the MCU is considered offline.
2. The MCU can also periodically check whether the module is working properly based on this heartbeat. If the module is issued without a heartbeat, the MCU can reset the WIFI module through the hardware reset pin provided by the module.
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x00 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 00 0000 ff
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x00 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x00: The first heartbeat return value after the MCU restarts, sent only once, used by the module to determine whether the MCU restarts during the work process. Return this value |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 00 0001 00 03 (MCU returns for the first time)
0x55aa 03 00 0001 01 04 (except for the first time, return normally)
### 3.2、Query Product Information
Explanation:
1. Product ID: Corresponds to the Tuya Developer Platform PID (product identification), which is generated by the Tuya Cloud Developer Platform and used to record product-related information in the cloud.
2. Product information consists of product ID and MCU software version
3. MCU software version number format definition: in dotted decimal form, "x.x.x" (0 \ <= x \ <= 99), x is a decimal number
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x01 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 01 0000 00
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x01 |
| Data Length | 2 | N |
| Data | N | {“p”:”AIp08kLIftb8x2x0”,“v”:”1.0.0”,”m”:1,”mt”:10,”n”:0,”ir”:”5.12”,”low”:0} |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: {“p”:”AIp08kLIftb8x2x0”,“v”:”1.0.0”,”m”:1,”mt”:10,”n”:0,”ir”:”5.12”,”low”:0}
Product information field description:
1\) p means the product ID is AIp08kLIftb8x2x0, which is the product ID created by the user on the Tuya IOT platform.
2\) v indicates that the MCU version is 1.0.0, and the MCU version number format needs to be defined in the format of x.x.x
3\) m indicates the working mode of the module: 0-normal distribution network working mode, 1-overtime distribution network working mode, 2-anti-mistouch working mode.
**normal distribution network working mode:** After leaving the factory, the module has been in the state of network distribution and has been maintained.
**overtime distribution network working mode:** The module is in a non-distribution state after it is powered on from the factory and requires the MCU to send a reset command before entering the corresponding distribution mode The device will enter the non-distribution state again after the module is in the distribution state for three minutes without the user distributing the module. The command will re-enter the network configuration mode.
**anti-mistouch working mode:** After the module is configured by the user locally (the MCU sends a reset command), the device is in the network to be configured If the status is not configured for three minutes, it will automatically restore the user's network connection before reset. The device breaks abnormally halfway after local reset Power on will also automatically restore the user's network connection before reset. In this mode, only when the device is moved from the APP by the user Except for the device, it will not record the last user's network connection and reconnect. This mode is for users who need local reset The needs of the scene.
4\) mt field (optional): Set the state switching time of safe mode and anti-mistouch mode, without uploading this field, follow the old mechanism Three minutes processing, can support the set time range: 3 minutes \~ 10 minutes.
5\) n field (optional): indicates the network configuration mode of the mode. Without this field, the traditional two-network mode switching mode is maintained: 0-smartconfig & AP coexistence distribution network mode The module supports both AP connection and EZ distribution without user switching. For the corresponding distribution status package, see 1-Only AP configuration mode In this mode, the product can only be configured through AP connection.
6\) ir field (optional): enable the infrared function of the module and inform the module that the infrared transceiver pins use those IO ports. Without this field, the infrared capability is turned off by default 5.12: the infrared transmit pin is IO5, and the infrared receive pin is IO12. Note that if the module self-processing mode is used in the working mode, do not repeat it with the IO port set according to the WIFI indicator light. Part of the module cross-group IO setting, you need to add 32 to the base of the setting group IO, PB20 set the serial number to 20+32. The infrared sending pin needs to use PWM resources, and the receiving needs to use IO interrupt. The specific module supports the IO port reference module information.
7\) low field (optional): Whether the module is turned on to maintain a low-power mode for long connection, without this field, the low-power mode is turned off by default. For some products, when there is no network control, the average power consumption of the module needs to be lower than 15MA under the connection of the module to maintain and route. Through this field, we can open the ability of the module. After the dual-mode module turns on this function, the module has only the Bluetooth distribution function, and the Bluetooth control will be turned off. Products that do not require power consumption do not need to care about this field. 0-turn off low power mode 1-Turn on the module low power mode
### 3.3、Query MCU and set the module's working mode
Explanation:
1. The module working mode is mainly for how to indicate the working status of WIFI and how to reset WIFI. There are mainly two cases:
a. MCU cooperates with the module, that is, the module notifies the MCU through the serial port The current working status of WIFI is supported by the MCU; the MCU detects the need to reset the WIFI and informs the module to reset the WIFI through the serial port.
b. Module self-processing: The working status of the WIFI module drives the LED status display through the WIFI GPIO pins; WIFI reset is handled by detecting the GPIO input requirements. The module's self-processing WIFI reset method is: WIFI detects the GPIO entry low level for more than 5s to trigger Wi-Fi reset. The GPIO pins used by the indicators and buttons are configured by the following commands.
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x02 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 02 0000 01
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x02 |
| Data length | 2 | 0x0000 / 0x0002
0x0000: Instruct the module to work in "MCU and module cooperative processing" mode. The MCU must implement the functions mentioned in the "Description" above.
0x0002: Instruct the module to work in "module self-processing" mode.
|
| Data | 0/2 | The data length is 2: the first byte is the WIFI status indication GPIO sequence number; the second byte is the WIFI reset button GPIO sequence number |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 02 0000 04 (MCU and module work together)
0x55aa 03 02 0002 0c0d1f (module self-processing, indicator 0x0c: GPIO12, reset button 0x0d: GPIO13)
### 3.4、Report device networking status
| Device Networking Status | Description | Status Values |
| ------------------------ | -------------------------------------------------- | ------------- |
| Status 1 | smartconfig configuration status | 0x00 |
| State 2 | AP configuration state | 0x01 |
| State 3 | WIFI is configured but not connected to the router | 0x02 |
| State 4 | WIFI is configured and connected to the router | 0x03 |
| Status 5 | Connected to the router and connected to the cloud | 0x04 |
| State 6 | WIFI device is in low power mode | 0x05 |
| State 7 | WIFI device is in smartconfig\&AP mode | 0x06 |
Explanation:
1. Device networking status: 1 smartconfig configuration status 2 AP configuration status 3 WIFI configured successfully but not connected to the router 4 WIFI configured successfully and connected to the router 5 The device is connected to a router and connected to the cloud. The corresponding LED displays of the "module self-processing" working mode are: 1 250ms flashing interval; 2 1500ms flashing interval; 3 long dark state; 4 or 5 long bright state
2. When the module detects the process of MCU restart or MCU disconnection and then online, it will actively send WIFI status to MCU
3. When the WIFI status of the module changes, it will actively send the WIFI status to the MCU
4. If the module working mode is set to "module self-processing", the MCU does not need to implement the protocol
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x03 |
| Data length | 2 | 0x0001 |
| Data | 1 | Indicate the working status of WIFI:
0x00: State 1
0x01: State 2
0x02: State 3
0x03: State 4
0x04: State 5
0x05: State 6
0x06: State 7
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 03 0001 00 03
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x03 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 03 0000 05
### 3.5、Reset WIFI
Explanation:
1. Reset WIFI status transition as shown below:
The module's self-processing WIFI reset method is: WIFI detects the GPIO entry low level for more than 5s to trigger Wi-Fi reset.
1. If the module working mode is set to "module self-processing", the MCU does not need to implement the protocol
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x04 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 04 0000 06
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x04 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 04 0000 03
### 3.6、Reset WIFI-select configuration mode
Explanation:
1. Compared to “Resetting WIFI” in section 3.5, this frame provides the MCU to selectively choose the configuration mode after resetting WIFI according to its own needs.
2. MCU access users can selectively implement the protocol
3. If the module working mode is set to "module self-processing", the MCU does not need to implement the protocol
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | -------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x05 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x00: Enter smartconifg configuration mode
0x01: Enter AP configuration mode
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 05 0001 00 08, enter smartconfig configuration mode
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x05 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 05 0000 04
### 3.7、Command issued
Explanation:
1. The datapoint command / status data unit is as follows:
| Data Section | Length (byte) | Explanation | | | |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----- | ----------------------------------- | -------------------------------------------------------------- |
| dpid | 1 | datapoint serial number | | | |
| type | 1 | Corresponds to the specific data type of a datapoint on the open platform, identified by the following "representation value" | | | |
| | | Type | Value | Length (bytes) | |
| | | raw | 0x00 | N | Corresponds to raw datapoint (module transparent transmission) |
| | | bool | 0x01 | 1 | value range: 0x00 / 0x01 |
| | value | 0x02 | 4 | Corresponds to int type, big-endian | |
| | | string | 0x03 | N | corresponds to a specific string |
| | | enum | 0x04 | 1 | Enumeration type, range 0-255 |
| | | bitmap | 0x05 | 1/2/4 | |
| len | 2 | Number of bytes corresponding to length | | | |
| value | 1/2/4 / N | hex indicates that big-endian transmission is used for more than 1 byte | | | |
1. Datapoint command / status data unit except "raw" type, other types are "obj" type datapoint
2. The "command delivery" may contain multiple datapoint "command data units"
3. "Command Issue" is an asynchronous processing protocol, corresponding to the "status report" of the MCU's datapoint
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x06 |
| Data length | 2 | Depends on Command Data Unit type and number |
| Data | N | "3.7.1 Command Data Unit" Group |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: The system switch corresponds to DP No. 3, using a bool-type variable, and the power-on value is 1.
0x55aa 00 06 0005 03 01 0001 01 10
### 3.8、Status report
Explanation:
1. For details of the datapoint status data unit, see "Section 3.7"
2. "State Report" is an asynchronous processing protocol. There are three types of "State Report" trigger mechanisms:
a. When the MCU receives the "command to issue a processing frame, the corresponding datapoint command is correctly executed, and then the changed datapoint status is sent to the module through the" status report "frame;
b. The MCU actively detects a change in the datapoint and sends the changed datapoint status to the module;
c. When the MCU receives the status query frame of “3.9”, it sends all datapoint status to the module.
3. The "status report" may contain multiple datapoint "command data units"
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x07 |
| Data length | 2 | Depends on the type and number of Status Data Units |
| Data | N | "3.7.1 Status Data Unit" Group |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: The humidity corresponds to No. 5 DP, using a valve-type variable, and the humidity is 30 ° C
0x55aa 03 07 0008 05 02 0004 0000001e 3a
### 3.9、Status query
Explanation:
1. "Status query" is an asynchronous processing protocol, which is mainly used by the module to query the status of all "obj" type datapoints of the MCU. When the MCU receives this frame, it reports the datapoint status through the "3.8" status report frame
2. There are two main timings for sending "Status Query":
a. The module is powered on for the first time, and after the connection is established with the MCU through the heartbeat, the query is sent;
b. During the module's work, it is detected that the MCU restarts or goes offline and then goes online. The query is sent.
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x08 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 08 0000 07
### 3.10、MCU upgrade service
Explanation:
1. When to upgrade the customer The Tuya IoT platform ’s own product page configuration related upgrade options are triggered. The module is only used as a data transmission channel to support MCU upgrades and does not perform any analysis of the data content.
2. At present, the MCU upgrade of Tuya platform supports the following four configuration methods:
a.App reminder upgrade: In this upgrade method, users will receive the pop-up window of the upgrade reminder every time they enter the device control panel. Whether to confirm the upgrade is confirmed by the user in the App.
b.App silent upgrade: This upgrade method App will not have any pop-up window. The firmware will automatically detect the upgrade within one minute after the firmware is powered on. It will automatically start pulling related upgrade packages if it finds a higher version upgrade package. After power-on, the module will go to the cloud to check whether there is an upgrade package configuration at an interval of 24 hours.
c.App forced upgrade:In this upgrade method, there will be an upgrade reminder pop-up on the App side. If the user does not confirm the upgrade, the user cannot use the control panel of this product normally.
d.App detection upgrade: this upgrade method App sideThere will not be any pop-up window for upgrade reminder. The user must click on the App to check the relevant firmware version by himself. If there is a higher firmware configuration, the upgrade prompt message will be displayed.
3. MCU upgrade related flowchart:
After the WIFI module sends all the upgrade packages, resend the 01 command word (3.2 query product information). The MCU needs to reply the software version number in the product information with the updated MCU version number in one minute. The version number needs to be configured in Tuya's background. Upgraded version numbers remain the same.
**3.10.1、Upgrade started (upgrade package size notification)**
Explanation:
1. The upgrade startup method includes automatic and manual upgrades. When it is in automatic upgrade, the module detects that the cloud MCU has a newer version of firmware, then it automatically starts the interaction process with the MCU upgrade package; when it is in manual upgrade, it is determined by the App that the module inspires the interaction process with the MCU upgrade package
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x0a |
| Data length | 2 | 0x0004 |
| Data | 4 | Firmware Package Bytes, unsigned int, Big Endian |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 0a 0004 00006800 75 (the firmware package length is 26624, which is 26KB)
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x0a |
| Data length | 2 | 0x0001 |
| Data | 1 | Upgrading packet transfer size:
0x00: default 256byte (compatible with old firmware)
0x01: 512byte
0x02: 1024byte
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 0a 0001 00 0d
**3.10.2、Upgrade package transmission**
Explanation:
1. Upgrade packet transmission data format: packet offset (unsigned short) + packet data
2. If the MCU receives the frame data length of 4 and the packet offset > = firmware size, the packet transmission ends.
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | -------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x0b |
| Data length | 2 | 0x0004 + Data packet length |
| Data | N | The first four bytes, fixed at the packet offset, followed by the packet content |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
example:
The file size to be upgraded is 530Byte, (the last packet of data may not be returned)
(1) The first packet of data, the packet offset is 0x00000000, and the packet length is 256
0x55aa 00 0b 0104 00000000 xx ... xx XX
(2) The second packet of data, the packet offset is 0x00000100, and the packet length is 256
0x55aa 00 0b 0104 00000100 xx ... xx XX
(3) The third packet of data, the packet offset is 0x00000200, and the packet length is 18
0x55aa 00 0b 0016 00000200 xx ... xx XX
(4) The last packet, the packet offset is 0x00000212, and the data packet length is 0
0x55aa 00 0b 0004 00000212 xx ... xx XX
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x0b |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 0b 0000 0d
### 3.11、Get System Time (GMT)
Explanation:
(1) Green Time does not include time zone and daylight saving time factors, and is an international standard time reference.
(2) When the local time stamp is calibrated before the module is connected to the network, it will return success with valid time data.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x0c |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 03 0c 0000 0e
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x0c |
| Data length | 2 | 0x0007 |
| Data | 7 | Data length is 7 bytes:
Data \[0] is the time success flag, 0 means failure, 1 means success
Data \[1] means year, 0x00 means 2000 Year
Data \[2] is the month, starting from 1 to 12
Data \[3] is the date, starting from 1 to 31
Data \[4] is the clock, starting from 0 to 23 ends
Data \[5] is minutes, starting from 0 to 59 and ends
Data \[6] is seconds, starting from 0 to 59 ends
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 0c 0007 01 10 04 13 05 06 07 4c (5: 6: 7 GMT on April 19, 2016)
### 3.12、Get local time
Explanation:
(1) Local time is based on GMT plus local time (where the device is activated) and daylight saving time.
(2) When the local time stamp is calibrated before the module is connected to the network, it will return success with valid time data.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x1c |
| Data length | 2 | 0x0000 |
| Data | xxxx | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x1c |
| Data length | 2 | 0x0008 |
| Data | Data | The length of the data is 8 bytes:
Data \[0] is the time success flag, 0 means failure, 1 means success
Data \[1] means year, 0x00 means 2000 Year
Data \[2] is the month, starting from 1 to 12
Data \[3] is the date, starting from 1 to 31
Data \[4] is the clock, starting from 0 to 23 ends
Data \[5] is minutes, starts from 0 to 59 ends
Data \[6] is seconds, starts from 0 to 15 ends
Data \[7] is days, from 1 Start to end of 7, 1 for Monday
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
example:
(1) If the device is activated and used in China, local time is Beijing time (Eastern District 8)
0x55aa 00 1c 0008 01 10 04 13 05 06 07 02 5f (Beijing time April 19, 2016 5: 6: 7PM)
(2) If the device is activated for use abroad, the local time is the time zone of the device
### 3.13、WIFI functional test (scan specified routes)
Explanation:
1. The module currently scans the specified SSID: tuya\_mdev\_test, and returns the scan result and signal strength percentage.
2. In order to prevent the defective products to the greatest extent, it is recommended that the customer control the distance between the router and the device to about 5 meters.
A signal strength of 60% or higher is qualified. Here you can adjust it according to your production line and factory environment.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x0e |
| Data length | 2 | 0x0000 |
| Data | None | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x0e |
| Data Length | 2 | 0x0002 |
| Data | 2 | Data length is 2 bytes:
Data \[0]: 0x00 failed, 0x01 succeeded;
When Data \[0] is 0x01, that is, Data \[1] indicates the signal strength (0-100, 0 signal is the worst, 100 signal is the strongest)
When Data \[0] is 0x00, which means failure, Data \[1] is 0x00 means that the specified ssid is not scanned, and Data \[1] is 0x01 indicates that the module has not flashed the authorization key
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.14、Get module memory
Description: Get the remaining memory of the WIFI module
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x0f |
| Data length | 2 | 0x0000 |
| Data | None | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x0f |
| Data length | 2 | 0x0004 |
| Data | 4 | Data length is 4 bytes, big-endian format:
Such as 0x00 0x00 0x28 0x00 represents the remaining 10240 bytes of memory
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.15、Turn on the function of obtaining weather data (optional)
Note: Turn on the function of obtaining weather data
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x20 |
| Data length | 2 | N ((L + K) + (L + K) ...) |
| Data | Data | L: Occupies 1 byte, indicating the length of K K: Request parameter name
For example: L: 0x06 K: w\.temp
L: 0x06 K: w\.pm25
L : 0x0a K: w\.humidity
L: 0x0b K: w\.condition
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | length (byte) | Description |
| ------------ | ------------- | ----------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x20 |
| Data Length | 2 | 0x0002 |
Data | 2 | Data \[0]:\
0x00 indicates failure. For the specific error reason, see the error code description of Data \[1]\
0x01 indicates success\
Data \[1]: \
0x00 No error\
0x01 error code, illegal data format\
0x02 error code, abnormal error | Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.16、Send weather data (optional)
Note: The weather data is issued. After the weather data function is turned on, the module will issue it regularly. After the function is turned on, it will be sent out immediately, followed by 30-minute intervals.
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x21 |
| Data length | 2 | N ((LKTLV) + (LKTLV) + ...) |
| Data | Data | 0x00: indicates failure
0x01: error code, indicates that the parameter service does not have permissions (confirm whether the parameter service is purchased)
0x01: indicates success
L: Parameter name length
K: Parameter name T: 0x00 integer, 0x01 character string
L: Field name length
V: Field value
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The MCU module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x21 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Remarks:
1. The request parameter list such as w\.temp, w\.pm25 returns w\.temp, and the returned parameters are less than the request parameters. Please check carefully that the request parameter names are correct.
2. The field value of w\.condition can refer to "Weather UTF-8 Code Comparison Table" or the following "W\.condition Weather UTF-8 Code Table"
example:
w\.humidity: 69, w\.temp: 32, w\.pm25: 10, w\.condition: cloudy (UTF-8 encoding E5A49A E4BA91)
55 AA 00 21 00 40 01 0A 77 2E 68 75 6D 69 64 69 74 79 00 04 00 00 00 45 06 77 2E 74 65 6D 70 00 04 00 00 00 20 06 77 2E 70 6D 32 35 00 04 00 00 00 10 0B 77 2E 63 6F 6E 64 69 74 69 6F 6E 01 06 E5 A4 9A E4 BA 91 1E
The weather UTF-8 code table for w\.condition is as follows:
| Text | hex encoding | text | hex encoding |
| ---------------------- | ------------------------------------------------ | -------------------- | --------------------------- |
| Sunny | E699B4 | Heavy Rain | E5A4A7 E99BA8 |
| Thunderstorm | E99BB7 E69AB4 | Sandstorm | E6B299 E5B098 E69AB4 |
| Light Snow | E5B08F E99BAA | Snow | E99BAA |
| Frost Mist | E586BB E99BBE | Heavy Rain | E69AB4 E99BA8 |
| Partial showers | E5B180 E983A8 E998B5 E99BA8 | Dust | E6B5AE E5B098 |
| Lightning | E99BB7 E794B5 | Light Shower | E5B08F E998B5 E99BA8 |
| Rain | E99BA8 | Sleet | E99BA8 E5A4B9 E99BAA |
| Dust tornado | E5B098 E58DB7 E9A38E | Ice particles | E586B0 E7B292 |
| Strong Sandstorm | E5BCBA E6B299 E5B098 E69AB4 | Yangsha | E689AC E6B299 |
| Light to moderate rain | E5B08F E588B0 E4B8AD E99BA8 | Mostly sunny | E5A4A7 E983A8 E699B4 E69C97 |
| Fog | E99BBE | Shower | E998B5 E99BA8 |
| Strong showers | E5BCBA E998B5 E99BA8 | Heavy Snow | E5A4A7 E99BAA |
| Heavy Rain | E789B9 E5A4A7 E69AB4 E99BA8 | Blizzard | E69AB4 E99BAA |
| Hail | E586B0 E99BB9 | Small to medium snow | E5B08F E588B0 E4B8AD E99BAA |
| Shao Yun | E5B091 E4BA91 | Snow showers | E5B08F E998B5 E99BAA |
| Zhongxue | E4B8AD E99BAA | Overcast | E998B4 |
| Ice Needle | E586B0 E99288 | Heavy Rain | E5A4A7 E69AB4 E99BA8 |
| Thunderstorm with hail | E99BB7 E998B5 E99BA8 E4BCB4 E69C89 E586B0 E99BB9 | Freezing rain | E586BB E99BA8 |
| Snow showers | E998B5 E99BAA | Light rain | E5B08F E99BA8 |
| Haze | E99CBE | Rain | E4B8AD E99BA8 |
| Cloudy | E5A49A E4BA91 | Thunderstorm | E99BB7 E998B5 E99BA8 |
| Medium to heavy rain | E4B8AD E588B0 E5A4A7 E99BA8 | Heavy rain | E5A4A7 E588B0 E69AB4 E99BA8 |
### 3.17、Status reporting (synchronous)
Explanation:
1. This command is a synchronous instruction. After the MCU data status is reported, you need to wait for the module to return the result.
2. Each time the sending module will respond, the WIFI module cannot report multiple times before it responds;
3. When the network is not good and the data is difficult to report in time, the module will fail after 5 and the MCU will need to wait more than 5 seconds.
4. For details of the datapoint status data unit, see "Section 3.7"
5. The "status report" may contain multiple datapoint "command data units"
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x22 |
| Data length | 2 | Depends on the type and number of Status Data Units |
| Data | N | "3.7.1 Status Data Unit" Group |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x23 |
| Data Length | 2 | 0x01 |
| Data | Data | 0x00: indicates failure
0x01: indicates success
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.18、Get the current WIFI signal strength (optional)
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x24 |
| Data length | 2 | 0 |
| Data | N | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ----------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x24 |
| Data length | 2 | 0x0001 |
| Data | Data | 0x00: indicates failure
less than 0: indicates signal strength, such as (-60db)
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.19、Notify WIFI module to turn off heartbeat (optional)
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x25 |
| Data length | 2 | 0 |
| Data | N | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x25 |
| Data length | 2 | 0 |
| Data | N | None |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Explanation:
For MCU modules that need to sleep to reduce power consumption, this command can be sent before sleep to turn off the heartbeat of the WIFI module, which is convenient for entering the sleep state. Do not send this command when the device is powered on. After the WIFI module is powered on, a heartbeat connection must be established with the MCU.
### 3.20、Serial port network interface (optional)
Explanation:
1. It can be used for Tuya App or Tuya App's SDK for independent development to obtain relevant distribution network parameters, and can send serial data to the module through the serial port to achieve the module's network distribution operation through serial communication.
2. The module must be in the network ready state to complete serial port network configuration.
3. After the module returns the response of successfully receiving the serial network configuration information, it will use the received information to connect to the route and activate it in the cloud.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x2A |
| Data length | 2 | xx |
| Data | Data | {"s": "xxx", "p": "yyy", "t": "zzz"} s: ssid p: password t: token, generated by the App |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x2A |
| Data Length | 2 | 0x0001 |
| Data | x | 0x00: Data received successfully
0x01: Not in the network status
0x02: json data is illegal
0x03: Other errors
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.21、Get the current WIFI network status
| Device Networking Status | Description | Status Values |
| ------------------------ | -------------------------------------------------- | ------------- |
| Status 1 | smartconfig configuration status | 0x00 |
| State 2 | AP configuration state | 0x01 |
| State 3 | WIFI is configured but not connected to the router | 0x02 |
| State 4 | WIFI is configured and connected to the router | 0x03 |
| Status 5 | Connected to the router and connected to the cloud | 0x04 |
| State 6 | WIFI device is in low power mode | 0x05 |
| State 7 | WIFI device is in smartconfig\&AP mode | 0x06 |
Note: Consistent with 3.4.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x2B |
| Data length | 2 | 0x0000 |
| Data | None | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x2B |
| Data length | 2 | 0x0000 |
| Data | x | 0x00: smartconfig configuration status
0x01: AP configuration status
0x02: WIFI is configured but not connected to a router
0x03: WIFI is configured and connected to a router
0x04: Connected to the router and connected to the cloud
0x05: WIFI device is in low power mode
0x06: WIFI device is in smartconfig\&AP mode
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.22、Sweeper map data service (optional)
Explanation:
1. The command of the sweeper stream service is not supported by all modules. The use of this service requires the use of a specific module to enable related services before it can be used normally.
2. This service is currently a service for the transmission of the map data of the sweeper, as a special shortcut channel for the sweeper and Tuya App map line.
3. The complete map data of the sweeper is distinguished by the map ID in the protocol. The data App of the same ID will think that this is a map data and will be accumulated.
4. The sweeping machine needs to move around the whole house during the cleaning process. Here, weak WIFI signals in some areas may cause data upload failure. At present, the module can cache 24 pieces of data under sufficient premise.
#### **3.22.1、Map Stream Data Transmission**
Explanation:
1\) The offset indicates the total length of data that has been sent before the map data MCU.
2\) The data content here can be up to 1024 bytes in the module serial port.
The data part of the data packet cannot exceed 1024 bytes, and the content of map data in each packet is recommended to be 512 bytes per packet.
3\) The map ID is used as a sign of a complete map data. The data transmission party needs to change the map ID to start a new cleaning after the completion of a completed cleaning, that is, the end of a map data. Generally, the map ID is performed in increments. Display local map ID. Changing the current map data display will clear the previous data and restart the display.
4\) After the data transmission is started, the module will stop sending heartbeat packets to ensure the priority transmission of map data. The subsequent modules will not actively resume the sending of heartbeat packets under the premise of continuous power.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ----------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x28 |
| Data length | 2 | 0x0006 + N |
| Data | 2 | Map ID number: The map ID number is used as the belonging identifier of a map data. |
| | 4 | Offset (the first packet is 0) |
| | N | Entity Data (Big Endian Mode) |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x28 |
| Data length | 2 | 0x0001 |
| Data | Data | 0x00: Success
0x01: The streaming service function is not enabled
0x02: The streaming server was not successfully connected
0x03: Data push timeout
0x04: The length of the transmitted data is wrong
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.23、WIFI functional test (connection specified route)
Explanation:
1. After the MCU sends the routing information to the module successfully, the module will use the relevant information to connect to the route.
2. The MCU here determines whether to connect to the router, according to the packet received in the module 3.4 protocol (state 4-WIFI is configured and connected to the router). Here it is judged that the failed MCU receives the return failure, or does not receive the status packet connected to the route for a long time (more than 15S) and considers it to have failed.
3. The production test can be re-sent to the production test and the test command can be resent. If no routing packet is received, it indicates that the module is in production test and needs to reset the module or send the test command to power on again.
4. The module needs to be connected to the network to complete the connection test.
5. Before the production test, the module's heartbeat package and product query package module must be initialized before entering the production test of the connection route.
6. The router name string length supports a maximum of 32 bytes, and the router password string length supports a maximum of 64 bytes.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ----------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x2C |
| Data Length | 2 | xxxx |
| Data | Data | {"ssid": "xxx", "password": "xxxxxxxx"} ssid: route name password: routing password |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x2C |
| Data length | 2 | 0x0001 |
| Data | 1 | The data length is 1 byte:
Data \[0]:
0x00 routing information reception failed:
(Please check whether the routing information packet sent is not the completed JSON packet data )
0x01 routing information received successfully (result please note the network status packet in 3.4)
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.24、Get module MAC
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x2d |
| Data length | 2 | 0x0000 |
| Data | None | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x2d |
| Data length | 2 | 0x0007 |
| Data | data \[0]:
Flag indicating whether the MAC address was successfully obtained:
0x00 indicates success, which means that the next 6 bytes of the MAC address are valid.
0x01 indicates that the MAC address failed, Indicates that the following 6 bytes of the MAC are invalid.
data \[1] \ \~ data \[6]: When the MAC address flag data \[0] is obtained, it indicates that the module has a valid MAC address.
| |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.25、Infrared status notification (optional)
| Device Infrared Status | Description | Status Value |
| ---------------------- | ------------------------ | ------------ |
| Status 1 | Sending Infrared Code | 0x00 |
| State 2 | Send infrared code end | 0x01 |
| State 3 | Infrared Learning Begins | 0x02 |
| State 4 | Infrared Learning End | 0x03 |
Explanation:
1. The infrared function is manually configured and sent samples by the Tuya IOT front desk configuration or the relevant project manager.
2. The time period of infrared code sending is very short and needs to maintain good real-time performance. Here the serial data is sent directly. No related retransmissions are performed.
3. According to their own development needs, customers can display related status according to the infrared status report.
4. Infrared code sending and receiving infrared codes need to use the two IO pins of the module. If the networking status of your device is also the module's self-processing mode, please note that the IO port should not be set with related IO pins.
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x2e |
| Data length | 2 | 0x0001 |
| Data | Data | Indicate infrared working status:
0x00: status 1
0x01: status 2
0x02: status 3
0x03: status 4
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x2e |
| Data length | 2 | 0x0000 |
| Data | None | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.26、Infrared enters production test (optional)
Explanation:
1. The infrared production test function can be entered only when the network is not configured.
2. The module enters the infrared learning state when it enters the infrared production test state.
3. Once the module enters the infrared production test mode, it will always be in the production test state and then send it out according to the learning data. When the module is equipped with the Internet or is powered off, it will exit the production test.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x2f |
| Data length | 2 | 0x0000 |
| Data | None | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x2f |
| Data length | 2 | 0x0001 |
| Data | Data | 0x00 indicates that the infrared transmission and reception production testing was successful
0x01 indicates that the infrared transmission and reception production test failed
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.27、Map streaming data transmission (supports multiple map data) (optional)
Explanation: 1) The commands of the sweeping machine streaming service are not supported by all modules. To use this service, you need to use a specific module to activate related services before it can be used normally. 2) This service is currently aimed at the data transmission of sweeper maps, and serves as a special shortcut for sweeper and graffiti APP map lines. 3) This channel is used for sweeping a map to show a sweeper machine with multiple data maps synthesized.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x30 |
| Data length | 2 | 0x0009+N |
| Data | 1 | Map service agreement version: 0x00 |
| | 2 | Map service session ID number: used as a sign for a map display |
| | 6 | BUF \[0] Sub-map ID number (a map session can be synthesized from multiple map data, such as a route map)
BUF \[1] Map ID data processing method 0x00: continue to accumulate 0x01: clear the data uploaded by the sub map ID number
BUF \[2] \~ BUF \[5] Submap data offset (the first packet is 0)
|
| | N | Entity data (big endian mode) |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x30 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x00：success
0x01：failure
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
### 3.28、File download service (optional)
Description: 1) This channel is used by customers to download and use application files other than MCU firmware. The files need to be uploaded to the Tuya product management background to be used with the corresponding version APP. 2) The firmware only performs the data transmission channel and does not do anything to the customer to download the file. The integrity check in the relevant file is handled by the user. 3) While the file is being downloaded, DP data can also be sent and uploaded normally. It is not recommended to do large amount of data communication during file download to affect the data download efficiency.
**3.28.1、Download start (file package size notification)**
Description: 1) Before the actual file is downloaded here, the module will first send the size of the file to be downloaded to the MCU as the download start notification. When the MCU confirms that the length of the packet is correct, it will start to pull the file package when the command packet is returned normally Otherwise, the process of pulling files will be interrupted and exited.
Module send:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x31 |
| Data length | 2 | 0x0004 |
| Data | 4 | File total bytes, unsigned int, big endian |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example: 0x55aa 00 31 0004 00006800 9C (file length 26624, or 26KB)
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x31 |
| Data length | 2 | 0x0001 |
| Data | 4 | File transfer size：0x00：256byte0x01：512byte0x02：1024byte |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example：0x55aa 03 31 0001 00 34
**3.28.2、File package transfer**
Description: 1) Upgrade package transmission data format: package offset (unsigned short) + package data 2) If the MCU receives the data length of the frame is 4 and the packet offset> = firmware size, the packet transmission ends
Description: 1) Upgrade package transmission data format: package offset (unsigned short) + package data 2) If the MCU receives the data length of the frame is 4 and the packet offset >= firmware size, the packet transmission ends
Module send:
| Field | Length (byte) | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x32 |
| Data length | 2 | 0x0004 + Packet length |
| Data | 4 | The first four bytes are fixed to the packet offset, followed by the data packet content |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
example:
The file size to be upgraded is 530Byte, (the last packet of data may not be returned)
(1) The first packet of data, the packet offset is 0x00000000, and the packet length is 256
0x55aa 00 32 0104 00000000 xx… xx XX
(2) The second packet data, the packet offset is 0x00000100, and the data packet length is 256
0x55aa 00 32 0104 00000100 xx… xx XX
(3) The third packet of data, the packet offset is 0x00000200, and the packet length is 18
0x55aa 00 32 0016 00000200 xx… xx XX
(4) The last packet, the packet offset is 0x00000212, and the data packet length is 0
0x55aa 00 32 0004 00000212 xx ... xx XX
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x32 |
| Data length | 2 | 0x0000 |
| Data | 0 | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Example：0x55aa 03 32 0000 34
### 3.29、Voice module related protocol (optional)
Description: 1) The protocols in this catalog apply to the universal docking of the voice module VWXR2 2) The general firmware of other non-voice modules does not have the relevant protocol functions in this directory
**3.29.1、Get voice status code (optional)**
Description:
1. The voice status code of the voice module will automatically return, and the MCU can also actively query.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x60 |
| Data length | 2 | 0x0000 |
| Data | 0 | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x60 |
| Data length | 2 | 0x0001 |
| Data | 1 | Voice status code:
0: idle;
1: mic mute state;
2: wake up;
3: recording;
4: recognition;
5: Recognition success;
6: Recognition failure;
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.29.2、mic mute setting (optional)**
Description:
1. The command word can be set to mute, or query the mute state.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x61 |
| Data length | 2 | 0x0001 |
| Data | 1 | Mute setting value:
0x00: mic on;
0x01: mic mute;
0xA0: query mute status;
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x61 |
| Data length | 2 | 0x0001 |
| Data | 1 | Mute state value:
0: mic is on;
1: mic is mute;
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.29.3、Speaker volume setting (optional)**
Description:
1. The command word can set the volume, and also can query the volume.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x62 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0-10：Volume value;
0xA0：query volume;
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x62 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0-10：Volume value; |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.29.4、Audio production test (optional)**
Description:
1. Audio production test is to record and broadcast while comparing the input and output audio signals of the module through acoustic instruments.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x63 |
| Data length | 2 | 0x0001 |
| Data | 1 | Audio production test value:
0x00: turn off the audio production test;
0x01: mic1 audio loop test;
0x02: mic2 audio loop test;
0xA0: query the current production test status;
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x63 |
| Data length | 2 | 0x0001 |
| Data | 1 | Current production value |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.29.5、Wake up production test (optional)**
Description:
1. After entering the wake-up test, it is required to play the wake-up word electrical signal for 10s, and return failure after 10s timeout.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x64 |
| Data length | 2 | 0x0000 |
| Data | 0 | |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | -------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x64 |
| Data length | 2 | 0x0001 |
| Data | 1 | Wake-up result returns
0: Wake-up failed;
1: Wake-up success;
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.29.6、extensions**
Description: Expand the relevant system functions of the voice module
1\) Add status notification and settings for "Play/Pause, Bluetooth On/Off, Local Alarm, Voice Control Combination" function
"Play/Pause" function: play and pause functions of music, ancient poems, jokes, etc.;
"Bluetooth on/off" function: Bluetooth switch of Bluetooth speaker;
"Local alarm clock" function: synchronous notification of alarm data set by voice and APP;
"Voice control combination" function: notification of voice control instructions such as "previous song" and "next song";
**MCU function settings:**
MCU sends:
| Field | Length (byte) | Description |
| ------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x65 |
| Data length | 2 | N |
| Data | 1 | Subcommand：0x00 |
| | Data：
{“play”:true,”bt\_play”:true}
| play: play/pause function
true (play)/false (pause)
bt\_play: Bluetooth switch function true (on)/false(off)
MCU settings only support "play/pause" ""Bluetooth switch"
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x65 |
| Data length | 2 | 0x0002 |
| Data | 1 | Subcommand：0x00 |
| | 1 | Operation result:
0x00: success
0x01: failure
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**Status notification:**
Module sends:
| Field | Length (byte) | Description |
| ------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x65 |
| Data length | 2 | 1+N |
| Data | 1 | Subcommand：0x01 |
| | Data：
{“play”:true,”bt\_play”:true,” alarm”:”xxxx”,” ctrl\_group”:”xxxx”}
| play: play/pause function
true(play)/false(pause)
bt\_play: Bluetooth switch function
true(on)/false(off)
alarm: local alarm function
"xxx" is a character string
ctrl\_group: voice control combination function
"xxx" is a character string
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x65 |
| Data length | 2 | 0x0002 |
| Data | 1 | Subcommand：0x01 |
| | 1 | Operation result:
0x00: success
0x01: failure
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
#### 3.30、Module development service
**3.30.1、Turn on module time service notification**
Description:
1\) The MCU requires the module to re-power on every time to notify the MCU whether the time of the module has been calibrated in the cloud. Use this command to open the module's initiative to notify the MCU of the time data service required.
2\) After the module is powered on, the service is started. When the time is calibrated, the time service required by the MCU to actively notify the relevant time is selected, and the time data required by the relevant MCU is sent.
3\) If the module is not powered on, the service will not be restarted after the service is turned on. If the module is not restarted, you need to obtain the time and time.
4\) At present, the acquisition time protocol of 3.11 and 3.12, the time stamp of the module will not be calibrated immediately after connecting to the server. There is a time period that causes the MCU to retry to obtain the time every time it is powered on. This service can be activated after the module Proactively notify the MCU after time calibration
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0002 |
| Data | 1 | 0x01 (subcommand) |
| | 1 | 0x00: Green time
0x01: Local time
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0002 |
| Data | 1 | 0x01 (subcommand) |
| | 1 | 0x00: Service started successfully
0x01: Service started failed
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.30.2、Module Time Service Notification**
Description:
1\) The module chooses to send the corresponding time data according to the service of the open time notification sent by the MCU.
2\) The module power-on service is closed, and the MCU needs to re-send the open module time notification service
Module sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0009 |
| Data | 1 | 0x02 (subcommand) |
| | 1 | 0x00: Green time
0x01: Local time
|
| | 7 | The data length is 6 bytes
Data \[0] is the year, 0x00 means 2000
Data \[1] is the month, from 1 to 12
Data \[2] is the date 1 to 31 end
Data \[3] is the clock, from 0 to 23
Data \[4] is the minute, from 0 to 59 end
Data \[5] is the second , From 0 to 15 end
Data \[6] is week, from 1 to 7 end, 1 represents Monday
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The MCU returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x02 (subcommand) |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.30.3、Actively request weather service data**
Description:
(1) For some product needs, it is necessary to have the ability to actively obtain weather service data based on the weather service that is actively sent for half an hour.
We provide this command for users to actively obtain weather service interface data.
(2) The frequency of this command cannot be less than one minute, and multiple requests within one minute are processed only once.
(3) This command is used to confirm the data request, whether the data is issued or the command to send weather data through 0x21.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x03 (subcommand) |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0002 |
| Data | 1 | 0x03 (subcommand) |
| | 1 | Execution result:
0x00: success
0x01: failure
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.30.4、Open module reset status notification (optional)**
Description:
(1) At present, the module supports local removal, APP removal, and APP factory reset, but the MCU has no way to know the module.
Status notification This service is used for users who need to open the module status notification.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x04 (subcommand) |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
Module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0002 |
| Data | 1 | 0x04 (subcommand) |
| | 1 | Execution result:
0x00: success
0x01: failure
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
**3.30.5、Module reset status notification (optional)**
| Device reset status | description | State value |
| ------------------- | ------------------ | ----------- |
| State 1 | Module local reset | 0x00 |
| State 2 | APP remote reset | 0x01 |
| State 3 | APP factory reset | 0x02 |
Description:
(1) The transmission in the reset state will be retransmitted at most twice, and the retransmission interval remains 1s
Module send:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0002 |
| Data | 1 | 0x05 (subcommand) |
| | 1 | Reset status:
0x00: Module local reset
0x01:APP remote reset
0x02:APP factory reset
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
MCU return:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x34 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x05 (subcommand) |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
#### Bluetooth related functions (optional)
**Bluetooth functional test (scan specified Bluetooth beacons)**
Description:
(1) The module currently scans the specified Bluetooth beacon: ty\_mdev, and returns the scan result and signal strength percentage
(2) In order to prevent defective products to the greatest extent, it is recommended that customers control the distance from the equipment to about 5 meters.
Signal strength greater than or equal to 60% is qualified. Here you can adjust it according to your own production line and factory environment.
MCU sends:
| Field | Length (byte) | Description |
| ------------ | ------------- | --------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x03 |
| Command Word | 1 | 0x35 |
| Data length | 2 | 0x0001 |
| Data | 1 | 0x01 (subcommand) |
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x00 |
| Command Word | 1 | 0x35 |
| Data length | 2 | 0x0003 |
| Data | 1 | 0x01 (subcommand) |
| | 2 | The data length is 2 bytes:
Data \[0]: 0x00 fails, 0x01 succeeds;
When Data \[0] is 0x01, which means success, Data \[1] indicates the signal strength (0-100, 0 signal is the worst, 100 signal is the strongest);
When Data \[0] is 0x00, that is, failure, Data \[1] is 0x00 means the specified Bluetooth beacon is not scanned, and Data \[1] is 0x01 The module has not burned the authorization key
|
| Checksum | 1 | Byte-sum results from the beginning of the frame, 256 remainder |
# Overview of migrating Tuya's MCU SDK
### Introduction
The mcu\_sdk package contains the MCU code that is automatically generated based on product functions defined on the Tuya Smart platform. The communication and protocol resolution architecture is prepared and can be directly added to the original MCU project to quickly develop MCU programs.
### Precautions
The SDK package has the following requirements on MCU hardware resources:
* Flash memory: 4 KB
* RAM: tens of bytes (depending on the DP data length), or 260 KB or higher if the OTA upgrade function is required
* The number of nested functions is 9.
Users without sufficient resources can implement protocol interworking without using the MCU SDK.
### ile Structure
| **Execution File** | **Header File** | **Description** |
| ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| mcu\_api.c | mcu\_api.h | Contain Wi-Fi–related functions. Customers can invoke the functions on demand. |
| protocol.c | protocol.h | Protocol files that contain data processing functions. Users need to modify the two files based on project requirements. |
| system.c | system.h | Contain detailed implementation of the serial port communication protocol. |
| | wifi.h | Contains Wi-Fi–related macro definitions. |
### Roadmap
Step 1: Compile the MCU basic program and migrate the SDK file.
Step 2: Verify the macro definition in protocol.h.
Step 3: Migrate the protocol.c file and invoke functions.
Step 4: Optimize the DP data report and delivery functions.
Step 5: Optimize the network configuration and indicator functions.
Step 6: Optimize the product testing function.
#### Compile the MCU basic program and migrate the SDK file.
Add the .c and .h files in the mcu\_sdk folder and corresponding header file reference path to the original project. Initialize MCU-related peripherals, including the serial port, external interrupt (button), and timer (indicator blinking).
#### Verify the macro definition in protocol.h.
**Verify the product information**
(1) PRODUCT\_KEY is the product PID macro definition, the PID is the unique identifier of each product, which can be copied directly
Please ensure that the code is consistent with the product PID listed on the website, if not download the latest SDK development kit. The download location is as follows:(2) MCU\_VER is the software version, the default is 1.0.0. If the MCU needs the OTA function, the new MCU code version number needs to be increased.
(3) CONFIG\_MODE is the network distribution mode, with default (AP and smart switch between each other) mode, security mode, and anti-mistouch mode. It is recommended to select the "anti-mistouch" mode.
Description of three distribution modes: ++Default mode++: AP and smart switch between each other. If the module is not configured or the configuration is removed, it will be in the state of network configuration after power-on and will remain. ++Safe Mode++: The module is in a non-distribution state after it is powered on from the factory. The MCU needs to send a reset command to enter the corresponding distribution mode. When the device is in the distribution state for a period of time (default 3 minutes), it is not When the user configures, the module will re-enter the non-distribution network state, and it needs to receive the reset command again to re-enter the network distribution mode. ++Anti-mistouch mode++: After the module is successfully configured by the user, after the local (MCU sends a reset command) reset, the device is in the state of network configuration, and it has not been reconfigured after a period of time (default 3 minutes). The module will automatically restore the user's network connection before resetting. After the local reset, the device is powered off abnormally, and the user's network connection before reset will be automatically restored after power on. In this mode, only when the device is removed from the APP by the user, the device will not record the last user's network connection and reconnect.
When the security mode or anti-mistouch mode is selected, you can open the CONFIG\_MODE\_DELAY\_TIME macro definition and set the retention time of the distribution mode, the setting range is 3 \~ 10 minutes. If it is not turned on, the default value of 3 minutes will be set.
The smart mode and the smart mode AP of the distribution mode are switched by default, and only one mode can be used at the same time. If you want to use smart and AP coexistence mode, you can open the macro definition CONFIG\_MODE\_CHOOSE to set. When CONFIG\_MODE\_CHOOSE is set to 0, the network configuration mode is coexistence of smart and AP, and there is no need to switch the network configuration mode at this time. When CONFIG\_MODE\_CHOOSE is set to 1, the network configuration mode is only AP mode. Without opening the CONFIG\_MODE\_CHOOSE macro definition, the default configuration mode will be used.
**Check whether the MCU firmware needs to be upgraded**
If OTA upgrade of MCU firmware is required, enable the firmware update macro, which is disabled by default.
OTA upgrade needs to compile the bin file of the MCU code first (must be the bin file, also need to pay attention to increase the version number), and then configure the OTA upgrade on the platform, upload the bin file, then the APP will receive an upgrade reminder (silent upgrade will not Reminder) Click to agree to start the upgrade. After the upgrade is complete, restart the MCU. The module will query the MCU version number to verify whether the upgrade was successful. Several types of OTA (1) App reminder upgrade: In this upgrade mode, users will receive a pop-up window of the upgrade reminder every time they enter the device control panel. Whether to confirm the upgrade is confirmed by the user himself in the app (2) App silent upgrade: This upgrade method App will not have any reminder pop-up window, the firmware will automatically detect the upgrade within one minute after power on and find that there is a higher version of the upgrade package will automatically start to pull the relevant upgrade package After power-on, the module will go to the cloud every 24 hours to check whether there is an upgrade package configuration. (3) App mandatory upgrade: In this upgrade method, there will be an upgrade reminder pop-up window on the App side. If the user does not confirm the upgrade, the user cannot use the product's control panel normally. (4) App detection and upgrade: In this upgrade method, there will not be any pop-up window for upgrade reminder on the App side. Users must click on the relevant firmware version check on the App side. If there is a high-level firmware configuration, the upgrade prompt message will be displayed.
note: (1) OTA generally reads and writes flash. To ensure reliability, it is recommended to read the data just written after each write of flash data and verify the data to be written to ensure that the flash is written. Correctness. (2) It is recommended to add an OTA timeout detection to prevent the MCU from staying in the OTA data reception state when the OTA fails. (3) Each packet of OTA data has packet offset information. The packet offset can be used to detect whether the OTA data packet is heavy or missing.
**Define the transmitting and receiving buffers**
The size of the serial port receive buffer is affected by the frequency with which serial data processing is called. If the MCU processes the serial data faster, the serial port receive buffer size can be reduced appropriately; the serial port send buffer size should be greater than the longest DP data length of the data. The serial data processing buffer size should also be greater than the longest DP data length of the data, and the size should be adjusted according to whether the OTA function is required, whether weather services and the number of weather service types, and the number of days are required.
**(Mandatory) Define the working mode of the Wi-Fi module**
1\) If the distribution network trigger and indication are controlled by the MCU (the distribution button and LED are connected to the MCU end), select the "module and MCU co-processing" working mode (commonly used), please keep the WIFI\_CONTROL\_SELF\_MODE macro definition commented
2\) If the Wi-Fi indicator and buttons are connected to the Wi-Fi module (module self-processing working mode), please turn on the WIFI\_CONTROL\_SELF\_MODE macro definition, and then connect the indicator and the GPIO connected to the button according to the actual hardware Fill in the two lines below
**Check whether the Wi-Fi product testing function is enabled**
In order to ensure the final mass production efficiency and quality, it is recommended to open this macro.
Detailed production test process, you can view \[wifi general docking production test documentation]
**Weather service**
If you need the weather service function, you need to open the WEATHER\_ENABLE macro definition
The weather service needs to be opened after the module is successfully connected to the route. After successful opening, the weather data will be delivered after the module is connected to the cloud, and thereafter, it will be delivered every 30 minutes. The weather service also needs to select the type of weather, you can select the options in the array weather\_choose in the protocol.c file,
After selection, write the number to WEATHER\_CHOOSE\_CNT macro definition.
The module of the new firmware will support the weather forecast function for up to 7 days. The number of forecast days can be set in the WEATHER\_FORECAST\_DAYS\_NUM macro definition
When it is set to 1, it means that only the data of the day is obtained. When the setting value is 0 or> 7, the module will reply with an error message and the weather service fails to open. The weather data sent by the module will carry the information of the number of days, 0 means the day, and it needs attention here.
**Streaming service**
Streaming services are generally used for MCUs of the sweeper type, and are mainly used for the transmission of large amounts of data. If necessary, you can open WIFI\_STREAM\_ENABLE macro definition
**Other functions**
For other functions, if necessary, the user can open the corresponding macro definition and perfect related functions.
#### Migrating the protocol.c File and Invoking Functions
1. Use #include "wifi.h" in the files (for example, the main.c file) that require Wi-Fi–related files.
2. After MCU peripherals are initialized, invoke the wifi\_protocol\_init() function in the mcu\_api.c file.
3. Add the single-byte sending function of the MCU serial port to the uart\_transmit\_output function in the protocol.c file and delete #error. The following figure shows an example.
1. Invoke the uart\_receive\_input function in the mcu\_api.c file in the serial port receiving interrupt service function, and use the received characters as parameter input. The following figure shows an example.
1. Invoke the wifi\_uart\_service() function in the mcu\_api.c file after the MCU enters the while cycle. The following shows an example of code structure in main.c.
```
include "wifi.h"
...
void main(void)
{
wifi_protocol_init();
...
while(1)
{
wifi_uart_service();
...
}
}
```
Note: The MCU must directly invoke the wifi\_uart\_service() function in the mcu\_api.c file in while. After the program is successfully initialized, it is recommended that the serial port interrupt not be disabled. If the serial port interrupt must be disabled, ensure that the interrupt is disabled for only a short time to prevent serial port data loss. Do not invoke the report function in the interrupt.
#### Processing DP Data Report and Delivery Functions
There are 6 main types of dp (1) bool type: The bool type is generally the dp of some switches, such as switch, ECO, and screen display. (2) Enum type: The enum type is generally used as dp with various states, such as working mode, wind speed, wind swing position. (3) Value type: The value type is generally used as the value type dp, such as the set temperature value, current temperature value, and power. (4) Fault type: The fault type is generally used for fault reporting, and the data is usually performed in bitmap format. (5) String type: String is generally used as a string type dp, some dp need to be transmitted in the form of a string, you can use this type. There are some dp that are inconvenient to use bool, enum, value, fault type, this type can also be used. (6) Raw type: The raw type is generally used for data that needs to be transparently transmitted. There is no requirement for the data format. Plain text or encryption can be used. When using it, the sender and receiver must communicate the data format, package and parsing method.
**Reporting data of all DPs**
After the Wi-Fi module restarts or the network is reconfigured, the Wi-Fi module proactively delivers a status query command. The MCU needs to report the status of the device's DPs to the Wi-Fi module for synchronization. (1) Open protocol.c and locate the all\_data\_update(void) function. (2) Enter initial values of all DPs to be reported into corresponding report functions. The values will be displayed on the App control panel. Note: Do not invoke the all\_data\_update() function manually. This function is automatically invoked at a specific time.
**Reporting data of a single DP**
When the status of a DP is changed, the MCU proactively reports the new DP status to the Wi-Fi module, and the DP status displayed on the App will be updated accordingly. The report data format is mcu\_dp\_xxxx\_updata(DPID\_X,n). DPID\_X indicates the DP whose status has changed. Functions in all\_data\_update() can be independently invoked. Example:
```
mcu_dp_bool_update(DPID_SWITCH,1); //Boolean data reporting
mcu_dp_value_update(DPID_TEMPER_SET,25); //Value data reporting
mcu_dp_string_update(DPID_DAY,"1234",4); //String data reporting
```
**DP data delivery**
Each deliverable DP has an independent data delivery processing function in the protocol.c file. The function format is dp\_download\_xxx\_handle(), and xxx indicates a deliverable DP. After the function parses a DP, the MCU performs logical control in the corresponding position. The following shows an example of receiving switch data.The MCU uses MCU\_ON\_switch1() and MCU\_OFF\_switch1() to turn on and off a switch, respectively. When the device status is changed under non-App control, the MCU invokes mcu\_dp\_bool\_update(DPID\_SWITCH\_1,switch\_1) to upload the real status of the switch. Typically, the receiving processing function automatically invokes the function.
#### Optimize the network configuration and indicator functions.
Skip this section if processing by the Wi-Fi module is used. When protocol migration is successful, the network configuration command and indicator function need to be optimized for network configuration. In mode of cooperative processing by the Wi-Fi module and MCU, the MCU can select the network configuration triggering and indication modes based on actual requirements. Typically, network configuration is triggered by the Wi-Fi reset button and indicated by quick or slow blinking of the Wi-Fi indicator. We recommend that you enable both network configuration modes for your product. Smart network configuration mode: The operation is simple and convenient, and the Wi-Fi indicator blinks quickly. AP network configuration mode: Network configuration is reliable, and the Wi-Fi indicator blinks slowly.
**Network configuration command**
The network configuration command can be implemented by the mcu\_reset\_wifi() and mcu\_set\_wifi\_mode() functions. Typically, these two functions are invoked in the button processing function after the button is pressed for network configuration. After mcu\_reset\_wifi() is invoked, the Wi-Fi module is reset and the previous network configuration information is cleared. The function invoking also triggers a switchover between the AP and smart network configuration modes.
After mcu\_set\_wifi\_mode() with parameter SMART\_CONFIG or AP\_CONFIG is invoked, the network configuration information is cleared, and smart or AP network configuration mode is used. This function has the same function as the mcu\_reset\_wifi() function. You can select one as needed.
**Network configuration indication**
Typically, the mcu\_get\_wifi\_work\_state() function is invoked at while(1) to return the Wi-Fi status. Then, you write the indicator blinking mode in based on the Wi-Fi status.
| Device Network Connection Status | Description | Status Value | LED Indicator Status |
| -------------------------------- | ---------------------------------------------------------------------------- | ------------ | ------------------------------------------ |
| State 1 | Smart network configuration | 0x00 | The indicator blinks at 250 ms intervals. |
| State 2 | AP network configuration | 0x01 | The indicator blinks at 1500 ms intervals. |
| State 3 | The Wi-Fi is configured. However, the device fails to connect to the router. | 0x02 | The indicator is off. |
| State 4 | The Wi-Fi is configured, and the device successfully connects to the router. | 0x03 | The indicator is steady on. |
| State 5 | The device connects to the router and cloud. | 0x04 | The indicator is steady on. |
| State 6 | The Wi-Fi device is in low power consumption mode. | 0x05 | The indicator is off. |
| State 7 | The Wi-Fi device is insmartconfig\&AP consumption mode. | 0x06 | TThe indicator blinks at 250 ms intervals. |
Invoke the mcu\_get\_wifi\_work\_state() function to obtain the Wi-Fi status. The function architecture is as follows:
```
void main(void)
{
...
while(1)
{
switch(mcu_get_wifi_work_state())
{
case SMART_CONFIG_STATE:
//smart config configuration state: LED flash quickly; the user needs to complete the configuration
break;
case AP_STATE:
//AP configuration state: LED flash slowly
break;
case WIFI_NOT_CONNECTED:
//Wi-Fi configuration is finished; the router is being connected to; LED keeps long dark
break;
case WIFI_CONNECTED:
//The router is successfully connected to; LED keeps long bright
break;
default:break;
}
...
}
}
```
Description of network status:
| Device Network Connection Status | Description | Description |
| -------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| State 1 | Smart network configuration | The wifi module is in smart distribution state |
| State 2 | AP network configuration | wifi module is in AP configuration |
| State 3 | The Wi-Fi is configured. However, the device fails to connect to the router. | The wifi module has received configuration information and is connecting to the router |
| State 4 | The Wi-Fi is configured, and the device successfully connects to the router. | The wifi module is connected to the router, but is not connected to the cloud. If the module has been equipped with a network and the mobile phone is also connected to this route, it can be controlled by the LAN |
| State 5 | The device connects to the router and cloud. | The wifi module has been connected to the cloud, and both the LAN and the external network can be controlled at this time |
| State 6 | The Wi-Fi device is in low power consumption mode. | wifi module enters low power consumption state |
| State 7 | The Wi-Fi device is insmartconfig\&AP consumption mode. | The wifi module is in smart & AP state, at this time, it can be either smart or AP. |
#### Perfect production test function
The production test has the following three forms, you can choose according to your product docking situation \* Common platform Wi-Fi function test process-scan specified route \* Common platform Wi-Fi function test process-connect designated route \* Common platform Wi-Fi function test process-infrared function test
The specific process can be viewed: \[Wi-Fi General Production Test Documentation]
### MCU\_SDK and module data communication guide
The frame format can refer to the protocol description document in the SDK development kit
#### Initialize communication
After the MCU and the module are powered on, some initial configuration is required. During this period, it is necessary to verify whether the MCU and the module can work normally, whether the communication connection is normal, the data required for the module activation, and the module acquisition work method.
**Heartbeat packet**
The heartbeat packet is the data for regular communication between the MCU and the module. It can be used as a basis for verifying whether the MCU or the module is working properly. Therefore, it is recommended that the frame for the first communication after the MCU and the module are powered on is the heartbeat packet. Only when the heartbeat packet is sent and the reply is normal, can the communication be continued.
**Query product information**
After the heartbeat package can interact normally, the module needs to query the product PID, version number, and network configuration method of the MCU firmware. The PID is used for product activation. The version number is used to verify whether the upgrade is successful after the OTA upgrade is completed. The distribution network mode of the module.
**Query MCU, set the working mode of the module**
Used to set the working mode of the module, select the MCU and module co-processing mode or module self-processing mode It can be selected according to the WIFI network status indicator and the hardware connection position of the module reset button.
#### Data interaction process
#### Data interaction considerations
Special Note: 1. In order to avoid unpredictable problems, it is recommended that normal data communication such as dp delivery and reporting, OTA upgrade, etc. should be performed after initialization is completed. 2. For devices with low power consumption and other MCUs that can control the power of the module, data interaction must be performed after the device is initialized.
# Wi-Fi Power Off Fast Connect Device Solution
# Overview
### Introduction
There are many security sensors in the market. Their product features are generally battery-powered, low power consumption, small size, and weak interaction. Wi-Fi low-power solutions are specifically designed for this category. The communication schematic diagram is as follows. Users only need to use the Tuya Wi-Fi low-power docking protocol to quickly complete the docking of the MCU, so that the device can be networked. Tuya provides complete modules, App, and cloud services during the process.
Compared with the Wi-F universal module solution, the Wi-Fi low-power module software is trimmed and optimized. In addition, after the data transmission is completed, the MCU needs to power off the module.
* One minute network configuration (time is optional) The default is 3 minutes.
### Development Process
The development process mainly includes: product creation-hardware debugging-software development-functional debugging.
#### Create Product
Log in to the [IoT Workbench](https://iot.tuya.com/) and create a product. Select the product category according to the actual needs, and select Wi-Fi for the networking method. After the product is created, you can select the functions, panels, modules, and firmware according to the actual needs of the product and then download it to the MCU development kit.
> Some product categories have extended options for power consumption. For normal power supply products, we can choose standard power consumption. Battery-powered products can choose low power consumption.
>
> **Note:** Power consumption selection will be related to the recommendation of subsequent modules and firmware.
Creating a product is described in detail in the [MCU Access Guide](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/mcu-access-guide/mcu-access-guide), so I won't repeat it here. For specific steps, please refer to: [Product Creation-IoT Platform Operation](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/mcu-access-guide/mcu-access-guide#IoT%20Platform%20Operation)
#### Hardware debugging
**Hardware selection**
When creating a product selection module, the platform will recommend some common module models. The recommended module models for low-power Wi-Fi communication solutions are as follows:
* **E2S / E3S** Firmware key: keyvw8xqm89v5vr4
* **XR1 / XR2 / XR3** Firmware key: keycnw55p5k7vueh
After selecting the module and firmware, you can purchase module samples online.
The hardware engineer can enter the drawing board stage, and the related materials for hardware development can be viewed in the document center:
Data manual link: [Wi-Fi module data manual](https://docs.tuya.com/en/iot/device-development/module/wifi-module/wifie1smodule)
Module minimum schematic: [Wi-Fi module minimal system schematic diagram](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/hardware-design-reference-wifi/wifie1smodulemcu) PCB data: [Common module package library](https://pan.baidu.com/s/10xJBTxyDQjweUI6C6LhrNQ)
**Note:** Wi-Fi low-power modules consume less power than Wi-Fi universal modules, but the peak current will reach more than 400mA (continuing us level), and there must be a margin when designing the power supply!
**Distribution Network Verification**
After getting the module, users do n’t need to worry about writing code first. It is recommended to use the module debugging assistant (MCU simulation mode) provided by Tuya to connect with the Wi-Fi module first. When verifying the module, users can be familiar with The protocol interaction process will greatly improve the efficiency of development and debugging later.
Tuya module debugging assistant-MCU simulation mode. The assistant will simulate the MCU to automatically reply the module's correct protocol data. After the module is networked with a mobile phone, the DP data can be reported and issued. The following briefly introduces the main steps of the assistant and module distribution network operation. Before using it, you need to know the instructions of Tuya Module Debugging Assistant in advance. Users who use the assistant for the first time can read in advance: [Module Debugging Assistant Instruction](https://docs.tuya.com/en/iot/device-development/access-mode-simmulator/access-mode-mdodule-simmulator)
**step1.** According to the minimum system schematic diagram, set up the module peripheral circuit, and simple test can directly fly the wire.
**step2.** Open the Tuya module debugging assistant in the development kit and import the debugging file. Protocol selection Wi-Fi Low power protocol, MCU simulation mode.
**step3.** Connect the serial port of the module to the computer through the USB to TTL tool. The assistant selects the corresponding serial port and baud rate. Open the serial port and click Start. You will see that the module and the host computer automatically perform the initialization process protocol interaction.
**Note:** Wi-Fi low-power module sends **01** command word upon power-on. After receiving the correct response, it will interact with subsequent initialization protocols. If no data is sent after power-on, please check whether the peripheral circuit of the module is correct.
**step4.** Click Reset Module, the module enters the network distribution mode. The module supports two modes of network configuration: EZ and AP mode ([the difference between EZ mode and AP mode](https://support.tuya.com/en/help/_detail/K9d1qfql1dekm)). The reset button will switch the network configuration mode. According to the status prompt, the App performs the corresponding network configuration operation. For the network configuration operation, you can read the instruction of the App. Attach a demo video of the network distribution in two modes:
#### Software Development
In the process of hardware debugging, the user saw that the module and the MCU have a series of serial protocol protocol interaction data. For the understanding of these data, please refer to the protocol document in the development kit.
The agreement is mainly divided into two parts: the basic agreement and the functional agreement. The basic protocol has nothing to do with the product. It is a common protocol of the module, including module initialization instructions and some extended function instructions. The function protocol part is mainly based on the command word of the report of the basic protocol, and has explained the DP data content format in detail. The complete content of the basic protocol, the document center is kept updated in real time, you can click the link to view: [Tuya-cloud-low-power-universal-serial-access-protocol](https://docs.tuya.com/zh/iot/device-development/access-mode-mcu/wifi-low-power-solution/tuyacloudlowpoweruniversalserialaccessprotocol)
There are two ways for MCU to interface with Tuya module: transplant the MCU SDK or connect the protocol by yourself.
* Self-docking agreement
When MCU resources are limited or the MCU SDK is not suitable for porting, customers can choose to connect the serial port protocol by themselves.
* Porting MCU SDK
If the MCU resources are sufficient, it is generally recommended that users directly port the MCU SDK for efficient and convenient development. The MCU SDK in the development kit is a C-based protocol application code provided by Tuya, which can be directly added to the MCU project. The MCU SDK requires MCU hardware resources: 4K bytes of Flash; RAM is related to the length of the DP point data, about 100 bytes (if OTA function is required, it must be greater than 260 bytes); the number of function nesting levels is 9 levels. If users with insufficient resources can connect the protocol by themselves, the functions in the SDK package can still be used as a reference.
MCU SDK Porting Tutorial: [Overview of migrating Tuya's MCU SDK](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/software-reference-wifi/overview-of-migrating-tuyas-mcu-sdk)
**Power off mechanism**
When distributing the network: Compared with the general solution, the low power consumption, if the module is not connected to the cloud within 3 minutes of the distribution network, the module will automatically enter the power consumption mode. The module will actively issue 55 aa 00 03 00 01 01
#### Functional debugging
After porting the MCU SDK code development, you can use the Tuya module debugging assistant-module simulation mode to verify the correctness of the MCU code. The usage method is similar to the MCU simulation mode. In the simulation module mode, the assistant will automatically send the initialization data stream to verify that the MCU response is correct and give corresponding prompts for the incorrect data. After the initial interaction is passed, you can manually click to test other extended functions.
**Note:** Tuya module debugging assistant module simulation mode, without networking function, only used to verify the correctness of MCU serial protocol transmission and reception. After the test is completed, the MCU can be connected to the actual module and network.
Debugging common tool links:
[Background log query entry](https://docs.tuya.com/en/iot/guidelines-for-platform/operation-center/operation#Log%20query%3A%20Use%20Behavior%20Query%20on%20a%20Single-Device%20Basis): IoT Workbench-Operation Center. You can query related device background log data based on the device ID.
[Tuya Online Support Portal](https://docs.tuya.com/en/iot/guidelines-for-platform/support-center/troubleshooting): Tuya provides online support services. If the problem documents cannot be answered, you can Ask questions directly online, and the professional and technical team will answer your questions.
[FAQ collection for open platform](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/faqs-wifi/tuya-question): develop common problems, understand them in advance, and avoid stepping into the pit.
# Zigbee General Solution
# Overview
## Introduction
The Zigbee universal solution is one of the mainstream MCU interconnection solutions. MCU only need to use the Tuya Zigbee universal serial port access protocol to quickly complete the MCU docking, so that the device can be connected to the Internet. Tuya provides complete modules, App, and cloud services during the process.
Compared with other communication module solutions, Zigbee modules require a gateway, have a short distance but low power consumption.
This article is mainly an overview of the development process of Tuya Zigbee universal solution MCU.
## Development Process
The development process mainly includes: product creation-hardware debugging-software development-functional debugging.
### Create Product
Log in to the [IoT Workbench](https://iot.tuya.com/) and create a product. Select the product category according to the actual needs, and select Zigbee for the networking method. After the product is created, you can select the functions, panels, modules, and firmware according to the actual needs of the product and then download it to the MCU development kit.
Creating a product is described in detail in the [MCU Access Guide](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/mcu-access-guide/mcu-access-guide), so I won't repeat it here. For specific steps, please refer to: [Product Creation-IoT Platform Operation](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/mcu-access-guide/mcu-access-guide#IoT%20Platform%20Operation)
### Hardware debugging
#### Hardware selection
When creating a product selection module, the platform will recommend some common module models. The most commonly used Zigbee modules in the Zigbee universal solution are TYZS3 and TYZS5.
Tuya Zigbee module, divided into strong current and weak current firmware. Strong current firmware is suitable for products with long power supply and insensitive to power consumption. Weak current firmware is suitable for battery-powered products that require higher power consumption.
After selecting the module and firmware, you can purchase module samples online.
The hardware engineer can enter the drawing board stage, and the related materials for hardware development can be viewed in the document center:
Data manual link: [Zigbee module data manual](https://docs.tuya.com/en/iot/device-development/module/zigbee-module/tyzs5-zigbee-module-datasheet)
Module minimum schematic: [Zigbee module minimal system schematic diagram](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/zigbee-general-solution/zigbee-module-mcu-development-overview/zigbee-module-mcu-development-overview?id=K9eibbird3q5x)
PCB data: [Common module package library](https://pan.baidu.com/s/10xJBTxyDQjweUI6C6LhrNQ)
#### Distribution Network Verification
After getting the module, users do n’t need to worry about writing code first. It is recommended to use the module debugging assistant (MCU simulation mode) provided by Tuya to connect with the Zigbee module first. When verifying the module, users can be familiar with The protocol interaction process will greatly improve the efficiency of development and debugging later.
Tuya module debugging assistant-MCU simulation mode. The assistant will simulate the MCU to automatically reply the module's correct protocol data. After the module is networked with a mobile phone, the DP data can be reported and issued. The following briefly introduces the main steps of the assistant and module distribution network operation. Before using it, you need to know the instructions of Tuya Module Debugging Assistant in advance. Users who use the assistant for the first time can read in advance: [Module Debugging Assistant Instruction](https://docs.tuya.com/en/iot/device-development/access-mode-simmulator/access-mode-mdodule-simmulator)
**step1.** According to the minimum system schematic diagram, set up the module peripheral circuit, and simple test can directly fly the wire.
**step2.** Open the Tuya module debugging assistant in the development kit and import the debugging file. Protocol selection Wi-Fi universal protocol, MCU simulation mode.
**step3.** Connect the serial port of the module to the computer through the USB to TTL tool. The assistant selects the corresponding serial port and baud rate. Open the serial port and click Start. You will see that the module and the host computer automatically perform the initialization process protocol interaction.
**Note:** If no data is sent after power on, please check if the peripheral circuit of the module is correct.
**step4.** Click Reset Module, the module enters the network distribution mode. According to the status prompt, the App performs the corresponding network configuration operation. For the network configuration operation, you can read the instruction of the App.
**Note:** Before configuring the sub-device, the gateway needs to be connected to the Internet with Tuya Smart or Smart Life App before adding the Zigbee sub-device. For details, please refer to the document [Zigbee Network Configuration Instructions](http://faq.cn.tuya.com/helpDetail.htm?tntInstId=WRNQWLCN\&helpCode=SCE_00000130\&helpId=90972006) and video [Zigbee Gateway Network Configuration](https://www.bilibili.com/video/av94188714?from=search\&seid=3135414516402258372)
### Software Development
In the process of hardware debugging, the user saw that the module and the MCU have a series of serial protocol protocol interaction data. For the understanding of these data, please refer to the protocol document in the development kit.
The agreement is mainly divided into two parts: the basic agreement and the functional agreement. The basic protocol has nothing to do with the product. It is a common protocol of the module, including module initialization instructions and some extended function instructions. The function protocol part is mainly based on the command word of the report of the basic protocol, and has explained the DP data content format in detail. The complete content of the basic protocol, the document center is kept updated in real time, you can click the link to view: [Tuya Zigbee module UART communication protocol](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/zigbee-general-solution/tuya-zigbee-module-uart-communication-protocol/tuya-zigbee-module-uart-communication-protocol)
There are two ways for MCU to interface with Tuya module: transplant the MCU SDK or connect the protocol by yourself.
* Self-docking agreement
When MCU resources are limited or the MCU SDK is not suitable for porting, customers can choose to connect the serial port protocol by themselves.
* Porting MCU SDK
If the MCU resources are sufficient, it is generally recommended that users directly port the MCU SDK for efficient and convenient development. The MCU SDK in the development kit is a C-based protocol application code provided by Tuya, which can be directly added to the MCU project. The MCU SDK requires MCU hardware resources: 4K bytes of Flash; RAM is related to the length of the DP point data, about 100 bytes (if OTA function is required, it must be greater than 260 bytes); the number of function nesting levels is 9 levels. If users with insufficient resources can connect the protocol by themselves, the functions in the SDK package can still be used as a reference.
MCU SDK Porting Tutorial: [Overview of migrating Tuya's MCU SDK](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/software-reference-wifi/overview-of-migrating-tuyas-mcu-sdk)
### Functional debugging
After porting the MCU SDK code development, you can use the Tuya module debugging assistant-module simulation mode to verify the correctness of the MCU code. The usage method is similar to the MCU simulation mode. In the simulation module mode, the assistant will automatically send the initialization data stream to verify that the MCU response is correct and give corresponding prompts for the incorrect data. After the initial interaction is passed, you can manually click to test other extended functions.
**Note:** Tuya module debugging assistant module simulation mode, without networking function, only used to verify the correctness of MCU serial protocol transmission and reception. After the test is completed, the MCU can be connected to the actual module and network.
Debugging common tool links:
[Background log query entry](https://docs.tuya.com/en/iot/guidelines-for-platform/operation-center/operation#Log%20query%3A%20Use%20Behavior%20Query%20on%20a%20Single-Device%20Basis): IoT Workbench-Operation Center. You can query related device background log data based on the device ID.
[Tuya Online Support Portal](https://docs.tuya.com/en/iot/guidelines-for-platform/support-center/troubleshooting): Tuya provides online support services. If the problem documents cannot be answered, you can Ask questions directly online, and the professional and technical team will answer your questions.
# Software development
# Tuya Zigbee module UART communication protocol
The Tuya Zigbee serial port general protocol is the Tuya custom Zigbee module serial port general protocol, which is mainly used for Tuya Zigbee module to directly connect with other MCU serial ports for serial communication.
Figure 1: Tuya Zigbee serial protocol structure
### Hardware connection
Zigbee module is powered by DC 3.3V, UART is set to 9600-8-N-1, no data flow control. The UART interface pins use standard logic. In the idle state, the TXD and RXD pins are both high level, with low level as the start bit and high level as the stop bit. The pin stays high even when the device goes to sleep.
For low-power devices, two GPIO ports (PWM1 and PWM2) are reserved between the Tuya Zigbee module and the MCU, which are used when the MCU and module connection wake up. PWM1 is used by the Zigbee module to wake the MCU, and PWM2 is used by the MCU to wake the Zigbee module. The default is high level, low level is valid for more than 10 ms. For low-power low-voltage devices, the initiator needs to make a wake-up handshake connection before actively initiating a command between the Zigbee module and the MCU.
For high-power devices without hibernation, the serial port is in a long listening state and does not need to be connected to PWM1 and PWM2. It can be left floating.
## Serial communication
### Frame format
The UART communication data frame between Tuya Zigbee module and MCU is composed of frame header (Front), version (Ver), command word (Cmd), data length (Length), data (Data) and checksum (Check). And description is as follows:
| Octets: 2 | 1 | 2 | 1 | 2 | Variable | 1 |
| --------- | --- | --- | --- | ------ | -------- | ----- |
| Front | Ver | Seq | Cmd | Length | Data | Check |
### Frame Format Description
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| Frame Header (Front) | 2 byte leader, fixed to 0x55aa |
| Version (Ver) | Serial communication protocol version, for upgrading and expansion |
| Sequence number (seq) | The sequence number of the transmitted data, ranging from 0 to 65535, and returned to 0 after reaching 65535 |
| Command Word (Cmd) | For specific frame types, refer to \[Table 2] (# 表 1) |
| Data length (Length) | effective data length of the transmission; single frame data length does not exceed 64 bytes |
| Data | Valid Data Transferred |
| Check | Check the data, starting from the header of the frame and summing the results by 256 bytes |
Table 1: Frame format description
Note: The version (Ver) is 1, and does not include the serial number parameter; The version number is greater than 1, including the serial number parameter;
| Cmd ID | Description |
| --------- | ----------------------------------------------------------- |
| 0x01 | Product Information Inquiry / Reporting |
| 0x02 | Device Status Query / Report |
| 0x03 | Zigbee Device Reset |
| 0x04 | Order Issuance |
| 0x05 | Status Report |
| 0x06 | Status Search |
| 0x07 | reserved |
| 0x08 | Zigbee Device Functional Test |
| 0x09 | Query key information (only scene switch devices are valid) |
| 0x0A | Scene wakeup command (only scene switch device is valid) |
| 0x0A-0x23 | reserved |
| 0x24 | Time synchronization |
Table 2: Cmd description table
All data larger than 1 byte is transferred in big-endian mode.
Under normal circumstances, the command word one send and one receive synchronization mechanism is adopted, that is, one party sends a command and the other responds. If the sender does not receive the correct response packet after timeout, the transmission timeout.
## Protocol details
### Query Product Information
Explanation:
1\) Product ID: Corresponds to the Tuya Developer Platform PID (Product Identification), which is generated by the Tuya Cloud Developer Platform and used to record product-related information in the cloud.
2\) Product information consists of product ID and MCU software version.
3\) MCU software version number format definition: in dotted decimal form, "x.x.x" (0 <= x <= 99), x is a decimal number.
Module sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x01 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55aa 02 N 01 0000 xx
The MCU returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x01 |
| Data Length | 2 | N |
| Data | N | {"p": "AIp08kLI", "v": "1.0.0"} |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: {"p": "AIp08kLI", "v": "2.0.0"}
p means product ID is AIp08kLI
v means MCU version is 2.0.0
0x55aa 02 N 01 00 1c 7b2270223a2241497031386b4c49222c2276223a22312e302e30227d xx
### Report module network status
| Device Status ID | Description |
| ---------------- | ------------------------------------------ |
| 0x00 | The device is not connected to the network |
| 0x01 | The device is connected to the network |
| 0x02 | Device network status is abnormal |
Explanation:
1\) The device is not connected to the network: When the device is powered on for the first time, or fails to connect to the network, or is disconnected from the network, the device status is not connected to the network; the status is sent to the MCU.
2\) The device is in the networked state: After the device is successfully connected to the network, the device is in the networked state; this state is sent to the MCU.
3\) When the network status of the module changes, it will actively send the network status of the module to the MCU.
Module sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x02 |
| Data Length | 2 | 0x0001 |
| Data | 1 | Indicate module working status: 0x00: status 1 0x01: status 2 |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55aa 02 N 02 0001 00 xx
The MCU returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x02 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55aa 02 N 02 0000 xx
### Configure Zigbee module
Note: There are two types of commands for configuring the Zigbee module, as shown in the figure below.
| Command | Explanation |
| ------- | ---------------------------------------------------------------------------------------------------- |
| 0x00 | Reset module software |
| 0x01 | Configure the module to start the network configuration (off the network first and then the network) |
MCU sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x03 |
| Data Length | 2 | 0x0001 |
| Data | 0 | 0x00 / 0x01 |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55aa 02 N 03 0001 01 xx
The module returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x03 |
| Data length | 2 | 0x0000 |
| Data | 0 | None |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55aa 02 N 03 0000 xx
### Command issued
Command issued frame format
! \[img] ()!
Explanation:
1\) The datapoint command / status data unit is as follows:
| Data Section | Length (byte) | Explanation | |
| ------------ | ------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Dpid | 1 | datapoint number | |
| Type | 1 | Corresponds to the specific data type of a datapoint on the open platform. | |
| Type | Value | Length (Bytes) | Description |
| raw | 0x00 | N | corresponding to raw datapoint (module transparent transmission) |
| bool | 0x01 | 1 | value range: 0x00 / 0x01 |
| value | 0x02 | 4 | corresponding to int type, big-endian representation |
| string | 0x03 | N | corresponds to a specific string |
| enum | 0x04 | 1 | Enumeration type, range 0-255 |
| bitmap | 0x05 | 1/2/4 | When the length is greater than 1 byte, big-endian means |
| Len | 2 | Number of bytes of length corresponding to value | |
| Value | 1/2/4 / N | hex indicates that more than 1 byte is transmitted in big-endian | |
2\) Except for the "raw" type, the datapoint command / status data unit belongs to the "obj" type datapoint.
3\) The "command delivery" may include multiple datapoint "command data units".
4\) "Command issuance" is an asynchronous processing protocol, corresponding to the "status report" of the MCU's datapoint.
Module sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x04 |
| Data length | 2 | Depends on "command data unit" type and number |
| Data | N | "3.4 Command Data Unit" Group |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: The system switch corresponds to DP No. 3, using a bool variable, and the boot value is 1.
0x55aa 02 N 04 0005 \*\* 03 01 0001 01 \*\* xx
### Status reporting (passive)
Explanation:
1\) After the MCU receives the command issued by the module side and performs the corresponding action, it needs to passively report the new status to the module side;
a. After the status is correctly executed, only the datapoint status of the performed operation is reported;
2\) "Status reporting (passive)" is a synchronous processing protocol. After receiving the datapoint information, the module will immediately return an ACK to the MCU;
3\) "Status reporting (passive)" may include multiple datapoint "command data units". For details of the datapoint status data unit description, see "Section 3.4"
MCU sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ---------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x05 |
| Data length | 2 | Depends on the type and number of Status Data Units |
| Data | N | "3.4 Status Data Unit" Group |
| Checksum | 1 | Byte-sum results from the header of the frame to 256 |
Example: Humidity corresponds to No. 5 DP, use valve type variable, humidity is 30 ℃
0x55aa 02 N 05 00 08 \*\* 05 02 0004 0000001e \*\* xx
The module returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | --------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x05 |
| Data Length | 2 | 0x0001 |
| Data | 0 | 0x00 / 0x01 0x00: Status reporting failed 0x01: Status reporting successful |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: Module returns ACK status to MCU successfully
0x55aa 02 N 05 0001 01 xx
### Status reporting (active)
Explanation:
1\) In the case that the MCU actively detects a change in the datapoint or the MCU restarts, it is necessary to send the changed datapoint status to the module.
a. When there is a normal change, only the changed datapoint is reported;
b. In abnormal situations such as restart, all datapoints need to be reported;
2\) "Status reporting (active)" is an asynchronous processing protocol. After receiving the response from the gateway within the timeout period, the module will return the status to the MCU. If the status returns timeout or the status is fail, the MCU needs to do random Backoff retransmission mechanism.
3\) The "status report (active)" may include multiple datapoint "command data units". For details of the datapoint status data unit description, see "Section 3.4".
MCU sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x06 |
| Data length | 2 | Depends on the type and number of Status Data Units |
| Data | N | "3.4 Status Data Unit" Group |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: Humidity corresponds to No. 5 DP, use valve type variable, humidity is 30 ℃
0x55aa 02 N 06 08 \*\* 05 02 0004 0000001e \*\* xx
The module returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | --------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x06 |
| Data Length | 2 | 0x0001 |
| Data | 0 | 0x00 / 0x01 0x00: Status reporting failed 0x01: Status reporting successful |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: Module returns ACK status to MCU successfully
0x55aa 02 N 06 0001 01 xx
### Zigbee module functional test
Note: Scan the RSSI value of the specified channel, and return the scan result and signal strength percentage. This command can run normally only when the device is not connected to the network. The module must be restarted after a single test.
MCU sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x08 |
| Data Length | 2 | 0x0001 |
| Data | Data | Channel Value (11-26) |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
example:
The MCU requires the module to scan the RSSI value of the 11 channels:
0x55aa 02 N 08 0001 0b xx
The module returns:
| Field | Length (byte) | Explanation |
| ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x08 |
| Data Length | 2 | 0x0002 |
| Data | 2 | The data length is 2 bytes: Data \[0]: 0x00 failed, 0x01 succeeded; When Data \[0] is 0x01, that is, success, Data \[1] indicates the signal strength (0-100, 0 signal is the most Poor, 100 signal is the strongest) When Data \[0] is 0x00, that is, failure, Data \[1] is 0x00 means that RSSI is not scanned on the specified channel, and Data \[1] is 0x01, which means the module has not flashed the authorization key |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
example:
0x55aa 02 N 08 0002 01 64 xx
Explanation:
The effective value of the channel is (11-26), and the invalid channel will use 11 channels by default;
### Time synchronization
Note: Time synchronization is used by the MCU to measure the network time usage of the synchronization gateway.
MCU sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x24 |
| Data length | 2 | 0x0000 |
| Data | NA | |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
The module returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x024 |
| Data Length | 2 | 0x0002 |
| Data | 2 | The data length is 8-byte time value, the format reference is as follows time synchronization data format |
| Checksum | 1 | Byte-sum results from the header of the frame to 256 |
Time-synchronized data format, including standard timestamps and local timestamps.
| Variable | Variable |
| --------------------------- | ------------------------ |
| Standard timestamp (4 byte) | Local timestamp (4 byte) |
Time synchronization data format
1.The standard time stamp is the total number of seconds from 00: 00: 00 on January 01, 1970, GMT.
Local timestamp = standard timestamp + seconds between standard time and local time (including time zone and daylight saving time)
## Scene switch protocol
In the scene switch device, the MCU only needs to inform the Zigbee module device how many keys it has through the serial port transparent transmission protocol, and which key is currently operated.
### Query key information
Module sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x09 |
| Data length | 2 | 0x0000 |
| Data | NA | |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
example:
The module requires to obtain the total value of the MCU's keys:
0x55aa 02 N 09 0000 xx
The MCU returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x09 |
| Data Length | 2 | 0x0001 |
| Data | 2 | Total number of keys on the panel switch |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
example:
0x55aa 02 N 09 0001 02 xx
### Scene wake command
MCU sends:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x0A |
| Data Length | 2 | 0x0001 |
| Data | Button ID | |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Note: There is a one-to-one correspondence between the key ID and the total number of keys.
example:
The MCU requires the module to execute the scenario corresponding to button 1:
0x55aa 02 N 0A 0001 01 xx
The module returns:
| Field | Length (byte) | Description |
| ------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Serial number | 2 | N |
| Command Word | 1 | 0x0A |
| Data Length | 2 | 0x0001 |
| Data | 1 | 0: Scene wakeup failed; 1: Scene wakeup successful; |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
example:
0x55aa 02 N 0A 0001 01 xx
## MCU OTA protocol
### Data format requested by OTA version
This command must be implemented if MCU upgrade is supported. The gateway will actively query the MCU version number, and the MCU can also report it actively. Query scenarios: 1. During network deployment 2. Device initiated time synchronization 3. When the MCU upgrade process is abnormal; 1. After successful network configuration (must be added) 2. Upgrade is complete.
Module sends:
| Field | Length (byte) | Description |
| ------------------------------ | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Business Sequence Number (Seq) | 2 | Module Generation |
| Command Word | 1 | 0x0B |
| Data length | 2 | 0x0000 |
| Data | 0 | NA |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55 AA 02 00 f0 0B 00 00 XX
MCU response:
| Field | Length (byte) | Description |
| ----------------------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Service Sequence Number (Seq) | 2 | SEQ issued by MCU |
| Command Word | 1 | 0x0B |
| Data Length | 2 | 0x0001 |
| Data | 1 | Version number (current version) (Bits) 01.00.0001 à1.0.1 |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 55 AA 02 00 39 0B 00 01 40 XX
### OTA Upgrade Notice
Module sends:
| Field | Length (byte) | Description |
| ------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Business Sequence Number (Seq) | 2 | Module Generation |
| Command Word | 1 | 0x0C |
| Data length | 2 | 0x0011 |
| Data | 8 | Data \[0] \~ Data \[7] PID |
| Data | 1 | Version number \*\* (upgrade version) \*\* (Bits) 01.00.0001 à1.0.1 |
| Data | 4 | Firmware size up to 64K |
| Data | 4 | Firmware checksum: 2 ^ 32 remainder from the result of byte-wise summation from the first byte of firmware |
| Checksum | 1 | Byte-sum results from the header of the frame to 256 |
Example: 0x55 AA 02 00 1C 0C 00 0F 30 31 32 33 34 35 36 37 40 00 01 00 00 30 31 32 33 XX
MCU response:
| Field | Length (byte) | Description |
| ------------------------------ | ------------- | ---------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Business Sequence Number (Seq) | 2 | seq issued by the module |
| Command Word | 1 | 0x0C |
| Data Length | 2 | 0x0001 |
| Data | 1 | 0x00: OK, 0x01: error |
| Checksum | 1 | Byte-sum results from the header of the frame to 256 |
Example: 0x55 AA 02 00 1C 0C 00 01 00 XX
### OTA firmware content request
MCU sends:
| Field | Length (byte) | Description |
| ------------------------------ | ------------- | ------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Business Sequence Number (Seq) | 2 | 0x0000 |
| Command Word | 1 | 0x0D |
| Data length | 2 | 0x000E |
| Data | 8 | PID |
| Data | 1 | Version number \*\* (upgrade version) \*\* (Bits) 01.00.0001 à1.0.1 |
| Data | 4 | Offset of packet (location of firmware) |
| Data | 1 | Packet size (up to 50 bytes) |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55 AA 02 00 00 0D 00 0E 30 31 32 33 34 35 36 37 40 00 00 00 01 32 XX
Module response:
| Field | Length (byte) | Description |
| ------------------------------ | ------------- | ------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Business Sequence Number (Seq) | 2 | 0x0000 |
| Command Word | 1 | 0x0D |
| Data length | 2 | 0x0006 + N |
| Data | 1 | Status 0: Success 1: Failure |
| Data | 8 | PID |
| Data | 1 | Version number \*\* (upgrade version) \*\* (Bits) 01.00.0001 à1.0.1 |
| Data | 4 | Offset of packet (location of firmware) |
| Data | N | Data |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 55 AA 02 00 39 0D XXXX 00 30 31 32 33 34 35 36 37 40 00 00 00 01…. XX
### OTA firmware upgrade result report
MCU sends:
| Field | Length (byte) | Description |
| ----------------------------- | ------------- | ---------------------------------------------------------------------------- |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Service Sequence Number (Seq) | 2 | SEQ issued by MCU |
| Command Word | 1 | 0x0E |
| Data length | 2 | 0x000A |
| Data | 1 | Status 0: Success 1: Failure |
| Data | 8 | PID |
| Data | 1 | Version number \*\* (upgraded current version) \*\* (Bits) 01.00.0001 à1.0.1 |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55 AA 03 00 f0 0E 00 0A 00 30 31 32 33 34 35 36 37 40 26
Module response:
| Field | Length (byte) | Description |
| ----------------------------- | ------------- | ------------------------------------------------------------ |
| Frame Header | 2 | 0x55aa |
| Version | 1 | 0x02 |
| Service Sequence Number (Seq) | 2 | SEQ issued by MCU |
| Command Word | 1 | 0x0E |
| Data Length | 2 | 0x0001 |
| Data | 1 | 0x00: OK, 0x01: error |
| Checksum | 1 | Byte-sum results from the header of the frame, 256 remainder |
Example: 0x55 AA 02 00 1C 0E 00 01 00 XX
# Hardware Design
## TYZS3 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
!
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 120mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYZS5 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 118mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RESET pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYZS6 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.In working mode，power supply consumption: 3.3V, the typical current is about 40mA. Proposed supply current≥100mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. nRST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYZS7 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 118mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. nRST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYZS8 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 120mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. nRST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYZS10 Module & MCU serial communication instructions
\## Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 120mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF.
## TYZS11 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 120mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. nRST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYZS12 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 120mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. nRST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYZS13 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The module is under the condition of 250Kbps rate and + 19dBm transmit power， power supply consumption: 3.3V, the typical current is about 120mA. Proposed supply current≥300mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. nRST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
# BLE General Solution
# BLE Module MCU Development Overview
## Introduction
Tuya is providing developers with MCU SDK that can be quickly programmed .This is a development kit generated automatically from the product’s function datapoint according to Tuya Serial Port Communication Protocol. MCU engineer can develop this procedure conveniently on this basis. This article will introduce you to the specific steps of MCU development.
> Schematic of gatewayless BLE single-point communication
> Schematic of BLE single-point with gateway communication
## Development Process
The development process mainly includes: Creating products - Hardware Debugging- Software Debugging - Function Debugging.
### Creating products
Login [Tuya Smart Developer Platform](https://iot.tuya.com/) to create products. Please note that the communication type is **"BLE"**.
> Tuya BLE Standard Module includes both Non-low power and Low power mode. User can choose whether to enable the low-power function through protocol instructions.
>
> * Non-low power mode is for products with long power supply and insensitive to power consumption.
> * Low power mode is for battery-powered products with higher power consumption requirements.
After the product is created, users can select functions, panels, modules and firmware according to the actual needs of the product, and download the corresponding MCU development kit.
Creating a product is described in detail in the [MCU Access Guide](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/mcu-access-guide/mcu-access-guide), so we won't go into details here.
### Hardware Debugging
When selecting module on the platform, the platform will recommend some common module models. After selecting the module and firmware, you can purchase module samples online.
The hardware engineer can enter the drawing board stage, and the related materials for hardware development can be viewed in the developer center:
Data manual link: [BLE module datasheet](https://docs.tuya.com/en/iot/device-development/module/ble-module/br3l);
Hardware design guidance: [BLE module hardware design](https://docs.tuya.com/zh/iot/device-development/access-mode-mcu/ble-general-solution/ble-hardware-design/tybt3)(not available now);
PCB data: [Common module package library](https://pan.baidu.com/s/10xJBTxyDQjweUI6C6LhrNQ).
**Note**: When the battery is used as the power supply, when the power supply voltage is lower than the normal working voltage, the internal flash operation of the module will risk the error, causing the firmware or user data to be modified abnormally.
You can choose 2 way to rescue it: 1.When the MCU detects that the battery voltage is too low, cut off the module's power.
2.When the MCU detects that the battery voltage is too low, turn off the broadcast and system timing, put module in deep sleep mode. The minimum working voltage of Telink module is 1.8V, MCU can be set at 2.0V (slightly higher than 1.8V).
#### Network verification
After getting the module, you don't need to write code first, first determine whether the module is working properly. Using the module debugging assistant (MCU simulation mode) provided by Tuya to cooperate with the module can perform network config operation, verify the module and be familiar with the protocol interaction process at the same time, and the development and debugging efficiency will be greatly improved later.
The framework of Tuya BLE Standard Serial Communication Protocol is shown below：
**Low-power Mode Control Pin**: At present, It's necessary required in Scheme of Standard Door Lock (TYBN1,BK3431Q), and it needs to be connected and used by MCU. For other standard scheme, to use the low-power mode, you must also connect the module's Low-power Control Part. If you don't need this mode, it's enough to just finish the basic connection part.
**Status of Connection Notification Pin**: In Low-power Mode, the GPIO will output high level when BLE connection with Mobile is successful. And when it's disconnected, the Pin will output low level.
> **Note**: Some module does not supply this function. For details, please refer to the Low-power Mode section of the protocol document (optional, different models have different screen printing, see the datasheet for details.
Tuya MCU simulation debugging assistant, the assistant can simulate MCU data transmission and reception. Set up the minimum system of the module and connect the serial port to the computer.The assistant has the following functions: 1. Pair with a networked module and verify that the module is working properly. 2. Before the MCU completes development, debug the App panel display. 3. When the MCU developer does not know how to send and reply data to the module, the data of the simulation assistant can be used as a reference.
For more information, please refer to the [Module Debugging Assistant Instruction](https://docs.tuya.com/en/iot/device-development/access-mode-simmulator/access-mode-mdodule-simmulator)
> Module Debugging Assistant (MCU simulation mode)
**step1.** According to the minimum system schematic diagram, build the module peripheral circuit, simple test can fly wire directly.
**step2.** Open the Tuya module debugging assistant in the development kit and import the debugging file. Protocol selection BLE single point general protocol, MCU simulation mode.
**step3.** Connect the module serial port to the computer through the USB to TTL tool. The assistant selects the corresponding serial port and baud rate. Open the serial port and click Start. You will see that the module and the host computer automatically perform the initialization process protocol interaction.
**Note：** After the Bluetooth module is powered on, it will continuously send heartbeat packets. After receiving the correct response, it will perform subsequent initialization protocol interactions. If no data is sent after power on, please check if the peripheral circuit of the module is correct.
**step4.** Click Reset Module, the module will disconnect the BLE connection of the module, release the BLE binding relationship, clear the module's cache information, and restart the module.
### Software Debugging
During hardware debugging, you can see that the module and the MCU have a series of serial protocol interaction data. For the data analysis part, users can refer to the protocol document in the development kit. The agreement is mainly divided into two parts: the basic protocol and the functional protocol.
The basic protocol has nothing to do with the product. It is a common protocol of the module, including module initialization instructions and some extended function instructions.
The functional protocol part is mainly based on the reporting and issuing command words of the basic protocol, and details the format of the Datapoint content. The full content of the basic protocol, the document center is kept updated in real time, you can click the link to view: [Tuya Cloud BLE Universal Serial Port Access Protocol](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/ble-general-solution/tuya-cloud-universal-serial-port-access-protocol/tuya-cloud-universal-serial-port-access-protocol)(not available now).
There are two ways for the MCU to connect with the Tuya module protocol: transplant the MCU SDK or connect the protocol by yourself.
* Connect protocol by yourself:
When the MCU resources are limited or the MCU SDK is not suitable for porting, customers can choose to connect the serial port protocol by themselves.
* Transplant MCU SDK:
If the MCU resources are sufficient, it is generally recommended that users directly port the MCU SDK for efficient and convenient development. The MCU SDK in the development kit is a C-based protocol application code provided by Tuya, which can be directly added to the MCU project.
The MCU SDK requires MCU hardware resources: Flash 4K bytes; RAM is related to the length of the DataPoint, about 100 bytes (if OTA function is required, it must be bigger than 260 bytes); the number of function nesting levels is 9 levels. If users with insufficient resources can connect the protocol by themselves, the functions in the SDK package can still be used as a reference.
For details can see: [Overview of migrating Tuya's MCU SDK](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/software-reference-wifi/overview-of-migrating-tuyas-mcu-sdk).
### Functions Debugging
After porting the MCU SDK code development, you can use the Tuya module debugging assistant - module simulation mode to verify the correctness of the MCU code. The usage method is similar to the MCU simulation mode. In the simulation module mode, the assistant will automatically send the initialization data stream to verify that the MCU response is correct and give corresponding prompts for the incorrect data. After the initial interaction is passed, you can manually click to test other extended functions.
**Note：** module simulation mode do not supply network functions, only used to verify the correctness of the MCU serial protocol transmission and reception. After the test is completed, the MCU can be connected to the actual module and test the network.
> Module Debugging Assistant (Module simulation mode)
Other Debugging Common Tools Links：
[Operations Center Guide](https://docs.tuya.com/en/iot/guidelines-for-platform/operation-center/operation#%E8%AE%BE%E5%A4%87%E6%97%A5%E5%BF%97%E6%9F%A5%E8%AF%A2%EF%BC%88%E6%94%AF%E6%8C%81%E5%8D%95%E4%B8%AA%E8%AE%BE%E5%A4%87%E4%BD%BF%E7%94%A8%E8%A1%8C%E4%B8%BA%E6%9F%A5%E8%AF%A2%EF%BC%89)：Tuya Smart Developer Platform - Operation. You can check device background log here according to your product id.
[Tutorial for Tuya Support Center](https://docs.tuya.com/en/iot/guidelines-for-platform/support-center/troubleshooting)：Tuya provide online technical support, you can ask any questions like the question about documents here.
[FAQ](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/ble-general-solution/faq-collection-for-open-platform/faq-collection-for-open-platform)(not available now)：FAQ, you can read it before developing to avoid some problem.
# BLE Hardware Design
## TYBT3 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The power supply consumption: 3.3V,proposed supply current≥100mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use. 4. The SDA pin is the low power control pin, the MCU sends and the module receives. 5. The SCL pin is the connection status indicator pin, the module sends and the MCU receives.
## TYBT4 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The power supply consumption: 3.3V,proposed supply current≥100mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use.
## TYBN1 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The power supply consumption: 3.3V,proposed supply current≥100mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use. 4. The IO11 pin is the low power control pin, the MCU sends and the module receives. 5. The IO14 pin is the "module wakes up MCU" pin, the module sends and the MCU receives.
## BT3L Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The power supply consumption: 3.3V,proposed supply current≥100mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use. 4. The TL\_B5 pin is the low power control pin, the MCU sends and the module receives. 5. The TL\_B4 pin is the connection status indicator pin, the module sends and the MCU receives.
## TYBT5 Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The power supply consumption: 3.3V,proposed supply current≥100mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use. 4. The IIC\_SDA pin is the low power control pin, the MCU sends and the module receives. 5. The IIC\_SCL pin is the connection status indicator pin, the module sends and the MCU receives.
## BT7L Module & MCU serial communication instructions
### Typical Application diagram
Diagram 1 MCU(3.3V) & Module cooperative processing mode
Diagram 2 MCU(5V) & Module cooperative processing mode
### Design specification
1.The power supply consumption: 3.3V,proposed supply current≥100mA. 2. Power filter capacitor C1 & C2 should be distributed as close to the 3.3V pin as possible.C1 & C2≥10uF. 3. RST pin is module hardware reset pin, effective under the low level. Without external circuitry, it can be directly connected to the IO port of MCU for use. 4. The B5 pin is the low power control pin, the MCU sends and the module receives. 5. The B4 pin is the connection status indicator pin, the module sends and the MCU receives.
# NB-IoT General Solution
# NB-IoT Development Guide
## Background
The Narrow Band Internet of Things (NB-IoT) is built on cellular mobile communication network to achieve thing-to-thing communication and thing-to-person communication. NB-IoT focuses on the Low Power Wide Area (LPWA) Internet of Things (IoT) market.
The NB-IoT network consumes only about 180 kHz of bandwidth. Using the License frequency band, three deployment methods such as in-band, guard band, or independent carrier can be used to coexist with the existing network. Can be directly deployed on GSM, UMTS or LTE networks to reduce deployment costs and achieve smooth upgrades.
#### NB-IoT Features
* **Low-power**: IoT Products(such as smart meter reading, environmental monitoring, smart agriculture, etc.) have no power supply in the installation environment and require batteries. In order to meet the battery's 5 to 10-year life expectancy, the NB-IoT network introduced PSM and eDRX technology. It greatly reduces the power consumption of the terminal, which can keep the device in a very low power consumption state for most of the life cycle, thereby ensuring the battery life.
* **Low-cost**: NB-IoT Products use narrow-band technology, low baseband complexity, only use a single antenna, adopt half-duplex mode, low cost of RF module, most unnecessary functions (SRVCC, IMS, emergency call, etc.) are cut and the use of the SoC's built-in power amplifier PA reduce the requirements for terminal flash storage space, terminal size, terminal radio frequency, etc., thereby greatly reducing the cost of NB-IoT.
* **Large number of connections**: NB-IoT has 50-100 times higher uplink capacity than 2G / 3G / 4G (specific service model). NB-IoT can provide 50-100 times the number of accesses than existing wireless technologies. A single cell can support 5 10,000-level user scale.
* **Wide coverage**: 164db MCL, NB-IoT improves 20db gain over GPRS, it can cover well in places where signals such as underground garages, basements, and underground pipes are difficult to reach.
| Features | Details | Specific value range |
| -------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Less data | Limited Air Interface resources (180khz), suitable for small data communication | 50 \~ 200 bytes is suitable, the smaller the better |
| Low frequency, long period | Most terminals should be in a dormant state for a long time, the frequency of reporting data is low | Report by day, 1-2 times per day is more appropriate. High frequency reporting (for example, 30 minutes), will occupy a large amount of network capacity. The higher the reporting frequency, the greater the impact on network capacity. |
| Low power consumption | Lowest power consumption in PSM mode | Power sensitive applications preferably |
| Slow mobility | Suitable for slow mobility | Movement speed is less than 30km/h |
| Wide coverage | Batter coverage | Can support scene coverage like basement |
| Low rate | The theoretical peak rate of upstream is 15.6kbps, theoretical peak rate of downstream is 21.25kbps | Bandwidth high-rate services cannot be carried by NB-IoT network |
#### NB-IoT Network Structure
The NB-IoT network consists of NB-IoT terminals, NB-IoT base stations, NB-IoT packet core networks, IoT connection management platforms, and industry application servers. The access network architecture of NB-IoT is the same as that of LTE.
#### Power-saving Mode
> The development of NB-IoT business scale is closely related to the bearer business model, and its applicable scenarios are "small traffic, reporting-oriented, long-term sleep, power consumption sensitive, low mobility" applications. In order to realize the large number of low-power devices carried by the NB-IoT network, the most important technologies are: PSM and eDRX
NB-IoT supports 3 power-saving modes: **PSM** (Power Saving Mode), **DRX** (Discontinuous Reception), **eDRX** (Extended DRX)
#### PSM Mode
The terminal is deeply dormant during non-business periods and does not receive downlink data. Only the terminal can actively receive the downlink data buffered by the IoT platform when it actively sends uplink data (MO Data).
In this mode, the radio frequency of the terminal is turned off, which is equivalent to the shutdown state, but the core network side still retains the user context. When the user enters the idle state / connected state, there is no need to attach the PDN to establish it.
It is suitable for services with no delay requirements for downlink data; terminal equipment has low power consumption and uses battery-powered methods, such as meter reading services.
State:
* Active: The module is in an active state; all functions are normally available and data can be sent and received; the module can switch to Idle mode or PSM mode in this mode.
* Idle: The module is in a light sleep state; the module can receive paging messages in network connected state. Module can switch to Active or PSM mode in this mode.
* PSM: The module is in a deep sleep state, only the RTC works internally, the network is in a disconnected state and it cannot receive paging messages. When the timer expires, the module will be woken up; the module can also be woken up by pulling down the PSM\_EINT pin.
#### eDRX Mode
The terminal equipment takes into account both low-power consumption and services with certain delay requirements. In each eDRX cycle, the terminal can receive downlink data only within the set paging time window, the rest of the time the terminal is in a sleep state and does not receive downlink data. This mode can achieve a balance between downlink service delay and power consumption, such as remotely shutting down the gas service.
Within each eDRX cycle, there is a paging time window (PTW). The terminal monitors the paging channel in the PTW according to the DRX cycle (the DRX cycle time is short, the terminal can be considered not to sleep and always reachable) in order to receive downlink Data, the rest of the time the terminal is dormant. The eDRX mode can be considered that the terminal equipment is reachable at any time, but the delay is large. The delay depends on the eDRX cycle configuration, which can achieve a balance between low power consumption and delay.
#### DRX Mode
It can be considered that the downlink service can reach the terminal equipment at any time. In each DRX cycle, the terminal detects whether a downlink service arrives once, which is suitable for services with high requirements on delay. Terminal equipment generally adopts power supply methods, such as street light services.
Due to the short DRX cycle (1.28s, 2.56s, 5.12s, or 10.24s, which is determined by the operator's network settings and depends on the APN service handled by SIM), it can be considered that downlink services are always available and the delay is small. It is suitable for services that have high requirements on delay, but the power consumption is relatively high. Terminal equipment generally uses the mains power supply method.
#### NB-IoT Latency
First time network access latency: After the NB-IoT terminal is turned on, the terminal has a lot of message interaction with the network (authentication, channel establishment, IP address allocation, etc.). It takes 6-8s to complete network access and obtain an IP address Used for later data transmission.
Data reporting and reception latency: After the NB terminal is successfully connected, when the terminal has data transmission, the terminal will actively establish a wireless connection with the base station (no authentication, IP address allocation and other processes are required at this time). Then send the data immediately. The delay of data reporting by the terminal is closely related to the state of the terminal and the wireless network coverage.
| Data reported by the terminal | Data issued by the platform(PSM) | Data issued by the platform(DRX) | Data issued by the platform(eDRX) |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Air interface delay + private network to client server delay | Air interface delay + private network to platform delay + PSM maximum sleep period (maximum 310 hours) | Air interface delay (750ms) + DRX paging cycle (maximum 10.24 seconds, minimum 1.28 seconds) | Air interface delay (750ms) + eDRX paging cycle (maximum 2.92 hours, minimum 5.12 seconds) |
| Seconds (3 to 30 seconds) | Hour / day, depending on the reporting period of the terminal | Seconds, depending on the DRX paging cycle | Seconds and hours, depending on eDRX paging cycle |
#### NB-IoT Key Parameters
The low-power consumption mechanism of the NB application is inseparable from the configuration of the SIM card operator. Therefore, when purchasing SIM cards, please be clear about the APN business you handle. Different APNs are suitable for different application scenarios.
> If you have any problem about how to choose APN business, please ask Tuya stuff.
#### NB-IoT Power Consumption
| State | Power consumption | Measured results |
| ---------- | ------------------------------- | ------------------------------- |
| PSM | 3 uA | 2.7 uA |
| eDRX | xxuA\~2 mA | 1 mA |
| DRX | 1\~4mA | 1mA |
| Connectted | Sending 200 mA, receiving 65 mA | Sending 189mA, receiving 161 mA |
## Tuya MCU Solution Introduction
The Narrow Band Internet of Things (NB-IoT) is built on cellular mobile communication network to achieve thing-to-thing communication and thing-to-person communication. NB-IoT focuses on the Low Power Wide Area (LPWA) Internet of Things (IoT) market.
The NB-IoT network consumes only about 180 kHz of bandwidth. Using the License frequency band, three deployment methods such as in-band, guard band, or independent carrier can be used to coexist with the existing network. Can be directly deployed on GSM, UMTS or LTE networks to reduce deployment costs and achieve smooth upgrades.
Tuya is providing developers with MCU SDK that can be quickly programmed .This is a development kit generated automatically from the product’s function datapoint according to Tuya Serial Port Communication Protocol. MCU engineer can develop this procedure conveniently on this basis. This article will introduce you to the specific steps of MCU development.
## Development Process
The development process mainly includes: Creating products - Hardware debugging-software debugging - function debugging.
### Creating products
Login [Tuya Smart Developer Platform](https://iot.tuya.com/) to create products. Please note that the communication type is **"NB-IoT"**, The type of power consumption is selected based on the characteristics of the product. For common battery-powered, monitoring and reporting services, please select **"PSM"**. For products that are not sensitive to power consumption and deliver controlled services, please select **"DRX"** (note that the choice of power consumption will affect the sending and production of subsequent modules).
After the product is created, users can select functions, panels, modules and firmware according to the actual needs of the product, and download the corresponding MCU development kit.
Creating a product is described in detail in the [MCU Access Guide](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/mcu-access-guide/mcu-access-guide), so we won't go into details here.
### Hardware Debugging
When selecting module on the platform, the platform will recommend some common module models. After selecting the module and firmware, you can purchase module samples online.
The hardware engineer can enter the drawing board stage, and the related materials for hardware development can be viewed in the developer center:
Data manual link: [NB-IoT module datasheet](https://docs.tuya.com/en/iot/device-development/module/nb-module/nm1)(not available now);
Hardware design guidance: [NM1 module hardware design](https://docs.tuya.com/zh/iot/device-development/access-mode-mcu/nbiot-general-solution/nbguide)(not available now);
PCB data: [Common module package library](https://pan.baidu.com/s/10xJBTxyDQjweUI6C6LhrNQ).
**Note**: The peak working current of the NB-IoT universal module will reach more than 300mA. Be sure to leave a margin when designing the power supply.
#### Build Minimal Hardware System
* Serial communication circuit-serial level 1.8V, level conversion required
* UART0: module firmware programming pin, which is generally not used in the solution connection process, which can connect to test point debug (baud rate 115200)
* UART1 (commonly used): Universal docking pin, used for serial communication between module and user chip (baud rate 115200 or 9600)
* UART2: Log print pin, used to find problems in the docking process. It needs to be used for collaborative judgment by grabbing logs, which can connect to test point debugging. (Baud rate 921600)
* Module wake-up circuit：
* Power-on wake-up pin： PWRKEY
* Low-power consumption mode wake-up pin： PSM\_EINT
* Sim card circuit： Determine SIM Encapsulation useing USIM or eSIM before designing (Will purchase SIM card according to product features)
* Power supply circuit： The peak working current of the NB-IoT universal module will reach more than 300mA. Be sure to leave a margin when designing the power supply
* Antenna circuit： Antenna RF circuit can refer to the hardware design manual (The antenna needs to communicate to the antenna manufacturer for matching.)
#### Network verification
After getting the module, you don't need to write code first, first determine whether the module is working properly. Using the module debugging assistant (MCU simulation mode) provided by Tuya to cooperate with the module can perform network config operation, verify the module and be familiar with the protocol interaction process at the same time, and the development and debugging efficiency will be greatly improved later.
Tuya MCU simulation debugging assistant can simulate MCU data transmission and reception. Set up the minimum system of the module and connect the serial port to the computer. The assistant has the following functions: 1. Pair with a networked module and verify that the module is working properly. 2. Before the MCU completes development, debug the App panel display. 3. When the MCU developer does not know how to send and reply data to the module, the data of the simulation assistant can be used as a reference.
For more information, please refer to the [Module Debugging Assistant Instruction](https://docs.tuya.com/en/iot/device-development/access-mode-simmulator/access-mode-mdodule-simmulator)
> Module Debugging Assistant (MCU simulation mode)
**step1.** According to the minimum system schematic diagram, build the module peripheral circuit, simple test can fly wire directly.
**step2.** Open the Tuya module debugging assistant in the development kit and import the debugging file. Protocol selection NB-IoT general protocol, MCU simulation mode.
**step3.** Connect the module serial port to the computer through the USB to TTL tool. The assistant selects the corresponding serial port and baud rate. Open the serial port and click Start. You will see that the module and the host computer automatically perform the initialization process protocol interaction.
**Note：** After the NB-IoT module is powered on, it will continuously send heartbeat packets. After receiving the correct response, it will perform subsequent initialization protocol interactions. If no data is sent after power on, please check if the peripheral circuit of the module is correct.
#### App Scan Code Binding
* Registration: After the factory authorization of NB-IoT module, Tuya Cloud will pull the module information and register the module on the telecommunication IoT platform.
* Activation: After the NB-IoT module is powered on for the first time and initialized, it will connect to the telecommunications IoT platform for activation, subject to the network status issued by the module.
* Use: Only modules that have been activated and not bound by other accounts can be successfully bound by the app.
> Note: NB-IoT QR Code is generated and printed by Tuya productions Tools. You can ask staff for details.
### Software Debugging
During hardware debugging, you can see that the module and the MCU have a series of serial protocol interaction data. For the data analysis part, users can refer to the protocol document in the development kit. The agreement is mainly divided into two parts: the basic protocol and the functional protocol.
The basic protocol has nothing to do with the product. It is a common protocol of the module, including module initialization instructions and some extended function instructions.
The functional protocol part is mainly based on the reporting and issuing command words of the basic protocol, and details the format of the Datapoint content. The full content of the basic protocol, the document center is kept updated in real time, you can click the link to view: [Tuya Cloud NB-IoT Universal Serial Port Access Protocol](https://docs.tuya.com/zh/iot/device-development/access-mode-mcu/nbiot-general-solution/universal-serial-port-access-protocol).
There are two ways for the MCU to connect with the Tuya module protocol: transplant the MCU SDK or connect the protocol by yourself.
* Connect protocol by yourself:
When the MCU resources are limited or the MCU SDK is not suitable for porting, customers can choose to connect the serial port protocol by themselves.
* Transplant MCU SDK:
If the MCU resources are sufficient, it is generally recommended that users directly port the MCU SDK for efficient and convenient development. The MCU SDK in the development kit is a C-based protocol application code provided by Tuya, which can be directly added to the MCU project.
The MCU SDK requires MCU hardware resources: Flash 4K bytes; RAM is related to the length of the DataPoint, about 100 bytes (if OTA function is required, it must be bigger than 260 bytes); the number of function nesting levels is 9 levels. If users with insufficient resources can connect the protocol by themselves, the functions in the SDK package can still be used as a reference.
For details can see: [Overview of migrating Tuya's MCU SDK](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/protocol-reference-wifi/overview-of-migrating-tuyas-mcu-sdk).
### Functions Debugging
After porting the MCU SDK code development, you can use the Tuya module debugging assistant - module simulation mode to verify the correctness of the MCU code. The usage method is similar to the MCU simulation mode. In the simulation module mode, the assistant will automatically send the initialization data stream to verify that the MCU response is correct and give corresponding prompts for the incorrect data. After the initial interaction is passed, you can manually click to test other extended functions.
**Note：** module simulation mode do not supply network functions, only used to verify the correctness of the MCU serial protocol transmission and reception. After the test is completed, the MCU can be connected to the actual module and test the network.
> Module Debugging Assistant (Module simulation mode)
Other Debugging Common Tools Links：
[Operations Center Guide](https://docs.tuya.com/en/iot/guidelines-for-platform/operation-center/operation#%E8%AE%BE%E5%A4%87%E6%97%A5%E5%BF%97%E6%9F%A5%E8%AF%A2%EF%BC%88%E6%94%AF%E6%8C%81%E5%8D%95%E4%B8%AA%E8%AE%BE%E5%A4%87%E4%BD%BF%E7%94%A8%E8%A1%8C%E4%B8%BA%E6%9F%A5%E8%AF%A2%EF%BC%89)：Tuya Smart Developer Platform - Operation. You can check device background log here according to your product id.
[Tutorial for Tuya Support Center](https://docs.tuya.com/en/iot/guidelines-for-platform/support-center/troubleshooting)：Tuya provide online technical support, you can ask any questions like the question about documents here.
[FAQ](https://docs.tuya.com/en/iot/device-development/access-mode-mcu/nbiot-general-solution/dsad)：FAQ, you can read it before developing to avoid some problem.
# Introduction to NB Module - NM1
## About This Document
### Applicable Scope
This document describes hardware interface specifications, electrical features, mechanical specifications, and other related in formation about the NM1 module to help you design and develop NM1 module hardware.
### Purpose
This document provides NM1 module design and development bases. Through this document, you can know the NM1 module and its technical parameters and develop related functional product or devices. In addition to functional features and technical parameters, this document also describes the product reliability test, related test standards, service function implementation process, RF performance indicators, and circuit design.
### Acronyms and Abbreviations
Table 1-2 Acronyms and abbreviations
| **Acronyms** | **Full Spelling** |
| ------------ | ------------------------------------------- |
| ESD | electrostatic discharge |
| USB | Universal Serial Bus |
| UART | universal asynchronous receiver/transmitter |
| SIM | subscriber identity module |
| SPI | serial peripheral interface |
| I2C | inter-integrated circuit |
| I/O | Input/Output |
| GPIO | General Purpose Input/Output |
| TDB | To be determined |
| RTC | real-time clock |
| ADC | analog to digital converter |
## Product Overview
NM1 is a compact , high performance, and low power NB IoT series module. It has the following features:
* Supports the B1,B3, B5, B8, B20 frequency bands (B2/B23/B13/B17/B18/B19/B25/B26/B28/B66 are in developing stage).
* Provides the SIM card interface (1.8 V), USB 1.1 interface, UART interface, SPI, I 2 C interface, and GPIO interface.
### Package Dimensions
The NM1 module has 66 pins. Its dimensions is 17.7 2.4 mm (H) x 17.7 mm (W) x 15.8 mm (D).
### Technical Parameters
Table 2-1 describes mechanical features, baseband features, RF features, technical standards, and environment features of the NM1 module.
Table 2-1 Technical parameters of the NM1 module
| **Item** | **Parameter** | **Specifications** |
| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mechanical features | Package size and type | 17.7 mm x 15.8 mm x 2.6 mm Stamp hole (52 pins) and base pad (14 pins) |
| Module | Platform | MT2625 |
| Module | Processor architecture | ARM Cortex-M4 |
| Module | SIM card interface | 1.8 V |
| Module | USB interface | USB 1.1 |
| Module | Voltage | 2.1 V to 3.63 V |
| Module | Working mode | Active: The NM1 module is active and can send and receive data. All functions are available. An active NM1 module can switch to the idle or PSM mode. Idle: The NM1 module is in idle state, connected to a network, and can receive paging messages. An idle NM1 module can switch to the active or PSM mode. PSM: Only RTC of the module works, and the module is disconnected from the network and cannot receive paging messages. The NM1 module is woken up from the PSM mode when the timer expires or the PWRKEY and PSM\_EINT\* pins are lowered. |
| Module | Power-saving | In PSM mode, the NM1 module consumes the minimum power of 5 µA. The PSM mode is provided to reduce power consumption and prolong the power supply duration of the battery. |
| Module | Serial port | Primary serial interface: transmits AT commands and data. The default baud rate is 115.2 kbit/s. It can also be used for firmware upgrade and the baud rate is 921.6 kbit/s. Debugging serial interface: exports log information for software commissioning. Auxiliary serial interface: transmits AT commands and data. |
| Module | Working current | TBD |
| Module | RTC | Supported |
| Module | ADC\* | The NM1 module has a 10-bit analog-digit conversion input interface to measure the voltage. This interface works in both active and idle modes. |
| Module | RI signal\* | When the NM1 module receives SMS messages or exports URC, it notifies the DTE over the RI pin. |
| Module | Network status indication\* | The NETLIGHT signal indicates the module's network connection status. |
| RF | Frequency band | B1, B2\*, B3, B5, B8, B12\*, B13\*, B17\*, B18\*, B19\*, B20, B25\*, B26\*, B28\*, and B66\* |
| RF | Maximum TX power | 23±2 dBm |
| RF | Receiving sensitivity | TBD |
| RF | Main antenna interface | Supported |
| RF | Antenna interface | Characteristic impedance of 50 ohms. The antenna is provided by a third party, but not Tuya. |
| Technical standard | Data rate | Single-tone: downlink 25.5 kbit/s and uplink 16.7 kbit/s Multi-tone\*: downlink 25.5 kbit/s and uplink 62.5 kbit/s |
| Technical standard | Network protocol | UDP/TCP/CoAP/LWM2M/PPP\*/SSL\*/DTLS\*/FTP\*/HTTP\*/MQTT\*/HTTPS\* |
| Environment feature | Temperature | Normal operating temperature: –35°C to +75°C1 Extended operating temperature: –40°C to +85°C2 Storage temperature: –40°C to +90°C |
| application | SMS\* | Text and packet data unit (PDU) modes |
| application | Upgrade | Upgrade is performed over the primary serial interface. |
Note:
1\) When the NM1 module works at a temperature within the normal operating temperature range 1 , its performance complies with 3GPP standards.
2\) When the NM1 module works at a temperature within the extended operating temperature range 2 , it works properly, has the SMS\* and data transmission functions, and will not have unrecoverable faults. The RF spectrum and network are not affected. Several indicators, for example, the output power, may exceed the 3GPP limits. After the operating temperature is restored to the normal operating temperature, all NM1 module indicators can meet 3GPP standard requirements.
3\) A feature with an asterisk (\*) is being developed.
### Product Functions
#### Baseband Functions
The NM1 module baseband includes the USB interface signal, SIM card interface signal, I 2 C interface signal, UART interface signal, working status indicator signal, module startup and reset signals, and multiplexing control signals, power supply, and grounding of multiple GPIO interfaces.
#### RF Functions
Table 2-2 Working frequency bands
| **Working Frequency Band** | **Uplink (MHz)** | **Downlink (MHz)** |
| -------------------------- | ---------------- | ------------------ |
| B1 | 1920–1980 | 2110–2170 |
| B2\* | 1850–1910 | 1930–1990 |
| B3 | 1710–1785 | 1805–1880 |
| B5 | 824–849 | 869–894 |
| B8 | 880–915 | 925–960 |
| B12\* | 699–716 | 729–746 |
| B13\* | 777–787 | 746–756 |
| B17\* | 704–716 | 734–746 |
| B18\* | 815–830 | 860–875 |
| B19\* | 830–845 | 875–890 |
| B20 | 832–862 | 791–821 |
| B25\* | 1850–1915 | 1930–1995 |
| B26\* | 814–849 | 859–894 |
| B28\* | 703–748 | 758–803 |
| B66\* | 1710–1780 | 2110–2200 |
Note: The NM1 module is being developed to support the frequency bands with an asterisk (\*).
Table2-3 Line loss requirements
| **Frequency Band** | **Requirement** |
| ---------------------------------------------------------------------- | ------------------ |
| LTE B5, B8, B12\*, B13\*, B17\*, B18\*, B19\* , B20, B26\* , and B28\* | Line loss < 1 dB |
| LTE B1, B2\*, B3, B25\*, and B66\* | Line loss < 1.5 dB |
Table 2-4 Antenna requirements
| **Item** | **Requirement** |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| Frequency band | LTE B1, B2\*, B3, B5, B8, B12\*, B13\*, B17\*, B18\*, B19\*, B20, B25\*, B26\*, B28\*, and B66\* |
| Standing wave ratio (SWR) | ≤ 2 |
| Efficiency (%) | ≥ 30 |
| Maximum input power (W) | 50 |
| Input impedance (ohm) | 50 |
| Polarization type | Linear polarization |
Note: The NM1 module is being developed to support the frequency bands with an asterisk (\*).
Table 2-5 Conducted RF transmit power
| **Frequency Band** | **Maximum Value (dBm)** | **Minimum Value (dBm)** |
| ------------------ | ----------------------- | ----------------------- |
| B1 | 23±2 dBm | < –39 |
| B2\* | 23±2 dBm | < –39 |
| B3 | 23±2 dBm | < –39 |
| B5 | 23±2 dBm | < –39 |
| B8 | 23±2 dBm | < –39 |
| B12\* | 23±2 dBm | < –39 |
| B13\* | 23±2 dBm | < –39 |
| B17\* | 23±2 dBm | < –39 |
| B18\* | 23±2 dBm | < –39 |
| B19\* | 23±2 dBm | < –39 |
| B20 | 23±2 dBm | < –39 |
| B25\* | 23±2 dBm | < –39 |
| B26\* | 23±2 dBm | < –39 |
| B28\* | 23±2 dBm | < –39 |
| B66\* | 23±2 dBm | < –39 |
Note:
1\) The designed conducted RF transmit power complies with the NB IoT protocol in 3GPP Release 13 and Release 14.
2\) The NM1 module is being developed to support the frequency bands with an asterisk (\*).
## Interfaces
### Pin Definition
#### Pin Symbols
Table 3-1 Pin symbols
| **Pin Symbol** | **Description** |
| -------------- | --------------- |
| I | Input |
| O | Output |
| I/O | Input/Output |
#### Pin Configuration Diagram
Figure 3-1 shows the NM1 module's interface pins.
#### Pins
Table 3-2 Interface pin definition
| **Pin No.** | **Analog Signal Definition** | **Pin Attribute** | **Input/Output** | **Pin Voltage (V)** | **Remarks** |
| ----------- | ---------------------------- | --------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| 1 | AGND | GND | N/A | N/A | N/A |
| 2 | GPIO0 | GPIO0 | N/A | 1.8 | N/A |
| 3 | SPI\_MISO | Primary device input and secondary device output signal | I | 1.8 | N/A |
| 4 | SPI\_MOSI | Primary device output and secondary device input signal | O | 1.8 | N/A |
| 5 | SPI\_SCLK | Serial clock signal | O | 1.8 | N/A |
| 6 | SPI\_CS | Chip selection signal | O | 1.8 | N/A |
| 7 | PWRKEY | Lower PWRKEY to power on the NM1 module. | I | Maximum value of VIL: 0.3 x VBAT Minimum value of VIH: 0.7 x VBAT | N/A |
| 8 | GPIO22 | GPIO22 | N/A | N/A | N/A |
| 9 | ADC0 | Common analog-digit conversion interface | I | 0–1.4 V | N/A |
| 10 | SIM\_GND | GND dedicated for the SIM card | N/A | N/A | N/A |
| 11 | SIM\_DATA | SIM card data signal | I/O | Maximum value of VIL: 0.25 x SIM\_VDD Minimum value of VIH: 0.75 x SIM\_VDD Maximum value of VOL: 0.15 x SIM\_VDD Minimum value of VOH: 0.85 x SIM\_VDD | N/A |
| 12 | SIM\_RST | SIM card reset signal | I/O | Maximum value of VOL: 0.15 x SIM\_VDD Minimum value of VOH: 0.85 x SIM\_VDD | N/A |
| 13 | SIM\_CLK | SIM card clock signal | I/O | Maximum value of VOL: 0.15 x SIM\_VDD Minimum value of VOH: 0.85 x SIM\_VDD | N/A |
| 14 | SIM\_VDD | SIM card power signal | O | 1.8 | N/A |
| 15 | RESET | Used to reset the NM1 module, which is active at low level | I | N/A | N/A |
| 16 | NETLIGHT | Network status indication | O | N/A | N/A |
| 17 | RXD | Primary serial interface that receives data | I | 1.8 | N/A |
| 18 | TXD | Primary serial interface that transmits data | O | 1.8 | N/A |
| 19 | PSM\_EINT | External interrupt pin, which is used to wake up the NM1 module from the PSM mode | I | N/A | N/A |
| 20 | SRCLKENAI | NFC interface | N/A | 1.8 | N/A |
| 21 | USB\_DP | USB+ signal | N/A | N/A | N/A |
| 22 | USB\_DM | USB– signal | N/A | N/A | N/A |
| 23 | USB\_EINT | USB\_EINT | | | N/A |
| 24 | VIO18\_EXT | 1.8 V output power (In PSM mode, no voltage is output.) | O | Vmin = 1.53 V Vnorm = 1.8 V | N/A |
| 25 | DVDD\_IO | NC | NC | NC | N/A |
| 26 | NC | NC | N/A | N/A | N/A |
| 27 | GND | GND | N/A | N/A | N/A |
| 28 | UART1\_RXD | Auxiliary serial interface that receives data | I | 1.8 | N/A |
| 29 | UART1\_TXD | Auxiliary serial interface that transmits data | O | 1.8 | N/A |
| 30 | UART1\_CTS | Determines whether data is received. | N/A | 1.8 | N/A |
| 31 | UART1\_RTS | Determines whether data is transmitted. | N/A | 1.8 | N/A |
| 32 | I2C0\_SDA | I2C0 data | I/O | N/A | N/A |
| 33 | I2C0\_SCL | I2C0 clock | O | N/A | N/A |
| 34 | GND | GND | N/A | N/A | N/A |
| 35 | RF\_ANT | RF antenna | Characteristic impedance of 50 ohms | | |
| 36 | GND | GND | N/A | N/A | N/A |
| 37 | GND | GND | N/A | N/A | N/A |
| 38 | RXD\_DBG | Debugging serial interface that receives data | I | 1.8 | N/A |
| 39 | TXD\_DBG | Debugging serial interface that transmits data | O | 1.8 | N/A |
| 40 | GND | GND | N/A | N/A | N/A |
| 41 | GND | GND | N/A | N/A | N/A |
| 42 | VSYS\_BB | Input power | I | Vmin = 2.1 V Vnorm = 3.3 V Vmax = 3.63 V | N/A |
| 43 | VBAT\_BOOST | Input power | I | Vmin = 2.1 V Vnorm = 3.3 V Vmax = 3.63 V | N/A |
| 44 | VSYS\_PA | Output power | O | 3.3 | N/A |
| 45 | GPIO11 | Reserved | N/A | 1.8 | N/A |
| 46 | GPIO10 | Reserved | N/A | 1.8 | N/A |
| 47 | GPIO25 | Reserved | N/A | 1.8 | N/A |
| 48 | MD\_WAKEUP | N/A | N/A | N/A | N/A |
| 49 | GPIO28 | Reserved | N/A | 1.8 | N/A |
| 50 | AP\_READY | N/A | N/A | N/A | N/A |
| 51 | STATUS | N/A | N/A | N/A | N/A |
| 52 | GPIO24 | Reserved | N/A | 1.8 | N/A |
| 53 | GPIO34 | Reserved | N/A | 1.8 | N/A |
| 54 | GPIO33 | Reserved | N/A | 1.8 | N/A |
| 55 | GPIO21 | Reserved | N/A | 1.8 | N/A |
| 56 | GPIO20 | Reserved | N/A | 1.8 | N/A |
| 57 | GPIO8 | Reserved | N/A | 1.8 | N/A |
| 58 | GPIO1 | Reserved | N/A | 1.8 | N/A |
| 59 | GPIO19 | Reserved | N/A | 1.8 | N/A |
| 60 | RTC\_GPIO0 | N/A | N/A | N/A | N/A |
| 61 | SIM\_DET | GPIO35 | N/A | SIM card detection | N/A |
| 62 | GPIO32 | Reserved | N/A | 1.8 | N/A |
| 63 | AVDD33\_VUSB | N/A | I | N/A | N/A |
| 64 | FREF | Base frequency | I | N/A | N/A |
| 65 | GPIO31 | GPIO31 | N/A | 1.8 | N/A |
| 66 | GND | GND | N/A | N/A | N/A |
### Electrical Conditions
Table 3-3 Electrical conditions
| **Signal** | **Description** | **Minimum Value** | **Typical Value** | **Maximum Value** | **Unit** |
| ----------- | --------------- | ----------------- | ----------------- | ----------------- | -------- |
| VBAT\_BOOST | Input power | 2.1 | 3.3 | 3.63 | V |
| VSYS\_BB | Input power | 2.1 | 3.3 | 3.63 | V |
| VSYS\_PA | Output power | N/A | 3.3 | N/A | V |
### Power Interface
#### Power Pins and Grounding
The NM1 module can be powered by a battery or external power supply. The GND signal pins indicate the power ground and signal ground of the NM1 module and need to be connected to the ground of the PCB . Improper connections of the GND signal pins may have adverse impact on the NM1 module performance.
#### Power Supply Requirements
The NM1 module's power design is important to its performance. The NM1 module can be powered by the low dropout regulator (LDO) with low static current and output current (up to 0.5 A) or the Li MnO2 battery. The input voltage range is from 2.1 V to 3.63 V. During data transmission, the power cannot be lower than the minimum working voltage 2.1 V. Otherwise, errors will occur. To ensure better power supply performance, it is recommended that three 47 µF (0805) ceramic capacitors and100 nF, 100 pF, and 22 pF (0402) filter capacitors be connected in parallel at the VBAT input end of the module. In addition, it is recommended that a TVS tube be connected to the VBAT input end to enhance the surge voltage bearing capability of the module. In principle, a longer VBAT cable leads to a larger trace width. Figure 3 2 shows the reference circuit.
### SIM Card Interface
#### Pins
Table 3-4 Definition and description of SIM card interface signals
| **Pin No.** | **Signal Name** | **Signal Definition** | **Remarks** |
| ----------- | --------------- | ------------------------- | -------------------------------------------------------- |
| 11 | SIM\_DATA | SIM card data pin | Voltage precision: 1.8 V±5% Maximum current: about 60 mA |
| 13 | SIM\_CLK | SIM card clock pin | Voltage precision: 1.8 V±5% Maximum current: about 60 mA |
| 12 | SIM\_RST | SIM card reset pin | Voltage precision: 1.8 V±5% Maximum current: about 60 mA |
| 14 | SIM\_VDD | SIM card power supply pin | Voltage precision: 1.8 V±5% Maximum current: about 60 mA |
#### SIM Card Interface Application
To ensure a better external SIM card performance and prevent the external SIM card being damaged, design the SIM card interface circuit in compliance with the following rules:
1）Place the external SIM card holder near the NM1 module. The external SIM card signal cable is 200 mm or shorter and is away from the RF cable and VBAT power cable.
2）The SIM\_VDD decoupling capacitance does not exceed 1 μF, and the capacitor is near the external SIM card holder.
3）To prevent interference, keep the SIM\_CLK and SIM\_DATA signal cables at a certain distance from each other and use a ground cable to separate them
4）Connect the SIM\_RST signal cable to the ground. To ensure a better ESD performance, you are advised to use TVS tubes to protect the pins of the external SIM card holder. The parasitic capacitance of the TVS tubes cannot be greater than 50 pF. Place ESD components near the external SIM card holder. Route the external SIM card signal cable from the external SIM card holder to the NM1 module through the ESD components.
### SPIs
#### Pins
Table 3-7 defines the SPI signals. (SPIs support the slave mode.)
Table 3-5 SPI signal definition
| **Pin No.** | **Signal Name** | **Function Description** |
| ----------- | --------------- | ----------------------------- |
| 3 | SPI\_MISO | Master input and slave output |
| 4 | SPI\_MOSI | Master output and slave input |
| 5 | SPI\_ SCLK | SPI clock signal |
| 6 | SPI\_CS | SPI selection signal |
#### SPI Electrical Parameters and application
The level of the SPI on the NM1 module is 1.8 V. If the host level is 3.3 V, add a level converter between the NM1 module and host. The level converter that supports the SPI data rate is recommended. Figure 3 4 shows the reference circuit.
### I2C Interface
#### Pins
Table 3-6 I2C interface signal definition
| **Pin No.** | **Signal Name** | **Function Description** |
| ----------- | --------------- | ------------------------ |
| 32 | SDA | I2C serial data |
| 33 | SCL | I2C serial clock |
I2C is a two line bus for communication between ICs. It has a serial data cable (SDA) and a serial clock cable (SCL) to transmit information between connected devices. I 2 C identifies each device based on its unique address and can be used as both a transmitter and a receiver.
### I2C Interface Electrical Parameters and application
### UART Interface
#### Pins
The NM1 module provides three UART interfaces. The primary serial interface can be used for firmware upgrade. The default baud rate is 115.2 kbit/s, and the downloading baud rate is 921.6 kbit/s. You can use a log viewing tool to view logs over the debugging serial interface to debug software.
Table 3-7 UART interface signal definition
| **Pin No.** | **Signal Name** | **Function Description** |
| ----------- | --------------- | ----------------------------------------------------- |
| 17 | RXD | Data receiving over the primary serial interface |
| 18 | TXD | Data transmission over the primary serial interface |
| 28 | UART1\_RXD | Data receiving over the auxiliary serial interface |
| 29 | UART1\_TXD | Data transmission over the auxiliary serial interface |
| 38 | RXD\_DBG | Data receiving over the debugging serial interface |
| 39 | TXD\_DBG | Data transmission over the debugging serial interface |
### UART Interface Electrical Parameters and application
Figure 3-6 Reference circuit
The level of the UART interfaces on the NM1 module is 1.8 V. If the application system level is 3.3 V, add a level converter to the connection between the NM1 module and application system over the serial interface. Figure 3 7 shows the reference circuit with a level converter, UM3202.
A triode can also be used for level conversion.
Note: Connection methods of the debugging, auxiliary, and primary serial interfaces are similar.
### USB Interface
#### Pins
The NM1 module has a USB 1.1 interface, which can only be used for module upgrade. If ESD design is required, the maximum capacitance of ESD components must be less than 0.5 pF. Otherwise, waveform distortion may occur, affecting bus communication. The differential impedance of differential data cables must be within 90 ohms.
Table 3-8 USB inte rface signal definition
| **Pin No.** | **Signal Name** | **Function Description** |
| ----------- | --------------- | -------------------------------------- |
| 17 | RXD | Receiving over the serial interface |
| 18 | TXD | Transmission over the serial interface |
| 21 | USB\_DP | USB+ signal |
| 22 | USB\_DM | USB– signal |
| 63 | AVDD33\_VUSB | Internal USB power supply |
#### USB Interface Application
The nominated input power of the NM1 module is 3.3 V. When the USB interface is used for downloading, add an LDO circuit to keep t he circuit voltage at 3.3 V.
### Power On/Power Off and Reset Interface
#### PWRKEY Pin
Table 3-9 PWRKEY signal definition
| **Pin No.** | **Signal Name** | **Function Description** |
| ----------- | --------------- | ------------------------ |
| 7 | PWRKEY | NM1 module power-on |
#### Power On/Power Off Interface application
To power on the NM1 module, lower the PWRKEY pin to a low level for a period of time and then disconnect it or raise it to a high level.
#### RESET Pin
| **Pin No.** | **Signal Name** | **Function Description** |
| ----------- | --------------- | ------------------------ |
| 15 | RESET | NM1 module resetting |
To reset the NM1 module, lower the RESET pin to a low level for a period of time and then disconnect it or raise it to a high level.
#### RESET Interface Application
## Design Instructions
This chapter provides general design guidance about the NM1 module to ensure a better product performance.
### General Design Rules and Requirements
During peripheral circuit design, ensure that the external power supply have sufficient power and the differential impedance of the USB 1.1 signa l cable is within 90 ohms. Design general signal interfaces as required to match the interface signal level and prevent the NM1 module being damaged due to inconsistent levels. The NM1 module has good RF indicator performance. You need to design the antenna circuit on the PCB as required and control the impedance to prevent the RF indicators being affected.
### Power Supply Circuit Design
The power supply on the PCB should supply 0.5 A or higher power to meet peak current requirements of the NM1 module. The trace width on the PCB must be large enough and form good circulation with the ground. In addition, add a large capacitor with over 1000 μF to the power supply circuit to ensure transient power supply, and control the power ripple within 100 mV.
### RF Circuit Design
| 34 | GND | GND | N/A | N/A | N/A |
| -- | ------- | ---------- | --- | -------------------------------- | --- |
| 35 | RF\_ANT | RF antenna | | 50 ohms characteristic impedance | |
| 36 | GND | GND | N/A | N/A | N/A |
| 37 | GND | GND | N/A | N/A | N/A |
#### RF Antenna Circuit Design
It is recommended that a πtype matching circuit be reserved during RF antenna per ipheral circuit design. Ensure that the matching circuit is near the antenna, and attach resistors based on actual debugging conditions.By default, no resistor is attached to C1 and C2, and a 0 ohms resistor is attached to R1. The RF antenna peripheral circuit must have 50 ohms impedance. In the recommended RF antenna peripheral circuit layout solution, the RF cable is routed at layer 1 and the reference cable at layer 2. Use the Shortcut to Si9000 software to calculate the PCB cable impedance of the RF antenna. Figure 4 1 shows a model. During PCB cabling design, ensure that the RF reference point is complete.
During impedance calculation, specify parameters shown in Figure 4 2 and change the RF trace width to obtain the required impedance value. For typical antennas, 50 ohm impedance is recommended.
#### Precautions for Initial Antenna Design
**Pre-project Evaluation**
Ensure that the antenna is horizontal with the base station for maximum efficiency. Do not place the antenna near the power cable, data cable, or chip that may generate electromagnetic interference. Do not reserve a place for hands on the antenna to prevent attenuation caused by the human body. Consider radiation reduction and structure implementation. In the initial design phase, th e structure, ID, circuit, and antenna engineers evaluate the antenna layout together.
**Antenna Matching Circuit**
If a long cable exists between the RF and antenna interfaces on the NM1 module, design 50 ohms characteristics impedance for the microstrip or stripline between the RF pad and the antenna interface during PCB circuit design. In addition, reserve a matching circuit.
### Suggestions on EMC and ESD Design
During overall design, consider EMC issues related to signal integrity and power integrity. During peripheral circuit cabling of the NM1 module, reserve doubled trace width between the power cable and signal cable to reduce signal coupling and ensure pure return current. During peripheral power circuit design, place the decoupling capacitor near the power pin on the NM1 module, keep high frequency and high speed circuits and sensitive circuits away from the PCB edges, and isolate the circuits from each other to reduce interference. Protect sensitive signals, and shield circuits or components on the PCB that may interfere the NM1 module. Consider ESD protection during design. Place ESD components near the key input and output signal interfaces, for example, the SIM card signal interface, to protect them. On the PCB , reasonably design mechanical p arts and PCB layout and ensure proper grounding of metal shielding covers to provide a smooth channel for static electricity discharging.
### PCB Solder Pad Design
You are advised to design the middle 14 pads on the PCB based on the sizes in the structure diagram. Externally extend the 52 signal pads around the PCB to the NM1 module for over 0.3 mm, and externally extend other three sides of the pads for 0.05 mm. Use 50 ohms impedance cables for the main antenna and Wi Fi antenna.
### Thermal Design
The NM1 module generates heat when it works and may be affected by other high temperature components. TheNM1 module design ensures good heat dissipation. When connecting the NM1 module to the PCB , properly connect the thermal pad to the ground to ensure thermal conduction and balance and a better electrical performance. Note:
1）Place the NM1 module away from the power supply and high speed signal cables, and protect these cables.
2）Place the antenna and the coaxial cable that is used to connect the antenna and NICPlace the antenna and the coaxial cable that is used to connect the antenna and NIC away from these away from these interference sources. interference sources.
3）Place the NM1 module away from components that generate a large amount of heat such as the CPU to prevent Place the NM1 module away from components that generate a large amount of heat such as the CPU to prevent the RF performance being affected by high temperature.the RF performance being affected by high temperature.
## Production Instructions
### Stencil Design
During stencil design, note the following: 1） When making the stencil of the thermal pad at the bottom of the NM1 module, reduce the stencil opening by 25% to reduce short circuits between the thermal pad and functional pins around the NM1 module. 2）To ensure better solde ring, use step stencils. 3）Use a diagonal opening for the stencil of the thermal pad. Figure 5 1 shows recommended stencil strips.
### Oven Temperature Curve
The oven temperature curve has great impact on the soldering quality and material status. When the temperature rises from the ambient temperature to 150°C, the rising speed is less than 3°C per second. A temperature higher than 217°C is allowed for a maximum of 70s, and 55s is recommended. Otherwise, some components may be invalid due to strong thermal attacks, resulting in a higher defect rate and more repair difficulty. The highest temperature cannot exceed 245°C. Some materials such as the crystal may have die cracks at a high temperature. As a result, the crystal does not work and the module functions are affected. Table 5 1 describes the oven temperature curve parameter settings, and Figure 5 2 shows the oven temperature curves.
| **Lead-free Oven Temperature Curve** | | |
| ------------------------------------ | ------------------------------------- | ------------------------------ |
| **Phase** | **Temperature** | **Description** |
| Preheating | From the ambient temperature to 150°C | Rising speed: < 3°C per second |
| Heat preservation | 150°C to 200°C | Duration: 40s to 110s |
| Soldering | > 217°C | Duration: 40s to 70s |
| Soldering | > 230°C | Duration: 15s to 45s |
| Soldering | Peak temperature | Maximum: 245°C |
| Soldering | Peak temperature | Minimum: 230°C |
To prevent the NM1 module being damaged due to overheating, you are advised to attach the module after reflow soldering of the PCB's first side
## Mechanical Dimensions
This chapter describes the mechanical dimensions of the NM1 module, in millimeters.
### NM1 Module Mechanical Dimensions
### Recommended Package Dimensions
# Access Mode SoC
# SoC Development Overview
### Overview
System on chip (SoC) solutions include development-free and custom firmware solutions that Tuya provides for electrical engineering and lighting products based on its extensive experience in product intelligence.
SoC development-free solution: Tuya provides many mature development-free solutions for electrical engineering and lighting products based on common functions and types of the products. After you select a development-free solution and configure product information online, Tuya will send the network connection module to you. The plug-and-play module immediately enables the settings you specify online after you connect it to your product without development.
SoC custom firmware solution: If the development-free solution cannot meet your functional requirements, select the SoC custom firmware solution. After you submit your requirements on the **Hardware Debug** page, a dedicated Tuya development team will develop the firmware and send the module with a customized panel and cloud functions to you.
SoC solutions help you quickly and efficiently make your products intelligent and mass-produce the products at low cost.
SoC solutions apply to switches, sockets, and bulbs and security\&sensor product. If you have higher development and configuration requirements for the preceding products, select the MCU development mode.
### Development Process Using a SoC Development-free Solution
#### Product Creation
**Logging In to the Tuya Smart Platform**
Log in to the Tuya Smart platform at with your Tuya account. If you do not have a Tuya account, register one.
#### Creating a Product
On the **Product** page, click **Create** in the **Easy Access to Get Your Smart Product** area.Select a product type. To create a switch or socket, click **Electrical**. To create a bulb, click **Smart Lighting**.Based on the network configuration mode and basic specifications of your product to be created, click a product image under **Plug and Play Solution**.
**Configuring Basic Product Information**
(Mandatory) Specify the product name. The product name is in *Brand* + *Product* + *Module model* format.
(Optional) Specify the product model (SN) to distinguish your product.
Confirm the communication mode. By default, the communication mode is the same as that in the previous development-free solution.
#### Configuring the Product Online
**Function Definition**
1. **Product configuration progress bar:** A product configuration progress bar is displayed on the top of the page. Configure the product information step by step.
2. **Submit your question**: Click **Submit your question** and report your development questions.
3. **Product information:**
Thumbnail: indicates the type of the product that you have created.
PID: the unique identifier of the product, which contains information about the product configuration, App, and module. Keep the product PID secure.
**Edit Product Information**: allows you to edit the product name, product model, and remarks. After modifying any information, click **Save** to save the modification.
4. **Product functions:** Click **View function details** to view functions of the product that you have created. The Tuya Smart team has defined functional solutions for smart switches, sockets, and bulbs. If the solutions cannot meet your requirements, create a custom product that does not use a SoC solution.
Confirm the product information and functions, and click **Next**.
**App UI Design**
**Selecting an App Control Panel Template**
Select a UI template for the App control panel used to control functions of your smart product and click **Next**.
**Verifying the App Control Panel Effect**
Download the Tuya Smart or Smart Life App and scan the QR code for the App UI template that you select to verify the App control panel effect. To change the UI style, click **Previous**, select another UI template, and click **Next**.
Scan the QR code to download the Tuya Smart App.
Scan the QR code to download the Smart Life App.
**Hardware Debug**
If you have hardware development capabilities, select a module and configure I/O port information based on the reference circuit diagram. The module firmware will be generated automatically. After you purchase the module, Tuya will burn the firmware on the module and send the module to you for testing.
**Selecting a Module**
Click **Module details** to view detailed information about the selected module or click **Change module** to select another module. You are advised to select a recommended module that supports most product functions and can meet your product requirements.
**Checking the Reference Circuit Diagram**
The **Circuit reference diagram** area displays a diagram of the circuit between the module you select and the product.
**Configuring Module Firmware I/O Port Information**
Configure the I/O port information by referring to the Corresponding figure of IO id and module IO name figure. Check the firmware configuration information, modify it as needed, and save the modification. The module will be programmed based on the settings that you specify on this page. After the module is delivered, the settings cannot be modified. If you modify the settings after the module is delivered, any online upgrades will not apply to the product because the settings will be inconsistent. The I/O port settings for power statistics equipment, sockets, panel switches, and bulbs are different. Enter the I/O port information based on the product type.
**Purchasing the Module**
Purchase the module online for product debugging. The module contains the preceding product configuration information and can be used for product debugging after you purchase it.
**Advanced Features**
After configuring the basic product functions, click **Advanced Features** and configure the following advanced product features based on your requirements: multilingual management, firmware updates, network configuration guide, scenario association, and quick toggles.
**Multilingual**
To manage the App languages, click **Settings** next to **Multilingual**.
1. Change the language. Select a language to display the text content on the App control panel.
2. Change the product name. After you change the product name on the Tuya Smart platform, the product name will be changed in the App accordingly.
3. Change panel fields. After you change the product name on the Tuya Smart platform, the product name will be changed in the App accordingly. For example, you can change **Switch**, **Timer**, and **Countdown**.
**Firmware Updates Center**
The **Firmware Updates Center** settings do not apply to SoC solutions or the MCU solution.
**Network Connections Guides**
The custom network configuration guide settings are available only to OEM App owners. If you use the Tuya Smart/Smart Life App or if you do not select the custom category for your OEM App, the Tuya general guide will apply to your product. After you complete the settings, synchronize the confirmed network configuration information to the product user manual.
**Scenario connection settings**
**Scenario connection settings** allows you to select data points (DPs) that trigger smart scenarios and task settings. Selected DPs will be displayed in the Tuya Smart App for you to configure.
**Quick toggle settings**
On **Quick toggle settings**, select an option for your product. A switch button will be displayed for the product in the Tuya Smart App. In addition, you can add the product to the widget area on the home screen for easy control.
After you change the product name on the Tuya Smart platform, the product name will be changed in the App accordingly.
The product added to the widget area:
#### Mass Production
After hardware debugging of your product is completed, click **Complete development** to enter the trial production phase.
In the trial production phase, you cannot modify the product firmware information, DPs, panel, or module settings. If you need to modify the information, click **Return to development**.
Click **Purchase**. The **Purchase module** page is displayed. Click **Submit**, specify your receiving address and production and delivery requirements, and click **Submit the order**.Before mass production starts, click **apply** in the **In trial production** area to apply for product testing and send samples to the address on the page. The Tuya professional test team will test the product for you and provide you a professional test report. After your product passes the test, click **Pass test, to mass production**. After you release the product, you can click **Purchase module** to place a bulk order for the modules.
### Functions of the Development-free Solution
Tuya has provided SoC development-free solutions based on its extensive experience in successful product intelligence for tens of thousands of customers. Currently, the SoC solutions apply only to electrical engineering and lighting products. The following tables summarize functions of a development-free solution.
Use the Tuya Smart or Smart Life App to scan the QR codes to experience some product solution functions.QR code for the development-free power statistics socket solution:
QR code for the development-free multi-way socket solution:
QR code for the development-free five-way bulb solution:
### Development Process Using a SoC Custom Firmware Solution
#### Product Creation
**Logging In to the Tuya Smart Platform**
Log in to the Tuya Smart platform at with your Tuya account. If you do not have a Tuya account, register one.
#### Creating a Product
On the **Product** page, click **Create** in the **Easy Access to Get Your Smart Product** area.
Click the product to be created under **Custom**.
**Configuring Basic Product Information**
(Mandatory) Specify the product name. The product name is in *Brand* + *Product* + *Module model* format.
(Optional) Specify the product model (SN) to distinguish your product.
Select the correct communication mode for your product.
#### Configuring the Product Online
Function Definition
Function Definition
1. **Product configuration progress bar**: A product configuration progress bar is displayed on the top of the page. Configure the product information step by step.
2. **Submit your question**: Click **Submit your question** and report your development questions.
3. **Product information**: Thumbnail: indicates the type of the product that you have created.
4. **Common functions**: Select product functions.
Confirm the product information and functions, and click **Next**. You are advised to carefully confirm the selected functions to prevent rework.
**Function Customization**
Set and edit standard, custom, and cloud functions and click **Next**.
1. **Configure standard functions.**
Click **Setting** and add standard functions. Click **Edit** or **Delete** next to a single DP to edit or delete it.
1. **Configure custom functions.**
If standard functions do not meet your requirements, define custom functions. DPs are abstract representations of product functions, each of which can be defined by different functional types, including Boolean, numeric, enumeration, fault, string, and transparent.
1. **Configure cloud functions.**
Timer and web page redirection are available. Tuya Cloud's timer function allows you to set the on/off time and intervals and does not require hardware development. The web page redirection function allows you to go to a web page from the App, for example, go to an online mall or the product user manual page.
To display cloud functions on the App control panel, select a UI template that supports cloud functions on the **App UI Design** page. Only some UI templates support cloud functions. The following figure shows cloud functions displayed on the App control panel.
**App UI Design**
The **App UI Design** page of a SoC firmware custom solution is the same as that of a SoC development-free solution.
**Hardware Debug**
**Selecting a Module**
Click **Module details** to view detailed information about the selected module or click **Change module** to select another module. You are advised to select a recommended module that supports most product functions and can meet your product requirements.
**Selecting a Development Solution**
Click **Use module custom firmware**, enter your contact method, specify your product requirements, and click **Submit Requirements**.
The Tuya Smart professional team will evaluate your product requirements and selected solution, develop customized firmware, test the product, and mass-produce the product.
The **Advanced Features** and **Mass Production** settings for a SoC custom firmware custom solution are the similar to those for a SoC development-free solution.
# Lighting
# Guidance
Creating a Plug-and-Play RGBCW Lamp on the Tuya Smart Platform
### Preface
The Tuya Smart platform provides plug-and-play solutions with the Wi-Fi, BLE Mesh (SIG), Zigbee, and BLE Mesh (Tuya) communication modes for LED lighting products, including dimmable white lamps (C), CW or CCT lamps, RGB lamps, RGBC lamps, and RGBCW or RGBCCT lamps.
This document describes how to use a plug-and-play solution to develop a Wi-Fi RGBCW lamp on the Tuya Smart platform and the precautions.
### Registering with and Logging In to the Tuya Smart Platform
1. Register with and log in to the Tuya Smart platform at .
2. (Recommended) Complete enterprise certification to upgrade your account to a corporate account with more functions.
### Creating an SoC Plug-and-Play RGBCW Lamp
1. On the **Product** page, click **Create** in the **Easy Access to Get Your Smart Product** area.
2. (Recommended) On the displayed **Create new product** page, choose **Smart Lighting** and select a product under **Plug and Play Solution**. Alternatively, select a product under **Custom** if the development-free solution cannot meet your product function requirements.
1. Specify the product name, which will be displayed on the App control panel.
2. Specify the internal or customer product model to facilitate product maintenance and order management.
3. After the product is created, click **Edit Product Information** on the product configuration page to modify the product name and model.
4. If you subscribe to a third-party service for the product, the third-party service subscription icon is highlighted for the product on the **Product** page.
### Viewing DPs
You cannot modify data points (DPs) of a plug-and-play solution. To view the DPs, click **View function details**.
### Configuring the App Control Panel
1. Click **App UI Design**. If you have upgraded your account to a corporate account, more templates and panel UI functions are available.
2. Select a control panel template and use the Tuya Smart or Smart Life App to scan the QR code to verify the control panel effect.
3. If you select a custom panel, click **Edit** to change panel elements, such as the background color and image.
### Debugging the Hardware
Perform operations in this chapter to configure the module's electrical parameters. It is recommended that engineers perform these operations because setting the parameters requires professional knowledge.
#### Selecting a Module and Checking the Reference Circuit Diagram (If you change the module, the reference circuit diagram will be updated.)
Select a module based on the product encapsulation, placement space, temperature, and antenna type. The Tuya Smart platform provides 10 Wi-Fi modules with their hardware design manuals and I/O interface connection diagrams. Note: The EN pins on the E3S and E3L modules need to be pulled up to a high level. Pay attention to the RF signal reference design. Modules recommended for different lighting products are as follows:
* Bulbs: TYE3L
* Filament lamps: TYLC5
* Candle lamps or GU10 bulbs: TYLC4
* Built-in power lamps or power lamps with metal covers: TYE1S-IPEX (supporting an external antenna)
* Power lamps with a plastic cover: TYE1S with an onboard antenna or TYE3S
* Compact products, such as light strip controllers: TYE2S
#### Configuring Module Firmware I/O Interface Information
**IIC Configuration**
a) **IIC Data I/O Interface**: indicates the data I/O interface for IIC communication. Five I/O interfaces are available. If IIC communication is not required, select **None**. The first I/O interface is the default I/O interface.
b) **IIC Clock Signal I/O Interface**: indicates the clock signal I/O interface for IIC communication. Five I/O interfaces are available. If IIC communication is not required, select **None**. The first I/O interface is the default I/O interface.
c) **IIC-2135 Color Light Current**: indicates the RGB light current when the SM2135 chip that uses the IIC protocol is used. The value range is 10 mA to 45 mA.
d) **IIC-2135 White Light Current**: indicates the CW light current when the SM2135 chip that uses the IIC protocol is used. The value range is 10 mA to 60 mA.
e) **IIC-R**, **IIC-G**, **IIC-B**, **IIC-2135-W**, and **IIC-2135-C**: indicate pins on the SM2135 that control the red, green, blue, cold white, and warm white light when the SM2135 chip that uses the IIC protocol is used.
**Product Function**
a) **Max Brightness (%)** and **Min Brightness (%)**: indicate the maximum and minimum duty cycles of the PWM waveforms generated by the I/O interfaces for the cold and warm white light. The value range is 1 to 100.
Note: The **Min Brightness (%)** parameter must be set based on the dimming depth of the selected dimmable integrated circuit (IC). If they do not match, the lamp will turn off in low brightness. The default minimum brightness is 10%.
b) **PWM Frequency (Hz)**: indicates the frequency of each PWM control signal. The value range is 100 Hz to 20,000 Hz.
Note: The **PWM Frequency (Hz)** parameter must be set based on the PWM frequency that the dimmable IC supports. The frequency of most PWM ICs on the market is in the range of 500 Hz to 5000 Hz. When you adjust the frequency to 8000 Hz or higher, ripples in the light are invisible under the mobile phone camera.
c) **Color Temperature Drive Method**: Options are **CW-Cold/Warm** and **CCT-Brightness/Color Temperature**. The two methods have the same functions and UIs in the App and can control the color temperature and adjust the light brightness. They vary in the design of the peripheral circuit. For a CCT lamp, the two channels of PWM signals are independent of each other, with one controlling the overall current and the other adjusting the current proportions of the warm and cold light. Only one channel of PWM signals changes when you adjust the brightness or color. For a CW lamp, one channel of PWM signals controls the cold light while the other controls the warm light. Both channels of PWM signals change when you adjust the brightness or color. CW and CCT lamps are Tuya's internal classification methods. In the industry, CCT lamps are those with a color temperature adjustment feature, which are different from the CCT lamps in Tuya.
Note: This parameter is important. An incorrect value will cause incorrect light control logic. If you are not sure which value to select, send the schematic diagram to Tuya engineers for confirmation.
d) **Color Drive Pin Connection Method**: The options are **Normal PWM Output**, **CW-PWM+RGB-I2C(16726)**, and **CW- I2C(sm2135)+RGB-I2C(sm2135)**. **Normal PWM Output** indicates that three I/O interfaces generate PWM signals to control the red, green, and blue light. **CW-PWM+RGB-I2C(16726)** indicates that the IIC communication method controls the red, green, and blue light between the module and the SM726EB linear IC. **CW- I2C(sm2135)+RGB-I2C(sm2135)** indicates that the IIC communication method controls the red, green, and blue light between the module and the SM2135 linear IC. Note: If you select an incorrect method, the lamp cannot be controlled.
e) **First Network Configuration Trigger Mode**: indicates the method for the module to enter the network configuration mode. **Blink After Power Cycling** indicates that you power-cycle the module several times or press and hold the network configuration button for several seconds to enter the network configuration mode. **Blink After Power-on** indicates that the module automatically enters the network configuration mode after being powered on.
f) **Power-off Memory**: The options are **Power-off Memory** and **Restore to the Default State After Power Cycling**. **Power-off Memory** indicates that the module status remains unchanged each time the product is powered on. However, the status must be retained for over 5s before the product is powered off. **Restore to the Default State After Power Cycling** indicates that the white light is displayed with the default brightness and color temperature after the module enters the network configuration mode. For details on how to set the brightness and color temperature, see "(3) Network Configuration."
g) **On/Off Gradual Change**: indicates whether the module's PWM signal gradually changes from the current duty cycle to 0 when the product is powered off and gradually increases from 0 when being powered on. The options are **Yes** and **No**.
**Network Configuration**
a) **Brightness upon Network Configuration (%)**: indicates the blinking light brightness during network configuration. The value indicates the duty cycle of the PWM signal. The value range is 10 to 100. Note: The minimum dimming depth of some dimmable ICs is 10%. If **Brightness upon Network Configuration (%)** is set to **10**, the lamp will turn off during network configuration and will not blink. It is recommended that **Brightness upon Network Configuration (%)** be greater than 20.
b) **Color upon Network Configuration**: indicates the light blinks in network configuration mode. The options are **R**, **G**, **B**, **C**, and **W**.
c) **Brightness After Network Configuration (%)** and **Color Temperature After Network Configuration**: indicate the white light brightness and color temperature after network configuration. The values are the duty cycles of the PWM signals for controlling the white light brightness and color temperature. Note: The brightness value must be greater than the minimum dimming depth of the dimmable IC, or the lamp will turn off after network configuration. Consumers may think that the lamp is faulty.
**I/O Settings**
Select the I/O interfaces and levels for the red, green, blue, cold white (bright), and warm white (CCT) control signals.
**Network Configuration Settings**
a) **Network Configuration Button**: indicates whether you can press and hold a button to enter the network configuration mode. The options are **None** and multiple I/O interfaces. The value **None** indicates that you cannot press and hold a button to enter the network configuration mode. If an I/O interface is selected, you can press and hold this button to enter the network configuration mode. Note: Select **None** if you do not need to press and hold the network configuration button to enter the network configuration mode. If an I/O interface is selected but not used, the module may be powered on or off unexpectedly.
b) **Button Pressing Time (s)**: indicates the time for pressing and holding the button to enter the network configuration mode. The value range is from 3s to 10s. If **Network Configuration Button** is set to **None**, this parameter does not need to be specified.
c) **Number of Resets**: indicates the number of resets for the module firmware to enter the network configuration mode. The value range is 3 to 10. Note: To power cycle the module's Vcc pin, power cycle the lamp. During network configuration, ensure that the voltage of the Vcc pin is Approaching 0 V before you power the lamp on.
d) **Low-power Control Pin**: indicates the low-power pin during IIC control. Currently, the pin can be configured only under the SM16726B drive. That is, this parameter needs to be specified only if **Color Drive Pin Connection Method** is set to **CW-PWM+RGB-I2C(16726)**.
Note: After all the parameters are configured, click **Save** on the top of the page for the parameters to take effect.
#### Purchasing Modules
After completing the configuration, click **Purchase** to purchase a small number of the modules for product debugging.
**Note: The module will be burned based on the settings that you specify on this page. After the module is delivered, the settings cannot be modified. To modify the settings, repurchase a module. If you modify the settings after the module is delivered, any online upgrades will not apply to the product because the settings will be inconsistent.**
### Configuring Advanced Features
For details on how to configure advanced features, visit .
### Mass Production
1. After you receive the sample modules and complete product debugging, send at least two product samples to Tuya for testing and verifying the product status.
2. After the sample product passes the test, click **Complete development** to enter the trial production phase.
3. After trial production is completed, click **Pass test, to mass production**. In the mass production phase, product settings cannot be modified to prevent misoperations and impact on consumers.
4. Do not delete products that are under development or have been developed to prevent data loss and causing the product to fail to function properly.
# Design
Step-by-Step Tuya Smart Lighting Product Design
### Step 1: Select a Module
#### Wi-Fi Modules
#### Bluetooth mesh Modules (Tuya)
#### Bluetooth mesh Modules (SIG)
#### Zigbee Modules
### Step 2: Select a Module Power Supply Mode
#### AC-DC Constant-Voltage Power Supply
* A module's normal working voltage range is 3.0 V to 3.6 V.
* If the output voltage is higher than 3.3 V, consider the output voltage ripple and output power in addition to the power to the module to prevent insufficient power supply to the module due to undervoltage output. The power supply system must ensure a stable power supply voltage under the maximum output power.
* If the output voltage is the module's power supply voltage or 3.3 V, set the output voltage central value to 3.3 V to have a ripple voltage of less than 100 mV and an average Wi-Fi module current of about 80 mA. The AC-DC power supply system must generate 200 mA current on average. The peak value of the dynamic output current of the power supply system must reach 450 mA, and the voltage drop cannot exceed 2.8 V. The 3.3 V Wi-Fi module's power supply pin is connected to a 0.1 μF ceramic capacitor to reduce interference. To power a 3.3 V Bluetooth or Zigbee module, the AC-DC power supply system must have a ripple voltage of less than 100 mV and can generate 50 mA current on average. When the dynamic output current is 100 mA, the output voltage drop does not exceed 2.8 V.
* In low standby power application scenarios, select the low standby power AC-DC drive chip and a module with low standby current.
* Use a diode and capacitor to isolate the AC-DC power supply circuit from the main power (highlighted with the red rectangle in the following figure) to prevent the working module from affecting the main power, especially the linear constant-current drive power source, so that light jitter will not occur.
#### DC-DC Constant-Voltage Power Supply
* When a module embedded with a DC-DC voltage reduction circuit is powered by DC voltage, the DC voltage cannot exceed 40 V.
* When the DC voltage exceeds 3.3 V, use a voltage reduction chip to reduce the voltage to 3.3 V. A switch-type voltage reduction control chip is recommended, as shown in the following figure. To power a 3.3 V Wi-Fi module, the DC-DC power supply system must have a ripple voltage of less than 100 mV and can generate 200 mA current. When the dynamic output current is 450 mA, the output voltage drop does not exceed 2.8 V. The 3.3 V Wi-Fi module's power supply pin is connected to a 0.1 μF ceramic capacitor to reduce interference. To power a 3.3 V Bluetooth or Zigbee module, the DC-DC power supply system must have a ripple voltage of less than 100 mV and can generate 50 mA current on average. When the dynamic output current is 100 mA, the output voltage drop does not exceed 2.8 V.
\* Low dropout (LDO) regulators are not recommended for powering Wi-Fi modules. If an LDO regulator is used, use a chip with 500 mA or higher power supply current and ensure good heat dissipation. When the input voltage is higher than 5 V, a switch-type power chip is recommended.
### Step 3: Install the Module and Antenna
Similar to light, wireless signals may be blocked by metal in the transmission path. If an antenna is mounted on a metal surface, the module cannot work properly.
To use a module in a sphere lamp, ensure that the module's antenna is out of the opening groove of the alumina substrate and that the onboard antenna is higher than the alumina substrate. When the light source is not affected and there are no shadows, position the antenna out of the lamp cup's shielding environment as much as possible.
When using a module in a lamp with a metal cover, for example, a downlight or spotlight lamp or lamp used outdoors, consider the antenna RF design and use an external antenna if needed. To use a module in a drive, keep the module away from components such as the transformer and inductor.
### Step 4: Select an LED Light Driving Method
#### AC-DC Constant-Current Driver for Monochromatic Lamps (W)
* Switch-type AC-DC constant-current driver, as shown in the following figure
Advantages: high efficiency, high power factor (PF), good constant-current characteristics, high linearity, and adjustable, wide output voltage range
Disadvantages: strong electromagnetic interference (EMI), high cost, noise during PWM light adjustment, and complex PCB layout
The module generates PWM signals.
\* Linear AC-DC constant-current driver
Advantages: low cost, no EMI issue, simple PCB layout, and no noise during PWM light adjustment
Disadvantages: low efficiency, narrow voltage range, poor constant-current characteristics, poor linearity, fixed output voltage, and low PF
The module generates PWM signals.
#### AC-DC Constant-Current Driver for Bi-Color Lamps (CW)
The solution has the CW and CCT control modes. The CW mode uses 2-channel PWM signals for simultaneous control of the brightness and color temperature. The 2-channel PWM signals are CW and WW signals, which respectively control the white light with a high color temperature and warm light with a low color temperature. During 1-channel light adjustment, CW signals are used. The CCT mode uses 2-channel PWM signals for separate control of the brightness and color temperature. The Bright signals control the brightness, and the CCT signals control the color temperature. For details, see the pin configuration.
* Switch-type AC/DC constant-current driver in CW mode
Advantages: high efficiency, good constant-current characteristics, high linearity, and good light adjustment
Disadvantages: strong EMI, circuit noise, large color temperature offset when the duty cycle is small, complex circuit layout, and high cost
The module generates 2-channel PWM signals: CW and WW.
\* Linear AC-DC constant-current driver in CW mode
Advantages: low cost, no EMI issue, simple PCB layout, and no noise during PWM light adjustment
Disadvantages: low efficiency, narrow voltage range, poor constant-current characteristics, poor linearity, fixed output voltage, and large color temperature offset when the duty cycle is small
The module generates 2-channel PWM signals: CW and WW.
* AC-DC constant-current driver in CCT mode
Advantages: high efficiency, good constant-current characteristics, high linearity, basically no color temperature offset, good light adjustment, simulated brightness control, low cost, simple circuit layout, and no noise
Disadvantages: strong EMI and higher cost than the linear AC-DC constant-current driver in CW mode
The module generates 2-channel PWM signals: Bright and CCT.
#### Constant-Current Driver for RGB Lamps
* DC-DC PWM-controlled linear constant-current driver
The module generates 3-channel PWM signals: PWMR, PWMG, and PWMB. The linear constant-current driver ensures constant RGB current output.
* DC-DC I2C-controlled linear constant-current driver
The I2C DAT and CLK signals can control RGB or RGBCW lamps, requiring only several control pins. The module generates I2C DAT and CLK signals to the drive chip to ensure constant RGB current. To use the I2C solution, pay attention to the PCB layout. I2C signals are vulnerable to interference from switch signals (AC-DC drive circuit). If the interference is serious, add a 10 pF to 50 pF filter capacitor to the DAT and CLK signal circuits during PCB layout design to reduce interference.
Note: Pull-up resistors need to be added to the physical circuits of the peripheral I2C DAT and CLK signals. Typically, the resistance value is 4.7 kiloohms, which can be adjusted based on the actual scenario.
* DC-DC PWM-controlled BJT/MOSFET switch driver
Use the BJT or MOSFET switch to control RGB through PWM signals. The RGB current is variable and discrete. Add a resistor for the red light control channel to limit the current because the red light diode has a low voltage. In this case, under the same input conditions as the constant-current solution, the loss is increased. Note: The bead voltage cannot be greatly different from the input voltage.
#### AC-DC I2C-controlled Linear Constant-Current Driver for RGBCW Lamps
Advantages: simple solution, simple peripheral parameters, low cost, and requires only the DAT and CLK signals for control
Disadvantages: driven by linear constant current, and DAT and CLK signals are vulnerable to interference
Note: The RGB light needs to be powered separately. An AC-DC + DC-DC power supply solution is recommended.
### Step 5: Define Module Pins
In network configuration mode, the CW pin generates a high or low level to indicate the network configuration status. The CW pin is used for 1-channel light control. For cold and warm light control in CW mode, the CW and WW pins control the cold and warm light, respectively. In CCT control mode, the Bright and CCT pins respectively control the brightness and color temperature.
The following tables define the module pins.
#### WIFI：
**Espressif Systems:**
**TYWE3S TYWE3L TYWE5P**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO5 | W | CW | Bright | | |
| IO13 | WW | CCT | | | |
| IO4 | | | R | SCL | |
| IO12 | | | G | | |
| IO14 | | | B | SDA | |
| IO16 | | | | Low-power | |
**TYWE3SE**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO22 | W | CW | Bright | | |
| IO13 | WW | CCT | | | |
| IO5 | | | R | SCL | |
| IO25 | | | G | | |
| IO14 | | | B | SDA | |
| IO33 | | | | Low-power | |
**TYWE1S TYLC4**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO5 | W | CW | Bright | | |
| IO13 | WW | CCT | | | |
| IO4 | | | R | SCL | |
| IO12 | | | G | Low-power | |
| IO14 | | | B | SDA | |
**TYWE2S TYWE2L**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO14 | W | CW | Bright | | |
| IO12 | WW | CCT | | | |
| IO5 | | | R | SCL | |
| IO4 | | | G | Low-power | |
| IO13 | | | B | SDA | |
**TYLC5**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO14 | W | CW | Bright | R | SCL |
| IO12 | WW | CCT | B | SDA | |
| IO4 | | | G | Low-power | |
**TYLC6 TYLC8**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO14 | W | CW | Bright | R | SCL |
| IO12 | WW | CCT | B | SDA | |
| IO13 | | | G | Low-power | |
**TYLC6E**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO4 | W | CW | Bright | | |
| IO5 | WW | CCT | R | | |
| IO12 | | | G | SDA | |
| IO14 | | | B | SCL | |
| IO13 | | | | Low-power | |
**TYLC2V**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| IO5 | W | CW | Bright | | |
| IO12 | WW | CCT | R | | |
| IO14 | | | G | SDA | |
| IO4 | | | B | SCL | |
| IO13 | | | | Low-power | |
**Realtek module pins:**
**WR1 (Pin-compatible with TYWE1S)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_5 | W | CW | Bright | | |
| GPIOA\_18 | WW | CCT | | | |
| GPIOA\_22 | | | R | SCL | |
| GPIOA\_15 | | | G | Low-power | |
| GPIOA\_14 | | | B | SDA | |
**WR3 and WR3L (Pin-compatible with TYWE3S and TYWE3L)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_12 | W | CW | Bright | | |
| GPIOA\_0 | WW | CCT | | | |
| GPIOA\_5 | | | R | SCL | |
| GPIOA\_15 | | | G | | |
| GPIOA\_14 | | | B | SDA | |
| GPIOA\_19 | | | | Low-power | |
**WR3E and WR3LE (Pin-compatible with TYWE3S and TYWE3L)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_12 | W | CW | Bright | | |
| GPIOA\_22 | WW | CCT | | | |
| GPIOA\_5 | | | R | SCL | |
| GPIOA\_15 | | | G | | |
| GPIOA\_14 | | | B | SDA | |
| GPIOA\_29 | | | | Low-power | |
**WR5P (Pin-compatible with TYWE5P)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_12 | W | CW | Bright | | |
| GPIOA\_5 | WW | CCT | | | |
| GPIOA\_14 | | | R | SCL | |
| GPIOA\_15 | | | G | | |
| GPIOA\_0 | | | B | SDA | |
| GPIOA\_22 | | | | Low-power | |
**RLC2V and RLC7V (Pin-compatible with TYLC2V)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_5 | W | CW | Bright | | |
| GPIOA\_12 | WW | CCT | R | | |
| GPIOA\_14 | | | G | SDA | |
| GPIOA\_15 | | | B | SCL | |
| GPIOA\_0 | | | | Low-power | |
**RLC4 (Pin-compatible with TYLC4)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_5 | W | CW | Bright | | |
| GPIOA\_12 | WW | CCT | | | |
| GPIOA\_19 | | | R | SCL | |
| GPIOA\_15 | | | G | Low-power | |
| GPIOA\_14 | | | B | SDA | |
**WR2L (Pin-compatible with TYWE2L)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_15 | W | CW | Bright | | |
| GPIOA\_14 | WW | CCT | | | |
| GPIOA\_19 | | | R | SCL | |
| GPIOA\_12 | | | G | Low-power | |
| GPIOA\_5 | | | B | SDA | |
**WR2E (Pin-compatible with TYWE2S)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_15 | W | CW | Bright | | |
| GPIOA\_24 | WW | CCT | | | |
| GPIOA\_12 | | | R | SCL | |
| GPIOA\_19 | | | G | Low-power | |
| GPIOA\_5 | | | B | SDA | |
**WR2 (Pin-compatible with TYWE2S)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_15 | W | CW | Bright | | |
| GPIOA\_14 | WW | CCT | | | |
| GPIOA\_12 | | | R | SCL | |
| GPIOA\_0 | | | G | Low-power | |
| GPIOA\_5 | | | B | SDA | |
#### Tuya Bluetooth mesh module pins:
**TYBY3**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_15 | W | CW | Bright | | |
| GPIOA\_14 | WW | CCT | | | |
| GPIOA\_12 | | | R | SCL | |
| GPIOA\_0 | | | G | Low-power | |
| GPIOA\_5 | | | B | SDA | |
**TYBT4L (Pin-compatible with TYWE3S)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIOA\_15 | W | CW | Bright | | |
| GPIOA\_14 | WW | CCT | | | |
| GPIOA\_12 | | | R | SCL | |
| GPIOA\_0 | | | G | | |
| GPIOA\_5 | | | B | SDA | |
| GPIOA\_5 | | | | Low-power | |
**TYBT8 (Pin-compatible with TYLC5)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| PWM1 | W | CW | Bright | R | SCL |
| PWM0 | WW | CCT | B | SDA | |
| PWM4 | | | G | Low-power | |
#### SIG Bluetooth mesh module pins:
**BT3L (Pin-compatible with TYWE3S)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| TL\_B5 | W | CW | Bright | | |
| TL\_C2 | WW | CCT | | | |
| TL\_B4 | | | R | SCL | |
| TL\_C3 | | | G | | |
| TL\_D2 | | | B | SDA | |
| TL-D7 | | | | Low-power | |
**BT8C (Pin-compatible with TYLC5 and TYBT8)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| PWM1 | W | CW | Bright | R | SCL |
| PWM0 | WW | CCT | B | SDA | |
| PWM4 | | | G | Low-power | |
#### Zigbee module pins
**TYZS3 and TYZS1L (Pin-compatible with TYWE3S)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| GPIO3 | W | CW | Bright | | |
| PWM1 | WW | CCT | | | |
| PWM2 | | | R | SCL | |
| PWM3 | | | G | | |
| SWO | | | B | SDA | |
| GPIO0 | | | | Low-power | |
**TYZS15 (Pin-compatible with TYLC5, TYBT8, and BT8C)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| PWM3 | W | CW | Bright | R | SCL |
| PWM1 | WW | CCT | B | SDA | |
| PWM2 | | | G | Low-power | |
**TYZS9V (Pin-compatible with TYLC2V)**
| I/O Interface | W | CW | CCT | RGB(PWM) | RGB (I2C) |
| ------------- | -- | --- | ------ | --------- | --------- |
| PWM2 | W | CW | Bright | | |
| GPIO2 | WW | CCT | R | | |
| PWM3 | | | G | SDA | |
| PWM1 | | | B | SCL | |
| GPIO0 | | | | Low-power | |
**The following figures show pins on some modules:**
When the Espressif Systems 8266 chip is being powered on, some I/O interfaces are unstable and have weak output with a high pulse for 180 ms during initialization. As a result, the high level-driven light blinks. To prevent this scenario, connect pull-down resistors whose resistance is less than or equal to 3.3 kiloohms to these I/O interfaces. A lower resistance may be required according to the peripheral circuit. For details, see the following initial pin status table.
**Initial pin status:**
| Pin | Initial Status | Recommended Configuration |
| ---- | --------------- | ----------------------------------- |
| IO2 | Pulled up | Add an external pull-down resistor. |
| IO4 | High resistance | Add an external pull-down resistor. |
| IO5 | High resistance | Add an external pull-down resistor. |
| IO12 | Pulled up | Add an external pull-down resistor. |
| IO13 | Pulled up | Add an external pull-down resistor. |
| IO14 | Pulled up | Add an external pull-down resistor. |
| IO15 | Low-level | |
| IO16 | High-level | |
---
[Next Page](/llms-full.txt/1)
.png?alt=media&token=70dfc8c2-b384-442d-b54e-3c5ed03a57ed)
General Knowledge
* [About IoT](https://docs.ifreeq.com/general-knowledge/about-iot)
* [Electricity](https://docs.ifreeq.com/general-knowledge/electricity)
* [Certification](https://docs.ifreeq.com/general-knowledge/certifications)
* [Industry Term](https://docs.ifreeq.com/general-knowledge/industry-terms)
* [Network Term](https://docs.ifreeq.com/general-knowledge/network-terms)
* [The Third-party Control](https://docs.ifreeq.com/general-knowledge/the-third-party-control)
## .png?alt=media&token=d4d160e2-16e3-43a9-822c-42104ece7513)
Developer documentation
* [Introduction
](https://docs.ifreeq.com/developer/introduction)
* [Quick Start
](https://docs.ifreeq.com/developer/quick-start)
* [Configure in Platform
](https://docs.ifreeq.com/developer/configure-in-platform)
* [Device Development
](https://docs.ifreeq.com/developer/device-development)
* [Smart Product Solution](https://docs.ifreeq.com/developer/smart-product-solution)
## 
FAQs
* [Device Development
](https://docs.ifreeq.com/faqs/device-development)
* [Smart Product Solution](https://docs.ifreeq.com/faqs/smart-product-solution)
* [Products](https://docs.ifreeq.com/faqs/products)
* [More FAQs](https://docs.ifreeq.com/faqs/more-faqs)
## 
Links to:
* [www.ifreeq.com](https://www.ifreeq.com)
* [store.ifreeq.com](https://store.ifreeq.com/)
* [www.ifreeq.com.cn](https://www.ifreeq.com.cn/)
* [expo.ifreeq.com](https://expo.ifreeq.com/)
# Update Log
Be sure to not miss out anything about our update
## 2020/08/21
* Add Home Automation Brand
* Add Home Automation Catalog
## 2020/07/15
Fixed some issues, modified the '[Introduction](https://docs.ifreeq.com/)' page, and added the "[Update Log](https://docs.ifreeq.com/update-log)" page.
## 2020/07/12
We update the FAQs documents, including FAQs about:
* Device Development
* Smart Product Solution
* Products
## 2020/07/10
We update the developer center's documents, including:
* Configure in Platform
* Device Development
* Smart Product Solution
* Quick Start
## 2020/07/07
We build our documentation center. And update the general knowledge parts.
# About IoT
## Introduction
### Definition
Internet of Things (IoT) uses sensors, chips, and wireless modules to interconnect all things for information exchange and communications. It is an extension of the Internet that uses computers and mobile terminals to interconnect people.
### Elements
* Devices with network connection capabilities
* Cloud services (data monitoring, storage, and analysis services and data security services)
* Control terminals: apps, cloud, and smart speakers such as Google Home and Amazon Echo
### Phases
* Sensing and control
* Scene association
* Robot/artificial intelligence (AI)
### DCM Architecture
## Industry Overview
### Rapid Increase in Device Connections
In 2018, the number of IoT connections in China increased rapidly. A report from Counterpoint, a well-known market research company, showed that the number of IoT connections of three major Chinese telecom operators took up more than 60% of global cellular IoT connections in 2018, and this share is expected to be retained by 2025.
IDC estimated that IoT will create a value of US$1.46 trillion by 2020 and generate a large number of opportunities in various market segments.
### Promising and Challenging 5G Era
5G has become the hottest topic in the technical world. In 2019, Ministry of Industry and Information Technology (MIIT) issued temporary 5G licenses. This started the 5G era.
Before commercial application, 5G is in a wild speculation period just like other new technologies. Typical operators, however, are still very careful about making 5G infrastructure investments.
According to 3GPP's work progress, established 5G standards focused on Enhanced Mobile Broadband (eMBB). This is also the focus of commercial applications in 2019 and 2020. However, eMBB mainly applies to the mobile Internet and has limited supports for IoT applications. Ultra-Reliable Low-Latency Communication (URLLC) and Massive Machine Type Communication (mMTC) are core technologies for applying 5G to IoT. However, these two technologies are not standardized yet and require time for commercial application. Therefore, it takes time for boosting the IoT development with 5G.
### Cloud, Edge, and Device Collaboration, and Further AI+IoT Integration
The edge layer is added to the original four-layer architecture because edge computing has become more and more important in IoT businesses. Edge computing, cloud computing, and device computing form a collaborative system that offers reliable, cost-effective IoT application solutions based on user scenes, resource constraints, and business timeliness. Cloud computing vendors, IT vendors, operators, and virtual industry vendors have reached a consensus on using IoT solutions for cloud, edge, and device collaboration even though they have different opinions about edge computing, edge node positions, and edge computing capabilities.
We believed that the combination of AI and IoT would make a big difference according to the Overall Industrial Report of the Chinese IoT Industry in 2017 and 2018. In 2019, AI giants were exploring how to use AI to empower industries of various national economic sectors, and the integration with IoT is crucially important. AI has integrated with multiple IoT layers, including the device, edge, and cloud layers.
Many technical companies, such as Hikvision, Megvii, and Horizon Robotics have released IoT-related platforms and products. The combination of AI and IoT will implement more products and services and bring more IoT technical solutions into reality.
# Electricity
* [History of domestic electricity](https://docs.ifreeq.com/general-knowledge/electricity/history-of-domestic-electricity)
* [Plug & socket types](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world)
* [Plug, socket & voltage by country](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country)
* [World map showing the spread of plug types](https://docs.ifreeq.com/general-knowledge/electricity/world-map-showing-the-spread-of-plug-types)
* [Useful information for travellers](https://docs.ifreeq.com/general-knowledge/electricity/useful-information-for-travellers)
* [Three-phase electric power (industrial applications only)](https://docs.ifreeq.com/general-knowledge/electricity/three-phase-electric-power-industrial-applications-only)
# Plug & socket types around the world
There are currently 15 types of electrical outlet plugs in use today, each of which has been assigned a letter by the US Department of Commerce International Trade Administration (ITA), starting with A and moving through the alphabet. These letters are completely arbitrary: they don’t actually mandate anything.
Click [here](https://docs.ifreeq.com/general-knowledge/electricity/world-map-showing-the-spread-of-plug-types) for a global map showing the spread of the different plug types used around the world.
Click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country) for a detailed list of the countries of the world with their respective plug and outlet types, voltage and frequency.
## Type A
* mainly used in the USA, Canada, Mexico & Japan (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 2 pins
* not grounded
* 15 A
* almost always 100 – 127 V
* socket compatible with plug type A
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-types-a-and-b)
## Type B
* mainly used in the USA, Canada, Mexico & Japan (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 15 A
* almost always 100 – 127 V
* socket compatible with plug types A & B
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-types-a-and-b)
## Type C
* commonly used in Europe, South America & Asia (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 2 pins
* not grounded
* 2.5 A, 10 A & 16 A
* almost always 220 – 240 V
* socket compatible with plug type C
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-c)
## Type D
* mainly used in India (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 5 A
* 220 – 240 V
* socket compatible with plug type D (partial and unsafe compatibility with C, E & F)
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-d)
## Type E
* primarily used in France, Belgium, Poland, Slovakia & Czechia (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 2 pins
* grounded
* 16 A
* 220 – 240 V
* socket compatible with plug types C, E & F
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-e)
## Type F
* used almost everywhere in Europe & Russia, except for the UK & Ireland (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 2 pins
* grounded
* 16 A
* 220 – 240 V
* socket compatible with plug types C, E & F
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-f)
## Type G
* mainly used in the United Kingdom, Ireland, Malta, Malaysia & Singapore (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 13 A
* 220 – 240 V
* socket compatible with plug type G
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-g)
## Type H
* used exclusively in Israel, the West Bank & the Gaza Strip (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 16 A
* 220 – 240 V
* socket compatible with plug types C & H (partial and unsafe compatibility with E & F)
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-h)
## Type I
* mainly used in Australia, New Zealand, China & Argentina (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 2 or 3 pins
* 2 pins: not grounded / 3 pins: grounded
* 10 A
* 220 – 240 V
* socket compatible with plug type I
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-i)
## Type J
* used almost exclusively in Switzerland & Liechtenstein (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 10 A
* 220 – 240 V
* socket compatible with plug types C & J
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-j)
## Type K
* used almost exclusively in Denmark & Greenland (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 16 A
* 220 – 240 V
* socket compatible with plug types C & K (partial and unsafe compatibility with E & F)
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-k)
## Type L
* used almost exclusively in Italy & Chile (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 10 A & 16 A
* 220 – 240 V
* 10 A socket compatible with plug types C & L (10 A version)
* 16 A socket compatible with plug type L (16 A version)
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-l)
## Type M
* mainly used in South Africa (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 15 A
* 220 – 240 V
* socket compatible with plug type M
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-m)
## Type N
* used in Brazil and South Africa (for a full list, click [here](https://docs.ifreeq.com/general-knowledge/electricity/plug-socket-and-voltage-by-country))
* 3 pins
* grounded
* 10 A, 16 A & 20 A
* 100 – 240 V
* socket compatible with plug types C & N
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-n)
## Type O
* used exclusively in Thailand
* 3 pins
* grounded
* 16 A
* 220 – 240 V
* socket compatible with plug types C & O (partial and unsafe compatibility with E & F)
[Learn more](https://docs.ifreeq.com/general-knowledge/electricity/plug-and-socket-types-around-the-world/power-plug-and-outlet-type-o)\ 
Algorithms
Baidu's algorithms are built on top of ultra-large-scale neural networks, trillions of parameters, and hundreds of billions samples.
* 
Computing
Baidu's computing power stems from hundreds of thousands of servers and the largest high performance GPU cluster in China.
* 
Data
Baidu has access to more than a trillion webpages, billions of search queries, and tens of billions of image and video content, and positioning data.
* 
Speech Recognition
Baidu's speech recognition technology has an accuracy rate of more than 97%.
* 
Image Recognition
Baidu's facial recognition system has an accuracy rate of more than 99.7%.
* 
Natural Language Processing
Baidu's AI has the ability to communicate with users via natural language and can understand users' intention with ease.
* 
User Profile
Baidu has access to nearly 100 million user profile data .
## Functionality Overview
DuerOS is integrated with Baidu's information and services ecosystem and has developed over 200 functional skillsets across 10 major categories . Users can control and command the devices with the sound of their voice to inquire information, ask for directions, create reminders, and more. DuerOS also supports third-party integration development, and Baidu currently has the largest partner ecosystem using the system. The open platform of DuerOS produces a system that allows our partners to build varying skillsets that can be applied to any given situation. DuerOS is building a new world of endless possibilities.
* 
Entertainment: Video Music, movie, television shows, variety show, short clip, audio book, and broadcasting, etc.
* 
Information: Inquiry Consultation, weather, stocks, flight, sports (NBA), FAQ, cookbook, images, etc.
* 
Lifestyle: Services Food, movie, take-out, hotel, shopping, taxi, cleaning service, travel, relaxation, and other O2O services.
* 
Travel: Conditions Map, route, road condition, traffic restriction, endorsement, and surrounding environment query, etc.
* 
Utility Tools: Ranslation, time, calculation, exchange rate, and unit conversion, etc.
* 
Personal: Assistant Schedule management, alarm clock, reminder, memo and notepad, etc.
* 
Learning: Encyclopedia, story, nursery rhyme, idiom, parenting, poetry and library, etc.
* 
Chat and Relax: Chat, joke, poetry, idioms, and games, etc.
* 
Smart Home: Command control, status inquiry, service manual, and customer service phone number, etc.
* 
Command Control: Phone calls, text messages, alarm clock, address book inquiry,, and other functions.
# FAQs About DuerOS
## Can I use Xiaodu to control the channel names?
No. Currently, you can use Xiaodu only to control digital channels.
## What functions does Xiaodu support?
For details, visit