path: root/README

at76_usb - Linux Driver for Atmel Based USB WLAN Adapters
=========================================================

This is a Linux driver for the Atmel based USB WLAN adapters.  Unlike
the driver developed by Atmel (atmelwlandriver), this driver is intended
to be accepted into the kernel, so it aims to be bloat-free, streamlined
and modern.

The authors of this driver are not associated with Atmel or any
corporation that builds devices with this chip.  The only information
source about the hardware is the Atmel's driver from
http://atmelwlandriver.sourceforge.net/

Look at http://at76c503a.berlios.de/ for more accurate information,
mailing lists and links.


Hardware Compatibility
----------------------

This driver supports USB devices using Atmel at76c503, at76c505 and
at76c505a chipsets.  Known devices with this chip are:

- Belkin F5D6050
- Dynalink/Askey WLL013
- Linksys WUSB11 v2.6
- Netgear MA101B

and many more.


Requirements
------------

Linux kernel 2.6.x (preferably current) with support for USB and
wireless networking.

Firmware for your device in the format compatible with this driver.  To
install the firmware, please read the README file included with the
firmware package.  The firmware can be downloaded from
http://developer.berlios.de/projects/at76c503a/


Installation
------------

To compile the driver, just run "make".  The build system defaults to
compiling the driver against the sources of the currently running
kernel.  If you want to compile for a different kernel, you may need to
specify KERNEL_PATH on the command line.

If the kernel was compiled in a separate directory, KERNEL_PATH should
point to that directory, not to the source tree.  The driver itself will
always compile in its source directory.

When cross-compiling, you may also need to set ARCH and CROSS_COMPILE
appropriately.  See the top-level kernel Makefile for details.

To install the driver, run "make install" as root.  If you supplied any
extra variables to "make", add them to "make install" as well.


Running
-------

First of all, please make sure that the firmware is installed.  The
driver will not work without the firmware.

Once the firmware and the driver are installed, you can connect the
device.  On most modern distributions, the driver will be loaded
automatically.  The driver will load the firmware using hotplug or udev
facility and will create a network interface for each device it finds. 

To make sure that it worked correctly, run "iwconfig".  It will show all
available wireless interfaces.

To configure the device, use "iwconfig" for wireless specific settings
and "ifconfig" or "ip" for network settings.

If you want the device to be configured in a certain way on system
startup, please use the facilities provided by your distribution.

The driver supports managed, ad-hoc and monitor modes.


Troubleshooting
---------------

If you have any problems with the driver, it's always a good idea to
check the messages from the kernel.  Use "dmesg" to display them.

If you are not sure whether the driver is loaded, use "lsmod" to see the
list of the loaded modules.  Look for "at76_usb".  If it's not there,
load it manually by "modprobe":

  modprobe at76_usb

If the driver is loaded but "iwconfig" doesn't show a wireless
interface, make sure that the firmware is loaded by the driver.  If the
driver cannot load the firmware, there will be a message from the driver
in the kernel log.  Make sure that you have a file with exactly that
name and that it's located in the firmware directory known to hotplug or
udev, usually /lib/firmware.

If you see a wireless interface but you are not sure which driver
created it, use "ethtool -i ethX", where "ethX" is the interface name.

If the interface is up, but "iwconfig" shows that it's not associated to
an access point, make sure that the card is in managed mode and that it
uses the same ESSID and WEP key as the access point you want to connect
to.  If using WEP, make sure you are using an authentication method
supported by the access point (open system or shared key).

When in the ad-hoc mode, make sure that all the participants are using
the same channel.

To learn about available access points, use "iwlist ethX scan" where
"ethX" is the interface name.

WPA is not currently supported by this driver, so you cannot connect to
access points with WPA enabled.


Private Parameters
------------------

In addition to the wireless parameters set by "iwconfig", there are
additional driver-specific parameters available via "iwpriv".  Running
"iwpriv ethX" will list all of them.

Following are some of the supported parameters:

- long preamble: iwpriv ethX set_preamble 0
- short preamble: iwpriv ethX set_preamble 1
- amount of debug messages: iwpriv ethX set_debug N
  with N a combination of bits, see DBG_* in at76_usb.h
- power save mode: iwpriv ethX set_powersave N (numbers 1, 2, 3 for
  for none, save and smart save respectively)
- scan channel time: iwpriv ethX set_scan_times <min_ch_time> <max_ch_time>
  (this may be required for 0.90.x firmware, i.e. Intersil radios)


Power Save Modes in Managed Mode
--------------------------------

You can activate 802.11 power save mode by executing

    iwconfig ethX power on power period N

The default period value is 0 and the smallest possible period of power
save (listen interval) is two beacon intervals.  This should lower power
consumption, but decrease data throughput and increase delays.

There is an Atmel specific power save mode called "smart power save"
which switches the device into active state (by a NULL packet to the AP)
as soon as there are pending packets at the AP for the STA and put it
back into doze state after the next beacon.  This saves the need for
sending PS_POLL packets.

It can only be activated by

  iwpriv ethX set_powersave 3

I don't know if the listen_interval is used in this mode.  If yes, you
can only set it earlier by iwconfig, e.g.

   iwconfig ethX power on power period N
   iwpriv ethX set_powersave 3


Known Problems
--------------

1) Bugs of the firmware 0.90.0-44 (the latest available for device with
   Intersil radio after Atmel stopped support for Intersil radio
   chipsets):

  - active scan doesn't send ProbeReq either in ad-hoc or in managed    
    mode

    * If your ad-hoc peer sends the beacon in longer intervals,
      the Atmel driver may not find it. Try to increase the max
      channel time to 500 or 1000 (default 120) by calling

              iwpriv ethX set_scan_times 10 <max channel time>

    * You cannot connect to an access point which hides its ESSID and
      requires the STA to probe it!

  - After joining an existing IBSS of a 2 Mbps card, the basic rates are
    wrong in the beacon, e.g. a 2 Mbps card broadcasts a basic rate set
    of 1 + 2 Mbps, but the Atmel device sends out basic rates of 1, 2,
    5.5 and 11 Mbps.  Subsequently, it cannot connect to the 2 Mbps
    card, because it sends its data packets to broadcast addresses with
    11 Mbps.

  - power saving mode does not work

2) firmware 1.101.0-84

  - if a 2 Mbps card joins an IBSS (ad-hoc mode) initiated by the Atmel
    device (which currently broadcasts 1 + 2 Mbps as the basic rates and
    5.5 and 11 Mbps as (additional) operational rates), the Atmel device
    sends out broadcast packets (e.g. ARP requests) with 11 Mbps.  This
    may be fixed by changing the tx rate in iwconfig from "auto"
    (default) to 1M or 2M.  I'm not sure if this is a firmware bug or a
    problem in the driver.

Only beacons are captured in monitor mode.


Credits
-------

Thanks to (in no particular order):

- the authors (Stavros et.al.) of the usbvnet driver
  (atmelwlandriver.sourceforge.net)
- Joerg Albert for lots of patches
- Brad Hards and Bas Vermeulen for the firmware code, which I ported to
  kernel space
- David Gibson, I used his orinoco driver for learning
- the author(s) of the usbnet driver
- the author(s) of the rtl8150 driver
- lots of other authors of USB and WLAN drivers, where I stole code from
- Pavel Roskin for testing, debugging and his patches
- Nick Jones for rewriting the iw_handler interface

Oliver Kurth, Mon,  6 Jan 2003 22:39:47 +0100
updated by Joerg Albert, Thu, 1 May 2003 and later