Chapter 195. WLAN API

Table of Contents

195.1. API
wlan_diag_dump_ascii — Output human-readable string

The WLAN API is primarily via the device driver get/set config (ioctl()-alike) interface, implemented via the driver supplied interface function:

int cyg_lwip_eth_ioctl (struct netif *netif , unsigned long key , void *data , int data_length );

See Chapter 16, User API for an overview of the general I/O config interface.

SET operations are used to change the active wireless configuration.

This option is used to activate any pending wireless configuration setting changes. This can result in disassociating from the active network configuration, and establishing a new session with the cached (pending) configuration. This information can include the MODE, ESSID, PASSPHRASE and SECTYPE settings.

This option is used to configure the pending interface wireless mode. It is not used for the active configuration until a WLAN_DRV_SET_COMMIT operation is performed.


Not all available WLAN mode definitions will necessarily be supported by the underlying wireless hardware driver. For example the CYGPKG_NET_WIFI_BROADCOM_WWD package only supports the modes WLAN_MODE_INFRA, WLAN_MODE_MASTER and WLAN_MODE_ADHOC.

The supplied (wlan_drv_mode_t) parameter value can be one of:


Infrastructure (multi-cell, roaming) network station. The interface will connect to an access-point, which will act as a bridge to other network segments.

Access-point (synchronisation master).
Adhoc (P2P) single-cell group network. Such a network has no structure, and no access-point is involved.
Wireless repeater. Packet forwarder.
Secondary master/repeater.
Passive monitor. This is used to listen on a network interface to capture packets, without transmitting to the network.
IEEE 802.11s mesh network.
This is a special option that is used to allow the driver to select which mode should be used. Normally this would not be appropriate, but some implementations may be limited to specific hardware implementions.

This option is used to configure the pending network name (SSID). It is not used for the active configuration until a WLAN_DRV_SET_COMMIT operation is performed.

The passed (wlan_drv_essid_t) structure provides the SSID vector (upto WLAN_ESSID_MAX_SIZE bytes in length).


This option is used to configure the pending network security encoding. It is not used for the active configuration until a WLAN_DRV_SET_COMMIT operation is performed.

The (wlan_drv_sectype_t) parameter is a bitfield encoding of the desired security features. The WLAN_SECTYPE_TYPE_MASK can be used to mask out the main security type encoding:

Wi-Fi Protected Access 2.
Wi-Fi Protected Access.

Wired Equivalent Privacy.


Deprecated. Due to security weaknesses it is not recommended to use WEP.

Open network, with no security required.

Along with the basic security type encoding the passed parameter can contain a set of authentication and cipher flags.

The authentication type flags:

Pre-Shared-Key (passphrase). The PSK mode is sometimes referred to as “Personal”.
IEEE 802.1x (enterprise).

The support cipher flags:

Wired Equivalent Privacy.
Temporal Key Integrity Protocol.
Counter Mode with CBC-MAC (CCM) mode Protocol. Sometimes referred to as AES (Advanced Encryption Standard) mode.

This option is used to configure the pending network security pre-shared key value. It is not used for the active configuration until a WLAN_DRV_SET_COMMIT operation is performed.

The passed (wlan_drv_passphrase_t) structure provides the key vector (upto WLAN_SECURITY_PASSPHRASE_LEN bytes in length).


For security reasons there is no equivalent GET operation to read the active passphrase value.


This option is used to configure the pending network security WEP key set. It is not used for the active configuration until a WLAN_DRV_SET_COMMIT operation is performed.

The passed (wlan_drv_wepkeys_t) structure contains the keys to be used for WEP authentication. The passed keys[] vector contains the binary keys when the supplied length field is either WLAN_SECURITY_WEP104_LEN or WLAN_SECURITY_WEP40_LEN. If hexadecimal ASCII representations are being supplied in the keys[] vector then the length is twice the binary key length.


The passed (wlan_drv_channel_t) value is used to configure the radio channel to be used for the interface. This is used for WLAN_MODE_ADHOC and WLAN_MODE_MASTER configurations.


For WLAN_MODE_INFRA configurations the WiFi device will scan for the required Access Point on all the allowed channels, and so the channel set via this operation may not actually be used.

This option is an alternative method for setting the WiFi channel as a frequency (specified in MHz).

This key is used to initiate a wireless network scan. The underlying wireless device driver defines for how long a scan is actually active.

The passed (wlan_drv_scan_t) structure is used to define the callback context for the application supplied handler executed for each network found during the scanning process. A handler function pointer, with the prototype as defined in wlan.h:

typedef void (*wlan_drv_scan_callback_fn)(void *private,wlan_drv_scan_info_t *info);

is required, along with a private context pointer.

For each network found the handler is called with a suitable (wlan_drv_scan_info_t) info pointer. If the scan is terminated then a NULL info parameter is passed to the handler, and the wireless device driver scan support will no longer reference the registered callback.

The eCos scan support is designed to allow the WLAN driver to have a minimal memory footprint, and so the application is responsible for storing/caching any network information seen.


To support this common eCos WLAN layer (allowing eCos applications to use WLAN functionality without having to have special handling for different chipset/driver combinations) when scanning there is a slight overhead in converting the driver specific scan results into the common eCos structure.

The application documented in Section 196.1, “wlan_scan” provides an example implementation using the eCos wireless network scan interface.

This key can be used to abort (terminate) an active scan.
The passed (wlan_drv_dbm_t) dBm value is used to configure the interface transmit power.
The passsed (wlan_drv_rts_t) threshold value specifies the number of bytes in a network packet as the point where the RTS/CTS mechanism is initiated.

GET operations are used to acquire the current, active, wireless configuration.


A non-error return for this operation indicates a WLAN capable driver.


The CYGPKG_NET_WLAN package requires that all eCos WLAN capable drivers provide support for a successful result from the WLAN_DRV_GET_INIT config key since it is used as an indicator that a specific Ethernet driver instance is a wireless interface. If WLAN_DRV_GET_INIT returns an error then the interface does NOT support the eCos wireless features.

Returns the active (wlan_drv_channel_t) channel number.
Returns the interface (wlan_drv_mode_t) mode.
This key returns the current SSID configuration in the referenced (wlan_drv_essid_t) structure.
This key obtains the active (wlan_drv_sectype_t) security encoding setting.
Obtains the current (cyg_drv_rate_t) bps communication rate value.
Obtains the current (wlan_drv_dbm_t) dBm transmission power setting.
The interpretation of this key is NOT defined. It is provided as an extension hook for any driver (hardware) specific control operations that may be needed.

195.1. API

wlan_diag_dump_ascii — Output human-readable string