Wi-Fi

Last Updated on : 2025-04-30 02:10:42download

Overview

This topic describes the features of the Wi-Fi protocol.

API description

tkl_wifi_init

OPERATE_RET tkl_wifi_init(WIFI_EVENT_CB cb)

Function description
- Set the operating status of the Wi-Fi network.
Parameter

Input/Output Parameter Description

[in] cb The callback invoked when Wi-Fi operating status is set.
Return value
- OPRT_OK: Success.
- Others: Failure.

Input/Output	Parameter	Description
[in]	cb	The callback invoked when Wi-Fi operating status is set.

tkl_wifi_scan_ap

OPERATE_RET tkl_wifi_scan_ap(CONST SCHAR_T *ssid, AP_IF_S **ap_ary, UINT_T *num)

Function description
- Scan for access points (AP) in the current environment.

Parameter

Input/Output	Parameter	Description
[in]	ssid	If `ssid` is `NULL`, scan for all APs. Otherwise, scan for the specified AP.
[out]	ap_ary	The result of scanning.
[out]	num	The number of scanned APs.

Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_AP_SCAN_FAILED: Scanning failed.

This is a blocking function.
Only APs within the current country code channel list can be scanned for.
When an AP with the specified SSID is present in the environment, the scanning success rate for this SSID shall exceed 98%.
The AP shall allocate memory within this API. Contiguous memory space is required when scanning for multiple APs.
TuyaOS proactively calls tkl_wifi_release_ap to release the memory.

tkl_wifi_release_ap

OPERATE_RET tkl_wifi_release_ap(AP_IF_S *ap)

Function description
- Release the AP information resources.
Parameter

Input/Output Parameter Description

[in] ap Release the AP information obtained by tkl_wifi_scan_ap.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_AP_RELEASE_FAILED: Failure.

Input/Output	Parameter	Description
[in]	ap	Release the AP information obtained by `tkl_wifi_scan_ap`.

tkl_wifi_start_ap

OPERATE_RET tkl_wifi_start_ap(CONST WF_AP_CFG_IF_S *cfg)

Function description
- Enable the AP mode.
Parameter

Input/Output Parameter Description

[in] cfg The AP configuration parameter.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_AP_START_FAILED: Failure.

Input/Output	Parameter	Description
[in]	cfg	The AP configuration parameter.

You must configure the maximum number of stations allowed to connect in AP mode using the max_conn parameter.
You must configure the IP address in AP mode based on the specified IP address information.
In station AP mode, when the AP port has active connections, if the station port fails to connect to the router, the AP port must maintain its connections without disconnection. That is, the AP port shall remain capable of sending/receiving broadcast packets.
Pairing in Wi-Fi Easy Connect (EZ) and AP compatible mode
- Both Soft AP and Station AP modes support enabling the sniffer feature and channel switching.
- When the sniffer feature is enabled, the callback data must include device connection request packets from the AP port.

tkl_wifi_stop_ap

OPERATE_RET tkl_wifi_stop_ap(VOID_T)

Function description
- Disable the AP mode.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_AP_STOP_FAILED: Failure.

The shutdown logic must be differentiated based on the device’s current operation mode (Soft AP or Station AP).
In Station AP mode, when the station port has an active connection, the AP port shutdown procedure must not disrupt the station port’s connection.

tkl_wifi_set_cur_channel

OPERATE_RET tkl_wifi_set_cur_channel(CONST UCHAR_T chan)

Function description
- Set a channel.
Parameter

Input/Output Parameter Description

[in] chan The channel.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_CHAN_SET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	chan	The channel.

Setting a channel outside the current country code’s regulatory domain shall result in operation failure.
You can set the channel in the sniffer callback.

tkl_wifi_get_cur_channel

OPERATE_RET tkl_wifi_get_cur_channel(UCHAR_T *chan);

Function description
- Get the current channel.
Parameter

Input/Output Parameter Description

[out] chan The channel.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_CHAN_GET_FAILED: Failure.

Input/Output	Parameter	Description
[out]	chan	The channel.

