Wi-Fi APIs

API Reference

Functions

OSStatus bk_wlan_set_country(const wifi_country_t *country)

configure country info

Attention

  1. The default country is {.cc=”CN”, .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO}

  2. When the country policy is WIFI_COUNTRY_POLICY_AUTO, the country info of the AP to which the station is connected is used. E.g. if the configured country info is {.cc=”USA”, .schan=1, .nchan=11} and the country info of the AP to which the station is connected is {.cc=”JP”, .schan=1, .nchan=14} then the country info that will be used is {.cc=”JP”, .schan=1, .nchan=14}. If the station disconnected from the AP the country info is set back back to the country info of the station automatically, {.cc=”USA”, .schan=1, .nchan=11} in the example.

  3. When the country policy is WIFI_COUNTRY_POLICY_MANUAL, always use the configured country info.

  4. When the country info is changed because of configuration or because the station connects to a different external AP, the country IE in probe response/beacon of the soft-AP is changed also.

  5. The country configuration is not stored into flash

  6. This API doesn’t validate the per-country rules, it’s up to the user to fill in all fields according to local regulations.

Return

  • kNoErr: succeed

  • kNotInitializedErr: WiFi is not initialized

  • kParamErr: invalid argument

Parameters

  • country: the configured country info

OSStatus bk_wlan_get_country(wifi_country_t *country)

get the current country info

Return

  • kNoErr: succeed

  • kNotInitializedErr: WiFi is not initialized

  • kParamErr: invalid argument

Parameters

  • country: country info

OSStatus bk_wlan_start(network_InitTypeDef_st *inNetworkInitPara)

Connect or establish a Wi-Fi network in normal mode (station or soft ap mode).

User example: 

//start a soft_AP 
 network_InitTypeDef_st wNetConfig;
 os_memset(&wNetConfig, 0x0, sizeof(network_InitTypeDef_st));
 ssid_len = os_strlen(ap_ssid);
 key_len = os_strlen(ap_key);
 os_strcpy((char *)wNetConfig.wifi_ssid, ap_ssid);
 os_strcpy((char *)wNetConfig.wifi_key, ap_key);
 wNetConfig.wifi_mode = BK_SOFT_AP;
 wNetConfig.dhcp_mode = DHCP_SERVER;
 wNetConfig.wifi_retry_interval = 100;
 os_strcpy((char *)wNetConfig.local_ip_addr, WLAN_DEFAULT_IP);
 os_strcpy((char *)wNetConfig.net_mask, WLAN_DEFAULT_MASK);
 os_strcpy((char *)wNetConfig.gateway_ip_addr, WLAN_DEFAULT_GW);
 os_strcpy((char *)wNetConfig.dns_server_ip_addr, WLAN_DEFAULT_GW);
 bk_wlan_ap_set_default_channel(channel);
 bk_printf("ssid:%s  key:%s\r\n", wNetConfig.wifi_ssid, wNetConfig.wifi_key);
 bk_wlan_start(&wNetConfig);

 //start a STA mode,connect the targe AP
 network_InitTypeDef_st wNetConfig;
 int ssid_len, key_len;
 os_memset(&wNetConfig, 0x0, sizeof(network_InitTypeDef_st));
 ssid_len = os_strlen(oob_ssid);
 key_len = os_strlen(connect_key);
 os_strlcpy((char *)wNetConfig.wifi_ssid, oob_ssid, sizeof(wNetConfig.wifi_ssid));
 os_strlcpy((char *)wNetConfig.wifi_key, connect_key, sizeof(wNetConfig.wifi_key));
 wNetConfig.wifi_mode = BK_STATION;
 wNetConfig.dhcp_mode = DHCP_CLIENT;
 wNetConfig.wifi_retry_interval = 100;
 bk_printf("ssid:%s key:%s\r\n", wNetConfig.wifi_ssid, wNetConfig.wifi_key);
 bk_wlan_start(&wNetConfig);
Attention

  1. This function can establish a Wi-Fi connection as a station or create a soft AP that other staions can connect (2 stations Max).

  2. In station mode,BK first scan all of the supported Wi-Fi channels to find a wlan that matchs the input SSID, and read the security mode. Then try to connect to the target wlan. If any error occurs in the connection procedure or disconnected after a successful connection, BK start the reconnection procedure in backgound after a time interval defined in inNetworkInitPara.

  3. Call this function twice when setup coexistence mode (staion + soft ap). This function retruns immediately in station mode, and the connection will be executed in background.

Return

  • kNoErr :succeed

  • others: other errors.

