WICED functions specific to Wi-Fi
wiced_result_t wiced_wifi_add_keep_alive |
( |
wiced_keep_alive_packet_t * |
keep_alive_packet_info | ) |
|
Add a network keep alive packet
Keep alive functionality enables the WLAN chip to automatically send an arbitrary IP packet and/or 802.11 Null Function data frame at a regular interval This
feature may be used to maintain connectivity with a Wi-Fi AP and/or remote network application
- A maximum of 4 keep alive packets can be configured to operate concurrently
- Keep alive packet functionality only works with client (STA) mode
- If the keep alive packet length is set to 0, a Null-Function Data frame is automatically used as the keep alive
- Any ethernet packet can be sent as a keep alive packet
- Parameters
-
[in] | keep_alive_packet_info | : Pointer to a wiced_keep_alive_packet_t structure used to setup the keep alive packet |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_add_packet_filter |
( |
uint8_t |
filter_id, |
|
|
const wiced_packet_filter_settings_t * |
settings |
|
) |
| |
Adds an ethernet packet filter which causes the WLAN chip to drop all packets that do NOT match the filter
When a packet filter(s) is installed, incoming packets received by the WLAN chip are run through the pre-installed filter(s). Filter criteria are added using this API function. If the WLAN chip receives a packet that matches one of the currently installed filters, the host MCU is notified, and the packet is forwarded to the MCU. Packets that do not match any of the installed filters are dropped by the WLAN chip. If
there are no packet filters installed, all received packets are passed from the WLAN chip to the host MCU
- Parameters
-
[in] | filter_id | : The unique user assigned ID for the filter |
[in] | settings | : Packet filter settings |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_clear_packet_filter_stats |
( |
uint32_t |
filter_id | ) |
|
Clear all packet filter statistics
- Parameters
-
[in] | filter_id | : The unique user assigned ID for the filter |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_delete_packet_filter_list |
( |
wiced_packet_filter_t * |
list | ) |
|
Delete a list of packet filters that were previously retrieved
This function deletes a list of packet filters created with one of the following functions:
- Parameters
-
[in] | list | : Pointer to the list to be deleted |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_disable_keep_alive |
( |
uint8_t |
id | ) |
|
Disable a keep alive packet specified by id
- Parameters
-
[in] | id | : ID of the keep alive packet to be disabled |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_disable_packet_filter |
( |
uint8_t |
filter_id | ) |
|
Disables a previously installed packet filter
- Parameters
-
[in] | filter_id | : The unique user assigned ID for the filter |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_disable_powersave |
( |
void |
| ) |
|
Disable 802.11 power save mode
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_enable_packet_filter |
( |
uint8_t |
filter_id | ) |
|
Enables a previously installed packet filter
- Parameters
-
[in] | filter_id | : The unique user assigned ID for the filter |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_enable_powersave |
( |
void |
| ) |
|
Enables powersave mode without regard for throughput reduction
This function enables (legacy) 802.11 PS-Poll mode and should be used to achieve the lowest power consumption possible when the Wi-Fi device is primarily passively listening to the network
- Warning
- An accurate 32kHz clock reference must be connected to the WLAN
sleep clock input pin while the WLAN chip is in powersave mode!
Failure to meet this requirement will result in poor WLAN performance.
The sleep clock reference is typically configured in the file:
<WICED-SDK>/include/platforms/<PLATFORM_NAME>/platform.h
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_enable_powersave_with_throughput |
( |
uint8_t |
return_to_sleep_delay_ms | ) |
|
Enables powersave mode while attempting to maximise throughput
Network traffic is typically bursty. Reception of a packet often means that another packet will be received shortly afterwards (and vice versa for transmit) In
high throughput powersave mode, rather then entering powersave mode immediately after receiving or sending a packet, the WLAN chip will wait for a timeout period before returning to sleep
- Note
- return_to_sleep_delay must be set to a multiple of 10. When set to 0, the timeout period defaults to 2 beacon intervals (approximately 204ms).
- Warning
- An accurate 32kHz clock reference must be connected to the WLAN
sleep clock input pin while the WLAN chip is in powersave mode!
Failure to meet this requirement will result in poor WLAN performance.
The sleep clock reference is typically configured in the file:
<WICED-SDK>/include/platforms/<PLATFORM_NAME>/platform.h
- Parameters
-
[in] | return_to_sleep_delay | : Timeout period (in milliseconds) before the WLAN chip returns to sleep |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_ap_info |
( |
wiced_bss_info_t * |
ap_info, |
|
|
wiced_security_t * |
security |
|
) |
| |
Gets information about the AP the client interface is currently associated to
- Note
- Only applicable if STA (client) interface is associated to an AP
- Parameters
-
[out] | ap_info | : Pointer to structure that will be populated with AP information |
[out] | security | : Pointer to structure that will be populated with AP security type |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_associated_client_list |
( |
void * |
client_list_buffer, |
|
|
uint16_t |
buffer_length |
|
) |
| |
Gets information about associated clients.
- Note
- Only applicable if softAP interface is up
- Parameters
-
[out] | client_list_buffer | : pointer to a buffer that will be populated with a variable length structure defined by wiced_maclist_t |
[in] | buffer_length | : length of the buffer |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_channel |
( |
uint32_t * |
channel | ) |
|
Get the current channel on STA interface
- Parameters
-
[out] | channel | : A pointer to the variable where the channel value will be written |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_counters |
( |
wiced_interface_t |
interface, |
|
|
wl_cnt_v6_t * |
counters |
|
) |
| |
Get WLAN counter statistics for the interface provided
- Parameters
-
[in] | interface | : The interface for which the counters are requested |
[out] | counters | : A pointer to the structure where the counter data will be written |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_disabled_packet_filter_list |
( |
uint32_t * |
count, |
|
|
wiced_packet_filter_t ** |
list |
|
) |
| |
Get a list of installed and disabled packet filters
- Warning
- wiced_wifi_delete_packet_filter_list() must be called after this function to release memory internally allocated for the list
- Parameters
-
[out] | count | : Number of filters disabled |
[out] | list | : A pointer to the retrieved filter list (this function automatically allocates memory for the list!) |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_enabled_packet_filter_list |
( |
uint32_t * |
count, |
|
|
wiced_packet_filter_t ** |
list |
|
) |
| |
Get a list of installed and enabled packet filters
- Warning
- wiced_wifi_delete_packet_filter_list() must be called after this function to release memory internally allocated for the list
- Parameters
-
[out] | count | : Number of filters enabled |
[out] | list | : A pointer to the retrieved filter list (this function automatically allocates memory for the list!) |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_keep_alive |
( |
wiced_keep_alive_packet_t * |
keep_alive_packet_info | ) |
|
Get information about a keep alive packet
- The ID of the keep alive packet should be provided in the keep_alive_info structure
- The application must pre-allocate a buffer to store the keep alive packet that is read from the WLAN chip
- The length of the buffer must be provided in the packet_length field of the structure
- The repeat period and keep alive packet bytes are populated by this function upon successful return
- Parameters
-
[in,out] | keep_alive_packet_info | : Pointer to the wiced_keep_alive_t structure to be populated |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_listen_interval |
( |
wiced_listen_interval_t * |
li | ) |
|
Gets the current value of all beacon listen interval variables
- Parameters
-
[out] | li | : The current value of all listen interval settings |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_get_packet_filter_stats |
( |
uint8_t |
filter_id, |
|
|
wiced_packet_filter_stats_t * |
stats |
|
) |
| |
Gets packet filter statistics including packets matched, packets forwarded and packets discarded.
- Parameters
-
[in] | filter_id | : The unique user assigned ID for the filter |
[out] | stats | : A pointer to a structure that will be populated with filter statistics |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_remove_packet_filter |
( |
uint8_t |
filter_id | ) |
|
Removes (uninstalls) a previously installed packet filter
- Parameters
-
[in] | filter_id | : The unique user assigned ID for the filter |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_scan_networks |
( |
wiced_scan_result_handler_t |
results_handler, |
|
|
void * |
user_data |
|
) |
| |
Scans for Wi-Fi networks
- Parameters
-
[in] | results_handler | : A function pointer for the handler that will process the network details as they arrive. |
[in] | user_data | : An argument that will be passed to the results_handler function of this device |
- Note
- The results_handler and user_data variables will be referenced after the function returns. Those variables must remain valid until the scan is complete.
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_set_listen_interval |
( |
uint8_t |
listen_interval, |
|
|
wiced_listen_interval_time_unit_t |
time_unit |
|
) |
| |
Sets the 802.11 powersave listen interval for a Wi-Fi client, and communicates the listen interval to the Access Point. The listen interval will be set to (listen_interval x time_unit) seconds.
The default value for the listen interval is 0. With the default value set, the Wi-Fi device wakes to listen for AP beacons every DTIM period.
If the DTIM listen interval is non-zero, the DTIM listen interval will over ride the beacon listen interval value.
If it is necessary to set the listen interval sent to the AP to a value other than the value set by this function, use the additional association listen interval API : wiced_wifi_set_listen_interval_assoc()
- Note
- This function applies to 802.11 powersave operation. Please read the WICED Powersave Application Note provided in the WICED-SDK/Doc directory for further information about the operation of the 802.11 listen interval.
- Parameters
-
[in] | listen_interval | : The desired beacon listen interval |
[in] | time_unit | : The listen interval time unit; options are beacon period or DTIM period |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_set_listen_interval_assoc |
( |
uint16_t |
listen_interval | ) |
|
Sets the 802.11 powersave beacon listen interval communicated to Wi-Fi Access Points
This function is used by Wi-Fi clients to set the value of the beacon listen interval sent to the AP (in the association request frame) during the association process.
To set the client listen interval as well, use the wiced_wifi_set_listen_interval() API
- Note
- This function applies to 802.11 powersave operation. Please read the WICED Powersave Application Note provided in the WICED-SDK/Doc directory for further information about the operation of the 802.11 listen interval.
- Parameters
-
listen_interval | : The beacon listen interval sent to the AP during association. The time unit is specified in multiples of beacon periods. |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_set_packet_filter_mode |
( |
wiced_packet_filter_mode_t |
mode | ) |
|
Sets the packet filter mode (or rule) to either forward or discard packets on a match
- Parameters
-
[in] | mode | : Packet filter mode |
- Returns
- wiced_result_t
wiced_result_t wiced_wifi_set_roam_trigger |
( |
int32_t |
trigger_level | ) |
|
Set roam trigger level
- Parameters
-
[in] | trigger_level | : Trigger level in dBm. The Wi-Fi device will search for a new AP to connect to once the
signal from the AP (it is currently associated with) drops below the roam trigger level |
- Returns
- wiced_result_t