tkl_wifi_set_sniffer

OPERATE_RET tkl_wifi_set_sniffer(CONST BOOL_T en, CONST SNIFFER_CALLBACK cb)

Function description
- Turn the sniffer on or off.
Parameter

Input/Output Parameter Description

[in] en Turn the sniffer on or off.

[in] cb The packet capture data callback.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_SNIFFER_SET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	en	Turn the sniffer on or off.
[in]	cb	The packet capture data callback.

The data returned to the application includes management pack data.

tkl_wifi_get_ip

OPERATE_RET tkl_wifi_get_ip(CONST WF_IF_E wf, NW_IP_S *ip)

Function description
- Get the IP address of the Wi-Fi network interface, including IP address, gateway address, and address mask.
Parameter
Input/Output Parameter Description
[in]

wf
The Wi-Fi mode.
WF_STATION
WF_AP
[out] ip The IP address.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_IP_GET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	wf	The Wi-Fi mode. `WF_STATION` `WF_AP`
[out]	ip	The IP address.

IP address configuration must be differentiated based on the Wi-Fi operation mode specified in the input parameters.

tkl_wifi_set_ip

OPERATE_RET tkl_wifi_set_ip(CONST WF_IF_E wf, NW_IP_S *ip)

Function description
- Set the static IP address of the Wi-Fi network interface, including IP address, gateway address, and address mask.
Parameter
Input/Output Parameter Description
[in]

wf
The Wi-Fi mode.
WF_STATION
WF_AP
[in] ip The IP address.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_IP_GET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	wf	The Wi-Fi mode. `WF_STATION` `WF_AP`
[in]	ip	The IP address.

IP address configuration must be differentiated based on the Wi-Fi operation mode specified in the input parameters.

tkl_wifi_set_mac

OPERATE_RET tkl_wifi_set_mac(CONST WF_IF_E wf, CONST NW_MAC_S *mac)

Function description
- Set the MAC address.
Parameter
Input/Output Parameter Description
[in]

wf
The Wi-Fi mode.
WF_STATION
WF_AP
[in] mac The MAC address.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_MAC_SET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	wf	The Wi-Fi mode. `WF_STATION` `WF_AP`
[in]	mac	The MAC address.

This configuration shall be permanently stored and persist after power cycles.

tkl_wifi_get_mac

OPERATE_RET tkl_wifi_get_mac(CONST WF_IF_E wf, NW_MAC_S *mac);

Function description
- Get the MAC address.
Parameter
Input/Output Parameter Description
[in]

wf
The Wi-Fi mode.
WF_STATION
WF_AP
[out] mac The MAC address.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_MAC_GET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	wf	The Wi-Fi mode. `WF_STATION` `WF_AP`
[out]	mac	The MAC address.

In StationAP mode, the MAC address allocation shall be differentiated based on the Wi-Fi operation mode specified in the input parameters.

tkl_wifi_set_work_mode

OPERATE_RET tkl_wifi_set_work_mode(CONST WF_WK_MD_E mode)

Function description
- Set the operation mode of the Wi-Fi network.
Parameter
Input/Output Parameter Description
[in]

mode
The Wi-Fi operation mode.
WWM_LOWPOWER: Turn off the Wi-Fi module
WWM_SNIFFER
WWM_STATION
WWM_SOFTAP
WWM_STATIONAP
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_WORKMODE_SET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	mode	The Wi-Fi operation mode. `WWM_LOWPOWER`: Turn off the Wi-Fi module `WWM_SNIFFER` `WWM_STATION` `WWM_SOFTAP` `WWM_STATIONAP`

The interval from powering on the device to invoking Tuya’s entry function void tuya_app_main(void) shall not exceed 200 milliseconds.
If device initialization takes more than 200 milliseconds, the underlying system can perform only essential initializations and invoke Tuya’s entry function. Then, move the time-consuming Wi-Fi initialization to another thread.
tuya_hal_wifi_set_work_mode is the first Wi-Fi-related API called by Tuya services. It verifies whether Wi-Fi initialization is completed. If initialization is incomplete, the function must block until completion is confirmed (single verification required).
If the device completes power-on to Tuya’s entry function invocation within 200 milliseconds, this requirement can be disregarded.

