Atheros AR5005 USB WirelessLAN Station Driver
==============================================
Copyright (C) 2004 Athros Communications Inc.


Introduction
============
The Atheros AR5005 USB Driver package is a combination of USB Firmware 
download driver and the WirelessLAN station Driver.  The drivers are built as 
loadable kernel modules.

Features
=========
- Insfrastructure (Managed) and Ad-Hoc Mode
- Open and Shared Key authentication mode with 64 ,128 and 154 bit encryption
- WPA and 802.1x Support using wpa_supplicant
- 802.11 a/b/g support with Atheros Turbo and SuperA/G modes
- Wireless Extension Support
- Short / Long preamble support

Using the Driver
================
The driver can be controlled and configured using Wireless Tools version 26 and above.  The driver supports Wireless Extension 15 or above and is tested against
Wireless Extension 15 and Wireless Tools 26. The Wireless Tools commands that
are currently supported are listed below.  For details please refer the man
pages of the commands. The device is identified by the name "ath0".  The driver
right now has support for only one device and is always identified by "ath0"

iwconfig and iwpriv commands can be executed at any point in time.  i.e if 
the driver is loaded but not active (ifconfig down), then the parameters are 
set in the local configuration and returned.  If the driver is loaded and active
(i.e ifconfig up), then the parameters are set and the driver is restarted as
and when required.  iwlist commands does not provide any valid result when the driver is not active.

iwconfig
--------
iwconfig utility is used for controlling some of the standard wireless
parameters of the driver as listed below

# iwconfig ath0 essid "desisred_essid" - Set the ESSID to "desired_essid"
# iwconfig ath0 essid any              - Set the ESSID to default one.
                                         i.e attach to any ESSID.
For Ad-Hoc networks, if the ESSID is not mentioned (i.e set to any) then the 
Ad-Hoc network will not be started. If the essid being set is different than
the current one the device is restarted for the changes to take effect.

# iwconfig ath0 key [1] 1234567890     - Set the default shared key 1 with the
                                         64bit key
# iwconfig ath0 key [1]                - Set key index 1 as default Tx key
# iwconfig ath0 key on                 - Turn on Encryption.
# iwconfig ath0 key off                - Turn on Encryption.
# iwconfig ath0 key open               - Set open system authentication
# iwconfig ath0 key restricted         - Set shared key authentication

Multiple Key options can be combined to form a single command. For example
'iwconfig ath0 key [1] 1234567890 key [1] key on key restricted` is a valid
command is executed from left to right. Please Note that setting the keys or 
key index does not enable encryption.  Encryption should be enabled/disabled
explicitly by calling key on/off commands.  The Key length is checked only
against the maximum length (128 bits) and the user is expected to input keys
with correct length for lower length keys. i.e, entering a key with 52 bits is
accepted, but is invalid.  Any change in encryption state or default transmit
key, results in driver restart.

# iwconfig ath0 channel 6             - Sets the ad-hoc channel 
# iwconfig ath0 freq 5.3G             - Sets the ad-hoc channel

The channel settings are only for Ad-Hoc or IBSS mode. In infrastructure mode 
these values are just stored, but does not have any effect. Based on the
channels, the netband (802.11a / 802.11b) is selected automatically.

# iwconfig ath0 mode Managed          - Set the device in infrastructure mode
# iwconfig ath0 mode ad-hoc           - set the device in AdHoc/IBSS mode

# iwconfig ath0 ap 00:03:01:22:33:44  - Set desired BSSID
# iwconfig ath0 ap off                - Leave BSSID selction to driver

# iwconfig ath0 rate 11M              - Set the Tx Data Rate to 11Mbps. (Does
                                        not have any effect on current driver)
# iwconfig ath0 rate auto             - Enable Auto Rate control

# iwconfig ath0 rts 512               - Set RTS threshold to 512.
# iwconfig ath0 rts off               - Disable RTS threshold

# iwconfig ath0 frag 512              - Set Fragmentation threshold to 512.
# iwconfig ath0 frag off              - Disable Fragmentation threshold

