Fullroaming software: A HostAP based driver for implementing and experimenting with a wide variety of handoff policies

Description

This page provides a description about the Fullroaming software, a HostAP based driver that provides a tunable and flexible way for implementing and experimenting with a wide variety of handoff policies. The driver was developed in particular for research in vehicular mobility in mesh networks [GFK08]. The software is freely distributed, and researchers are encouraged to make use of it in order to conduct research in related topics.

Download

The software is available for download here.

Researchers that for any purpose make use of the software, are kindly requested to cite the publication [GFK08] for which it was developed (.pdf) (bibtex: Show).

   author = {Anastasios Giannoulis and Marco Fiore and Edward Knightly},
   title = {Supporting Vehicular Mobility in Urban Multi-hop Wireless Networks},
   booktitle = {{ACM MobiSys}},
   year = {2008},
   month = {June},
   address = {Breckenridge, CO}

Installation

The driver can be installed by following these steps:

1. Download Linux Kernel Source:
   Our software has been tested to be compatible with 2.6.x Linux kernel versions (up to 2.6.20) which can be found here. Extract the source files in in /usr/src/.
2. Create an Alternative Bootable Linux Kernel, Dedicated for Experimentation (optional):
   Despite optional, this is a strongly recommended step, as the modification of kernel modules for experimentation (such as of that corresponding to the HostAP driver) puts in jeopardy the stability of the operating system. Compile the downloaded Linux kernel source files, and make another bootable kernel image by following e.g. these instructions. For all experimentation, you can use this new kernel image, so that your initial version of your operating system remains intact as a stable backup solution.
3. Download Fullroaming Software:
   This can be found here. Extract the *.c and *.h files in /usr/src/linux-source-x.y.z/drivers/net/wireless/hostap/, where x.y.z is the version of the Linux Kernel that you downloaded.
4. Compile Custom HostAP Driver:
   Compile the custom driver by e.g. executing this script in the /usr/src/linux-source-x.y.z/drivers/net/wireless/hostap/ directory (path variables defined in this script have to be adjusted according to the Linux kernel version). A customized hostap module will be loaded. Hence, a network interface that makes use of HostAP drivers should be able to operate as specified by the source code in the ../hostap/ directory (.c & .h files).
5. Enable Custom Functionality:
   The custom functionality can be applied with the execution of the following command, which sets the hostroaming mode of the wireless interface (the default hostroaming mode is 0):

     iwpriv interface hostroaming 3

Hardware

The released driver has been tested to function with the SMC2532W-B wireless interfaces. Any wireless interface that makes use of HostAP drivers should be able to support the functionality of the released software version. However, this cannot be guaranteed for all wireless interfaces without any further modifications to the driver code, due to particularities that can potentially arise because of different hardware implementations. If researchers are making use of SMC2532W-B wireless interfaces with secondary firmware older than the 1.7.0 version, then they will have to upgrade it using this file e.g. by following the instructions here.

Implementation

Once installed, the software can represent a wide family of already implemented handoff policies. Those can be enabled by an appropriate selection of different control parameters. The description of the relationship between the main control parameters and the policy behavior follows. Furthermore, we also describe how novel policies can be implemented. For both cases, we highlight the main parts of the source code that are crucial to the implementation process:

Setting Control Parameters in hostap_wlan.h

This file contains the definition of the following control parameters:

• Weighting control parameter (δ)

Its value is set with the following definition:

 #define HOSTAP_FULLROAMING_DELTA d        

where d is a non-negative number. It expresses the degree of weighting of network-based over signal-based information, for the "Differential Capacity Handoff" framework, as proposed and described in [GFK08]. For maximum weighting without incurring additional connectivity penalty (see [GFK08]), δ should take an empirical value that is experimentally found. In practice, instead of assigning off-line such an empirical value, more flexible hardware & software implementations can allow a gradual increase of δ until no additional throughput outages (see [GFK08]) are observed.

Setting δ=0, omits the network-based information and reduces the handoff policy to a purely signal-based policy. The one implemented in this release employs hysteresis and time-averaging of signal-based indicators by using an Exponential Weighted Moving Average (EWMA) filter. The operation of "Averaged with Hysteresis", as termed in [GFK08], is primarily determined by the following parameters (α,β,γ):

• Scanning Frequency (γ)

Its value is set with the following definition:

 #define HOSTAP_FULLROAMING_SCAN g

where g in seconds, is the period of active scanning. The network interface probes for beacons and from those received, it extrapolates every g seconds a signal-based indicator σ_i(k), for the i 'th AP after the k 'th iteration.

• Filter Memory (α)

Its value is set with the following definition:

 #define HOSTAP_FULLROAMING_ALPHA a        

where (a/100) in [0,1] is the memory of the filter, with lower values denoting stronger preference for more recent signal-based indicators.

A time-averaged quality metric q_i(k) is derived for the i 'th AP after the k 'th scanning, according to the following recursive formula:

 qi(k) = α*qi(k-1)+(1-α)*σi(k)

Setting α=0 reduces the signal-based component to a memoryless policy.

• Hysteresis threshold (β)

Its value is set with the following definition:

 #define HOSTAP_FULLROAMING_HYSTHRESH b

where b is a non-negative number. A value of (b/100) dB is the hysteresis threshold for handoff initiation, i.e. a handoff is only initiated when the quality metric q_j(k) of an AP_j different than the one of the current association AP_i, is greater than its quality metric q_i(k) by at least β.

Setting α,β=0 reduces to the "Always Strongest Signal" policy, as termed in [GFK08].

• Switching Period

Its value is set with the following definition:

 #define HOSTAP_SWITCHING_PERIOD p

When p>0, the driver disregards both the signal-based and network-based quality indicators (described above) and initiates a handoff between two Access Points that are specified in hostap_info.c, every time a total number of p beacons are collected from the associated AP. If p is non-positive, then the switching functionality is disabled and handoff is initiated according to the previously described behavior.

Setting Quality Scores in hostap_hw.c

In this file, each AP can be assigned a quality score that can express network information, as described in [GFK08]. Hence, for a given δ>0, different quality scoring mechanisms can be implemented and evaluated by modifications to this file. All necessary actions can be performed in the function prism2_init_local_data():

• First, the MAC address of the N 'th AP has to be defined. For example, if this is 12:34:56:78:90:AB, then insert the following line:

 u8 macN[ETH_ALEN]={0x12,0x34,0x56,0x78,0x90,0xAB};

• In the same function, a quality score can be assigned to the AP with this MAC address:

 memcpy(local->hardcoded_weights[N].bssid,macN,ETH_ALEN); 
 local->hardcoded_weights[N].weight = QN;

where (QN/100) is a number in [0,1] denoting the quality score for AP_N.

We note that our experimentation was limited to a hard-coded, offline assignment of quality scores to APs. In practice, this can represent the scenario of a single advertisement of quality scores from the network upon login. However, the framework proposed in [GFK08] is more general. More flexible hardware & software implementations for wireless interfaces can allow adaptive quality scoring, that is entirely determined by the clients.

Redesigning the Handoff Architecture in hostap_info.c

The evaluation of APs and the handoff initiation are performed in the function handle_fullroaming_selec_work() of this file. Hence, researchers can implement novel handoff policies by using and/or modifying the following parts of this function's code:

• First, all sensed APs are processed with this for-loop:

 list_for_each(ptr, &local->bss_list) {
       bss = list_entry(ptr, struct hostap_bss_info, list);
       ...
 }

where bss is a "runner" variable, pointing to each AP.

• For each AP, a signal-based indicator:

 bss->quality_sample;

is returned by the network interface. The "quality_sample" field is derived from the "hostap_80211_rx_status->signal" variable (see hostap_80211_rx.c), that reflects the signal quality of a link to an AP, as estimated by the network interface through its scanning process.

• Researchers can apply a different AP evaluation than that of the Differential Capacity Handoff framework, apply alternative quality metrics for each AP and store those in the following variable:

 bss->transformed_quality;

Subsequently, the existing code will compare all APs, and point to the AP with the highest quality metric through the following variable:

 best_bss;

• The conditions for handoff initiation are specified in the following conditional statement; this for example forces a disconnection from the currently associated AP and initiates a connection to the best AP when the difference of their quality metrics exceeds the hysteresis threshold β:

	if ( ... ( best_bss->transformed_quality >  bssid_transformed + HOSTAP_FULLROAMING_HYSTHRESH) ))) {
		...
        }

The handoff architecture can be modified, according to different policy behavior by determining i) the conditions for handoff initiation ii) the AP evaluation criteria.

Setting APs for periodic switching

In the same function, two APs are specified between which the driver initiates periodic handoffs, if HOSTAP_SWITCHING_PERIOD>0 in hostap_wlan.h. For example, with the following two declarations:

 u8 mac0[ETH_ALEN]={0x01,0x23,0x45,0x67,0x89,0xAB};
 u8 mac1[ETH_ALEN]={0xFE,0xDC,0xBA,0x98,0x76,0x54};

the driver will initiate periodic handoff between the two Access Points with MAC addresses 01:23:45:67:89:AB and FE:DC:BA:98:76:54.