Parameters

  • inNetworkInitPara:: Specifies wlan parameters.

int bk_wlan_stop(char mode)

disconect and stop WiFi in sta/ap mode

Return

  • kNoErr :succeed

  • others: other errors.

Parameters

  • mode:: Specifies wlan interface.

    • Soft_AP: soft-ap mode

    • Station: sta mode

OSStatus bk_wlan_start_sta_adv(network_InitTypeDef_adv_st *inNetworkInitParaAdv)

Connect to a Wi-Fi network with advantage settings (station mode only)

Attention

  1. This function can connect to an access point with precise settings, that greatly speed up the connection if the input settings are correct and fixed. If this fast connection is failed for some reason, BK change back to normal: scan + connect mode refer to bkWlanStart. This function returns after the fast connection try.

  2. This function cannot establish a soft ap, use StartNetwork() for this purpose. If input SSID length is 0, BK use BSSID to connect the target wlan. If both SSID and BSSID are all wrong, the connection will be failed. User example: 

    network_InitTypeDef_adv_st  wNetConfigAdv;
 os_memset( &wNetConfigAdv, 0x0, sizeof(network_InitTypeDef_adv_st) );
 os_strcpy((char*)wNetConfigAdv.ap_info.ssid, oob_ssid);
 hwaddr_aton("48:ee:0c:48:93:12", (u8 *)(wNetConfigAdv.ap_info.bssid));
 wNetConfigAdv.ap_info.security = BK_SECURITY_TYPE_WPA2_MIXED;
 wNetConfigAdv.ap_info.channel = 11;
 os_strcpy((char*)wNetConfigAdv.key, connect_key);
 wNetConfigAdv.key_len = os_strlen(connect_key);
 wNetConfigAdv.dhcp_mode = DHCP_CLIENT;
 wNetConfigAdv.wifi_retry_interval = 100;
 bk_wlan_start_sta_adv(&wNetConfigAdv);

Return

  • kNoErr :succeed

  • others: other errors.

Parameters

  • inNetworkInitParaAdv:: Specifies the precise wlan parameters.

OSStatus bk_wlan_get_ip_status(IPStatusTypedef *outNetpara, WiFi_Interface inInterface)

Read current IP status on a network interface.

Return

  • kNoErr :succeed

  • others: other errors.

Parameters

  • outNetpara:: Point to the buffer to store the IP address.

    • inInterface: Specifies wlan interface.

      • Soft_AP: The soft AP that established by bk_wlan_start()

      • Station: The interface that connected to an access point

OSStatus bk_wlan_get_link_status(LinkStatusTypeDef *outStatus)

Read current wireless link status on station interface.

Return

  • kNoErr : on success.

  • kGeneralErr : if an error occurred

Parameters

  • outStatus:: Point to the buffer to store the link status.

int wlan_ap_sta_info(wlan_ap_stas_t *stas)

Get the information of connected stations.

Return

0 on success, -1 on failure

Parameters

  • stas: Pointer to the stations information

void bk_wlan_ap_para_info_get(network_InitTypeDef_ap_st *ap_info)

Read current wireless link status on soft-AP interface.

Return

  • kNoErr : on success.

  • kGeneralErr : if an error occurred

Parameters

  • ap_info:: Point to the buffer to AP info.

OSStatus bk_wlan_ap_is_up(void)

whether the AP status is power on

Return

  • 0 : AP is working.

  • others : AP is not started.

Parameters

  • void:

OSStatus bk_wlan_sta_is_connected(void)

as sta mode,whether the status is connected to the AP

Return

  • 0 : AP is working.

  • others : AP is not started.

Parameters

  • void:

void bk_wlan_ap_set_default_channel(uint8_t channel)

in soft-ap mode,set the channel for soft-ap

Return

  • void

Parameters

  • channel: the channel for soft-ap

void bk_wlan_scan_ap_reg_cb(FUNC_2PARAM_PTR ind_cb)

Register wifi scan event notification callback.

Attention

  1. you must regist it before bk_wlan_start_scan, otherwise you cant get scan done event

Return

  • void

Parameters

  • ind_cb:: scan done event callback

int wlan_sta_scan_result(ScanResult_adv *results)

ger wifi scan results

Attention

  1. you must use it after scan done event, otherwise you will get nothing

Return

  • void

Parameters

  • results:: scan results

void bk_wlan_start_scan(void)

Start a wlan scanning in 2.4GHz in BK backfround.

