Tuya Wi-Fi SDK Reference

Change log

Version

Description

Date

1.0.0

The initial version.

20200301

Overview

The Tuya device OS is a proprietary IoT operating system, which provides abundant components and you can make SDK customization according to your business requirements. It has the characteristic of lightweight, interconnection, secure transmission, fully functional components and rapid development, effectively lowering the development threshold and shortening the development cycle. It can be widely used in wearable devices, video monitors, compute gateways, smart speakers, smart locks and other smart home appliances.

The Tuya Wi-Fi SDK is developed based on the Tuya device OS technology and tailored according to the Wi-Fi application in the Internet of Things scenarios. It is applicable to any Wi-Fi chip that is configured according to the Tuya Smart platform interconnection rules.

Project address

GitHub repo of the Tuya Wi-Fi SDK for RTL8710BN

Directories

The following table describes the directories of the Tuya Wi-Fi SDK.

Directory

Subdirectory

Description

Reference

apps

/

Stores your application and samples of the Tuya Wi-Fi SDK. It is better to create a folder for every application or sample.

See the sample of Tuya Wi-Fi SDK for usage instruction.

oem_rtlbn_1_plug_demo

Contains one or more samples.

N/A.

sdk

sdk

Stores the header files and library files of Tuya Wi-Fi SDK.

See the API reference section for details.

include

Stores all of the APIs provided by Tuya Wi-Fi SDK.

N/A.

lib

The libtuya_iot.a file that is compiled by Tuya Wi-Fi SDK.

N/A.

platforms

/

Stores the development environment and toolchains of Tuya Wi-Fi SDK. The platform is an empty folder at first. Related toolchains are downloaded automatically to this folder during compiling.

N/A.

build_app.sh

/

The compiling entry point for applications and samples.

Environment preparation and compilation.

CHANGELOG.md

/

Records all the notable changes for each version.

N/A.

README.md

/

User guide written in Markdown.

N/A.

Initialization

Process

The initialization is the process of loading and running firmware automatically after the device is powered on for initializing.

Because the Tuya Wi-Fi SDK is platform independent, differences exist in its initialization process for different products. Taking the lighting products that have SoC designs and are connected via Wi-Fi as an example, the initialization process is shown in the following picture.

The initialization of Tuya Wi-Fi SDK is almost completed in the user_main() API. It mainly includes the following stages:

  • pre_init_process: makes preparation before initializing the Tuya IoT SDK. It is optional, therefore you can implement it depending on your needs. The pre_init_process is vastly used for lighting products, it is recommended to turn on them as soon as possible to create a better user experience. During the pre_init_process stage, the following actions will be performed.

    • pre_device_init: prints the status information and sets the importance level of logs.

    • tuya_cnt_rst_judge: counts the hardware devices.

    • tuya_iot_kv_flash_init: initializes the storage space to store the generated critical data during the pre_init_process operation.

    • Your customized actions, such as subscribing to events.

  • tuya_iot_init: this stage is to initialize necessary functions for Tuya Wi-Fi SDK. Allocate necessary compute and storage resources.

  • app_init: initializes the programming code of application, and set the working mode.

  • device_init: performs API initialization according to the working mode. The initialization API varies for different product categories.

    • SoC series: tuya_iot_wf_soc_dev_init

    • MCU series: tuya_iot_wf_mcu_dev_init

    • Gateway series: tuya_iot_wf_gw_dev_init

    • To initialize a product, you must set the value of product_key, firmware_key and start_mode (network configuration mode).

Working mode

During the app_init stage, you must select an appropriate working mode. The mode determines the initialization, network configuration, reset and other properties of your products.

GWCM_OLD

The GWCM_OLD mode is mainly applicable for the firmware using serial port interaction type.

Production testing: only after the MCU initiates a production testing request, which can be initiated any time, the device can scan the router that are used for production testing.

Note: if a SoC firmware uses the OLD mode, it cannot enter into the production testing mode.

GWCM_LOW_POWER

The GWCM_LOW_POWER mode is mainly applicable for the sockets with SoC designs.

  • Before configuring the network:

    • After powering on, the GWCM_LOW_POWER mode is indicated with a constant light status. Manual switching is required to enter the network configuration status.

    • Within 10 seconds, if the device keeps disconnected, you can restart it to re-enter the network configuration status.

    • After 10 seconds, if the device keeps disconnected, you can restart it to re-enter the GWCM_LOW_POWER status.

    • If the device keeps disconnected within 3 minutes, it enters into the GWCM_LOW_POWER status automatically.

  • Network configured and product added

    • Removal from App: the device restarts and enters into the network configuration mode automatically. By default, the network configuration is the EZ mode (smart configuration). The existing value of the SSID and PassWD will be erased.

    • Manual removal: the device restarts and enters into the network configuration mode automatically. The existing value of the SSID and PassWD will be erased.

    • Network not configured:

      • Within 10 seconds, if the device keeps disconnected, you can restart it to re-enter the network configuration status.

      • After 10 seconds, if the device keeps disconnected, you can restart it to re-enter the GWCM_LOW_POWER status.

      • If the device keeps disconnected within 3 minutes, it enters into the GWCM_LOW_POWER status automatically.

    • Network configured: the device is activated and connected again.

  • Production testing: when a device is in the GWCM_LOW_POWER mode, you must restart it to scan the production testing router to enter the production testing mode.

GWCM_SPCL_MODE

The SPCL_MODE mode is mainly applicable for the lighting products with SoC designs.

  • Before configuring the network:

    • After powering on, the SPCL_MODE mode is indicated with a constant light status. Manual switching is required to enter the network configuration status.

    • Within 10 seconds, if the device keeps disconnected, you can restart it to re-enter the network configuration status.

    • After 10 seconds, if the device keeps disconnected, you can restart it to re-enter the GWCM_SPCL_MODE status.

    • If the device keeps disconnected within 3 minutes, it enters into the LOW_POWER status automatically.

  • Network configured and product added

    • Removal from App: the device restarts and enters into the network configuration mode automatically. By default, the network configuration is the EZ mode (smart configuration). The existing value of the SSID and PassWD will be erased.

    • Manual removal: the device restarts and enters into the network configuration mode automatically. The existing value of the SSID and PassWD will be erased.

    • Network not configured:

      • Within 10 seconds, if the device keeps disconnected, you can restart it to re-enter the network configuration status.

      • After 10 seconds, if the device keeps disconnected, you can restart it to re-enter the GWCM_SPCL_MODE status.

      • If the device keeps disconnected within 3 minutes, it enters into the GWCM_SPCL_MODE status automatically.

    • Network configured: the device is activated and connected again.

  • Production testing: when a device is in the GWCM_SPCL_MODE mode, you must restart it to scan the production testing router to enter the production testing mode.

