Use MCU SDK

Operation Instructions to MCU SDK

1.Introduction

This is a MCU procedure generated automatically from the product’s function datapoint according to Tuya Serial Port Communication Protocol. MCU engineer can develop this procedure quickly on this basis.

2.How to Obtain

Open the background website of the Developer

https://iot.tuya.com/

If the product has been established, click “Debugging process” and download MCU SDK

If you do not have the account of your company, please contact relevant officer of your company

3.ile Structure

The file includes:

Execution file Header file Description
mcu_api.c mcu_api.h The client can invoke WIFI-related functions contained
protocol.c protocol, h According to project requirements, the client needs to alter two files containing the data processing functions
system.c system, h There is no need to know the detailed realization of serial port communication protocol.
wifi.h

4.Configuration

4.1 Alter Product Information (Necessary)

Open the protocol.h and find “Product Key” in the background of the Developer. Please make sure that the code is the same as that listed on the website. This PID is the unique identifier of each product. You must check whether it is your product ID. If not, modify it or re-download the latest SDK development packet and perform code transplant.

#define PRODUCT_KEY "ZKtkyqNRJH7h3eL1"

4.2 Whether MCU Needs to Support the Firmware Update (Optional)

If it needs to support MCU firmware update, please enable this macro

#define         SUPPORT_MCU_FIRM_UPDATE

WARNING!!! ​ In current receive buffer, the firmware update function is disabled. The firmware update packet is of 256 bytes.

​If this function needs to be enabled, the receive buffer of serial port will become larger.

4.3 Define the Send-receive Buffer (Optional)

Open the protocol.h and alter the buffer size when the transmission data is too long (in general, the default value is used)

#ifndef SUPPORT_MCU_FIRM_UPDATE
#define WIFI_UART_QUEUE_LMT             16              //The size of the data receive queue can be decreased if the MCU does not have enough RAM
#define WIFI_UART_RECV_BUF_LMT          24              //Based on the User’s data size, it must exceed 24
#else
#define WIFI_UART_QUEUE_LMT             128             //The size of the data receive queue can be decreased if the MCU does not have enough RAM
#define WIFI_UART_RECV_BUF_LMT          300             //The firmware update buffer shall be large and must exceed 260
#endif

4.4 Configure WIFI Module Reset Mode (Necessary)

Open protocol.h

1.If wifi indicator and the key are on wifi module (under module self-processing mode), please enable them

#ifdef          WIFI_CONTROL_SELF_MODE

Then GPIO pin connected to the indicator and the key are placed into the two lines below according to actual hardware connections

#ifdef          WIFI_CONTROL_SELF_MODE
	#define     WF_STATE_KEY            14                //wifi module state key shall be set according to particular GPIO pin

	#define     WF_RESERT_KEY           0                 //wifi module reset key shall be set according to particular GPIO pin

#endif

2.If the indicator and the key are installed on the MCU (under the module processing with the MCU), please keep the define noted

//#ifdef          WIFI_CONTROL_SELF_MODE

4.5 Whether MCU Needs to Support Timing Function (Optional)

If MCU needs to support timing function, please enable this macro

#define         SUPPORT_MCU_RTC_CHECK                //开启校时功能

and code in mcu_write_rtctimein of the Protocol.c file

If any #err prompts within mcu_write_rtctime, please delete this #err after the function is completed

When wifi module is networked correctly, the mcu can invoke mcu_get_system_time() function to enable the timing function

5.Transplant Guidelines

  1. The MCU must invoke the function of wifi_uart_service() in mcu_api.c from while
  2. After the normal initialization of the program, it is recommended not to disable the serial port interrupt. If it must be disabled, the time must be short. If the interrupt is disabled, it may lead to the loss of serial port data packet
  3. Please do not invoke the report functions when the interrupt / timer is disabled

6.Start WIFI Service

  1. "wifi.h” files shall be included in the files with wifi-related files used.
  2. In MCU initialization, invoke the function of wifi_protocol_init() in mcu_api.c
  3. Fill the serial port single-byte send function into uart_transmit_output function in protocol.c file and delete #error
  4. Invoke the function of uart_receive_input in mcu_api.c file of the serial port receive functions and upload the received characters as parameters
  5. SCM enters a circle and then invokes wifi_uart_service() function in mcu_api.c file

Eg. Add codes into main.c as follows:

include "wifi.h"
...
void main(void)
{
	wifi_protocol_init();
	...
	while(1)
	{
		wifi_uart_service();
		...
	}
}

7.Functions

7.1 Function Point Definition

In protocol.c file ,confirm dpID and dp type in issuing st ructure of download_cmd

This is an automatically generated code. If there is any alteration at development platform, please re-download MCU_SDK

#define DPID_SWITCH                     1                       //Readable/Writabl
#define DPID_TEMPER_SET                 2                       //Readable/Writable

const DOWNLOAD_CMD_S download_cmd[] = 
{
  {DPID_SWITCH,                 DP_TYPE_BOOL},
  {DPID_TEMPER_SET,             DP_TYPE_VALUE},
};

7.2 Data Receive-Handle Function of MCU Serial Port

Fill corresponding dp handle function indp_download_switch_1_handle() (automatically generated according to dp point) of protocol.c file

static unsigned char dp_download_switch_1_handle(const unsigned char value[], unsigned short length)
{
	//Case: the type of current DP is BOOL
	unsigned char ret;
	//0:Off  /1:On

	unsigned char switch_1;

	switch_1 = mcu_get_dp_download_bool(value,length);
	if(switch_1 == 0)
	{
		//On-Off-Off
	}
	else
	{
		//On-Off-On
	}

	//There shall be feedbacks after DP data processing

	ret = mcu_dp_bool_update(DPID_SWITCH_1,switch_1);
	if(ret == SUCCESS)

		return SUCCESS;
	else
		return ERROR;
	}

After the function points are analyzed by above functions, they are mapped to relevant execution functions to complete detail actions. In this case, after receiving the switch data and perform switch actions, it will invoke mcu_dp_bool_update(DPID_SWITCH_1,switch_1); When function point (switch) state is uploaded, this receive-handle function has automatically invoked this function; When the device state changes under non-APP controlled mode, the MCU needs to invoke mcu_dp_bool_update(DPID_SWITCH_1,switch_1); Finally, it is required to upload the real-time state of function point (See details in single data reporting of 7.4)

7.3 Data Receive Debugging

  1. Use Tuya serial port debugging helper to complete “7.2 Configuration Verification”, then click **“Add Command”**to send several commands at the same time
  2. Click Command Issuing
  3. The functions added on the previous page will receive the data issued now

