Chapter 188. API

Table of Contents

188.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 15, User API for an overview of the general I/O config interface.

SET operations are used to change the active wireless configuration.

WLAN_DRV_SET_COMMIT
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.
WLAN_DRV_SET_MODE

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.

[Note]Note

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:

WLAN_MODE_INFRA

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

WLAN_MODE_MASTER
Access-point (synchronisation master).
WLAN_MODE_ADHOC
Adhoc (P2P) single-cell group network. Such a network has no structure, and no access-point is involved.
WLAN_MODE_REPEAT
Wireless repeater. Packet forwarder.
WLAN_MODE_SECOND
Secondary master/repeater.
WLAN_MODE_MONITOR
Passive monitor. This is used to listen on a network interface to capture packets, without transmitting to the network.
WLAN_MODE_MESH
IEEE 802.11s mesh network.
WLAN_MODE_AUTO
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.
WLAN_DRV_SET_ESSID

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

WLAN_DRV_SET_SECTYPE

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:

WLAN_SECURITY_TYPE_WPA2
Wi-Fi Protected Access 2.
WLAN_SECURITY_TYPE_WPA
Wi-Fi Protected Access.
WLAN_SECURITY_TYPE_WEP

Wired Equivalent Privacy.

[Note]Note

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

WLAN_SECURITY_TYPE_NONE
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:

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

The support cipher flags:

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

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

[Note]Note

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

WLAN_DRV_SET_ENCODE

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.

WLAN_DRV_SET_CHANNEL

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.

[Note]Note

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.

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

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.

[Note]Note

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 189.1, “wlan_scan” provides an example implementation using the eCos wireless network scan interface.

WLAN_DRV_SET_SCAN_ABORT
This key can be used to abort (terminate) an active scan.
WLAN_DRV_SET_TXPOWER
The passed (wlan_drv_dbm_t) dBm value is used to configure the interface transmit power.
WLAN_DRV_SET_RTS
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.

WLAN_DRV_GET_INIT

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

[Note]Note

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.

WLAN_DRV_GET_CHANNEL
Returns the active (wlan_drv_channel_t) channel number.
WLAN_DRV_GET_MODE
Returns the interface (wlan_drv_mode_t) mode.
WLAN_DRV_GET_ESSID
This key returns the current SSID configuration in the referenced (wlan_drv_essid_t) structure.
WLAN_DRV_GET_SECTYPE
This key obtains the active (wlan_drv_sectype_t) security encoding setting.
WLAN_DRV_GET_RATE
Obtains the current (cyg_drv_rate_t) bps communication rate value.
WLAN_DRV_GET_TXPOWER
Obtains the current (wlan_drv_dbm_t) dBm transmission power setting.
WLAN_DRV_VENDOR
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.

188.1. API

wlan_diag_dump_ascii — Output human-readable string