GWCM_OLD_CPT

The GWCM_OLD_CPT mode is mainly used for electrical and lighting products with SoC designs. After powering on, products enter the network configuration state and wait for configuration.

When the device waits for network configuration, you can restart the device to make it scanned by routers and enter into the production testing mode.

GWCM_LOW_POWER_AUTO_CFG

The GWCM_LOW_POWER_AUTO_CFG mode is mainly used for electrical products with SoC designs. Usually, those products flash when they are powered on, and enter into the LOW_POWER mode 3 minutes later.

  • Before configuring the network: after powering on, the products enter into the EZ (network smart configuration) mode, and sway between the EZ and AP mode.

    • Network not configured: if the product is restarted within 3 minutes, it keeps the last network configuration state. If the network of the product is not configured within 3 minutes, it enters into the LOW_POWER mode automatically.

  • Network configured and device added

    • Removal from App: the device restarts and enters into the network configuration mode automatically. By default, the network configuration is the EZ mode (smart configuration). The existing value of the SSID and PassWD will be erased.

    • Manual removal: the device restarts and enters into the network configuration mode automatically. The existing value of the SSID and PassWD will be erased.

    • If the device keeps disconnected within 3 minutes, it enters into the GWCM_SPCL_MODE status automatically.

    • Network configured: the device is activated and connected again.

  • Production testing: when a device is in the GWCM_LOW_POWER_AUTO_CFG mode, you must restart it to scan the production testing router to enter the production testing mode.

GWCM_SPCL_AUTOCFG

The GWCM_SPCL_AUTOCFG mode is mainly used for lighting products with SoC designs.

  • Before configuring the network:

    • After powering on, the GWCM_SPCL_AUTOCFG mode is indicated with a constant light status. Manual switching is required to enter the network configuration status.

    • Within 10 seconds, if the device keeps disconnected, you can restart it to re-enter the network configuration status.

    • After 10 seconds, if the device keeps disconnected, you can restart it to re-enter the GWCM_LOW_POWER status.

    • If the device keeps disconnected within 3 minutes, it enters into the GWCM_LOW_POWER status automatically.

  • Network configured and product added

    • Removal from App: the device restarts and enters into the network configuration mode automatically. By default, the network configuration is the EZ mode (smart configuration). The existing value of the SSID and PassWD will be erased.

    • Network not configured:

      • Within 10 seconds, if the device keeps disconnected, you can restart it to re-enter the network configuration status.

      • After 10 seconds, if the device keeps disconnected, you can restart it to re-enter the GWCM_SPCL_AUTOCFG status.

      • If the device keeps disconnected within 3 minutes, it enters into the GWCM_LOW_POWER status automatically.

    • Manual removal: the device restarts and enters into the network configuration mode automatically. The existing value of the SSID and PassWD will be erased.

    • Network configured: the device is activated and connected again.

  • Production testing: when a device is in the GWCM_SPCL_AUTOCFG mode, you must restart it to scan the production testing router to enter the production testing mode.

API reference

TY_IOT_CBS_S

In the app_init phase of the initial process, users need to provide some callbacks according to their needs. The SDK will notify the application of the corresponding state change through the callback at the corresponding stage.

typedef struct {
    GW_STATUS_CHANGED_CB 	gw_status_cb;
    GW_UG_INFORM_CB 		gw_ug_cb;
    GW_RESET_IFM_CB 		gw_reset_cb;
    DEV_OBJ_DP_CMD_CB 		dev_obj_dp_cb;
    DEV_RAW_DP_CMD_CB 		dev_raw_dp_cb;
    DEV_DP_QUERY_CB 		dev_dp_query_cb;
    ACTIVE_SHORTURL_CB 		active_shorturl;
}TY_IOT_CBS_S;

Description

The SDK callback interface.

Member description

Member

Prototype

Description

gw_status_cb

VOID (*GW_STATUS_CHANGED_CB)(IN CONST GW_STATUS_E status);

It is called when the SDK internal status changes.

gw_ug_cb

int (*GW_UG_INFORM_CB)(IN CONST FW_UG_S *fw);

It is called when the SDK detects it.

gw_reset_cb

VOID (*GW_RESET_IFM_CB)(GW_RESET_TYPE_E type);

It is called when SDK resets the device.

dev_obj_dp_cb

VOID (*DEV_OBJ_DP_CMD_CB)(IN CONST TY_RECV_OBJ_DP_S *dp);

It is called when SDK receives DP.

dev_raw_dp_cb

VOID (*DEV_RAW_DP_CMD_CB)(IN CONST TY_RECV_RAW_DP_S *dp);

It is called when SDK receives RAW DP.

dev_dp_query_cb

VOID (*DEV_DP_QUERY_CB)(IN CONST TY_DP_QUERY_S *dp_qry);

It is called when SDK receives DP query command.

tuya_iot_init

Prototype

OPERATE_RET tuya_iot_init(IN CONST CHAR_T *fs_storge_path)

Description

Initializes the Tuya IoT system. And it must be called at first.

Parameter

Parameter

Description

Data type

Required?

Notice

fs_storge_path

Allocates a readable and writable file partition for the SDK

CHAR_T

Yes

The path length cannot be greater than 110 bytes.

Return value

Return value

Description

OPRT_OK

Success

Error Code

The error code is returned on failure.

tuya_iot_get_sdk_info

Prototype

CHAR_T *tuya_iot_get_sdk_info(VOID);

Description

Obtains the Tuya IoT SDK version information.

Parameter

Parameter

Description

Data type

Required?

Notice

VOID

N/A

N/A

N/A

N/A

Return value

Return value

Description

SDK information

A string. SDK information includes SDK compilation time, platform, and version number, and enabled function attributes

tuya_iot_sys_mag_hb_init

Prototype

OPERATE_RET tuya_iot_sys_mag_hb_init(IN CONST DEV_HEARTBEAT_SEND_CB hb_send_cb);

Description

Enables heartbeat management capabilities of child devices.

Parameter

Parameter

Description

Data type

Required?

Notice

hb_send_cb

The gateway checks all child devices every 3 seconds. If the child device does not send a heartbeat to the gateway within the timeout period of the heartbeat packet, the gateway will set the child device offline and notify the user at least three times through hb_send_cb

hb_send_cb callback function

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_iot_set_wf_gw_prod_info

Prototype

OPERATE_RET tuya_iot_set_wf_gw_prod_info(IN CONST WF_GW_PROD_INFO_S *wf_prod_info);

Description

Sets the authorization information of the configuration Wi-Fi device. The authorization information needs to be obtained through Tuya, otherwise the device cannot be used normally.

Parameter

Parameter

Description

Data type

Required?

Notice

wf_prod_info

This structure contains device information: uuid and authkey Wi-Fi ssid and password.

WF_GW_PROD_INFO_S *

Yes

You need to pass this information to the SDK.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

Error code returned on failure

tuya_iot_wf_mcu_dev_init

Prototype

OPERATE_RET tuya_iot_wf_mcu_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode, 
                                     IN CONST TY_IOT_CBS_S *cbs, IN CONST CHAR_T *p_firmware_key, 
                                     IN CONST CHAR_T *product_key, IN CONST CHAR_T *wf_sw_ver, IN CONST CHAR_T *mcu_sw_ver);

Description

The metworking module and MCU device initialization interface.

Parameter

Parameter

Description

Data type

Required?

Notice

cfg

How Wi-Fi devices work. Working mode: 1. Non-low power consumption mode. 2. Low power consumption mode. 3. Special low power consumption mode.

GW_WF_CFG_MTHD_SEL

Yes

N/A

start_mode

Wi-Fi distribution mode: 1. Only work in ap configuration mode. 2. Only smart config mode. 3. ap and smart config mode, the default ap mode. 4. ap and smart config mode. The default value sets to the smart config mode. Select the mode according to actual needs.

GW_WF_START_MODE

Yes

N/A

cbs

Wi-Fi SDK user callback function

TY_IOT_CBS_S *

Yes

N/A

p_firmware_key

Firmware key. When the firmware is uploaded to the Tuya platform, there will be a firmware key.

String

Yes

N/A

product_key

Get when Tuya creates a product

String

Yes

N/A

wf_sw_ver

Wi-Fi software version number

String

Yes

N/A

mcu_sw_ver

MCU firmware version number

String

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_iot_wf_soc_dev_init

Prototype

OPERATE_RET tuya_iot_wf_soc_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode,
                                     IN CONST TY_IOT_CBS_S *cbs, IN CONST CHAR_T *product_key, IN CONST CHAR_T *wf_sw_ver);

Description

The Wi-Fi SoC device initialization interface.

Parameter

Parameter

Description

Data type

Required?

Notice

cfg

How Wi-Fi devices work. Working mode: 1) Non-low power consumption mode. 2) Low power consumption mode. 3) Special low power consumption mode.

GW_WF_CFG_MTHD_SEL

Yes

N/A

start_mode

Wi-Fi distribution mode: 1) Only works in AP configuration mode. 2) Only smart config mode. 3) AP and smart config mode, the default AP mode. 4) AP and smart config mode. The default smart config mode. Select the mode according to your actual needs.

GW_WF_START_MODE

N/A

cbs

Wi-Fi SDK user callback function

TY_IOT_CBS_S *

N/A

product_key

Get when Tuya creates a product

String

N/A

wf_sw_ver

Software version number

String

xx.xx.xx

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_iot_wf_gw_init

Prototype

OPERATE_RET tuya_iot_wf_gw_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode, 
                                IN CONST TY_IOT_CBS_S *cbs, IN CONST TY_IOT_GW_CBS_S *gw_cbs, 
                                IN CONST CHAR_T *product_key, IN CONST CHAR_T *wf_sw_ver, IN CONST GW_ATTACH_ATTR_T *attr, 
                                IN CONST UINT_T attr_num);

Description

The Wi-Fi gateway initialization interface.

Parameter

Parameter

Description

Data type

Required?

Notice

cfg

How Wi-Fi devices work. Working mode: 1) Non-low power consumption mode 2) Low power consumption mode 3) Special low power consumption mode

GW_WF_CFG_MTHD_SEL

Yes

N/A

start_mode

Wi-Fi distribution mode: 1. Only works in AP configuration mode 2. Only smart config mode 3. AP and smart config mode, the default AP mode 4. AP and smart config mode, the default smart config mode

GW_WF_START_MODE

Yes

N/A

cbs

Tuya Wi-Fi SDK user callback

TY_IOT_CBS_S *

Yes

N/A

gw_cbs

Tuya Gateway user callback

TY_IOT_GW_CBS_S *

Yes

N/A

product_key

Tuya platform creation time to obtain

String

Yes

N/A

wf_sw_ver

Software version number

String

Yes

N/A

attr

Array of Gateway Attributes

GW_ATTACH_ATTR_T *

Yes

N/A

attr_num

Gateway attribute length

UINT_T

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_iot_wf_gw_dev_init

Prototype

OPERATE_RET tuya_iot_wf_gw_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg, IN CONST GW_WF_START_MODE start_mode,
                                     IN CONST TY_IOT_CBS_S *cbs, IN CONST TY_IOT_GW_CBS_S *gw_cbs, IN CONST CHAR_T *product_key,
                                     IN CONST CHAR_T *wf_sw_ver, IN CONST GW_ATTACH_ATTR_T *attr, IN CONST UINT_T attr_num);

Description

The Wi-Fi gateway and device initialization interface. Compared with tuya_iot_wf_gw_init, this function makes the gateway have the attributes of the device and can set function points.

Parameter

