Arduino  1.8.10
wl_api Reference Manual
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 :

  • Simple : The API is as simple as is practicable to make it easy to use.
  • Minimal size : The API is usable on very resource constrained platforms.
  • Portable : The API is deployable on any platform with a standards compliant C compiler.
  • OS independent : The API is deployable on systems using a real time operating system as well as with applications running on the "bare metal" of a hardware platform (that is without an operating system).

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_tick() function. When wl_tick() is called wl_api reacts to any received management frames, expires any internal timers and performs any other tasks necessary for forward progress. After wl_tick() returns nothing will happen unless it or some other wl_api function is called again. Also, to send and receive data, the wl_process_rx() and wl_process_tx() must be invoked upon reception and transmission of data.

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).

A note on the code examples

The code examples illustrate how to call the different wl_api functions. They do not constitute a complete program. Functions with the prefix "app_" in the code examples are application specific calls that illustrate a particular action. These functions are not part of the API and will have to be implemented if needed. For a complete working code example see one of the H&D Wireless software reference designs, such as the WiFi HTTP server demo code in the Atmel Software Framework.

The API is structured into these functional groups:

Also documented here is the transport layers for SPI and SDIO. There interfaces are only necessary when porting the library to a new hardware platform.

Contact Information

For further information, visit H&D Wireless.
Support and FAQ: