Operation Details

The operation of the WLN library can be observed in the debug mode by adding #define WLN_DEBUG_PRINT 1 to the defines section of the global.tbh file of your project. A wealth of status information will then be printed in the console pane as the WLN library operates.

Once the wln_start() is called, the WLN library will attempt to bring up the Wi-Fi interface, then find the specified wireless network and associate with it. The library uses active scanning (wln.activescan), which means that it can handle wireless networks that do not broadcast their SSIDs. The operation is persistent — the library will repeatedly try to find the target wireless network and associate with it. There is no limit on the number of attempts. If the association with the wireless network is lost, the library will try to find the network and associate with it again. If there are several access points with the same SSID (name) in range, the library will always choose the access point with the strongest signal.

A buffer space of 5 to 8 pages is required for the library to operate. During wln_start() execution, the library will check if the required buffer space is available and call callback_wln_pre_buffrq() if more space is needed. Once successful association is achieved, callback_wln_ok() is called. If scanning or association fails, callback_wln_failure() is invoked to notify your system of the fact. Current association status can also be checked through wln_check_association().

One of the most important features of the WLN library is the support for WPA/WPA2 security. The library will associate your device with any access point configured for WPA-PSK, WPA2-PSK, or mixed WPA-PSK/WPA2-PSK modes.

Using WPA1 or WPA2 involves calculating the pre-shared master key. Wln_wpa_mkey_get() is provided for key calculation. This function takes up to two minutes to complete. Fortunately, you don't have to recalculate the key all the time — see Trying WPA code example for details. While wln_wpa_mkey_get() is executing, callback_wln_mkey_progress_update() is called periodically to tell your application of the calculation progress.

The library can simultaneously maintain association with the selected access point and search for another access point with the same or different SSID (name). The search is initiated through wln_rescan() and delivers the result via callback_wln_rescan_result(). The primary purpose of rescanning is to find out if there are access points in range that offer a better signal than the current access point. Your application can switch to another access point by calling wln_change(). For illustration see Roaming Between Access Points code example.

Some access points disassociate devices after a period of inactivity. To prevent this, you can add #define WLN_KEEP_ALIVE 1 to your project. The WLN library will then periodically send out broadcast UDP datagrams (the period is defined by WLN_KEEP_ALIVE_TIMEOUT). This is normally enough to prevent access points from kicking your device out.

Calling wln_stop() terminates library operation and shuts down the Wi-Fi interface. Related buffers are released at that time.