Refers to tuya_iot_wf_gw_init interface description.

Return value

Refers to tuya_iot_wf_gw_init interface description.

tuya_iot_reg_get_wf_nw_stat_cb

Prototype

OPERATE_RET tuya_iot_reg_get_wf_nw_stat_cb(IN CONST GET_NW_STAT_CB nw_stat_cb);

Description

Gets Wi-Fi status interface.

Parameter

Parameter

Description

Data type

Required?

Notice

nw_stat_cb

Tuya SDK network detection callback, the parameter of the callback function is the network status.

nw_stat_cb

Yes

See SDK samples for details.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

Network configuration

The process

After the device is initialized, the most important follow-up is to configure the network so that the device can connect to the cloud through the router. If the device has been connected, you do not need to configure the network after device restarting or initializing.

You need to determine the working mode supported by the Wi-Fi network card, and inform the Tuya Wi-Fi SDK the network configuration mode of the device when the tuya_iot_wf_soc_dev_init or tuya_iot_wf_gw_dev_init is initialized. Refer to the description of start_mode parameters of the interface for more information. During the network configuration, you must use a mobile App to interact with the device, and send the ssid, pswd, token, and other information through coding, broadcast packets and multicast packets until the network is configured.

EZ mode

EZ indicates fast configuration. When the Wi-Fi module works in the monitor mode, the device can easily to receive and resolve the Wi-Fi beacon packets that are sent by the mobile App, and get configuration information from them. Later, the Wi-Fi module turns to the station mode and wait for network configuration.

AP network configuration mode

The process of AP network configuration is relatively complicated. In this mode, devices must enable AP hotspot, and wait for network connection from mobile phone. Next, the configuration information is sent via LAN network to the device, and the Wi-Fi module turns to the station mode and wait for network configuration.

Other network configuration mode

The Tuya Wi-Fi SDK supports other network configuration mode, such as QR code scanning or Bluetooth communication. In those configuration mode, your application obtains the ssid, passwd, and token via the following methods and directly applies for device joining by calling APIs.

  • QR code: the devices scan the QR code that are generated by App to obtain the ssid, passwd, and token information.

  • Easy routing: the devices obtain the ssid, passwd, and token information via routers.

  • FFS: the devices obtain the ssid, passwd, and token information via third party devices, such as Amazon Echo.

  • Sound wave: the devices obtain the encoded ssid, passwd, and token information via serial ports or sound waves.

  • Bluetooth: the devices obtain the ssid, passwd, and token information via Bluetooth.

The network configuration mode

You can choose the network configuration mode by calling the device_init() API, and the following values are supported.

  • AP only (WF_START_AP_ONLY): only works in the AP configuration mode.

  • Smart only (WF_START_SMART_ONLY): works in the smart config mode.

  • AP first (WF_START_AP_FIRST): works both in the AP configuration mode and the smart config mode, but the AP configuration mode is the default setting.

  • Smart first (WF_START_SMART_FIRST): works both in the AP configuration mode and the smart config mode, but the smart config mode is the default setting.

  • Both AP and Smart (WF_START_SMART_AP_CONCURRENT): works both in the AP configuration mode and the smart config mode.

API reference

tuya_hal_wifi_all_ap_scan

Prototype

OPERATE_RET tuya_hal_wifi_all_ap_scan(OUT AP_IF_S **ap_ary, OUT UINT_T *num);

Description

Scans all AP.

Parameter

Parameter

Description

Data type

Required?

Notice

ap_ary

List of AP information in the current environment.

AP_IF_S **

Yes

As output parameter

num

The length of the current environment AP information list.

UINT_T

Yes

As output parameter

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_assign_ap_scan

Prototype

OPERATE_RET tuya_hal_wifi_assign_ap_scan(IN CONST CHAR_T *ssid, OUT AP_IF_S **ap);

Description

Scans the specified AP.

Parameter

Parameter

Description

Data type

Required?

Notice

ssid

The ssid of the specified AP.

String

Yes

Input Parameter

ap

Gets the specified AP information.

AP_IF_S **

Yes

Output

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_release_ap

Prototype

OPERATE_RET tuya_hal_wifi_release_ap(IN AP_IF_S *ap);

Description

Release processing of resources.

Parameter

Parameter

Description

Data type

Required?

Notice

ap

When the ap information is useless, release the memory requested in tuya_hal_wifi_all_ap_scan and tuya_hal_wifi_assign_ap_scan.

AP_IF_S *

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_set_cur_channel

Prototype

OPERATE_RET tuya_hal_wifi_set_cur_channel(IN CONST BYTE_T chan);

Description

Sets the Wi-Fi working channel.

Parameter

Parameter

Description

Data type

Required?

Notice

chan

Wi-Fi working channel to be set

BYTE_T

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_get_cur_channel

Prototype

OPERATE_RET tuya_hal_wifi_get_cur_channel(OUT BYTE_T *chan);

Description

Gets the current working channel.

Parameter

Parameter

Description

Data type

Required?

Notice

nw_stat_cb

Network change callback function, the parameter of the callback function is the network status.

nw_stat_cb

Yes

See SDK samples for details.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_sniffer_set

Prototype

OPERATE_RET tuya_hal_wifi_sniffer_set(IN CONST BOOL_T en, IN CONST SNIFFER_CALLBACK cb);

Description

Wi-Fi device promiscuous mode setting.

Parameter

Parameter

Description

Data type

Required?

Notice

en

Enables or disables Wi-Fi sniffer mode

nw_stat_cb

Yes

N/A

cb

Notification callback function. The captured 802.11 air packet contains the frame header.

SNIFFER_CALLBACK

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_get_ip

Prototype

OPERATE_RET tuya_hal_wifi_get_ip(IN CONST WF_IF_E wf, OUT NW_IP_S *ip);

Description

Gets Wi-Fi device ip information.

Parameter

Parameter

Description

Data type

Required?

Notice

wf

Wi-Fi working mode , AP and station.

WF_IF_E

Yes

N/A

ip

Saves the obtained IP information structure, the information contains IP, submask, gateway.

NW_IP_S *

Yes

Output parameters

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_get_mac

Prototype

