Skip to main content

TAL Wi-Fi API Reference

The TAL Wi-Fi API (tal_wifi.h) provides a platform-independent interface for Wi-Fi station and AP operations. It wraps the TKL Wi-Fi adapter, which in turn calls the platform's Wi-Fi driver (ESP-IDF, T5AI SDK, Linux, etc.).

Header: #include "tal_wifi.h"

Initializationโ€‹

tal_wifi_initโ€‹

Initialize the Wi-Fi subsystem and register the event callback.

OPERATE_RET tal_wifi_init(WIFI_EVENT_CB cb);
ParameterDirectionTypeDescription
cbinWIFI_EVENT_CBCallback invoked on Wi-Fi events (connect, disconnect, IP obtained)

Return: OPRT_OK on success.

Call this once at startup before any other Wi-Fi operation.

Scanningโ€‹

tal_wifi_all_ap_scanโ€‹

Scan all visible access points.

OPERATE_RET tal_wifi_all_ap_scan(AP_IF_S **ap_ary, uint32_t *num);
ParameterDirectionTypeDescription
ap_aryoutAP_IF_S **Pointer to the AP info array (allocated by the function)
numoutuint32_t *Number of APs found

Return: OPRT_OK on success. Caller must free the result with tal_wifi_release_ap().

tal_wifi_assign_ap_scanโ€‹

Scan for a specific SSID.

OPERATE_RET tal_wifi_assign_ap_scan(int8_t *ssid, AP_IF_S **ap);

tal_wifi_release_apโ€‹

Free the memory allocated by scan functions.

OPERATE_RET tal_wifi_release_ap(AP_IF_S *ap);

Station Connectionโ€‹

tal_wifi_station_connectโ€‹

Connect to an access point.

OPERATE_RET tal_wifi_station_connect(int8_t *ssid, int8_t *passwd);
ParameterDirectionTypeDescription
ssidinint8_t *SSID to connect to
passwdinint8_t *Password (NULL or empty for open networks)

tal_wifi_station_disconnectโ€‹

Disconnect from the current access point.

OPERATE_RET tal_wifi_station_disconnect(void);

tal_fast_station_connectโ€‹

Reconnect using cached AP info (channel, BSSID) to skip scanning.

OPERATE_RET tal_fast_station_connect(FAST_WF_CONNECTED_AP_INFO_T *fast_ap_info);

tal_wifi_get_connected_ap_infoโ€‹

Get cached AP info for subsequent fast connects.

OPERATE_RET tal_wifi_get_connected_ap_info(FAST_WF_CONNECTED_AP_INFO_T **fast_ap_info);

tal_wifi_station_get_statusโ€‹

Get current station connection status.

OPERATE_RET tal_wifi_station_get_status(WF_STATION_STAT_E *stat);

Status values include: WSS_IDLE, WSS_CONNECTING, WSS_PASSWD_WRONG, WSS_NO_AP_FOUND, WSS_CONN_FAIL, WSS_CONN_SUCCESS, WSS_GOT_IP.

tal_wifi_station_get_conn_ap_rssiโ€‹

Get signal strength of the connected AP.

OPERATE_RET tal_wifi_station_get_conn_ap_rssi(int8_t *rssi);

Returns RSSI in dBm (negative value; e.g., -45 is strong, -80 is weak).

tal_wifi_station_get_err_statโ€‹

Get error status after a failed connection attempt.

OPERATE_RET tal_wifi_station_get_err_stat(WF_STATION_STAT_E *stat);

Soft APโ€‹

tal_wifi_ap_startโ€‹

Start a soft access point.

OPERATE_RET tal_wifi_ap_start(WF_AP_CFG_IF_S *cfg);

The config struct includes SSID, password, channel, encryption type, and max stations.

:::note ESP32 Limitation tal_wifi_ap_stop() on ESP32 is currently incomplete (returns OPRT_OK but does not fully tear down the AP). Switching from AP to STA mode may require a device restart. :::

tal_wifi_ap_stopโ€‹

Stop the soft access point.

OPERATE_RET tal_wifi_ap_stop(void);

Network Configurationโ€‹

tal_wifi_get_ip / tal_wifi_set_ipโ€‹