Please refer the man pages of iwconfig for further reference

iwlist
------
# iwlist ath0 frequency
# iwlist ath0 channel
Lists the available channels/ frequencies for the selected net band. If all net
bands are selected then we have around 30 channels to display.  But 'iwpriv'
has a limitation that it can only get and display 16 channels maximum.

# iwlist ath0 rate
# iwlist ath0 bitrate
Lists the supported data rate for the selected net band.  iwpriv has a 
limitation that it can only get and display 8 data rates maximum. The date rates
are displayed according to the selected net band. Even though the maximum is 8,
iwlist command from the default Redhat 9.0 release fails to display them.
Upgrading it to Wireless tools v26 fixes the problem.

# iwlist ath0 encryption
# iwlist ath0 key
Lists all four default shared keys set in the driver.  Also lists the supported
key sizes, encryption status, default transmit key and authentication type

# iwlist ath0 txpower
Lists supported transmit power level in dBm and milliwatt. The driver has
support for setting 802.11a and 802.11b power levels separately.  This cannot
be done in linux and the list is common for both.

# iwlist ath0 scanning
Scan the medium and lists the available AccessPoint/Ad-Hoc networks.  The list
also displays the capabilities of the networks, like privacy, supported
frequencies and data rates. Scanning on average takes three to five seconds.
iwpriv waits for a maximum of 5 seconds for the driver to return the scan
results. Driver may not have completed the scan by then.  Run the scan command
a couple of times to get the complete list of available networks.

Please refer the manpages of iwlist for further reference

iwpriv
------
These are the private extensions, for the features supported by the driver, but
not by iwconfig commands.

iwpriv ath0 netband 31      - Sets the netband for operation to 802.11/a/b/g
                              with turbo mode enabled
                              Possible Values
                                1   -   802.11a
                                2   -   802.11a Turbo
                                4   -   802.11b
                                8   -   802.11g
                                16  -   108G
                              It is possible to set a combination of these.  i.e
                              setting 28(16+8+4) means 802.11b/g with 108G

iwpriv ath0 adhocband 1     - Sets the adhoc band to 802.11a for starting ad-hoc
                              Possible Values
                                0   -   802.11b
                                1   -   802.11a
                                2   -   802.11a Turbo
                                4   -   802.11g
                                5   -   108G

iwpriv ath0 spreamble 1     - Enable Short preamble (0 disables it)

Apart from the above private commands, various debug levels can be set if the
driver is built with DEBUG flags enabled. Type "iwpriv ath0" to list out the
supported commands


Using WPA Supplicant
====================

a) Install and run the Atheros USB Driver as mentioned in the previous section
b) Under wpa_supplicant directory create a configuration file (.config) with
   the following contents and make the supplicant. Refere wpa_supplicant's 
   README file for more options
       CONFIG_DRIVER_ATHUSB=y
       CONFIG_DRIVER_WEXT=y
       CONFIG_WIRELESS_EXTENSION=y
c) Create a Configuration file with the WPA-PSK options - Refer conf.ath file 
   in the supplicant directory for options
d) Run the supplicant with the options as mentioned below
       wpa_supplicant -i ath0 -D athusb -c conf.ath -w -d
e) Options -d and -w are optional and all other parameters are mandatory. Refer
   the man pages for full option details

Known Issues
============
a) Starting an Ad-Hoc network does not generate beacon frames. This results in
   other adhoc cells getting joined to this network.  Joining other networks is
   working fine. Using Firmware version 1.0.1.4 solves this problem.  Current
   code uses 1.0.1.4 version numbers and firmware, though the code base is 
   from version 1.0.1.6.
b) Selecting CCMP cipher in wpa supplicant requires that AES being selected
   in the AP.  Selecting "AUTO" cipher in AP doesnt seem to generate a WPA IE
   that the WPA supplicant can decode properly. There is no problem if TKIP is
   selected and "AUTO" cipher works fine.
c) Scanning does not happen always.  When the driver is doing its own scanning,
   for a brief amount of time, user initiated scan (iwlist scan) fails for
   unknown reasons.