OPERATE_RET tuya_hal_wifi_get_mac(IN CONST WF_IF_E wf, OUT NW_MAC_S *mac);

Description

Gets the MAC address of the Wi-Fi device.

Parameter

Parameter

Description

Data type

Required?

Notice

wf

Wi-Fi working mode. AP and station

nw_stat_cb

Yes

N/A

mac

Saves the obtained MAC address

NW_MAC_S *

Yes

As output parameter

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_set_mac

Prototype

OPERATE_RET tuya_hal_wifi_set_mac(IN CONST WF_IF_E wf,IN CONST NW_MAC_S *mac);

Description

Sets the MAC address of the Wi-Fi device is optional.

Parameter sescription

Parameter

Description

Data type

Required?

Notice

wf

Wi-Fi working mode, AP and station

WF_IF_E

Yes

Input parameters

mac

The set MAC address

NW_MAC_S *

Yes

Input parameters

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_wk_mode_set

Prototype

OPERATE_RET tuya_hal_wifi_wk_mode_set(IN CONST WF_WK_MD_E mode);

Description

Sets the Wi-Fi working mode.

Parameter

Parameter

Description

Data type

Required?

Notice

mode

Sets the Wi-Fi working mode: 1. Low power mode 2. Promiscuous mode 3. station mode 4. ap mode 5. ap + station mode

WF_WK_MD_E

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_wk_mode_get

Prototype

OPERATE_RET tuya_hal_wifi_wk_mode_get(OUT WF_WK_MD_E *mode);

Description

Gets Wi-Fi working mode.

Parameter

Parameter

Description

Data type

Required?

Notice

mode

Same meaning as the parameter mode in tuya_hal_wifi_wk_mode_set

WF_WK_MD_E

Yes

Output parameters

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_station_connect

Prototype

OPERATE_RET tuya_hal_wifi_station_connect(IN CONST CHAR_T *ssid, IN CONST CHAR_T *passwd);

Description

Sets up the Wi-Fi device to establish a connection with the AP/hotspot/Wi-Fi router.

Parameter

Parameter

Description

Data type

Required?

Notice

ssid

The ssid connected to the ap/hotspot/Wi-Fi router

String

Yes

N/A

password

The password to connect to the ap/hotspot/Wi-Fi router

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_station_disconnect

Prototype

OPERATE_RET tuya_hal_wifi_station_disconnect(VOID);

Description

Disconnect the Wi-Fi device from the AP/hotspot/Wi-Fi router.

Parameter

VOID.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_station_get_conn_ap_rssi

Prototype

OPERATE_RET tuya_hal_wifi_station_get_conn_ap_rssi(OUT SCHAR_T *rssi);

Description

Gets the signal strength of the Wi-Fi device in station mode connected to the AP.

Parameter

Parameter

Description

Data type

Required?

Notice

rssi

obtained rssi

SCHAR_T*

Yes

output parameter

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_station_stat_get

Prototype

OPERATE_RET tuya_hal_wifi_station_stat_get(OUT WF_STATION_STAT_E *stat);

Description

Gets the connection status of the Wi-Fi device in station mode.

Parameter

Parameter

Description

Data type

Required?

Notice

stat

Wi-Fi and ap connection status in Station mode, which includes Not connected, Connecting, Wrong password, ap not found, Connection failed, Successful connection, and Successful acquisition.

WF_STATION_STAT_E *

Yes

Output parameters

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_set_country_code

Prototype

OPERATE_RET tuya_hal_wifi_set_country_code(IN CONST CHAR_T *p_country_code);

Function sescription

Sets the country code.

Parameter sescription

Parameter

Description

Data type

Required?

Notice

p_country_code

The frequency and channel signal strength of Wi-Fi devices vary in different countries.

CHAR_T *

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_ap_start

Prototype

OPERATE_RET tuya_hal_wifi_ap_start(IN CONST WF_AP_CFG_IF_S *cfg);

Description

Starts the Wi-Fi AP hotspot.

Parameter

Parameter

Description

Data type

Required?

Notice

cfg

Start as a configuration parameter in AP mode. The ssid, password, channel, encryption method, whether to hide ssid, and maximum number of connections are supported.

WF_AP_CFG_IF_S *

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_hal_wifi_ap_stop

Prototype

OPERATE_RET tuya_hal_wifi_ap_stop(VOID);

Description

Stop Wi-Fi AP hotspot.

Parameter

None.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

tuya_iot_gw_wf_user_cfg

Prototype

OPERATE_RET tuya_iot_gw_wf_user_cfg(IN CONST CHAR_T *ssid, IN CONST CHAR_T *passwd, IN CONST CHAR_T *token);

Description

When the network is not configured in the AP or EZ mode, call this interface for processing.

Parameter

Parameter

Description

Data type

Required?

Notice

ssid

The ssid used by the network in AP mode.

String

Yes

N/A

passwd

The password used for network configuration in AP mode.

String

Yes

N/A

token

The token used by the distribution network in AP mode.

String

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

Device reset

APP reset

You can reset a device via App. The APP reset APIs send a reset message through MQTT to reset the device.

Local reset

Alternatively, the SDK retains the ability to reset the gateway locally, for example, you can reset the device locally by pressing buttons.

tuya_iot_gw_unactive

OPERATE_RET tuya_iot_gw_unactive(VOID);

Description

Resets the device to unassociate the gateway with the App, so that the gateway is in an inactive state.

Note: This function is asynchronous, and it will trigger the gw_reset_cb callback after execution, you can restart the thread in the callback.

Parameter

None.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

Firmware upgrade

The process

Configuration of firmware package

  1. After the gateway or device is successfully configured, App obtains the virtual ID of the device, and add it to the white list for firmware upgrade.

  2. Compile the firmware package that is to be upgraded, and the firmware version is newer than the firm that is running in the device.

  3. Log on to the Tuya IoT console, find the relevant product, and upload the compiled firmware package.

  4. Perform the follow-ups. For more information, see Upgrade Firmwares.

How the upgrade starts

