1.5.0.3R3
Software Development Kit
Wi-Fi (802.11) functions

Data Structures

struct  ltrx_scan_result
 Contains network information acquired from network scan. More...
 

Functions

wiced_result_t wiced_wifi_add_keep_alive (wiced_keep_alive_packet_t *keep_alive_packet_info)
 
wiced_result_t wiced_wifi_add_packet_filter (uint8_t filter_id, const wiced_packet_filter_settings_t *settings)
 
wiced_result_t wiced_wifi_clear_packet_filter_stats (uint32_t filter_id)
 
wiced_result_t wiced_wifi_delete_packet_filter_list (wiced_packet_filter_t *list)
 
wiced_result_t wiced_wifi_disable_keep_alive (uint8_t id)
 
wiced_result_t wiced_wifi_disable_packet_filter (uint8_t filter_id)
 
wiced_result_t wiced_wifi_disable_powersave (void)
 
wiced_result_t wiced_wifi_enable_packet_filter (uint8_t filter_id)
 
wiced_result_t wiced_wifi_enable_powersave (void)
 
wiced_result_t wiced_wifi_enable_powersave_with_throughput (uint8_t return_to_sleep_delay_ms)
 
wiced_result_t wiced_wifi_get_ap_info (wiced_bss_info_t *ap_info, wiced_security_t *security)
 
wiced_result_t wiced_wifi_get_associated_client_list (void *client_list_buffer, uint16_t buffer_length)
 
wiced_result_t wiced_wifi_get_channel (uint32_t *channel)
 
wiced_result_t wiced_wifi_get_counters (wiced_interface_t interface, wl_cnt_v6_t *counters)
 
wiced_result_t wiced_wifi_get_disabled_packet_filter_list (uint32_t *count, wiced_packet_filter_t **list)
 
wiced_result_t wiced_wifi_get_enabled_packet_filter_list (uint32_t *count, wiced_packet_filter_t **list)
 
wiced_result_t wiced_wifi_get_keep_alive (wiced_keep_alive_packet_t *keep_alive_packet_info)
 
wiced_result_t wiced_wifi_get_listen_interval (wiced_listen_interval_t *li)
 
wiced_result_t wiced_wifi_get_packet_filter_stats (uint8_t filter_id, wiced_packet_filter_stats_t *stats)
 
wiced_result_t wiced_wifi_remove_packet_filter (uint8_t filter_id)
 
wiced_result_t wiced_wifi_scan_networks (wiced_scan_result_handler_t results_handler, void *user_data)
 
wiced_result_t wiced_wifi_set_listen_interval (uint8_t listen_interval, wiced_listen_interval_time_unit_t time_unit)
 
wiced_result_t wiced_wifi_set_listen_interval_assoc (uint16_t listen_interval)
 
wiced_result_t wiced_wifi_set_packet_filter_mode (wiced_packet_filter_mode_t mode)
 
wiced_result_t wiced_wifi_set_roam_trigger (int32_t trigger_level)
 

Detailed Description

WICED functions specific to Wi-Fi

Function Documentation

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