Get or set the IP configuration for station or AP interface.

OPERATE_RET tal_wifi_get_ip(WF_IF_E wf, NW_IP_S *ip);
OPERATE_RET tal_wifi_set_ip(WF_IF_E wf, NW_IP_S *ip);

WF_IF_E is WF_STATION or WF_AP. NW_IP_S contains ip, mask, gw as strings.

tal_wifi_get_mac / tal_wifi_set_macโ€‹

Get or set the MAC address.

OPERATE_RET tal_wifi_get_mac(WF_IF_E wf, NW_MAC_S *mac);
OPERATE_RET tal_wifi_set_mac(WF_IF_E wf, NW_MAC_S *mac);

tal_wifi_get_bssidโ€‹

Get the BSSID of the connected AP.

OPERATE_RET tal_wifi_get_bssid(uint8_t *mac);

:::warning ESP32 On ESP32, this function may return OPRT_OK without filling the buffer. Verify the output. :::

Channel and Modeโ€‹

tal_wifi_set_cur_channel / tal_wifi_get_cur_channelโ€‹

OPERATE_RET tal_wifi_set_cur_channel(uint8_t chan);
OPERATE_RET tal_wifi_get_cur_channel(uint8_t *chan);

tal_wifi_set_work_mode / tal_wifi_get_work_modeโ€‹

OPERATE_RET tal_wifi_set_work_mode(WF_WK_MD_E mode);
OPERATE_RET tal_wifi_get_work_mode(WF_WK_MD_E *mode);

Modes: WWM_STATION, WWM_SOFTAP, WWM_STATIONAP.

tal_wifi_set_country_codeโ€‹

Set the Wi-Fi regulatory country code.

OPERATE_RET tal_wifi_set_country_code(char *country_code);

Supported: "CN", "US", "JP", "EU".

Sniffer Modeโ€‹

tal_wifi_sniffer_setโ€‹

Enable or disable promiscuous (sniffer) mode.

OPERATE_RET tal_wifi_sniffer_set(BOOL_T en, SNIFFER_CALLBACK cb);

When enabled, raw 802.11 frames are delivered to the callback. Used for Tuya's SmartConfig provisioning.

Management Framesโ€‹

tal_wifi_send_mgntโ€‹

Send a raw management frame.

OPERATE_RET tal_wifi_send_mgnt(uint8_t *buf, uint32_t len);

tal_wifi_register_recv_mgnt_callbackโ€‹

Register a callback for received management frames.

OPERATE_RET tal_wifi_register_recv_mgnt_callback(BOOL_T enable, WIFI_REV_MGNT_CB recv_cb);

Power Managementโ€‹

tal_wifi_lp_enable / tal_wifi_lp_disableโ€‹

Enable or disable Wi-Fi low-power mode.

OPERATE_RET tal_wifi_lp_enable(void);
OPERATE_RET tal_wifi_lp_disable(void);

tal_wifi_set_lps_dtimโ€‹

Set the DTIM interval for low-power mode.

void tal_wifi_set_lps_dtim(uint32_t dtim);

Call before entering low-power mode.

Otherโ€‹

tal_wifi_rf_calibratedโ€‹

Check if Wi-Fi RF calibration has been performed.

BOOL_T tal_wifi_rf_calibrated(void);

tal_wifi_ioctlโ€‹

Platform-specific Wi-Fi control.

OPERATE_RET tal_wifi_ioctl(WF_IOCTL_CMD_E cmd, void *args);
note

Returns OPRT_NOT_SUPPORTED on ESP32.

Usage Exampleโ€‹

#include "tal_wifi.h"
#include "tal_log.h"

static void wifi_event_cb(void *arg)
{
    WF_STATION_STAT_E stat;
    tal_wifi_station_get_status(&stat);
    if (stat == WSS_GOT_IP) {
        NW_IP_S ip;
        tal_wifi_get_ip(WF_STATION, &ip);
        TAL_PR_INFO("connected, IP: %s", ip.ip);
    }
}

void connect(void)
{
    tal_wifi_init(wifi_event_cb);
    tal_wifi_station_connect((int8_t *)"MySSID", (int8_t *)"MyPassword");
}

Referencesโ€‹