Customizing Firmware and Radios on the Target Device
The Devicescape Wireless Infrastructure Platform supports firmware development for a target device with single or multiple radios, single or multiple bands, and one or two ethernet ports. The out-of-box Devicescape Reference AP provided with the platform is configured as a single-radio AP with two ethernet ports. You can easily modify it for different configurations to suit your target hardware.
Various hardware configurations for the end product are possible. For example, a two-radio access point with dual band capabilities (where one radio offers IEEE 802.11 g/b and the other offers IEEE 802.11a/A Turbo) is capable of broadcasting in two different IEEE 802.11 modes simultaneously.
Conversely, other customizations you might want to make involve modifying the "hardware" (radio MAC address) to support functionality (virtual wireless networks) provided in the firmware.
Information on how to customize the firmware (for radios and ethernet ports) and hardware (radio MAC address) is provided in these sections.
Device Management Configuration File (rescueconfig.xml)
To configure the firmware for the number and types of radios you want to support on the target device, you need to edit the "Radio" details in the file rescueconfig.xml. To configure the firmware for the number of ethernet ports you want to support, you need to add or remove the ethernet interface definitions in that same configuration file. There are two ways to update the configuration file:
Configuring Firmware for Number and Type of Radios
As shipped, the firmware is configured for a one-radio AP. The following sections are included here:
Configuring for Two Radios
To configure for two radios instead of one, find the following line in rescueconfig.xml that defines "Radio 2" and edit to remove the "comment" characters at the beginning and end of this section. (The comment opens at the first instance of "Radio 2" and closes at the end of the file as shown below.)
- Change the given
rescueconfig.xml file (which has Radio 2 configuration commented out):
<bridge-port name="brvwn1">
<interface>wlan1vwn1</interface>
<txop-limit>0</txop-limit>
To this, which has Radio 2 configuration uncommented. ("Radio 2" heading is kept as a comment for clarity):
<bridge-port name="brvwn1">
<interface>wlan1vwn1</interface>
<txop-limit>0</txop-limit>
- Set the MAC address and any other factory defaults on the board as described in the final section of the Getting Started Guide for your target board.
Configuring for Three or More Radios
To configure for three or more radios, edit rescueconfig.xml as follows:
- Uncomment the "
Radio 2" configuration details as described in the previous section.
- Copy and paste the "
Radio 2" configuration information at the end of the file, just before the closing </config> tag.
For each additional radio beyond Radio 2:
- Copy and paste a new set of
Radio <Number> configuration information.
- In the new section:
- Uncomment the configuration. (If desired, keep the introductory "
Radio <Number>" heading in comments for clarity, and modify it to reflect the radio number; for example: "Radio 3").
- Change the
wlan<number> as appropriate. For example, to add a third radio, you would change wlan1 to wlan2 etc. (The wlan numbering is wlan0 for a single radio, wlan1 for a two-radio AP, wlan2 for a three-radio AP, and so on.)
- Set the MAC address and any other factory defaults on the board as described in the final section of the Getting Started Guide for your target board.
Configuring Radio Properties for Type of Radio
The rescueconfig.xml file provides default values for various radio properties. You will need to change the values for these properties as appropriate for the type of radios on your target device.
The following sections provide information on appropriate values for each of these properties, which are provided by the Device Management Agent plugins and exposed in the AP's command line interface (CLI). For more details, see also the CLI Classes and Properties Reference in the Administrator Guide.
You will need to know the number and types of radios you have on your target device, and keep track of the logical radio names and how the logical names correspond to physical radios. For example, you might have an "a" mode radio in slot 1 (physical) that corresponds to wlan0 (logical), a "b/g" radio in slot 2 that corresponds to wlan1, and so on. Most of properties described below are radio-specific and require that you name the radio (for example, wlan0) to which they apply as a part of the configuration. (The exception to this in the topics below is country code.)
Country Code
Although not a radio property per-se, the country code affects the channel set available to the radio. The country code (ISO/IEC 3166-1) is used to set the regulatory domain, which limits the available channels and transmit power to the values allowed by the specified regulator. By default, the country code is set to "us", which sets it to transmit at radio frequencies permitted in the United States.
The country code is set in the "system" class and applies to all radios on the device.
In the <system></system> block in the rescueconfig.xml file, set the country code to the country where the radio will operate. By default, the country code is set to "us" for United States.
<model>Devicescape Wireless Infrastructure Platform Reference AP</model>
<encrypted-password>2yn.4fvaTgedM</encrypted-password>
Description
Add descriptive detail about the radio provided by the manufacturer. This is arbitrary human-readable text. We recommend including at least the valid radio modes and the radio number (as it corresponds to any LED or antenna labels) in the description, for example: "Radio 1 - IEEE 802.11a" or "Radio 2 IEEE 802.11 b/g".
The description you provide will be included in the output for the "get radio" command at the AP command line interface (CLI).
The description is set with the <description> tags as shown in the following example.
<description>Radio 2 - IEEE 802.11g</description>
<channel-policy>static</channel-policy>
<static-channel>11</static-channel>
Radio Mode
The radio mode (sometimes referred to as the "hardware mode") defines the Physical Layer (PHY) standard being used by the radio. If you have a multi-radio device (two or more radios), different modes may be available simultaneously. On a single-radio device, multiple modes may be available, but not simultaneously.
The mode is set with the <mode> tags. For example, to set the radio mode to IEEE 802.11g, edit the rescueconfig.xml file for the particular radio as follows: <mode>g</mode>.
Valid values for mode depend on the capabilities of the radio. Set the default mode to be one that matches the capabilities of your radio. The possible values for mode are:
a - IEEE 802.11ab - IEEE 802.11bg - IEEE 802.11g or IEEE 802.11 Atheros Super AG.turbo-a - Atheros 5 GHz Turbo (IEEE 802.11a turbo)dynamic-turbo-a - Atheros Dynamic Turbo 5 GHz (IEEE 802.11a dynamic turbo)turbo-g - Atheros 2.4 GHz Turbo (IEEE 802.11g turbo)dynamic-turbo-g - Atheros Dynamic Turbo 2.4 GHz (IEEE 802.11g turbo)
The channel settings available depend on the radio mode. See the description for Static Channel to determine which channels can be used for the various radio modes. The following example shows the radio mode set to "g" for the wlan1 radio.
<description>Radio 2 - IEEE 802.11g</description>
<channel-policy>static</channel-policy>
<static-channel>11</static-channel>
Configuring the AP Web UI for Valid Radio Modes
As a part of radio mode customization, also be sure to verify that the Web UI is configured to display only valid radio modes for your target device. To do this, edit the ap-def.hdf file in the web-ui-ap-admin package in the src directory (then rebuild and re-install the package on the target) or directly on the root filesystem in /home/httpd/ap-def.hdf.
The ap-def.hdf file includes the following mode definitions:
# supported radio modes for radio 1
RADIO_1_MODE_DYNAMIC_TURBO_A = 1
RADIO_1_MODE_DYNAMIC_TURBO_G = 1
RADIO_1_MODE_DEFAULT_G = 1
# supported radio modes for radio 2
By default, all radio modes are listed in the ap-def.hdf file. Remove the modes that are not supported by your target hardware.
Below these settings, there are some other Web UI options that you may want to adjust depending on your target hardware and product requirements.
For more information on configuring the AP Web UI, see Using the Web UI Framework to Develop and Customize AP UIs.
Static Channel
Specify the default channel number on which the radio will transmit and receive. The radio will operate on this frequency until the channel is manually changed (via the CLI or Web UI) or if the channel policy is set to automatic selection (in which case, the static-channel is ignored).
Each radio mode offers a number of channels, dependent on how the spectrum is licensed by national and transnational authorities such as the Federal Communications Commission (FCC) or the International Telecommunication Union (ITU-R).
You need to make sure to set static-channel to a channel number appropriate to the radio mode for this radio. For example, if the radio mode is set to IEEE 802.11b/g, you can set the radio mode to channel 6. Use the <static-channel> tags; for example: <static-channel>11</static-channel>. The following example shows the static-channel setting for wlan1 radio.
<description>Radio 2 - IEEE 802.11g</description>
<channel-policy>static</channel-policy>
<static-channel>11</static-channel>
Note also that the country code you use can affect the channels. The following mappings of modes to channel sets assume the country code is set to "us".
- For IEEE 802.11b and IEEE 802.11g modes (including b/g radios), the radio can use channels 1 through 11 inclusive.
- For IEEE 802.11a mode, the radio can use channels 36, 40, 44, 48, 52, 56, 60, 64, 149, 153, 157, 161, 165.
- For Atheros 5 GHz Turbo or Atheros Dynamic Turbo 5 GHz (IEEE 802.11a turbo), the radio can use a subset of the "a" mode channels: 40, 48, 56, 153, and 161.
- For Atheros 2.4 GHz Turbo or Atheros Dynamic Turbo 2.4 GHz (IEEE 802.11g turbo), the radio can use only one of the "b/g" mode channels: 6.
Basic and Supported Rates
You must also edit the rescueconfig.xml file to adjust supported rates and basic rates instances for each radio.
A basic rate set is all rates that the AP will advertise to the network for the purposes of setting up communication with other APs and client stations on the network. (Basic rates are the rates a device is expected to support for a given radio mode.) It is generally more efficient to have an AP broadcast a subset of its supported rate sets. To specify a basic rate, use the <basic-rate> tags named for the radio to which they apply, as shown in Basic Rates Example: Suggested Defaults for mode g.
A supported rate set is all rates that the access point (AP) supports. The AP will automatically choose the most efficient rate based on factors like error rates and distance of client stations from the AP. To specify a supported rate, use the <supported-rate> tags named for the radio to which they apply, as shown in the code example Supported Rates Example: Suggested Defaults for mode g.
Suggested defaults for basic and supported rates for the various radio modes are as follows. Rates are expressed in megabits per second.
|
Radio Mode
|
Basic Rates
|
Supported Rates
|
|
a
(IEEE 802.11a)
|
24, 12, 6 megabits per second (Mbps)
|
54, 48, 36, 24, 18, 12, 9, 6 Mbps
|
|
b
(IEEE 802.11b)
|
2, 1 Mbps
|
11, 5.5, 2, 1 Mbps
|
|
g
(IEEE 802.11g)
|
11, 5.5, 2, 1 Mbps
|
54, 48, 36, 24, 18, 12, 11, 9, 6, 5.5, 2, 1 Mbps
|
|
turbo-a
(Atheros Turbo 5 GHz)
|
48, 24, 12 Mbps
|
108, 96, 72, 48, 36, 24, 18, 12 Mbps
|
|
dynamic-turbo-a
(Atheros Dynamic Turbo 5 GHz / IEEE 802.11a)
|
24, 12, 6 Mbps
|
54, 48, 36, 24, 18, 12, 9, 6 Mbps
|
|
turbo-g
(Atheros Turbo 2.4 GHz / IEEE 802.11g))
|
48, 24, 12 Mbps
|
108, 96, 72, 48, 36, 24, 18, 12 Mbps
|
|
dynamic-turbo-g
(Atheros Dynamic Turbo 2.4 GHz / IEEE 802.11g)
|
11, 5.5, 2, 1 Mbps
|
54, 48, 36, 24, 18, 12, 11, 9, 6, 5.5, 2, 1 Mbps
|
Code Listing 1 Basic Rates Example: Suggested Defaults for mode g
<basic-rate name="wlan1">
<basic-rate name="wlan1">
<basic-rate name="wlan1">
<basic-rate name="wlan1">
Code Listing 2 Supported Rates Example: Suggested Defaults for mode g
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
<supported-rate name="wlan1">
Configuring Firmware for Single or Dual Ethernet Ports
As shipped, the rescueconfig.xml file is configured for an AP with two ethernet ports. If your target device has only one ethernet port, you should modify the configuration to support it.
To configure the firmware for a single radio, simply remove the "eth1" interface section from rescueconfig.xml. Do this by removing or commenting out the following lines:
<description>Ethernet - Guest</description>
Deploying the New Configuration
After you modify the firmware configuration (for number/type of radios or ethernet ports), you will need to redeploy it. The procedure for redeploying will be different depending on whether you modified rescueconfig.xml in an extracted source package or directly on the target, as described in these sections.
Rebuild the Source Package and Upload to the Target
If you modified the configuration by updating the source package, after you update the file you will need to rebuild the device-mgmt-agent-ap package and upload it on the AP:
Reset the Configuration and Reboot the AP
If you modified the configuration directly on the target, then after you update the file you will need to reset the configuration and reboot the AP to allow the changes to take affect properly.
To do this, run the following commands in /etc/ on the target:
set config default rescue
set config startup rescue
|
Note
|
The first command (to reset the default configuration file) is only necessary if you manually created a default configuration file.
|
Customizing an Atheros Radio MAC Address to Support VWNs
Atheros radios support multi-BSSIDs for implementing Virtual Wireless Networks (VWNs) on the access point. (For more information about this feature see the Administrator Guide - the Web Docs online link to that topic is http://www.devicescape.com/docs/wip/admin_guide/VLANs.php.) If you have an Atheros radio on your target board and you want to provide support for VWNs, you will need to modify the default MAC address for the radio to enable generation of multiple MAC addresses using the original as the base.
|
Note
|
A symptom of not having this configured properly is continuous error messages on the command line console Guest network (which uses VWNs) and/or VWNs are enabled on a deployed AP. If the the MAC address assigned to the radio cannot support the number of BSSs that have been configured via VWNs, errors will be generated when VWNs are enabled.
To verify that this is the case, use the CLI to type set dot11 debug 1 and you should see an error message similar to the following:
Configuration file: /tmp/hostapd.conf.wlan0
Invalid BSSID mask ff:ff:ff:ff:ff:f0 for start address 00:e0:b8:76:28:d1.
Start address must be the first address in the block (i.e., addr AND mask == addr)
|
VWNs use multiple BSSIDs for a single target device. Multiple BSSID functionality is implemented in hardware by using multiple MAC addresses generated from the radio MAC address. The multiple MAC addresses are generated by incrementing the radio MAC address to create additional addresses. However, the radio MAC address can only be incremented over the range of MAC addresses given by the least significant bits of the radio MAC address that are set to 0.
This means that if the radio MAC address is odd, it can only have 1 BSS:
Radio MAC address: 00:00:00:00:00:01
If the radio MAC address is even, if can have 2 BSSes:
Radio MAC address: 00:00:00:00:00:02
If the radio MAC address is divisible by 4, it can have 4 BSSes:
Radio MAC address: 00:00:00:00:00:04
To utilize the out-of-the-box VWN configuration, it is necessary to support 16 BSSes, therefore the MAC address must be divisible by 16. This is the same as having it end in a zero:
Radio MAC address: 00:00:00:00:00:10
You can change the radio MAC address in one of two ways:
- Use ART (Atheros Radio Test), which is available from Atheros under license, to change the MAC address in the radio EEPROM. We recommend using this method to permanently associate a MAC address with the radio.
Or
- Use the CLI command:
set radio name static-mac mac
where name is the name of the radio (for example, wlan0) and mac is the starting MAC address (for example, 00:e0:b8:76:28:d0). Note that static-mac is a hidden property of the radio class so you will not see it in the CLI.
If you use the CLI approach, do this as a part of the provisioning process so that the MAC address is stored in the default configuration and not just the startup configuration.