tkl_wifi_get_work_mode

OPERATE_RET tkl_wifi_get_work_mode(WF_WK_MD_E *mode)

Function description
- Get the operating mode of the Wi-Fi network.
Parameter
Input/Output Parameter Description
[out]

mode
The Wi-Fi operation mode.
WWM_LOWPOWER: Turn off the Wi-Fi module
WWM_SNIFFER
WWM_STATION
WWM_SOFTAP
WWM_STATIONAP
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_WORKMODE_GET_FAILED: Failure.

Input/Output	Parameter	Description
[out]	mode	The Wi-Fi operation mode. `WWM_LOWPOWER`: Turn off the Wi-Fi module `WWM_SNIFFER` `WWM_STATION` `WWM_SOFTAP` `WWM_STATIONAP`

tkl_wifi_get_connected_ap_info

OPERATE_RET tkl_wifi_get_connected_ap_info(FAST_WF_CONNECTED_AP_INFO_T **fast_ap_info)

Function description
- Get the connected AP’s information for Wi-Fi Easy Connect functionality.
Parameter

Input/Output Parameter Description

[out] fast_ap_info The information about the connected AP.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_APINFO_GET_FAILED: Failure.

Input/Output	Parameter	Description
[out]	fast_ap_info	The information about the connected AP.

fast_ap_info shall dynamically allocate memory within this API.
Router information shall be acquired after every successful reconnection, with updates synchronized to flash storage.

tkl_wifi_get_bssid

OPERATE_RET tkl_wifi_get_bssid(UCHAR_T *mac)

Function description
- Get the MAC address of the connected AP.
Parameter

Input/Output Parameter Description

[out] mac The MAC address.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_BSSID_GET_FAILED: Failure.

Input/Output	Parameter	Description
[out]	mac	The MAC address.

tkl_wifi_set_country_code

OPERATE_RET tkl_wifi_set_country_code(CONST COUNTRY_CODE_E ccode)

Function description
- Set the country code.

Parameter

Input/Output	Parameter	Description
[in]	ccode	The country code. Valid values: `COUNTRY_CODE_CN`: China, channels 1 to 13 `COUNTRY_CODE_US`: The United States, channels 1 to 11 `COUNTRY_CODE_JP`: Japan, channels 1 to 14 `COUNTRY_CODE_EU`: Europe, channels 1 to 13

Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_CCODE_SET_FAILED: Failure.

Currently, the country code implementation shall support China (CN 1 to 13), the United States (US 1 to 11), Japan (JP 1 to 14), and Europe (EU 1 to 13).
Meet the following country-specific compliance requirements:
- During router scanning, only APs broadcasting on channels within the country code’s authorized channel list shall be detectable.
- The adaptive feature shall be implemented in the European region.
- Attempting to set a channel outside the current country code’s permitted range will return an error.

tkl_wifi_set_rf_calibrated

OPERATE_RET tkl_wifi_set_rf_calibrated(VOID_T);

Function description
- Check whether the RF is calibrated.
Return value
true: The RF is calibrated.
false: The RF is not calibrated.

tkl_wifi_set_lp_mode

OPERATE_RET tkl_wifi_set_lp_mode(CONST BOOL_T enable, CONST UCHAR_T dtim)

Function description
- Set the low power mode of the Wi-Fi network.
Parameter

Input/Output Parameter Description

[in] enable Specifies whether to enable the low power mode of the Wi-Fi.

[in] dtim The delivery traffic indication map (DTIM) parameter.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_WF_LPMODE_SET_FAILED: Failure.

Input/Output	Parameter	Description
[in]	enable	Specifies whether to enable the low power mode of the Wi-Fi.
[in]	dtim	The delivery traffic indication map (DTIM) parameter.

tkl_wifi_station_fast_connect

OPERATE_RET tkl_wifi_station_fast_connect(CONST FAST_WF_CONNECTED_AP_INFO_T *fast_ap_info)