void (*function)((void *ctxt, uint8_t param)) Register callback function using mhdr_scanu_reg_cb(scan_cb, 0) before scan.

Attention

Once the scan is completed, BK sends a notify with callback function:

User example: 

 static const char *crypto_str[] = {
    "None",
    "WEP",
    "WPA_TKIP",
    "WPA_AES",
    "WPA_MIXED",
    "WPA2_TKIP",
    "WPA2_AES",
    "WPA2_MIXED",   
    "WPA3_SAE",        
    "WPA3_WPA2_MIXED", 
    "EAP",
    "OWE",
    "AUTO",
};
 static void scan_cb(void *ctxt, uint8_t param)
 {
     ScanResult_adv apList;
     if (bk_wlan_ap_is_up() > 0)
         ret = wlan_ap_scan_result(&apList);
     else
         ret = wlan_sta_scan_result(&apList);

     if (!ret) {
         int ap_num = apList.ApNum;
         int i;

         bk_printf("Got ap count: %d\r\n", apList.ApNum);
         for (i = 0; i < ap_num; i++)
             bk_printf("    \"%s\", %02x:%02x:%02x:%02x:%02x:%02x, %d, %s, %d\n",
                     apList.ApList[i].ssid, MAC2STR(apList.ApList[i].bssid),
                     apList.ApList[i].ApPower, crypto_str[apList.ApList[i].security],
                     apList.ApList[i].channel);
         os_free(apList.ApList);
     }
 }
  
 bk_wlan_scan_ap_reg_cb(scan_cb);
 bk_wlan_start_scan();
Return

  • void

Parameters

  • void:

void bk_wlan_start_assign_scan(UINT8 **ssid_ary, UINT8 ssid_num)

Start a wlan scanning ,which scan the target AP.

Return

  • void

Parameters

  • ssid_ary: Point to the ssids list you want to scan

    • ssid_num number of ssids

void bk_wlan_set_monitor_filter(unsigned char filter)

set filter flag in monitor mode

Return

  • void

Parameters

  • filter:

    • bit0:1:mulicast_brdcast is not filte

    • bit1:1: duplicate frame is not filte

void bk_wlan_register_monitor_cb(monitor_cb_t fn)

Register wifi monitor event notification callback.

Attention

  1. you must regist it before bk_wlan_start_monitor, otherwise you cant get monitor frame

Return

  • void

Parameters

  • fn:: monitor data event callback

int bk_wlan_start_monitor(void)

Start wifi monitor mode.

User example: 

void bk_demo_monitor_cb(uint8_t *data, int len, wifi_link_info_t *info)
{
   //the frame data of monitor
}

bk_wlan_register_monitor_cb(bk_demo_monitor_cb);
bk_wlan_start_monitor();
Attention

  1. This function disconnect wifi station,can coexit with AP mode

Return

  • void

Parameters

  • void:

int bk_wlan_stop_monitor(void)

Stop wifi monitor mode.

Return

  • void

Parameters

  • void:

int bk_wlan_set_channel(int channel)

Set channel at the asynchronous method.

Attention

  1. This function change the monitor channel (from 1~13).

  2. it can change the channel dynamically, don’t need restart monitor mode.

Return

  • 0 : success

  • others : failed.

Parameters

  • channel: set the monitor channel

int bk_wlan_is_monitor_mode(void)

whether the monitor mode is power on

Return

  • 0 : monitor is working.

  • others : monitor is not started.

Parameters

  • void:

int bk_wlan_send_80211_raw_frame(uint8_t *buffer, int len)

Send raw 802.11 frame.

Attention

  1. This API can be used in WiFi station, softap, or monitor mode.

  2. Only support to send non-QoS frame.

  3. The frame sequence will be overwritten by WiFi driver.

  4. The API doesn’t check the correctness of the raw frame, the caller need to guarantee the correctness of the frame.

Return

  • 0 : success.

  • others : failed.

Parameters

  • buffer: : the buffer of tx frame

    • len : len of frame data

int bk_wlan_send_raw_frame_with_cb(uint8_t *buffer, int len, void *cb, void *param)

Send raw 802.11 frame and register tx result notoify.

Attention

  1. This API can be used in WiFi station, softap, or monitor mode.

  2. Only support to send non-QoS frame.

  3. The frame sequence will be overwritten by WiFi driver.

  4. after tx done,will notify the result of tx

Return

  • 0 : success.

  • others : failed.

Parameters

  • buffer: : the buffer of tx frame

    • len : len of frame data

    • cb : callback of tx done

    • param : param of tx frame,normally set NULL