Wi-Fi APIs
Important
The WiFi API v2.0 is the lastest stable WiFi APIs, it’s used to deprecate the WiFi API v1.0. All new applications should use WiFi API v2.0.
Wi-Fi Interface
The BK WiFi Driver supports following logical WiFi interfaces:
BK STA interface
BK AP interface
BK Monitor interface
Each interface can be operated independently, so theretically all interfaces can be started independently. However because of performance and interference consideration, we limit the coexisting of some interfaces.
E.g. if the monitor interface is started, the starting of STA interface will fail, refer to API for detailed limitation of interface coexisting.
Wi-Fi API Categories
Most of WiFi APIs can be categoried as:
Common APIs
The common APIs are prefixed with bk_wifi, the APIs may be common for all interfaces or some interfaces, e.g. bk_wifi_init() etc.
Interface specific APIs.
The API name are prefixed with bk_wifi_interface, the interface can be sta, ap or monitor. e.g. bk_wifi_sta_start() etc.
Module specific APIs
The API name are prefixed with bk_wifi_module, the module can be scan or filter etc, e.g. bk_wifi_scan_start() etc. The API has no direct relationship with the interface, or the API caller don’t nedto care about on which interface the API is operated. E.g. the scan API can be based on STA interface, it can also based on AP interface, but the caller don’t care about it.
- Common WiFi APIs:
bk_wifi_init()
- init WiFibk_wifi_deinit()
- deinit WiFibk_wifi_set_country()
- set country codebk_wifi_get_country()
- get country codebk_wifi_send_raw()
- send raw 802.11 frame
- Interface specific WiFi APIs:
bk_wifi_sta_start()
- start BK STAbk_wifi_sta_stop()
- stop BK STAbk_wifi_sta_set_config()
- set basic configurations BK STA, such as SSID etcbk_wifi_sta_get_config()
- get basic configuration of BK STAbk_wifi_sta_get_linkstate_with_reason()
- get actual link status of BK STA and reason codebk_wifi_sta_get_link_status()
- get link status of BK STAbk_wifi_sta_connect()
- connect the BK STA to APbk_wifi_sta_disconnect()
- disconnect the Wi-Fi connectionbk_wifi_sta_pm_enable()
- enable STA power managementbk_wifi_sta_pm_disable()
- disable STA power managementbk_wifi_get_channel()
- get current channel IDbk_wifi_set_mac_address()
- set Wi-Fi MAC addressbk_wifi_manual_cal_rfcali_status()
- get Wi-Fi Calibration statusbk_wifi_ap_start()
- start BK APbk_wifi_ap_stop()
- stop BK APbk_wifi_ap_set_config()
- set the basic configuration of BK AP, such as SSID etcbk_wifi_ap_get_config()
- get the basic configuration of BK APbk_wifi_ap_get_sta_list()
- get the STAs connected to BK APbk_wifi_sta_get_mac()
- get STA MAC addressbk_wifi_ap_get_mac()
- get AP MAC addressbk_wifi_monitor_start()
- start the monitorbk_wifi_monitor_stop()
- stop the monitorbk_wifi_monitor_set_config()
- set basic configuration of the monitorbk_wifi_monitor_get_config()
- get basic configuration of the monitorbk_wifi_monitor_register_cb()
- register monitor callback functionbk_wifi_monitor_set_channel()
- set the channel of monitor
- Module Specific WiFi APIs:
bk_wifi_scan_register_cb()
- register scan callback functionbk_wifi_scan_start()
- start the scanbk_wifi_scan_stop()
- stop the scanbk_wifi_scan_get_result()
- get the scan resultbk_wifi_scan_dump_result()
- dump the scan resultbk_wifi_scan_free_result()
- dump the scan resultbk_wifi_filter_set_config()
- set filter configurationbk_wifi_filter_register_cb()
- register the filter callback function
Compitability and Extension
The WiFi APIs are flexible, easy to be extended and backward compatible. For most of the WiFi configurations, we put some reserved fields in the config struct for future extendence. The API users need to make sure the reserved fields are initialized to 0, otherwise the compatibility may be broken as more fields are added.
Programing Principle
Important
- Here is some general principle for WiFi API users:
Always init the reserved fields of config stuct to 0
Use BK_ERR_CHECK to check the return value of the WiFi API
If you are not sure how to use WiFi APIs, study the WiFi example code first
If you are not sure how to initialize some fields of config struct, use the default configuration macro to use the config first and then set application specific fields, e.g. use WIFI_DEFAULT_INIT_CONFIG() to init wifi_config_t first.
Don’t do too much work in WiFi event callback, relay the event to your own application task.
User Development Model
Similar as most popular WiFi driver, the Beken WiFi driver is implemented as event driver. The application call WiFi APIs to operate the WiFi driver and get notified by WiFi event.
API Reference
Header File
Functions
-
bk_err_t bk_wifi_init(const wifi_init_config_t *init_config)
This API initializes the WiFi driver, e.g. creating task for supplicant, allocating resource for low level WiFi driver etc.
Usage example:
wifi_init_config_t init_config = WIFI_DEFAULT_INIT_CONFIG; BK_LOG_ON_ERR(bk_wifi_init(&init_config);
- Attention
1. This API is the 1st API that should be called before any other WiFi API can be called.
2. Make sure the reserved field in config is zero, otherwise you may encounter compatibility issue in future if more config fields are added.
- Returns
BK_OK: succeed
others: other errors.
-
bk_err_t bk_wifi_deinit(void)
Deinit the BK WiFi driver.
This API free all resources related to WiFi.
- Attention
1. This API is not ready yet, will support in future release.
- Returns
BK_OK: succeed
BK_ERR_NOT_SUPPORT: The API is not supported yet.
others: other errors.
-
bk_err_t bk_wifi_sta_start(void)
Start the BK STA.
This API init the resoure specific to BK STA, e.g. init STA specific globals, init the supplicant and STA specific WiFi driver etc.
- Attention
1. Make sure the bk_wifi_sta_set_config() are succeedful before calling this API.
2. This API connect the BK STA to the configured AP automatically.
3. If the BK STA is already started, this API ignores the request and returns BK_OK. if you want to restart the BK STA, call bk_wifi_sta_stop() first and then call this API.
4. TODO description about fast connection
- Returns
BK_OK: succeed
BK_ERR_WIFI_STA_NOT_CONFIG: the BK STA is not configured.
BK_ERR_WIFI_MONITOR_IP: the BK STA can’t be started because monitor is started.
others: other errors.
-
bk_err_t bk_wifi_sta_stop(void)
Stop the BK STA.
- Attention
This API causes the BK STA disconnect from the AP, it similar as bk_wifi_sta_disconnect(), but this API may free resource.
- Returns
BK_OK: succeed
BK_FAIL: fail
-
bk_err_t bk_wifi_scan_stop(void)
Stop the pure scan operation.
- Attention
This API causes the BK STA disconnect from the AP, it similar as bk_wifi_sta_disconnect(), but this API may free resource.
- Returns
BK_OK: succeed
BK_FAIL: fail
-
bk_err_t bk_wifi_sta_set_config(const wifi_sta_config_t *sta_config)
Config the BK STA.
This API configures the basic configurations of the BK STA, it should be called before we call bk_wifi_sta_start() to start the BK STA. It can also be used to update the configuration after the BK STA is started.
Usage example:
wifi_sta_config_t sta_config = WIFI_DEFAULT_STA_CONFIG(); os_strncpy(sta_config.ssid, "ssid", WIFI_SSID_STR_LEN); os_strncpy(sta_config.password, "password"); //more initialization here BK_LOG_ON_ERR(bk_wifi_sta_set_config(&sta_config));
- Attention
1. Don’t call this API when the monitor is in-progress
2. If STA is already connected to AP, this API cases BK STA reconnects the AP.
3. Make sure the reserved fields in sta_config is zero, otherwise you may encounter compatibility issue in future if more config fields are added.
4. Auto reconnect max count and timeout can be set. When user app receives EVENT_WIFI_STA_DISCONNECTED event, it’s user app’s responsibility to reconnect to AP manually. Max count and timeout set to zero to let supplicant automatically handles connection without user app’s interaction.
- Parameters
sta_config – the STA configuration
- Returns
BK_OK: succeed
BK_ERR_STA_NOT_STARTED: the STA is not started, call bk_wifi_sta_start() first.
BK_ERR_NULL_PARAM: parameter config is NULL.
BK_ERR_WIFI_RESERVED_FIELD: the reserved field of config is not 0.
others: other errors
-
bk_err_t bk_wifi_sta_get_config(wifi_sta_config_t *sta_config)
Get the configuration of the BK STA.
- Parameters
sta_config – store the BK STA configuration
- Returns
BK_OK: succeed
BK_ERR_NULL_PARAM: the parameter config is NULL.
BK_ERR_WIFI_STA_NOT_CONFIG: STA is not configured yet.
others: other errors
-
bk_err_t bk_wifi_sta_get_linkstate_with_reason(wifi_linkstate_reason_t *info)
Get the WiFi station state of the BK STA.
If sta is idle or connected, reason code will be WIFI_REASON_MAX
- Attention
the difference between this API and bk_wifi_sta_get_link_status() is
This API gets the actual WiFi STA link status and reason code
- Parameters
state – store the WiFi station state of the BK STA
- Returns
BK_OK: succeed
BK_ERR_NULL_PARAM: the parameter config is NULL.
others: other errors
-
bk_err_t bk_wifi_sta_get_link_status(wifi_link_status_t *link_status)
Get the WiFi link info of the BK STA.
Get the actual WiFi link status of the BK STA.
- Attention
the difference between this API and bk_wifi_sta_get_config() is
This API gets the actual STA link info while the later gets the configured value
This API can get more info of the link, such as RSSI, WiFi link status, AID etc.
The AID is only valid if ->state is WIFI_LINK_CONNECTED.
- Parameters
link_status – store the WiFi link status of the BK STA
- Returns
BK_OK: succeed
BK_ERR_NULL_PARAM: the parameter link_info is NULL.
BK_ERR_WIFI_DRIVER: WiFi low level driver has failure.
BK_ERR_WIFI_NO_MEM: Not enough memory
others: other errors
-
bk_err_t bk_wifi_sta_connect(void)
Connect the BK STA to the AP.
- Attention
1. Make sure STA is started by bk_wifi_sta_start() before calling this API.
2. Don’t call this API when the monitor is in-progress
3. If STA is already connected to AP, this API reconnects the BK STA.
4. TODO - multiple same SSID connect???
- Returns
BK_OK: succeed
BK_ERR_WIFI_STA_NOT_STARTED: the STA is not started, call bk_wifi_sta_start() first.
BK_ERR_WIFI_MONITOR_IP: the API is not allowed because monitor is in-progress.
others: other failures.
-
bk_err_t bk_wifi_sta_disconnect(void)
Disconnect the WiFi connection of the BK STA.
- Attention
TODO - add description about disconnect event!
- Returns
BK_OK: succeed
others: other failures.
-
bk_err_t bk_wifi_scan_start(const wifi_scan_config_t *scan_config)
Start a scan.
This API notifies the WiFi driver to start a scan, the event EVENT_WIFI_SCAN_DONE will be raised if the scan is completed. General steps to use this API:
prepare the scan done event callback, the callback can call bk_wifi_scan_get_result() to get the scan result and then call bk_wifi_scan_free_result() to free the resource.
call bk_event_register_cb(EVENT_MOD_WIFI, EVENT_WIFI_SCAN_DONE, …) to register scan done event callback.
call this API to trigger this the scan.
Usage example:
//Define your scan done handler int scan_done_handler(void *arg, event_module_t event_module, int event_id, void *event_data) { wifi_scan_result_t scan_result = {0}; BK_LOG_ON_ERR(bk_wifi_scan_get_result(&scan_result)); bk_wifi_scan_dump_result(&scan_result); bk_wifi_scan_free_result(&scan_result); return BK_OK; } //Start the scan wifi_scan_config_t config = {0}; BK_LOG_ON_ERR(bk_event_register_cb(EVENT_MOD_WIFI, EVENT_WIFI_SCAN_DONE, scan_done_handler, NULL)); BK_LOG_ON_ERR(bk_wifi_scan_start(&scan_config));
- Attention
1. This API triggers an active scan on all channels (TODO double check)
2. Pass NULL scan_config to scan all APs, otherwise scan the SSID specified in scan_config.ssid
3. Make sure the reserved fields in scan_config is zero, otherwise you may encounter compatibility issue in future if more config fields are added.
4. TODO scan result limits???
- Parameters
scan_config – the configuration of scan
- Returns
BK_OK: succeed
BK_ERR_WIFI_STA_NOT_STARTED: the STA is not started, call bk_wifi_sta_start() first.
BK_ERR_WIFI_MONITOR_IP: the API is not allowed because monitor is in-progress.
others: other failures.
-
bk_err_t bk_wifi_scan_get_result(wifi_scan_result_t *scan_result)
Get the scan result.
Usage example:
wifi_scan_result_t scan_result = {0}; BK_LOG_ON_ERR(bk_wifi_scan_get_result(&scan_result)); bk_wifi_scan_free_result(&scan_result);
- Attention
1. The caller don’t need to allocate memory for scan_result->aps, this API will allocate the memory for scan_result->aps according to the actual found AP number.
2. Don’t forget to call bk_wifi_scan_free_result(&scan_result) to free the the resource allocated in this API, otherwise memory leak.
- Parameters
scan_result – store the scan result
- Returns
BK_OK: succeed
BK_ERR_NULL_PARAM: NULL scan_result
BK_ERR_NO_MEM: out of memory
others: other failures
-
bk_err_t bk_wifi_scan_dump_result(const wifi_scan_result_t *scan_result)
Dump the scan result.
- Parameters
scan_result – The scan result to be dumped.
- Returns
BK_OK: succeed
BK_ERR_PARAM: invalid scan result
-
void bk_wifi_scan_free_result(wifi_scan_result_t *scan_result)
Free the scan result.
- Attention
This API free scan_result->aps which allocated in bk_wifi_scan_get_result(), it doesn’t free scan_result. So if scan_result is allocated by the caller, the caller need to free it.
- Parameters
scan_result – The scan result to be freed.
- Returns
BK_OK: always succeed
-
bk_err_t bk_wifi_sta_add_vendor_ie(uint8_t frame, uint8_t *vsie, uint8_t len)
Add/Update/Del STA’s Vendor Specific IE before connect to AP.
- Attention
If you want to add vsie when sta starts, just initialize wifi_sta_config_t when call bk_wifi_sta_set_config().
- Parameters
buf – vsie buf
len – vsie buf len
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_ap_start(void)
Start the BK AP.
This API init the resoure specific to BK AP, e.g. init BK AP specific globals, init the hostapd and AP specific WiFi driver etc.
If the BK AP is already started, this API ignores the request and returns BK_OK, we can call bk_wifi_ap_stop() to stop BK AP first and then call bk_wifi_ap_start() to restart it.
Restart AP Usage example:
BK_LOG_ON_ERR(bk_wifi_ap_stop()); BK_LOG_ON_ERR(bk_wifi_ap_start());
- Attention
1. Don’t call this API when the monitor is in-progress
2. If bk_wifi_ap_set_config() is not called, this API start the AP with default value, normally you should configure the AP first before calling this API.
- Returns
BK_OK: succeed
BK_ERR_WIFI_AP_NOT_CONFIGURED: the WiFi AP is not configured, call bk_wifi_ap_set_config() first.
others: other errors
-
bk_err_t bk_wifi_ap_stop(void)
Stop the BK AP.
- Returns
BK_OK: succeed
BK_WIFI_NOT_INIT: the WiFi is not initialized, call bk_wifi_init() first.
others: other errors
-
bk_err_t bk_wifi_ap_set_config(const wifi_ap_config_t *ap_config)
Config the BK AP.
Usage example:
wifi_ap_config_t ap_config = WIFI_DEFAULT_AP_CONFIG(); os_strncpy(ap_config.ssid, "ssid", WIFI_SSID_STR_LEN); os_strncpy(ap_config.password, "password", WIFI_PASSWORD_LEN); BK_LOG_ON_ERR(bk_wifi_ap_set_config(&ap_config));
- Attention
1. Make sure the reserved field in config is zero, otherwise you may encounter compatibility issue in future if more config fields are added.
- Parameters
ap_config – the AP configuration
- Returns
BK_OK: succeed
BK_ERR_NULL_PARAM: the ap_config is NULL.
others: other errors
-
bk_err_t bk_wifi_ap_get_config(wifi_ap_config_t *ap_config)
Get the configuration of the BK AP.
- Parameters
ap_config – store the configuration of BK AP
- Returns
BK_OK: succeed
BK_ERR_NULL_PARAM: the parameter config is NULL.
others: other errors
-
bk_err_t bk_wifi_ap_get_sta_list(wlan_ap_stas_t *stas)
Get the STAs connected to BK AP.
- Attention
Free stas->sta after usage.
- Parameters
stas – store the STA list in BK AP
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_calculate_pmk(const char *ssid, const char *pwd, char *pmk)
Calculate softap’s Pmk when softap is starts.
- Parameters
ssid – softap’s ssid
pwd – softap’s pwd
pmk – softap’s pmk
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_ap_add_vendor_ie(void *buf, uint8_t len)
Add softap’s Vendor Specific IE when softap is running.
- Attention
If you want to add vsie when softap starts, just initialize wifi_ap_config_t when call bk_wifi_ap_start().
- Parameters
buf – vsie buf
len – vsie buf len
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_ap_del_vendor_ie(void)
Delete softap’s Vendor Specific IE when softap is running.
- Attention
If you want to add vsie when softap starts, just initialize wifi_ap_config_t when call bk_wifi_ap_start().
- Returns
BK_OK: succeed
others: other errors
Update softap’s Hidden Ssid Capaility when softap is running.
BK_OK: succeed
others: other errors
- Attention
If you want to update hidden ssid capability when softap starts, just call bk_wifi_ap_update_hidden_cap().
- Parameters
flag – set true for hidden ssid
- Returns
-
bk_err_t bk_wifi_monitor_start(void)
Start the monitor.
- Attention
1. When monitor mode is enabled, the scan will not work and bk_wifi_scan_start() returns BK_ERR_WIFI_MONITOR_IP.
2. When monitor mode is enabled, the STA connect will not work and bk_wifi_sta_connect() returns BK_ERR_WIFI_MONITOR_IP.
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_monitor_set_config(const wifi_monitor_config_t *monitor_config)
Configure the monitor.
- Parameters
monitor_config – the configuration of monitor
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_monitor_get_config(wifi_monitor_config_t *monitor_config)
Get the configuration of the monitor.
- Parameters
monitor_config – store the configuration of monitor
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_monitor_register_cb(const wifi_monitor_cb_t monitor_cb)
Register the user callback of monitor.
- Parameters
monitor_cb – monitor callback
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_monitor_set_channel(const wifi_channel_t *chan)
Set monitor channel.
- Attention
1. Currently we only support HT20, chan->second should always be 0.
2. This API is only used for settting monitor channel, NOT for other purpose.
3. This API directly change the hardware channel, it may impacts BK STA/AP if the STA or AP interface is started. TODO describe details of the impact.
4. The channel range can be set is from channel 1 to channel 14,
- Parameters
chan – channel of monitor
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_twt_setup(uint8_t setup_type, uint16_t mantissa, uint8_t min_twt)
twt set up
- Parameters
setup_type – suggest/demand
mantissa – wake_int_mantissa
min_twt – min_twt_wake_dur
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_filter_set_config(const wifi_filter_config_t *filter_config)
Set the filter configuration.
The filter is used to configure what kind of management packets can be received by the filter callback registered by bk_wifi_filter_register_cb().
Per the WiFi receiving data path, the management frames are firstly received by WiFi hardware, then the hardware relays them to WiFi software (WiFi driver). Normally the hardware receives all management frames in the air, however it don’t relay all of them to WiFi driver (WiFi software), it only relays management frames necessary to STA or AP or scan or monitor, depends on which interface or function are enabled. In other word, WiFi driver only receives management frames necessary to them from hardware.
When no filter callback is registered, all management frame processing is ended in WiFi driver unless the filter callback is registered.
If filter callback is register and if filter_config.rx_all_default_mgmt is set to 1, then all the management frames received by WiFi driver are relayed to the filter callback. Notified that the default management frame types can be received depends on whether STA or AP or scan or monitor are enabled or not, e.g. when only STA is enabled, the WiFi driver needs to handle PROBE response, but don’t need to handle PROBE request, so the WiFi driver only receive PROBE response from WiFi hardware.
Here is summary about default management frame received by WiFi:
How about if the filter callback wants to receive more management frame types, e.g. want to receive PROBE request when only STA is enabled. We can set filter_config->rx_probe_req to receive PROBE response no matter whether AP is enabled or NOT.Condition
Default management frame
STA connected
Management frames sent by the connected AP, such as beacon etc.
AP started
Management frames sent by connected STA and probe request etc.
Scan starting
Probe response and beacon frames of all APs.
Monitor started
All kind of management frames
Usage example:
// Only receive management frame default received by WiFi driver // Equal to the case when bk_wifi_filter_set_config() is not called wifi_filter_config_t filter_config = WIFI_DEFAULT_FILTER_CONFIG(); BK_LOG_ON_ERR(bk_wifi_filter_set_config(&filter_config); // Receive all beacon and management frames default received by WiFi driver filter_config.rx_all_beacon = 1; BK_LOG_ON_ERR(bk_wifi_filter_set_config(&filter_config); // Only receive all beacon filter_config.rx_all_beacon = 1; filter_config.rx_all_default_mgmt = 0; BK_LOG_ON_ERR(bk_wifi_filter_set_config(&filter_config);
- Attention
1. If this API is not called, the default filter is to relay all mamangement frames received by WiFi driver to the filter callback.
2. If STA is enabled, the WiFi driver only receives beacon from the connected AP, if scan is enabled or filter_config->rx_all_beacon is set, the WiFi driver receives beacons of all APs.
- Parameters
filter_config – configuration of filter
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_filter_get_config(wifi_filter_config_t *filter_config)
Get the filter configuration.
- Parameters
filter_config – store configuration of filter
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_filter_register_cb(const wifi_filter_cb_t filter_cb)
Register the filter user callback.
- Attention
1. If the monitor is enabled, the management packets received by filter callback can also be received by monitor callback. If this is not what we want, we can disable filter when enabling monitor, or disable monitor when enabling filter.
2. During WiFi scan, the filter also works.
3. Pass NULL callback or set all fields of filter_config to 0 to disable the filter.
4. The memory used to hold the frame buffer and frame_info will be freed immediately when the callback is returned, so don’t relay them to other task. Make a copy of them and then relay to other task if necessary.
5. Don’t do too much work in the filter callback because it’s called in WiFi driver core thread, otherwise it may impact the WiFi performance.
- Parameters
filter_cb – the filter user callback
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_sta_get_mac(uint8_t *mac)
Get the MAC of BK STA.
- Attention
1. The AP’s MAC is derived from the base MAC of the system.
2. If you want to change the MAC of AP, call bk_set_mac() to set the base MAC of the system.
- Parameters
mac – store the MAC of BK STA
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_ap_get_mac(uint8_t *mac)
Get the MAC of BK AP.
- Attention
1. The AP’s MAC is derived from the base MAC of the system.
2. If you want to change the MAC of AP, call bk_set_mac() to set the base MAC of the system.
- Parameters
mac – store the MAC of BK AP
- Returns
BK_OK: succeed
others: other errors
-
bk_err_t bk_wifi_send_raw(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.
- Parameters
buffer – raw 802.11 frame
len – the length of the 802.11 frame
- Returns
kNoErr: succeed
otherwise: fail
-
bk_err_t bk_wifi_send_raw_ex(wifi_raw_tx_info_t *raw_tx, void *cb, void *param)
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.
- Parameters
raw_tx – : raw tx information, refer to struct wifi_raw_tx_info_t
cb – : send status call back
param – : send status call back paramter
- Returns
kNoErr: succeed
otherwise: fail
-
bk_err_t bk_wifi_set_tx_raw_rate_power(uint32_t rate, uint32_t power)
Update raw 802.11 frame TX rate and power.
- Parameters
rate – : TX rate control
power – : TX power control
- Returns
kNoErr: succeed
otherwise: fail
-
bk_err_t bk_wifi_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.
- Parameters
country – the configured country info
- Returns
BK_OK: succeed
BK_ERR_WIFI_NOT_INIT: WiFi is not initialized
BK_ERR_PARAM: invalid argument
-
bk_err_t bk_wifi_get_country(wifi_country_t *country)
get the current country info
- Parameters
country – country info
- Returns
BK_OK: succeed
BK_ERR_WIFI_NOT_INIT: WiFi is not initialized
BK_ERR_PARAM: invalid argument
-
bk_err_t bk_wifi_sta_pm_enable(void)
enable wifi sta power management
- Returns
BK_OK: on succeed
others: real error, used for future.
-
bk_err_t bk_wifi_sta_pm_disable(void)
disable wifi sta power management
- Returns
BK_OK: on succeed
others: real error, used for future.
-
bk_err_t bk_wifi_get_channel(void)
get current channel ID
- Parameters
basically – range from 1~13
- Returns
BK_OK: on succeed
others: real error, used for future.
-
bk_err_t bk_wifi_set_mac_address(char *mac)
Set Wi-Fi MAC addresses.
The given MAC address will become the station MAC address.The AP MAC address (i.e BSSID) will be the same MAC address but with the local bit set.
example: mac c8478cxxyyzz txevm -e 2 //if needed
Note
on some platforms the change of MAC address can only take effect after reboot.
- Parameters
mac – system mac
- Returns
- BK_OK: on succeed - others: real error, used for future.
-
bk_err_t bk_wifi_manual_cal_rfcali_status(void)
Get Wi-Fi Calibration status.
- Returns
BK_OK: on succeed
others: real error, used for future.
-
bk_err_t bk_wifi_ap_vif_probe_req_frame_cb_register(void *cb)
Register a cb of probe request for ap.
- Parameters
cb – callback function of probe request to register
-
bk_err_t bk_wifi_send_listen_interval_req(uint8_t interval)
Set listen interval.
- Parameters
any – value is acceptable,but 1, 3, 10 is recommended.
- Returns
-BK_OK: on success -others:real error, used for future.
-
bk_err_t bk_wifi_get_statistic_info(wifi_statistics_info_t *wifiinfo)
Get wifi statistic info.
- Parameters
get – wifi info from fw
- Returns
-BK_OK: on success -others:real error, used for future.
-
void bk_wifi_ota_dtim(bool is_open)
set wifi ps dtim info.
- Parameters
dtim – 1 open or not
- Returns
-void.
API Typedefs
Header File
Structures
-
struct wifi_init_config_t
-
struct wifi_channel_t
-
struct bk_vise
-
struct wifi_sta_config_t
Public Members
-
char ssid[WIFI_SSID_STR_LEN]
SSID of AP to be connected
-
uint8_t bssid[WIFI_BSSID_LEN]
BSSID of AP to be connected, fast connect only
-
uint8_t channel
Primary channel of AP to be connected, fast connect only
-
wifi_security_t security
Security of AP to be connected
-
char password[WIFI_PASSWORD_LEN]
Security key or PMK of the wlan.
-
struct bk_vise *vsies[NUM_WIFI_VENDOR_ELEM_FRAMES]
Vnedor Specific IEs
-
uint8_t reserved[32]
reserved, must set to 0
-
int auto_reconnect_count
auto reconnect max count, 0 for always reconnect
-
int auto_reconnect_timeout
auto reconnect timeout in secs, 0 for no timeout
-
bool disable_auto_reconnect_after_disconnect
disable auto reconnect if deauth/disassoc by AP when in connected state
-
char ssid[WIFI_SSID_STR_LEN]
-
struct wifi_linkstate_reason_t
Public Members
-
wifi_link_state_t state
Wifi linkstate
-
wifi_err_reason_t reason_code
Wifi disconnect reason code, success will be WIFI_REASON_MAX
-
wifi_link_state_t state
-
struct wifi_link_status_t
Public Members
-
wifi_link_state_t state
The WiFi connection status
-
int aid
STA AID
-
int rssi
The RSSI of AP the BK STA is connected
-
char ssid[WIFI_SSID_STR_LEN]
SSID of AP the BK STA is connected
-
uint8_t bssid[WIFI_BSSID_LEN]
BSSID of AP the BK STA is connected
-
uint8_t channel
Primary channel of AP the BK STA is connected
-
wifi_security_t security
Security of AP the BK STA is connected
-
char password[WIFI_PASSWORD_LEN]
Passord of AP the BK STA is connected
-
wifi_link_state_t state
-
struct wifi_scan_config_t
-
struct wifi_scan_ap_info_t
Public Members
-
char ssid[WIFI_SSID_STR_LEN]
SSID of AP found by scan
-
uint8_t bssid[WIFI_BSSID_LEN]
BSSID of AP found by scan
-
int rssi
RSSI of AP found by scan
-
uint8_t channel
The channel of the AP found by scan
-
wifi_security_t security
The security type of the AP found by scan
-
uint8_t reserved[16]
Reserved, must be zero
-
char ssid[WIFI_SSID_STR_LEN]
-
struct wifi_scan_result_t
Public Members
-
int ap_num
The number of AP found by scan
-
wifi_scan_ap_info_t *aps
The APs found by scan
-
int ap_num
-
struct wifi_ap_config_t
Public Members
-
char ssid[WIFI_SSID_STR_LEN]
The SSID of BK AP
-
char password[WIFI_PASSWORD_LEN]
Password of BK AP, ignored in an open system.
-
uint8_t channel
The channel of BK AP, 0 indicates default TODO
-
wifi_security_t security
Security type of BK AP, default value TODO
Whether the BK AP is hidden
-
uint8_t acs
Whether Auto Channel Selection is enabled
-
uint8_t vsie_len
Beacon/ProbeResp Vendor Specific IE len
-
uint8_t vsie[255]
Beacon/ProbeResp Vendor Specific IE
-
uint8_t max_con
Max number of stations allowed to connect to BK AP, TODO default value?
-
uint8_t max_statype_num[4]
Max number of different station types allowed to connect to BK AP
-
uint8_t reserved[32]
Reserved, must be zero
-
char ssid[WIFI_SSID_STR_LEN]
-
struct wlan_ap_sta
Wlan station information definition.
-
struct wlan_ap_stas
Wlan connected stations information definition.
-
struct wlan_ap_vsie
softap beacon/probe response’s vendor IEs Dynamic change softap’s vendor specific IEs.
-
struct wlan_sta_vsie
STA vendor IEs for (re)assoc, scan, p2p, p2p go, etc. Dynamic change STA’s vendor specific IEs.
-
struct wifi_monitor_config_t
-
struct wifi_filter_config_t
Public Members
-
uint32_t rx_all_default_mgmt
Set the bit to enable the callback to receive all management frame recived by WiFi driver
-
uint32_t rx_probe_req
Set the bit to enable the callback to receive probe request
-
uint32_t rx_probe_rsp
Set the bit to enable the callback to receive probe response
-
uint32_t rx_all_beacon
Set the bit to enable the callback to receive all beacon
-
uint32_t rx_action
Set the bit to enable the callback to receive action frame
-
uint32_t reserved
Reserved bits, must set to 0
-
uint32_t rx_all_default_mgmt
-
struct wifi_country_t
-
struct wifi_event_sta_connected_t
-
struct wifi_event_sta_disconnected_t
-
struct wifi_event_ap_connected_t
Public Members
-
uint8_t mac[WIFI_MAC_LEN]
MAC of the STA connected to the BK AP
-
uint8_t mac[WIFI_MAC_LEN]
-
struct wifi_event_ap_disconnected_t
Public Members
-
uint8_t mac[WIFI_MAC_LEN]
MAC of the STA disconnected from the BK AP
-
uint8_t mac[WIFI_MAC_LEN]
-
struct wifi_statistics_info_t
Wi-Fi Statistic info.
Public Members
-
uint32_t tx_success_count
Number of TX successes, 0 if unavailable
-
uint32_t tx_retry_count
Number of TX retries, 0 if unavailable
-
uint32_t tx_fail_count
Number of TX failures, 0 if unavailable
-
uint32_t rx_success_count
Number of RX successes, 0 if unavailable
-
uint32_t rx_crcerror_count
Number of RX FCS errors, 0 if unavailable
-
uint32_t mic_error_count
Number of MIC errors, 0 if unavailable
-
int8_t noise
Average noise level in dBm, -128 if unavailable
-
uint16_t phyrate
Maximum used PHY rate, 0 if unavailable
-
uint16_t txrate
Average used TX rate, 0 if unavailable
-
uint16_t rxrate
Average used RX rate, 0 if unavailable
-
int8_t rssi
Average beacon RSSI in dBm, -128 if unavailable
-
uint8_t bandwidth
Average used bandwidth, 0 if unavailable
-
uint8_t idle_time_per
Percent of idle time, 0 if unavailable
-
uint32_t tx_success_count
-
struct raw_tx_cntrl_t
Wi-Fi RAW TX control.
-
struct wifi_raw_tx_info_t
Wi-Fi RAW TX control.
Public Members
-
uint8_t *pkt
RAW data tx packet address
-
int len
RAW data tx packet length
-
raw_tx_cntrl_t tx_cntrl
RAW data tx control information
-
uint8_t *pkt
Macros
-
BK_ERR_WIFI_NOT_INIT
WiFi is not initialized, call bk_wifi_init() to init the WiFi
-
BK_ERR_WIFI_STA_NOT_STARTED
STA is not started, call bk_wifi_sta_start() to start the STA
-
BK_ERR_WIFI_AP_NOT_STARTED
AP is not initialized, call bk_wifi_ap_start() to start the AP
-
BK_ERR_WIFI_CHAN_RANGE
Invalid channel range
-
BK_ERR_WIFI_COUNTRY_POLICY
Invalid country policy
-
BK_ERR_WIFI_RESERVED_FIELD
Reserved fields not 0
-
BK_ERR_WIFI_MONITOR_IP
Monitor is in progress
-
BK_ERR_WIFI_STA_NOT_CONFIG
STA is not configured, call bk_wifi_sta_config() to configure it
-
BK_ERR_WIFI_AP_NOT_CONFIG
AP is not configured, call bk_wifi_ap_config() to configure it
-
BK_ERR_WIFI_DRIVER
Internal WiFi driver error
-
BK_ERR_WIFI_MONITOR_ENTER
WiFi failed to enter monitor mode
-
BK_ERR_WIFI_DRIVER_DEL_VIF
WiFi driver failed to delete WiFi virtual interface
-
BK_ERR_WIFI_DRIVER_AP_START
WiFi driver failed to start BK AP
-
BK_ERR_WIFI_CHAN_NUMBER
Invalid channel number
-
WIFI_MIN_CHAN_NUM
Minimum supported channel number
-
WIFI_MAX_CHAN_NUM
Maximum supported channel number
-
WIFI_SSID_STR_LEN
Maximum NULL-terminated WiFi SSID length
-
WIFI_BSSID_LEN
Length of BSSID
-
WIFI_MAC_LEN
Length of MAC
-
WIFI_PASSWORD_LEN
Maximum NULL-terminated WiFi password length
-
WIFI_DEFAULT_INIT_CONFIG()
default init configuration
-
WIFI_DEFAULT_STA_CONFIG()
default STA configuration
-
WIFI_DEFAULT_AP_CONFIG()
default AP configuration
-
WIFI_DEFAULT_SCAN_CONFIG()
default Scan configuration
-
WIFI_DEFAULT_FILTER_CONFIG()
default Filter configuration
-
BK_MAX_STA_TYPE
-
OUI_BEKEN
-
WLAN_EID_VENDOR_SPECIFIC
Type Definitions
-
typedef struct wlan_ap_sta wlan_ap_sta_t
Wlan station information definition.
-
typedef struct wlan_ap_stas wlan_ap_stas_t
Wlan connected stations information definition.
-
typedef struct wlan_ap_vsie wlan_ap_vsie_t
softap beacon/probe response’s vendor IEs Dynamic change softap’s vendor specific IEs.
-
typedef struct wlan_sta_vsie wlan_sta_vsie_t
STA vendor IEs for (re)assoc, scan, p2p, p2p go, etc. Dynamic change STA’s vendor specific IEs.
-
typedef bk_err_t (*wifi_monitor_cb_t)(const uint8_t *frame, uint32_t len, const wifi_frame_info_t *frame_info)
Monitor callback to receive frames relayed by WiFi driver.
- Attention
1. The memory of frame and frame_info will be freed immediately when the callback is returned. If we want to use the frame or frame_info in other task, make a copy of them and handle them accordingly.
2. Don’t do too much work in the callback because the callback is called in context of WiFi core thread, too much work may impact the performance of WiFi.
-
typedef bk_err_t (*wifi_filter_cb_t)(const uint8_t *frame, uint32_t len, const wifi_frame_info_t *frame_info)
Filter callback to receive frames relayed by WiFi driver.
- Attention
1. The memory of frame and frame_info will be freed immediately when the callback is returned. If we want to use the frame or frame_info in other task, make a copy of them and handle them accordingly.
2. Don’t do too much work in the callback because the callback is called in context of WiFi core thread, too much work may impact the performance of WiFi.
Enumerations
-
enum wifi_event_t
WiFi public event type.
Values:
-
enumerator EVENT_WIFI_SCAN_DONE
WiFi scan done event
-
enumerator EVENT_WIFI_STA_CONNECTED
The BK STA is connected
-
enumerator EVENT_WIFI_STA_DISCONNECTED
The BK STA is disconnected
-
enumerator EVENT_WIFI_AP_CONNECTED
A STA is connected to the BK AP
-
enumerator EVENT_WIFI_AP_DISCONNECTED
A STA is disconnected from the BK AP
-
enumerator EVENT_WIFI_COUNT
WiFi event count
-
enumerator EVENT_WIFI_SCAN_DONE
-
enum wifi_err_reason_t
Values:
-
enumerator WIFI_REASON_UNSPECIFIED
-
enumerator WIFI_REASON_PREV_AUTH_NOT_VALID
-
enumerator WIFI_REASON_DEAUTH_LEAVING
-
enumerator WIFI_REASON_DISASSOC_DUE_TO_INACTIVITY
-
enumerator WIFI_REASON_DISASSOC_AP_BUSY
-
enumerator WIFI_REASON_CLASS2_FRAME_FROM_NONAUTH_STA
-
enumerator WIFI_REASON_CLASS3_FRAME_FROM_NONASSOC_STA
-
enumerator WIFI_REASON_DISASSOC_STA_HAS_LEFT
-
enumerator WIFI_REASON_STA_REQ_ASSOC_WITHOUT_AUTH
-
enumerator WIFI_REASON_PWR_CAPABILITY_NOT_VALID
-
enumerator WIFI_REASON_SUPPORTED_CHANNEL_NOT_VALID
-
enumerator WIFI_REASON_BSS_TRANSITION_DISASSOC
-
enumerator WIFI_REASON_INVALID_IE
-
enumerator WIFI_REASON_MICHAEL_MIC_FAILURE
-
enumerator WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT
-
enumerator WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT
-
enumerator WIFI_REASON_IE_IN_4WAY_DIFFERS
-
enumerator WIFI_REASON_GROUP_CIPHER_NOT_VALID
-
enumerator WIFI_REASON_PAIRWISE_CIPHER_NOT_VALID
-
enumerator WIFI_REASON_AKMP_NOT_VALID
-
enumerator WIFI_REASON_UNSUPPORTED_RSN_IE_VERSION
-
enumerator WIFI_REASON_INVALID_RSN_IE_CAPAB
-
enumerator WIFI_REASON_IEEE_802_1X_AUTH_FAILED
-
enumerator WIFI_REASON_CIPHER_SUITE_REJECTED
-
enumerator WIFI_REASON_TDLS_TEARDOWN_UNREACHABLE
-
enumerator WIFI_REASON_TDLS_TEARDOWN_UNSPECIFIED
-
enumerator WIFI_REASON_SSP_REQUESTED_DISASSOC
-
enumerator WIFI_REASON_NO_SSP_ROAMING_AGREEMENT
-
enumerator WIFI_REASON_BAD_CIPHER_OR_AKM
-
enumerator WIFI_REASON_NOT_AUTHORIZED_THIS_LOCATION
-
enumerator WIFI_REASON_SERVICE_CHANGE_PRECLUDES_TS
-
enumerator WIFI_REASON_UNSPECIFIED_QOS_REASON
-
enumerator WIFI_REASON_NOT_ENOUGH_BANDWIDTH
-
enumerator WIFI_REASON_DISASSOC_LOW_ACK
-
enumerator WIFI_REASON_EXCEEDED_TXOP
-
enumerator WIFI_REASON_STA_LEAVING
-
enumerator WIFI_REASON_END_TS_BA_DLS
-
enumerator WIFI_REASON_UNKNOWN_TS_BA
-
enumerator WIFI_REASON_TIMEOUT
-
enumerator WIFI_REASON_PEERKEY_MISMATCH
-
enumerator WIFI_REASON_AUTHORIZED_ACCESS_LIMIT_REACHED
-
enumerator WIFI_REASON_EXTERNAL_SERVICE_REQUIREMENTS
-
enumerator WIFI_REASON_INVALID_FT_ACTION_FRAME_COUNT
-
enumerator WIFI_REASON_INVALID_PMKID
-
enumerator WIFI_REASON_INVALID_MDE
-
enumerator WIFI_REASON_INVALID_FTE
-
enumerator WIFI_REASON_MESH_PEERING_CANCELLED
-
enumerator WIFI_REASON_MESH_MAX_PEERS
-
enumerator WIFI_REASON_MESH_CONFIG_POLICY_VIOLATION
-
enumerator WIFI_REASON_MESH_CLOSE_RCVD
-
enumerator WIFI_REASON_MESH_MAX_RETRIES
-
enumerator WIFI_REASON_MESH_CONFIRM_TIMEOUT
-
enumerator WIFI_REASON_MESH_INVALID_GTK
-
enumerator WIFI_REASON_MESH_INCONSISTENT_PARAMS
-
enumerator WIFI_REASON_MESH_INVALID_SECURITY_CAP
-
enumerator WIFI_REASON_MESH_PATH_ERROR_NO_PROXY_INFO
-
enumerator WIFI_REASON_MESH_PATH_ERROR_NO_FORWARDING_INFO
-
enumerator WIFI_REASON_MESH_PATH_ERROR_DEST_UNREACHABLE
-
enumerator WIFI_REASON_MAC_ADDRESS_ALREADY_EXISTS_IN_MBSS
-
enumerator WIFI_REASON_MESH_CHANNEL_SWITCH_REGULATORY_REQ
-
enumerator WIFI_REASON_MESH_CHANNEL_SWITCH_UNSPECIFIED
-
enumerator WIFI_REASON_BEACON_LOST
The BK STA can’t detect the beacon of the connected AP
-
enumerator WIFI_REASON_NO_AP_FOUND
Can’t find the target AP
-
enumerator WIFI_REASON_WRONG_PASSWORD
The password is wrong
-
enumerator WIFI_REASON_DISCONNECT_BY_APP
The BK STA disconnected by application
-
enumerator WIFI_REASON_DHCP_TIMEOUT
The BK STA dhcp timeout, 20s
-
enumerator WIFI_REASON_MAX
The BK STA connect success
-
enumerator WIFI_REASON_UNSPECIFIED
-
enum wifi_security_t
Values:
-
enumerator WIFI_SECURITY_NONE
Open system.
-
enumerator WIFI_SECURITY_WEP
WEP security, it’s unsafe security, please don’t use it
-
enumerator WIFI_SECURITY_WPA_TKIP
WPA TKIP
-
enumerator WIFI_SECURITY_WPA_AES
WPA AES
-
enumerator WIFI_SECURITY_WPA_MIXED
WPA AES or TKIP
-
enumerator WIFI_SECURITY_WPA2_TKIP
WPA2 TKIP
-
enumerator WIFI_SECURITY_WPA2_AES
WPA2 AES
-
enumerator WIFI_SECURITY_WPA2_MIXED
WPA2 AES or TKIP
-
enumerator WIFI_SECURITY_WPA3_SAE
WPA3 SAE
-
enumerator WIFI_SECURITY_WPA3_WPA2_MIXED
WPA3 SAE or WPA2 AES
-
enumerator WIFI_SECURITY_EAP
EAP
-
enumerator WIFI_SECURITY_OWE
OWE
-
enumerator WIFI_SECURITY_AUTO
WiFi automatically detect the security type
-
enumerator WIFI_SECURITY_NONE
-
enum wifi_link_state_t
Values:
-
enumerator WIFI_LINKSTATE_STA_IDLE
sta mode is idle
-
enumerator WIFI_LINKSTATE_STA_CONNECTING
sta mode is connecting
-
enumerator WIFI_LINKSTATE_STA_DISCONNECTED
sta mode is disconnected
-
enumerator WIFI_LINKSTATE_STA_CONNECTED
sta mode is connected
-
enumerator WIFI_LINKSTATE_STA_GOT_IP
sta mode got ip
-
enumerator WIFI_LINKSTATE_AP_CONNECTED
softap mode, a client association success
-
enumerator WIFI_LINKSTATE_AP_DISCONNECTED
softap mode, a client disconnect
-
enumerator WIFI_LINKSTATE_AP_CONNECT_FAILED
softap mode, a client association failed
-
enumerator WIFI_LINKSTATE_MAX
reserved
-
enumerator WIFI_LINKSTATE_STA_IDLE
-
enum wifi_country_policy_t
Values:
-
enumerator WIFI_COUNTRY_POLICY_AUTO
Country policy is auto, use the country info of AP to which the station is connected
-
enumerator WIFI_COUNTRY_POLICY_MANUAL
Country policy is manual, always use the configured country info
-
enumerator WIFI_COUNTRY_POLICY_AUTO
-
enum wifi_second_channel_t
Values:
-
enumerator WIFI_SECOND_CHANNEL_NONE
HT20 mode, no secondary channel
-
enumerator WIFI_SECOND_CHANNEL_ABOVE
Second channel is above the primary channel
-
enumerator WIFI_SECOND_CHANNEL_BELOW
Second channel is below the primary channel
-
enumerator WIFI_SECOND_CHANNEL_NONE