After the firmware is uploaded to cloud, your devices will not receive the upgrade notification immediately. At present, the following upgrade notification is available.

  • App notification: when your users switch to the App panel of the devices, they receive an upgrade reminder box and can choose to upgrade or not.

  • Silent upgrade: after the devices are restarted, they will ask the cloud if there is a silent upgrade task, and complete the upgrade automatically. If your users happen to switch to the App panel of the devices during the upgrade, an progress tracker will be displayed, and the device cannot be operated for a while.

  • Forcible upgrade: when your users switch to the App panel of the devices for the first time, they receive the upgrade reminder pop-up and only confirmation is provided. The equipment cannot be operated for a while.

  • Upgrade detection: your users switch to the App panels of the devices and click the upper right corner to enter the information center to check the firmware version of the device, and proactively update the firmware.

The firmware upgrade process

API reference

tuya_iot_upgrade_gw_notify

Prototype

OPERATE_RET tuya_iot_upgrade_gw(IN CONST FW_UG_S *fw, IN CONST GET_FILE_DATA_CB get_file_cb, 
                                IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb, IN CONST PVOID_T pri_data, 
                                BOOL_T notify, UINT_T download_buf_size);

Description

The networking module firmware upgrade processing interface.

Parameter

Parameter

Description

Data type

Required?

Notice

fw

The firmware information

FW_UG_S structure pointer

Yes

N/A.

get_file_cb

Downloads the file to store.

Callback function

Yes

N/A.

upgrd_nofity_cb

Notifies the upgrade status of the application

Callback function

Yes

N/A.

pri_data

Parameters passed to get_file_cb and upgrd_nofity_cb.

Pointer

No

If no parameters are passed, set to NULL.

notify

Chooses whether to report upgrade progress via SDK.

Boolean

Yes

TRUE is reported by the SDK, FALSE is reported by the application layer

download_buf_size

Download maximum cache, unit: byte.

UINT_T

No

Pass in 0, SDK default cache size

Return value

Return value

Description

OPRT_OK

Success

Error Code

The error code is returned on failure.

tuya_iot_dev_upgd_progress_rept

Prototype

OPERATE_RET tuya_iot_dev_upgd_progress_rept(IN CONST UINT_T percent, IN CONST CHAR_T *devid, IN CONST DEV_TYPE_T tp);

Description

Reports the upgrade progress.

Parameter

Parameter

Description

Data type

Required?

Notice

percent

Upgrade progress value

UINT_T

Yes

0~99

devid

When the sub-device is passed, the device ID of the sub-device; When the gateway is passed, NULL.

CHAR_T *

Yes

Refer to the SDK samples.

tp

Device type

DEV_TYPE_T

Yes

Refer to the SDK samples.

Return value

Return value

Description

OPRT_OK

Success

Error Code

The error code is returned on failure.

Data point of devices

The process

Tuya Smart provides a network application protocol based on MQTT to achieve device control and status reporting. MQTT is a lightweight message transmission protocol designed specifically for the Internet of things applications in low bandwidth and unstable network environment.

The Tuya Wi-Fi SDK encapsulates the APIs for MQTT protocol layer, which is presented in the form of data points (hereinafter referred to as DP points). It supports data type of integer, Boolean, enum, string, bitmap, and raw, which are the same as defining variables in C programming language.

You must create corresponding data points on the Tuya IoT console according to the device functions, and create a new DP Point description. For more information, see Overview of function definition.

Features

  • At present, up to 35 DPs for each product are supported. To develop complex functions, the raw data is recommended.

  • The objects such as Boolean, integer, string, enum, and bitmap, the Tuya Wi-Fi SDK filters the reported values, and the repeated data will be dropped.

API reference

dev_obj_dp_cb

Prototype

VOID dev_obj_dp_cb(IN CONST TY_RECV_OBJ_DP_S *dp);

Description

The OBJ function point information command callback.

Parameter

Parameter

Description

Data type

Required?

Notice

dp

TY_RECV_OBJ_DP_S contains the dp command type, device ID controlled by dp point, the mb_id group ID when the dtt_tp is multi-broadcasted, the length of function point structure array, and the function point structure array. For more information, see tuya_cloud_com_defs.h.

TY_RECV_OBJ_DP_S*

Yes

You can focus on the function point structure arrays. Function points are defined on the Tuya platform.

Return value

Return value

Description

None

No return value

Error Code

Error Code Returned on failure

dev_raw_dp_cb

Prototype

VOID dev_raw_dp_cb(IN CONST TY_RECV_RAW_DP_S *dp);

Description

The command callback for function points passthrough.

Parameter

Parameter

Description

Data type

Required?

Notice

dp

The structure contains the dp command type, the device ID controlled by DP, the mb_id group ID when the dtt_tp is multi-broadcasted, the Number of data bytes passed through, the passed through data types, and the function point structure array. For more information, see tuya_cloud_com_defs.h.

TY_RECV_RAW_DP_S*

Yes

N/A

Return value

Return value

Description

VOID

No return value

dev_dp_query_cb

Prototype

VOID dev_dp_query_cb(IN CONST TY_DP_QUERY_S *dp_qry);

Description

The device specific data query entry. It is an optional implementation.

Parameter

Parameter name

Description

Parameter type

Whether it is mandatory

Notice

dp_qry

TY_DP_QUERY_S*

Yes

N/A

Return value

Return value

Description

VOID

No return value

dev_report_dp_json_async

Prototype

OPERATE_RET dev_report_dp_json_async(IN CONST CHAR_T *dev_id, IN CONST TY_OBJ_DP_S *dp_data, IN CONST UINT_T cnt);

Description

The report function point information in an asynchronous way.

Parameter

Parameter

Description

Data type

Required?

Notice

dev_id

The device ID.

String

Yes

If it is a child device, this parameter is the ID of the child device. If it is a gateway or MCU, this parameter is NULL.

dp_data

The function point data structure.

TY_OBJ_DP_S structure array pointer

Yes

N/A

cnt

Number of dp_data structure arrays

UINT_T

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

Error Code Returned on failure

dev_report_dp_raw_sync

Prototype

OPERATE_RET dev_report_dp_raw_sync (IN CONST CHAR_T *dev_id, IN CONST BYTE_T dpid, IN CONST BYTE_T *data,IN CONST UINT_T len, 
                                    IN CONST UINT_T timeout);

