Navigation
Home
bsd
atuwi
0.2
atuwi-README.txt








































atuwi-README.txt
   
   		ATUWI - The FreeBSD USB WLAN driver project
   
   
   **** Current driver features
   
   - Support for both RFMD and Intersil radio parts.
   - Support for Ad-hoc networks.
   - Support for Infrastructure mode (currently in infrastructure mode only 'open
     system' authentication is implemented).
   - Setting the channel / SSID / WEP mode / WEP key / mac-addr via ifconfig.
   - Automatic scanning and associating with a wireless network.
   - bpf support for both DLT_EN10MB and DLT_IEEE802_11
   
   
   
   **** Known BUGS and limitations
   
   - 'shared key' authentication is not yet implemented.
   - There is no timeout when we're associated and connected to a network. Once
     the driver is associated with an AP it assumes the connection will stay
     forever.
   - Nothing is done with the reg-domain of the device. Right now setting
     an unsupported channel will not return any error, but the device will
     simply refuse to work.
   - Only 'auto rate fallback' is supported at this moment. There is no way to
     force the driver to use a specified transmit-rate.
   - The firmware doesn't have a real promiscuous mode. We only receeive things
     addressed to us and to the broadcast address.
   - The firmware doesn't understand supported-rates fields longer than 5
     bytes, so connecting to 54G networks is impossible at this moment. There
     is a newer firmware image that corrects this, but I'm having trouble
     loading the newer firmware. For now the only solution is to degrade the AP
     into '802.11b-only mode'.
   
   
   
   **** Installing the driver
   
   To use this driver you need FreeBSD 5.1-RELEASE or later with the kernel
   sources installed.
   
   First, unpack the driver into your source tree. (You may want to create
   backups of your source tree before you begin.)
   
   # cd /usr/src
   # tar -xvzf /the/path/to/atuwi-0.2.tar.gz
   
   This should extract the following files :
   sys/dev/usb/if_atuwi.c
   sys/dev/usb/if_atuwireg.h
   sys/dev/usb/atuwi_rfmd_fw.h
   sys/dev/usb/atuwi_intersil_fw.h
   sys/dev/usb/usbdevs-atuwi-2004-01-11.diff
   sys/dev/usb-reset-2004-01-08.diff
   sys/modules/atuwi/Makefile
   sys/modules/atuwi/atuwi-README.txt
   sys/conf/files-atuwi-2004-01-11.diff
   
   The atuwi-driver uses a system called 'DFU' to upload firmware into the USB
   adapter. After the firmware has been uploaded, the adapter has to be
   resetted. The current USB stack doesn't have the ability to do this in a
   nice way, so I have added this functionality and provided a patch.
   Patching your USB code and recompiling it can be done as follows:
   # cd /usr/src/sys/dev
   # patch <usb-reset-2004-01-08.diff
   
   Now update the usbdevs list with the ID's of the WLAN adapters and rebuild it:
   # cd /usr/src/sys/dev/usb
   # patch usbdevs usbdevs-atuwi-2004-01-11.diff
   # make -f Makefile.usbdevs
   
   Note that for the changes to take effect you'll have to recompile your
   kernel and reboot now. Otherwise the driver will work, but you will have to
   use a trick to get the firmware to work. (Which is explained later on)
   
   After that it's time to compile the driver itself :
   # cd /usr/src/sys/modules/atuwi
   # make
   
   If you've made it up to here you should now be the happy owner of a file
   called 'if_atuwi.ko'. Let's try to load it and see if it works...
   # kldload /usr/src/sys/modules/atuwi/if_atuwi.ko
   
   Now plug in the WLAN adapter and watch the debug output. If all goes well
   the debug messages will stop with something like :
   'atuwi0: Atmel Wireless adapter, rev 1.10/1.00, addr 3 attached successfully'
   
   Congratulations, you can now begin configuring the interface (and skip the
   next chapter). If the debug messages stop with something like
   'device_probe_and_attach: atuwi0 attach returned 35', read the next chapter.
   If you don't see any debug messages that start with 'atuwi0', you must have
   a WLAN adapter that's either not supported, or not yet listed in the driver.
   Please email me ( Danovitsch @ Vitsch . net ) the output of 'usbdevs -v' so
   I can add the USB ID's to the driver.
   
   
   
   **** How to reset the adapter without the reset code in the kernel?
   
   If for some reasone you are using a kernel without my reset modifications,
   you will have to use a little trick to reset the adapter. If you remove a
   USB plug from a hub, you first disconnect the two data pins and then the two
   pins supplying the power. (This is because the data pins are shorter in
   length.) So if you gently unplug the USB connector only half way out of the
   hub (about 2 milimeters) the data pins are disconnected from the hub, but
   the device is still powered. This means the hub will detect the device is
   gone, but the firmware will stay in the RAM of the device. When you plug the
   device back in now, the hub will detect the device again.
   Doing this is fairly easy, but it won't always work on the first attempt.
   Just try a couple of times.
   
   
   
   **** Examples of joining a network in Ad-Hoc and Infrastructure mode
   
   The following are a couple of self-explenatory examples that show how the
   interface can be configured :
   
   # ifconfig atuwi0 192.168.1.10 ssid "SomeName"
   This command let the driver scan all channels and try to join an Access
   Point with ssid 'SomeName'.
   
   # ifconfig atuwi0 192.168.1.10 ssid "Some Other Name" mediaopt adhoc channel 3
   After this command the driver will scan all channels for an adhoc network
   with ssid 'Some Other Name'. It will connect to the first match it finds,
   regardless of the given channel.
   If no network is found, the driver will start it's own network on channel 3.
   
   Switching back from Ad-Hoc mode to Infrastructure mode can be done with this
   command :
   # ifconfig atuwi0 -mediaopt adhoc
   
   And switching from Infrastructure to Ad-Hoc can be done like this:
   # ifconfig atuwi0 mediaopt adhoc
   
   
   
   **** Configuring the interface to use WEP encryption
   
   The following command will set a 64-bit WEP key :
   # ifconfig atuwi0 wepmode on weptxkey 1 wepkey 1:0x1122334455
   
   And setting a 128-bit WEP key :
   # ifconfig atuwi0 wepmode on weptxkey 1 wepkey 1:0x11223344556677889900112233
   
   Turning WEP off again :
   # ifconfig atuwi0 wepmode off
   
   Possible wepmode's are :
   off	no encryption is done when transmitting.
   mixed	transmitted packets are encrypted, but both encrypted and
   	non-encrypted packets are received.
   on	transmitted packets are encrypted. only WEP encrypted packets are
   	received.
   
   WEP encrypted packets will ONLY be received if the transmitter and the
   receiver are using the exact same WEP key (wether we're in mixed mode or
   not).
   
   When setting WEP keys, make sure the length is exactly 10 hex-digits for
   64-bit keys or 23 hex-digits for 128-bits.
   
   
   
   **** Setting up your system to automagically configure the interface
   
   If you are going to plug/unplug the adapter, you probably want the thing to
   be automatically configured when it's plugged in. USBD will do this for us
   after some minor modifications.
   
   # edit /etc/usbd.conf
   Somewhere in the file add the next couple of lines :
   
   device "USB WLAN"
           devname "atuwi[0-9]+" 
           attach  "/etc/pccard_ether ${DEVNAME} start"
           detach  "/etc/pccard_ether ${DEVNAME} stop"
   
   Save the file and restart usbd :
   # killall -TERM usbd
   # usbd
   
   Now add your settings to /etc/rc.conf . The syntax should look like this :
   ifconfig_atuwi0="192.168.3.20 ssid TheNetworkName wepmode on weptxkey 1 etc.."
   
   To let the system know we want to automatically load the settings add :
   removable_interfaces="atuwi0"
   
   And to make 'usbd' start during boot you should have :
   usbd_enable="YES"
   
   After plugging the device into the usb hub it should now be automatically
   detected and configured.
   
   
   
   **** Compiling the driver into the kernel
   
   Although it's possible to load the driver at boot time it might be easier to
   compile the driver into the kernel sometimes. To do this we have to add the
   driver to the list of options that can be choosen in a kernel-config :
   # cd /usr/src/sys/conf
   # patch files files-atuwi-2004-01-11.diff
   
   Now edit your kernel config file and simply add a line with 'device atuwi' to
   it. Re-config, compile, install, reboot and the adapter should initialise at
   boot time :)
   
   
   
   **** Using the driver during 'sysinstall' from a floppy
   
   What if you're with your laptop in the middle of nowhere, far from your
   cat-5 hub, but just in range of a wireless network and you suddenly feel the
   urge to install FreeBSD?
   Well... I found myself in that situation yesterday and I found out that
   using the driver from sysinstall is very easy and completely painless :)
   First, make your kernel & mfsroot floppies. Then take a third floppy and put
   the driver on it :
   
   Format the floppy
   # fdformat /dev/fd0
   # disklabel -w -r /dev/fd0 fd1440
   # newfs /dev/fd0
   
   Mount it, copy the driver and unmount it again.
   # mount -t ufs /dev/fd0 /mnt
   # cp /usr/src/sys/modules/atuwi/if_atuwi.ko /mnt
   # umount /mnt
   
   Now boot your system with the kernel & mfsroot floppies. When sysinstall
   appears simply insert the driver floppy and follow the menu to load it.
   During install things like ssid and WEP-settings can be filled in in the box
   'extra options to ifconfig'.
   
   
   For those that are having a little chicken-and-egg problem with the 'compile
   the driver, put it on a floppy, and then install FreeBSD' order and for the
   impatient, the floppy image can also be downloaded from the internet from :
   
   http://pilske.dyn.vitsch.net/bsd/atuwi/atuwi-driver.flp.tar.gz
   
   After downloading, extract the image and burn it onto a floppy. The driver
   on the image is compiled with 5.1-RELEASE and supports both RFMD and
   Intersil devices.
   
   
   
   **** Some final tips
   
   By default the driver tends to be a bit too verbose. The debug flags can be
   altered on-the-fly with sysctl variable 'hw.atuwi.debug' .
   
   This will silence the driver:
   sysctl -w hw.atuwi.debug=0x00
   
   For an explanation of possible debug flags, settings and optimizations of
   the driver please have a look at /usr/src/sys/dev/usb/if_atuwireg.h
   
   
   
   
   
   

syntax highlighted by Code2HTML, v. 0.9.1


Email me with questions/comments : Daan <Daan @ pa4dan . nl>