7.4 Single Data Reporting

  1. When mcu state changes, the User needs to report actively
  2. If the countdown exists, you need to report the remaining time every minute
  3. The reporting format is mcu_dp_xxxx_updata(DPID_X,n). DPID_X is consistent with `7.1 Function Point Definition '.

For example:

  mcu_dp_bool_update(DPID_SWITCH,1);                   //BOOL type data reporting
  mcu_dp_value_update(DPID_TEMPER_SET,25);             //VALUE type data reporting
  mcu_dp_string_update(DPID_DAY,"1234",4);             //STRING type data reporting
  mcu_dp_raw_update(DPID_SWITCH,1);                    //RAW type data reporting
  mcu_dp_bitmap_update(DPID_TEMPER_SET,25);            //Failure data reporting
  mcu_dp_enum_update(DPID_DAY,"1234",4);               //Enumeration type data reporting

  //Example
  // Readable and writable
  mcu_dp_bool_update(DPID_SWITCH,1);                    //BOOL type data reporting
  mcu_dp_value_update(DPID_TEMPER_SET,25);              //VALUE type data reporting
  mcu_dp_string_update(DPID_DAY,"1234",4);              //VALUE type data reporting
  mcu_dp_bool_update(DPID_LOOK,0);
  mcu_dp_value_update(DPID_APPOINT,38);
  mcu_dp_string_update(DPID_WEEK,"456",3);

  //Read only
  update_temper_handle();
  update_error_handle();

7.5 All Data Reporting

  1. Open protocol.c to find all_data_update(void)
  2. List all datapoints to be reported in this function
  3. wifi_sdk will invoke this function at specified time (if at boot) to acquire current states of all functions

The User shall not invoke all_data_update(void), which will be invoked automatically at specified time

void all_data_update(void)
{
  //Please complete the reporting of all dp points
  /*
  mcu_dp_bool_update(DPID_SWITCH,1);                   //BOOL type data reporting
  mcu_dp_value_update(DPID_TEMPER_SET,25);             //VALUE type data reporting
  mcu_dp_string_update(DPID_DAY,"1234",4);             //STRING type data reporting
  mcu_dp_raw_update(DPID_SWITCH,1);                    //RAW type data reporting
  mcu_dp_bitmap_update(DPID_TEMPER_SET,25);            //Failure data reporting
  mcu_dp_enum_update(DPID_DAY,"1234",4);               //Enumeration type data reporting
  */
  //Example
  //Readable and writable
  mcu_dp_bool_update(DPID_SWITCH,/1);                  //BOOL type data reporting
  mcu_dp_value_update(DPID_TEMPER_SET,25);             //VALUE type data reporting
  mcu_dp_string_update(DPID_DAY,"1234",4);             //STRING type data reporting
  mcu_dp_bool_update(DPID_LOOK,0);
  mcu_dp_value_update(DPID_APPOINT,38);
  mcu_dp_string_update(DPID_WEEK,"456",3);

  //Read only
  update_temper_handle();
  update_error_handle();
}

7.6 Reset WIFI

When wifi module needs to be connected to a new router, the WIFI needs to be reset and the following functions shall be invoked:

mcu_reset_wifi();	

The function mcu_get_reset_wifi_flag() can be invoked to return wifi reset results

The function (as shown below) in mcu_api.c file can be invoked for wifi mode setting:

mcu_set_wifi_mode(WIFI_CONFIG_E mode);

The function mcu_get_wifi_work_state() can be invoked to return the result of wifi setting.

7.7 Reset WIFI–Obtain state

Notes:

  1. WIFI working status:

    1 smartconfig configuration status

    2 AP configuration status

    3 WIFI successfully configured but not accessed to the router

    4 WIFI successfully configured and accessed to the router Under the module self-processing mode, corresponding LED will:

     (1) flash 250ms at intervals; 
    

    ​ (2) flash 1500ms at intervals;

    ​ (3) stay in long dark state and

    ​ (4) long bright state

  2. When the module detects MCU restart or MCU offline and online again, it will automatically report WIFI state to MCU

  3. When the module detects any change of WIFI state, it will automatically report WIFI state to MCU

  4. If the module works under the module self-processing mode, MCU does not need to perform the protocol

The function mcu_get_wifi_work_state() could be called to obtain the connection status. The common application is as follow:

void main(void)
{	
	...	

	while(1)
	{
		switch(mcu_get_wifi_work_state())
		{
			case SMART_CONFIG_STATE:
			//mart 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_CONNECTING:
			//WIFI configuration is finished; the router is being connected to; LED keeps long dark
			break;
			case WIFI_CONNECTING:
			//The router is successfully connected to; LED keeps long bright
			break;
			default:break;
		}	
		...	

	}	
}

7.8 MCU Online Upgrade

1.Open protocol.h, enable the marco definition and set MCU version number

#define         SUPPORT_MCU_FIRM_UPDATE  //Enable MCU firmware update function (default disabled)
#define MCU_VER "1.0.0"                  //User’s software version is used for MCU firmware update and MCU upgrade version needs to be altered

If the data packet is too large, please adjust the buffer size according to particular demands:

WIFI_UART_RECV_BUF_LMT          300            //The firmware update buffer shall be large and must exceed 260

In corresponding update function protocol.c:

/*****************************************************************************
Function name : mcu_firm_update_handle
Function description: MCU enters the firmware update mode
Input parameters: value: firmware buffer
           position:current data packet depends on firmware position
           length:the length of current firmware packet (when the length of firmware packet is 0, the firmware packet is sent)
Return Parameters: none
Instructions: MCU needs to perform this function on its own
*****************************************************************************/
unsigned char mcu_firm_update_handle(const unsigned char value[],unsigned short position,unsigned short length)
{
  #error Please add MCU firmware update codes on your own and delete this line after the codes are added "
  if(length == 0)
  {
    //Firmware data sent
    
  }
  else
  {
    //Firmware data processing
  }
  
  return SUCCESS;
}

MCU can invoke mcu_firm_update_query() in mcu_api.c to acquire the latest state of MCU firmwar

Note: The update can be started by the phone. In debugging, use debugging helper of Tuya Serial Port to click Update Startup

7.9 cquire Online Time

1.MCU needs to acquire the network time. Open protocol.h and enable the define below

#define         SUPPORT_MCU_RTC_CHECK                //Enable timing function

2.Invoke mcu_get_system_time(void) to enable the acquisition procedure

400 Call

Consult

400-881-8611