Description

The device data reporting interface in the passthrough method, and the caller guarantees the reliability of data reporting.

Parameter

Parameter

Description

Data type

Required?

Notice

dev_id

The device ID.

String

Yes

If it is a child device, this parameter is the ID of the child device. If it is a gateway or MCU, this parameter is NULL.

dpid

function point id

UINT_T

Yes

N/A

data

data

BYTE_T *

Yes

N/A

len

Data length

UINT_T

Yes

N/A

timeout

Function plunger timeout

UINT_T

Yes

Unit: seconds.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

dev_report_dp_stat_sync

Prototype

OPERATE_RET dev_report_dp_stat_sync(IN CONST CHAR_T *dev_id, IN CONST TY_OBJ_DP_S *dp_data, IN CONST UINT_T cnt, 
                                    IN CONST UINT_T timeout);

Description

The structured device data reporting interface in the passthrough method, and the caller guarantees the reliability of data reporting. It is usually used for statistical data reporting.

Parameter

Parameter

Description

Data type

Required?

Notice

dev_id

The device ID.

String

Yes

If it is a child device, this parameter is the ID of the child device. If it is a gateway or MCU, this parameter is NULL.

dp_data

Function point information structure array

TY_OBJ_DP_S *

Yes

N/A

cnt

Dp state array length

UINT_T

Yes

N/A

timeout

Function plunger timeout

UINT_T

Yes

Units: seconds.

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

Error Code Returned on failure

Log management

The Tuya Wi-Fi SDK can collect and redirect logs. By default, the log is printed to a standard terminals and can be redirected if needed, such as printing to a file or the cloud.

AddOutputTerm

Prototype

OPERATE_RET AddOutputTerm(IN CONST CHAR_T *name, IN CONST LOG_OUTPUT term);

Description

Adds an output callback for the tuya_SDK log to write the log to a file.

Parameter

Parameter

Description

Data type

Required

Notice

name

The name of the log callback

String

Yes

Used for DelOutputTerm to unregister this callback

term

LOG_OUTPUT

callback

Yes

N/A

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

DelOutputTerm

Prototype

VOID DelOutputTerm(IN CONST CHAR_T *name);

Description

Unregisters the log callback registered by the AddOutputTerm interface.

Parameter

Parameter

Description

Data type

Required?

Notice

name

The name of the log callback.

String

Yes

Unregisters log callback registered by AddOutputTerm interface.

Return value VOID

SetLogManageAttr

Prototype

OPERATE_RET SetLogManageAttr(IN CONST LOG_LEVEL curLogLevel);

Description

Sets the log level.

Parameter

Parameter

Description

Data type

Required?

Notice

curLogLevel

Log level

UINT

Yes

See uni_log.h instructions

Return value

Return value

Description

OPRT_OK

Operation succeeded.

Error Code

The error code is returned on failure.

Timer

Add a system timer

Prototype

OPERATE_RET sys_add_timer(IN CONST P_TIMER_FUNC pTimerFunc,
IN CONST PVOID pTimerArg, OUT TIMER_ID *p_timerID);

Description

Adds a system timer.

Parameter

Parameter

Description

Data type

Required?

Notice

pTimerFunc

Timer handler function

P_TIMER_FUNC

Yes

Pointer to callback function for timer aging call

pTimerArg

Timer processing parameters

PVOID

Yes

Timer related parameters, the specific type is determined internally by the callback function

p_timerID

Timer ID number

TIMER_ID *

Yes

Output parameter, add timer ID successfully returned

Return value

Return value

Description

OPERATE_RET

Error code information

sys_stop_timer

Prototype

OPERATE_RET sys_stop_timer(IN CONST TIMER_ID timerID));

Description

Stops a timer.

Parameter

Paramete

Description

Data type

Required?

Notice

timerID

timer ID number

TIMER_ID *

Yes

The timer ID that needs to be stopped.

Return value

Return value

Description

OPERATE_RET

Error code information

IsThisSysTimerRun

Prototype

BOOL IsThisSysTimerRun(IN CONST TIMER_ID timerID);

Description

Determines whether a timer is running.

Parameter

Parameter

Description

Data type

Required?

Notice

timerID

timer ID number

TIMER_ID *

Yes

Your need to determine whether the timer ID is running.

Return value

Return value

Description

BOOL

Whether the timing is running

sys_start_timer

Prototype

OPERATE_RET sys_start_timer(IN CONST TIMER_ID timerID, IN CONST TIME_MS timeCycle, IN CONST TIMER_TYPE timer_type);

Description

Starts a timer.

Parameter

Parameter

Description

Data type

Required?

Notice

timerID

timer ID number

TIMER_ID *

Yes

need to determine whether the timer id running timer

timeCycle

Timed period

TIME_MS

Yes

Timed period, (in milliseconds)

timer_type

timer type

TIMER_TYPE

Yes

TIMER_ONCE single execution TIMER_CYCLE loop execution

Return value

Return value

Description

BOOL

Whether the timing is running

message queue

CreateMsgQueAndInit

Prototype

OPERATE_RET CreateMsgQueAndInit(OUT MSG_QUE_HANDLE *pMsgQueHandle);

Description

Createa message queues.

Parameter

Parameter

Description

Data type

Required?

Notice

pMsgQueHandle

Message management structure handle

MSG_QUE_HANDLE *

Yes

Output parameter, handle returned after successful creation

Return value

Return value

Description

OPERATE_RET

Error code information

AddMsgNodeToQueue

Prototype

OPERATE_RET AddMsgNodeToQueue(IN CONST MSG_QUE_HANDLE msgQueHandle, IN CONST MSG_ID msgID, IN CONST P_MSG_DATA pMsgData,IN CONST MSG_DATA_LEN msgDataLen, IN CONST MSG_TYPE msgType);

Description

Creates message queues.

Parameter

Parameter

Description

Data type

Required?

Notice

pMsgQueHandle

Message management structure handle

MSG_QUE_HANDLE

Yes

Create handle returned successfully

msgID

Message ID

MSG_ID

Yes

N/A

pMsgData

Message data

P_MSG_DATA

Yes

N/A

msgDataLen

