wl_api Reference Manual

v2.1.1

wl_api_block_diagram_small.png

wl_api Architecture

(o)WL API © is a programming interface for WiFi (802.11). It aims to be a complete interface for embedded applications wanting to use wireless as a communications interface. (o)WL API © is shortened "wl_api" in this document.

wl_api has been designed to meet the following goals :

As a consequence of these design goals wl_api does not allow very fine grained control of most parameters relating to 802.11 networks. That would increase the flexibility of the API while also increasing complexity and code size. When the underlying WiFi hardware can support a richer feature set the extra features can be offered as a add-on library if required.

The wl_api is implemented by two libraries. The core library is compiled for a hardware platform and is independent of operating system or IP stack. The core library contains all WiFi functionality. The core library is supported by a suite of transport libraries. The transport libraries implements the hardware communication layer and are specific to the type of hardware interface used to connect the host platform to the WiFi hardware. For example, there are transport libraries for SPI and for SDIO. Only the core library has a public interface (wl_api.h) but applications will need to link with both the core library and a transport library matching the hardware configuration.

Operation Principles

There are three important properties of wl_api to keep in mind when programming with it.

The first is that wl_api is asynchronous. For instance, when the wl_connect() function is called to attempt connection with an access point it will trigger a sequence of packets being exchanged with the access point after which, if everything is okay, a connection has been established. The wl_connect() call is asynchronous (or non-blocking) which means that you don't know if the connection attempt has succeeded after the call returns. You only know if the sequence was successfully started or not. To find out if, and when, the connection attempt was successful you must register an event handler using the function wl_register_event_cb(). This is true of a number of API calls (which is indicated in their documentation).

The second important property is that wl_api is polled. wl_api never executes "by itself", since it would then have to support interrupts, timers, locks and other operating system dependent features. Instead all asynchronous processes proceed when wl_api is polled by calling the wl_poll() function. When wl_poll() is called wl_api reacts to any received packets, expires any internal timers and performs any other tasks necessary for forward progress. After wl_poll() returns nothing will happen unless it or some other wl_api function is called again.

The third important property is that wl_api is not thread safe. All wl_api calls must execute in the same context since the library has no knowledge of the locking mechanisms available (if any).

The API is structured into these functional groups:

Contact Information

For further information, visit H&D Wireless.
Support and FAQ: http://www.atmel.com/

API Reference Manual Copyright © 2009 H&D Wireless AB, All rights reserved.