Function description
- Connect to a router quickly.
Parameter

Input/Output Parameter Description

[in] fast_ap_info The information about the AP required for Wi-Fi Easy Connect.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_FAST_CONN_FAILED: Failure.

Input/Output	Parameter	Description
[in]	fast_ap_info	The information about the AP required for Wi-Fi Easy Connect.

This function shall only be invoked during the first connection attempt after pairing and restart.

tkl_wifi_station_connect

OPERATE_RET tkl_wifi_station_connect(CONST SCHAR_T *ssid, CONST SCHAR_T *passwd)

Function description
- Connect to a router.
Parameter

Input/Output Parameter Description

[in] ssid The SSID of the wireless network.

[in] passwd The password.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_CONN_FAILED: Failure.

Input/Output	Parameter	Description
[in]	ssid	The SSID of the wireless network.
[in]	passwd	The password.

This is a non-blocking interface. After the connection process is successfully started, the application will call tuya_hal_wifi_station_get_status every 1s to query the Wi-Fi connection status.
The auto-reconnect feature shall be enabled with a reconnection interval of ≤1 minute. The application will initiate reconnection attempts every 1 minute during disconnection states.

tkl_wifi_station_disconnect

OPERATE_RET tkl_wifi_station_disconnect(VOID_T)

Function description
- Disconnect from a router.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_DISCONN_FAILED: Failure.

tkl_wifi_station_get_conn_ap_rssi

OPERATE_RET tkl_wifi_station_get_conn_ap_rssi(SCHAR_T *rssi)

Function description

Get the signal strength of the connected AP.
Parameter

Input/Output Parameter Description

[out] rssi The signal strength.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_RSSI_GET_FAILED: Failure.

Input/Output	Parameter	Description
[out]	rssi	The signal strength.

If the location of the device and router is not changed, obtaining RSSI multiple times will only result in small fluctuations.
If the location of the device and router is changed, the RSSI obtained will change accordingly.

tkl_wifi_station_get_status

OPERATE_RET tkl_wifi_station_get_status(WF_STATION_STAT_E *stat)

Function description
- Get the current Wi-Fi connection status.
Parameter
Input/Output Parameter Description
[out]

stat
The connection status. Valid values:
WSS_IDLE
WSS_CONNECTING
WSS_PASSWD_WRONG
WSS_CONN_FAIL
WSS_CONN_SUCCESS
WSS_GOT_IP
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_STAT_GET_FAILED: Failure.

Input/Output	Parameter	Description
[out]	stat	The connection status. Valid values: `WSS_IDLE` `WSS_CONNECTING` `WSS_PASSWD_WRONG` `WSS_CONN_FAIL` `WSS_CONN_SUCCESS` `WSS_GOT_IP`

tkl_wifi_send_mgnt

OPERATE_RET tkl_wifi_send_mgnt(CONST UCHAR_T *buf, CONST UINT_T len)

Function description
- Send the management pack data.
Parameter

Input/Output Parameter Description

[in] buf The data buffer of the management pack.

[in] len The data length of the management pack.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_MGNT_SEND_FAILED: Failure.

Input/Output	Parameter	Description
[in]	buf	The data buffer of the management pack.
[in]	len	The data length of the management pack.

tkl_wifi_register_recv_mgnt_callback

OPERATE_RET tkl_wifi_register_recv_mgnt_callback(CONST BOOL_T enable, CONST WIFI_REV_MGNT_CB recv_cb)

Function description
- Specifies whether the application layer receives management pack data.
Parameter

Input/Output Parameter Description

[in] enable Specifies whether to enable receiving management pack data.

[in] recv_cb The callback for receiving management pack data.
Return value
- OPRT_OS_ADAPTER_OK: Success.
- OPRT_OS_ADAPTER_MGNT_REG_FAILED: Failure.

Input/Output	Parameter	Description
[in]	enable	Specifies whether to enable receiving management pack data.
[in]	recv_cb	The callback for receiving management pack data.

Prev DocGPIO

Next DocType Development Kit