Message data length

MSG_DATA_LEN

Yes

N/A

msgType

Message Type

MSG_TYPE

Yes

N/A

Return value

Return value

Description

OPERATE_RET

Error code information

GetMsgNodeFromQueue

Prototype

OPERATE_RET GetMsgNodeFromQueue(IN CONST MSG_QUE_HANDLE msgQueHandle, IN CONST MSG_ID msgID, OUT P_MSG_LIST *ppMsgListNode);

Description

Gets the message node of the specified ID.

Parameter

Parameter

Description

Data type

Required?

Notice

pMsgQueHandle

Message management structure handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

msgID

Message ID

MSG_ID

Yes

pMsgListNode

Message node

P_MSG_LIST *

Yes

Output parameter, obtained message node

Return value

Return value

Description

OPERATE_RET

Error code information

GetFirstMsgFromQueue

Prototype

OPERATE_RET GetFirstMsgFromQueue(IN CONST MSG_QUE_HANDLE msgQueHandle, OUT P_MSG_LIST *ppMsgListNode);

Description

Gets the message node that first enters the chain.

Parameter

Parameter

Description

Data type

Required?

Notice

pMsgQueHandle

Message management structure handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

pMsgListNode

Message node

P_MSG_LIST *

Yes

Output parameter, obtained message node

Return value

Return value

Description

OPERATE_RET

Error code information

GetMsgNodeNum

Prototype

OPERATE_RET GetMsgNodeNum(IN CONST MSG_QUE_HANDLE msgQueHandle,OUT PINT pMsgNodeNum);

Description

Gets the total number of message nodes in the linked list.

Parameter

Parameter

Description

Data type

Required?

Notice

pMsgQueHandle

Message management structure handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

pMsgNodeNum

Total number of message nodes

PINT

Yes

Output parameters, total number of message nodes obtained

Return value

Return value

Description

OPERATE_RET

Error code information

DelAndFreeMsgNodeFromQueue

Prototype

OPERATE_RET DelAndFreeMsgNodeFromQueue(IN CONST MSG_QUE_HANDLE msgQueHandle, IN CONST P_MSG_LIST pMsgListNode);

Description

Removes the message node from the chain and free the message node memory.

Parameter

Parameter

Description

Data type

Required?

Notice

pMsgQueHandle

Message management structure handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation.

pMsgListNode

Deleted message node

P_MSG_LIST

Yes

Deleted message node

Return value

Return value

Description

OPERATE_RET

Error code information

ReleaseMsgQue

Prototype

OPERATE_RET ReleaseMsgQue(IN CONST MSG_QUE_HANDLE msgQueHandle);

Description

Releases the memory occupied by the message queue.

Parameter

Parameter

Description

Data type

Required?

Notice

pMsgQueHandle

Message management structure handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

Return value

Return value

Description

OPERATE_RET

Error code information

PostMessage

Prototype

OPERATE_RET PostMessage(IN CONST MSG_QUE_HANDLE msgQueHandle, IN CONST MSG_ID msgID, IN CONST P_MSG_DATA pMsgData, IN CONST MSG_DATA_LEN msgDataLen);

Description

Delivers a message to the module (the message is executed first).

Parameter dDescription

Parameter

Description

Data type

Required?

Notice

msgQueHandle

Message processing handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

msgID

Message ID

MSG_ID

Yes

N/A

pMsgData

Message data

P_MSG_DATA

Yes

N/A

msgDataLen

Message data length

MSG_DATA_LEN

Yes

N/A

Return value

Return value

Description

OPERATE_RET

Error code information

PostInstancyMsg

Prototype

OPERATE_RET PostInstancyMsg(IN CONST MSG_QUE_HANDLE msgQueHandle, IN CONST MSG_ID msgID, IN CONST P_MSG_DATA pMsgData, IN CONST MSG_DATA_LEN msgDataLen);

Description

Delivers urgent messages (messages are executed immediately).

Parameter

Parameter

Description

Data type

Required?

Notice

msgQueHandle

Message processing handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

msgID

Message ID

MSG_ID

Yes

N/A

pMsgData

Message data

P_MSG_DATA

Yes

N/A

msgDataLen

Message data length

MSG_DATA_LEN

Yes

N/A

Return value

Return value

Description

OPERATE_RET

Error code information

WaitMessage

Prototype

OPERATE_RET WaitMessage(IN CONST MSG_QUE_HANDLE msgQueHandle, OUT P_MSG_LIST *ppMsgListNode);

Description

Delivers urgent messages (messages are executed immediately). WaitMessage needs to be called successfully, and DelAndFreeMsgNodeFromQueue needs to be called after the message is processed to release the message

Parameter

Parameter

Description

Data type

Required?

Notice

msgQueHandle

Message processing handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

ppMsgListNode

Message node

P_MSG_LIST *

Yes

Output parameters, message node received

Return value

Return value

Description

OPERATE_RET

Error code information

Task queue

CreateAndStart

Prototype

OPERATE_RET CreateAndStart(OUT THRD_HANDLE *pThrdHandle, IN CONST P_THRD_FUNC pThrdFunc,
IN CONST PVOID pThrdFuncArg, IN CONST STACK_SIZE stack_size,IN CONST TRD_PRI pri,
IN CONST CHAR *thrd_name);;

Description

Creates a task.

Parameter

Parameter

Description

Data type

Required?

Notice

pThrdHandle

pThrdHandle task handle

MSG_QUE_HANDLE

Yes

Handle returned after successful creation

pThrdFunc

Task processing function

P_THRD_FUNC

Yes

N/A

pThrdFuncArg

Task parameters

PVOID

Yes

N/A

stack_size

Specify the task stack size

STACK_SIZE

Yes

N/A

pri

Task priority

TRD_PRI

Yes

N/A

thrd_name

Task name

CHAR *

Yes

N/A

return value

Return value

Description

OPERATE_RET

Error code information

ThrdJoin

Prototype

OPERATE_RET ThrdJoin(IN CONST THRD_HANDLE thrdHandle, OUT VOID **ppThrdRet);;

Description

Creates a task.

Parameter

Parameter

Description

Data type

Required?

Notice