MCU Access
Tuya Gateway Development Overview
Introduction
This article is mainly an overview of the MCU development process of Tuya Gateway general solution.
Development Process
The development process mainly includes: product creation-hardware debugging-software development-functional debugging.
Create Product
Log in to the IoT Workbench 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.
The specific steps to create a product can refer to: Product Creation-IoT Platform Operation
Hardware debugging
Hardware selection
When creating a product selection module, the platform will recommend some common module models. At present, the gateway MCU access solution can only be provided by Wi-Fi gateway module-WRG1.
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 Gateway Module-WRG1 Datasheet
Module minimum schematic: Wi-Fi Gateway Module-WRG1 minimal system schematic diagram PCB data: Common module package library
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 WRG1 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
step1. According to the minimum system schematic diagram, set up the module peripheral circuit, and simple test can directly fly the wire.
step2. Set device capabilities,open the Tuya module debugging assistant in the development kit and import the debugging file. Protocol selection Wi-Fi gateway 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. The module supports two modes of network configuration: EZ and AP mode (the difference between EZ mode and AP mode). 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: Wi-Fi module network distribution demonstration video.
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 Gateway 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: Tuya Cloud Gateway Access Protocol Analysis
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, please refer to: Tuya Wi-Fi Gateway MCU_SDK Instructions
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: IoT Workbench-Operation Center. You can query related device background log data based on the device ID.
Tuya Online Support Portal: 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.
Tuya Gateway MCU Access Communication Protocol
Version Record：
Serial communication convention
Baud rate：115200
Data bit：8
Parity: None
Stop bit：1
Data flow control: none
MCU：User will control the chip through control board, connected with Tuya module through serial port
Frame format description
Basic agreement details
Query product information
Description：
product ID：Corresponding to the PID on Tuya IoT Platform, generated by Tuya IoT developer platform, used to record product related information in the cloud
The product information is comprised by product ID and MCU version
MCU version number format definition: in dotted decimal format，”x.x.x”（0<=x<=99），x is decimal.
Module send：
For example：0x55aa 00 01 0000 00
MCU return：
For example：{“v”:”1.0.0”,”m”:1,”cap”:0, “tp”:4,“p”:”mhnmpqzf7ntzmmdb”}
v means MCU version is 1.0.0
m represents pairing methods: 0 default pairing mode、1 Low power consumption mode、2 special pairing mode
cap represent device ability: bit0(local group)，bit1(local scene) ，bit2(gateway have function dp), bit3(is sigmesh), bit4(support MCU upgrade), bit5(group control command with sub_id) , bit6 (Bluetooth serial port paring mode，otherwise just AP mode is available)(the bit unused is 0）
Case 1: device support the local group control， cap is 1:
Case 2：device support local group control and local scene，cap is 3;
Case 3：device does not support local group control and local scene, but the gateway has function dp, cap is 4
Case 4：device is sigmesh device, with local group，it has to issue sub_id when control the group(issue 0x22 command), cap is 41（0x29）
tp represents the sub-devices type integrated： 1:Zigbee 2:Bluetooth 3:Smart IR 4:Others if tp is not transmitted, it will be others defaultly； Pls note：The type of sub-devices: zigbee/Bluetooth/Smart IR are applied for Tuya self-developed products, if it the products developed by the customers, the sub-devices category will be others. p represent gateway product pid，pid is mhnmpqzf7ntzmmdb
Querying MCU, set the working mode of the module
Description：
The working mode of the module is mainly for how to indicate the working status of the Wi-Fi module and how to reset the Wi-Fi module. There are two main cases：
MCU cooperates with the module, that is, the module notifies the MCU through the serial port, the current working status is supported by the MCU, the Wi-Fi will be reset through the serial port when the MCU detect the reset request.
Module self-processing: The working status of the WIFI module drives the LED status display through the WIFI GPIO pin; WIFI reset is processed by detecting the GPIO input requirements
The method of resetting the Wi-Fi module through module self-processing：WIFI will be triggered when detecting that the low level of GPIO entrance last for more than 5s. Reset: The GPIO pins used by the indicators and buttons are configured by the following commands.
Module send：
For example：0x55aa 00 02 0000 01
MCU return：
For example：0x55aa 00 02 0000 04（MCU work with the module）
0x55aa 00 02 0004 0103 0102 0C（module self-processing，indicator 0x0103：PB_3，reset button 0x0102：PB_2）
Report the device connection status
Description：
Device connection status：1 smart configuration status 2 AP configuration status 3 WIFI is configured but not connected to the router 4 WIFI is configured and connected to the router 5 Device is connected to the router and the cloud. The LED indicator under 'module self-processing' working mode is：1 Flashing at intervals of 250ms；2 Flashing at intervals of 1500ms；3 Long dark status；4 or 5 Long light status
When the module detects that the MCU restarts or the MCU is disconnected and then goes online, it will sends the WIFI status to the MCU actively.
When the WIFI status of the module changes, it will actively send the WIFI status to the MCU
If the module working mode is set to 'module self-processing', the MCU does not need to implement this protocol
Module send：
For example：0x55aa 00 03 0001 00 03
MCU return：
For example：0x55aa 00 03 0000 02
Reset WIFI
Description：
If the module working mode is set to 'module self-processing', the MCU does not need to implement this protocol
MCU send：
For example：0x55aa 00 04 0000 03
Module return：
For example：0x55aa 00 04 0000 03
Reset WIFI-select the configuration mode
Description：
Compared with 'Reset WIFI' in section 3.5, this section provides the MCU to selectively choose the configuration method after resetting the WIFI depend on different conditions.
MCU solution users can selectively implement this protocol depend on their requirements.
If the module working mode is set to 'module self-processing', the MCU does not need to implement this protocol
MCU send：
For example：0x55aa 00 05 0001 00 05，get into smart configuration mode
Module return：
Foe example：0x55aa 00 05 0000 04
Allow sub-device to access the network
Description：
The App sends a network access permission to the Gateway, and allows the sub-device to access the network within a certain period of time.
Module send：
MCU return：
Disable the permission of sub-device accessing the network
Description：
The App sends a command to close the network to the Gateway
Module send：
MCU return：
Add sub-device
Description：
MCU send the sub-device network access to Wi-Fi
pk_type is alternate field, can be ignored, the default value is 1
MCU send：
Module return：
Delete the sub-device
Description：
The App sends a command to close the network to the Gateway.
Module send：
MCU return：
Heartbeat detection
Description：
WIFI module schedule（1-3 mins）detect the online/offline status of sub-device. When adding sub-devices in batches,heartbeat detection will stop.
Module send：
MCU return：
| Field | Length（byte） | Description |
| -------- | --------------------------------- | ------------------------------------------------------------ | | Header | 2 | 0x55aa | | Version | 1 | 0x00 | | Command word | 1 | 0x0A | | Data length | 2 | N | | Data | { “sub_id”:“xxxx”, “hb_time”:xx } | sub_id：sub-device ID Heartbeat intervalhb_time（Unit: second）for example：60 means 60 seconds，0 does not support heartbeat，always online。If the heartbeat interval is less than 180s, it will be processed for 180s (except 0) | | Checksum | 1 | The result obtained by summing bytes from the beginning of the frame to the remainder of 256 |
Description：
The online device needs to responde to the heartbeat. If it does not reply for two consecutive heartbeat cycles, the device is considered offline.
Status query
Description：
Used to synchronize the status of sub-devices.
Module send：
MCU return：（3.13 status report）
Command issue
Description：
Control command issue.
datapoint: command status unit:
datapoint: the command / status data unit is as follows:
datapoint command/ except for the 'raw' type, other types of state data units belong to the 'obj' type datapoint
'command issue' contains several datapoint 'command data unit'
'command issue' is asynchronous processing protocol，corresponding to MCU datapoint 'status report'
Module send：
Status report
Description：
The sub-device actively pushes the instruction after the command is issued and replied or the status changes.
MCU send：
| Field | Length（byte） | Description |
| -------- | ---------------------------------------- | ------------------------------------------------------------ | | Header | 2 | 0x55aa | | Version | 1 | 0x00 | | Command word | 1 | 0x0D | | Data length | 2 | N | | Data | id_len(1byte) + sub_id(nbyte)+ datapoint | id_len: sub-device id length sub_id: sub-device id. when the sub_id is '0000',this command is to the gateway itself's dp (main device) . datapoint: Control command data point collection | | Checksum | 1 | The result obtained by summing bytes from the beginning of the frame to the remainder of 256 |
Group sub-device join in
Description：Local group sub-devices are added, support local group-created devices. Module send：
MCU return：
Group sub-device deletion
Description：The local group sub-device is deleted.
Module send：
MCU return：
Get system time (Green Time)
MCU send：
For example：0x55aa 00 10 0000 0F
Module return：
For example：0x55aa 00 10 0007 01 10 04 13 05 06 07 50（April 19, 2016 5: 6: 7 GMT）
Obtain system time
MCU send：
Module return：
For example：
(1)If the device is activated in China, the local time is Beijing time (East 8 District)
0x55aa 00 11 0008 01 10 04 13 05 06 07 02 54（Beijing time April 19, 2016 5: 6: 7）
(2)If the device is activated abroad, the local time is the time zone of the device
Add devices in bulk
Description：Add multiple sub-devices of the same pid in batch. Note：The maximum number of sub-devices added in a batch is 32. MCU send：
Module return：
Back to add device result
Description：inform the MCU result when adding the devices successfully
Module send：
MCU return：
Control group command issu
Module send：
MCU return：
WIFI functionality test
Description：scan the specific SSID: tuya_mdev_test, return the scanning result and signal percentage
MCU send：
Module return：
Obtain the WIFI status
Description：The MCU can obtain the WIFI status according to this command. See 3.3 for specific WIFI status. The gateway will not restore the wifi state before the network initialization is completed.
MCU send：
Module return：
Restore to the factory setting（optional）
Description：The local factory restoration will cause the cloud information and local information to be out of sync, and it must be used while the device is online or before the device is activated for the first time.
MCU send：
Report the removing status
Description：1）When the gateway receive the command of remove or restore the factory setting, it will report to the MCU.
2）If only receive the removing instruction, the gateway will only remove the distribution network and will not delete the sub-device information. The sub-device information will still be displayed on the App the next time the device is online.
3）If receiving the factory restoring instruction, the gateway will remove the network distribution and delete all sub-devices information.
Module send：
3.25 delete the sub-devices locally
Description：
MCU send the command to delete the sub-devices
MCU send：
Module return：
Allow to stop adding sub-devices locally
MCU send：
Module return：
Obtain the module memory
Description：obtain the remaining memory of Wi-Fi module
MCU send：
Module return：
Query the sub-device list
Description： 1）MCU can query all sub-devices list under the gateway.
2）when the list data is larger than 255 bytes, it will be sent separately MCU send：
Module return：
OTA service
Description：
When to upgrade the firmware will depend on the configurations customers set on IoT platform, module will only serves as a data transmission channel that supports MCU upgrades, and does not do any analysis of the data content.
Currently, the MCU OTA supports 4 methods on IoT Platform as follows.
App reminder upgrade：the end user will receive the pop-up message of upgrade every time they enter the device panel, the end user will decide update or not.
App silent upgrade：there is no pop-up reminder of this method, The firmware will automatically detect the upgrade within one minute after it is powered on. If the upgrade package is found and with a higher version, it will automatically start to pull the relevant upgrade package. After the first power-on, the module will go to the cloud to detect whether there is an upgrade package configuration every 24 hours.
App forced upgrade: the end user will receive the pop-up message of this method, the panel cannot be used normally if the end user does not confirm the upgrade.
App detection upgrade: there is not pop-up message on the app side, the end user has to click 'check the firmware upgrade' to detect if newer version is available. The pop-up message only appears when newer version is available.
MCU OTA process：
After the Wi-Fi module has sent all the upgrade packages, re-send the 01 command word (3.2 query product information). The MCU needs to reply within one minute to the software version number in the product information with the upgraded MCU version number. The version number needs to be the same as the upgraded version number configured at the Tuya backend.
MCU start upgrade
Description：
After the Wi-Fi module has sent all the upgrade packages, re-send the 01 command word (3.1 query product information). The MCU needs to reply within one minute with the software version number in the product information with the upgraded MCU version number. The version number needs to be the same as the upgraded version number configured at Tuya backend.
Module send：
MCU return：
MCU OTA package transmission
Description：
Upgrade package transmission data format: the package offset (unsigned short) + package data
The package transmission will be end when the MCU receive the data length is 4 and the package offset is >= the size of firmware
Module send：
For example：
If the size of upgraded package is 530 Bytes，(The last package data response is optional)
(1) The first package data，the package offset is 0x00000000，the length is 256
0x55aa 00 1e 0104 00000000 xx…xx XX
(2) The second package data，the package offset is 0x00000100，the length is 256
0x55aa 00 1e 0104 00000100 xx…xx XX
(3) The third package data，the package offset is 0x00000200，the length is 18
0x55aa 00 1e 0016 00000200 xx…xx XX
(4) The last package，the package offset is 0x00000212，the length is 0
0x55aa 00 1e 0004 00000212 xx...xx XX
MCU return：
The sub-device upgrade start
Module send：
MCU return：
Sub device upgrade package transmission
Description：
Upgrade package transmission data format: package offset (unsigned short) + package data
The package transmission will be end when the MCU receive the data length is 4 and the package offset is >= the size of firmware
Module send：
For example：
If sub_id 为”1234”, the size of upgrade package is 530 Bytes，(The last package data response is optional)
(1) The first package data，the package offset is 0x00000000，the data length is 256
0x55aa 00 20 0109 04 31 32 33 34 00000000 xx…xx XX
(2) The second package data，the package offset is 0x00000100，the data length is 256
0x55aa 00 20 0109 04 31 32 33 34 00000100 xx…xx XX
(3) The third package data，the package offset is 0x00000200，the data length is 18
0x55aa 00 20 001B 04 31 32 33 34 00000200 xx…xx XX
(4) The third package data，the package offset is 0x00000212，the data length is 0
0x55aa 00 20 0009 04 31 32 33 34 00000212 xx...xx XX
MCU return：
Query sub-device version number
Module send：
MCU return：
the group control command issue (with sub_id)
Module send：
MCU return：
serial port distribution network （Integrated）
MCU send：
Module return：
Serial port transparent transmission distribution network (distributed)
WiFI send the broadcast
Description：The data packet is transparently transmitted by the Wi-Fi module to the MCU module for broadcasting
Module send：
MCU return：
MCU send the network pairing information
Description：The data packet is transparently transmitted by the App to the WI-Fi through the MCU
MCU send：
Module return：
WIFI report the network paring information
Description：Data package will be transmitted transparently to the app from the MCU through Wi-Fi
Module send：
MCU return：
MCU connection status
Description：The MCU will actively push the connection status with the mobile to the wifi module.
MCU send：
Wi-Fi module disconnect actively
Module send：
MCU return：
Query dp status
Module send：
MCU return：3.13 protocol（command word 0x0D）
Update the status of sub-device online/offline
MCU send：
Module return：
get module MAC address
MCU send：
Module return：
Recorded status report in real time (with time）
Description： 1）For record-type sub-devices such as door locks, the dp status is also reported with the time stamp when these records were generated 2）This reporting interface is a synchronous reporting interface. After the mcu report data, you can check the result returned from the module to determine the success of the report.
Module send：
MCU return：
FAQs
Version Record
Q：How many sub-devices can be connected under one gateway？
A：1：Up to 128 sub-devices； 2：The number of sub-devices added at one time cannot exceed 32
Q：Does it support 433, Bluetooth and 485 sub-devices?
A：Gateway general MCU integration:MCU is developed by customers according to the Wi-Fi module Tuya provides. As long as the MCU sends data according to the serial port protocol, it can access the Tuya platform. Therefore, the general connection of the gateway is not related to the communication type of the sub-device.
Q：What is the number of local linkages？
A：This is related to the number of conditions and actions created by the user. One condition is about 250 bytes, and one action is about 200 bytes. If you create 1 condition and 5 actions, it is not recommended to exceed 10.
Q：How to set sub-device heartbeat interval by the MCU？
A：The MCU sets the next heartbeat interval in the heartbeat reply frame. The default heartbeat interval time is 1min, and the minimum settable heartbeat interval is 180s
Q：When will the module query the sub-device heartbeat？
A：The module will query the sub-device heartbeat before the heartbeat cycle arrives, and the heartbeat of the sub-device will be delivered in advance (8S + random seconds). This is to avoid the condition that the MCU has no time to deal with the heartbeat when multiple sub-devices sending the heartbeat at the same time.
Q：How does the module determine the online or offline status of the sub-device？
A：The module will send a heartbeat query package to the MCU in ahead of time before the heartbeat cycle arrives. If the MCU does not reply within 8s, the heartbeat query package will be retransmitted again. If the MCU has not responded in 3 times. The module will report to the cloud that device is offline. After that, the module will stop sending a heartbeat frame until the MCU sends a status frame of the sub-device to the WiFi module. The module will notify the cloud to be online and restart the sub-device heartbeat.
Q：When will the module refresh the heartbeat and re-start？
A：During the heartbeat interval, the module will refresh the heartbeat and re-start when it receives the status data of the sub-device.
Q：What is the maximum frame and frequency that the module serial port can receive?
A：It is recommend that each frame of the data does not exceed 256 bytes, if the amount of data needed to synchronise the status of the sub-device after networking is quite a few, it can be sent in packets. The frame interval is recommended to be 100ms.
Q：'pid', 'sub_id', 'gid‘，any length limitation of these fields？
A：'pid' can be filled in created on IoT platform. The length of 'sub_id' cannot exceed 25 bytes. 'gid' is decided when the module issue，the range is from 0 to 65535，the length cannot exceed 5 bytes.
Q：Any limitation of MCU or sub-device version number?
A：yes，the firmware version number format is xx.xx.xx x is from 0 to 9
Q：Will the sub-device information still exist when the gateway is removed?
A：The information of sub-devices will be kept if only removing the gateway. However, the sub-device information will not be available when the gateway is restored to the factory setting. Besides, the information also be invalid when the device is re-paired under another app account.
Q：After the serial port command is issued, how long does it take for the MCU not to reply with an ACK?
A: The default timeout time for general commands is 500ms. Heartbeat detection is 8s.
Q：What if the App issues a control command but the sub-device is not detected offline in time?
A：The commando will be resent, resent 2 times in 1s interval -> resent 3 times at 10s intervals -> stop resending
Q：How to control WiFi module hardware reset?
A：Pull low the pin 8-EN
Q：How to obtain the Wi-Fi running log？
A：When you encounter problems during debugging and need to obtain the module operation log for Tuya analysis, as shown above, the flying line leads the Log_Tx andGND pins, connect the USB to serial port tool, the serial port configuration 38400,8, N, 1, Use the PC serial assistant to grab the log to save the text, and give it to the graffiti engineer for analysis.
If the above methods cannot solve my issues?
Pls log in Tuya IoT Platform，Tuya online support team， Tuya will have professional engineers to answer your questions online. In order to quickly understand and solve your problem, it is recommended that you describe your problem in the following format:
-Problem background: For example,I am the engineer of XYZ company, doing XX solution for now. -Problem description: Describe as far as possible the conditions under which your problem occurs. What is the problem phenomenon? Can it be re-appeared? -Problem attachments: Please upload attachments for screenshots or logs of faulty scenes if you have.
Last updated