This guide will tell you how to set up USB ADSL modems which use the eagle-usb chipset, such as the Sagem F@st800 modem by using the eagle-usb driver. Note that there is no way of installing these drivers without administrator access, so if you want to install this modem on a computer on which you only have limited priviledges then please ask the computer's administrator, and possibly give them this guide.

Introduction

Support for these modems has been built into the Linux kernel 2.6.16 (using the ueagle-atm driver), but currently Dapper Drake uses version 2.6.15, so drivers for these modems must be added by the user.

NOTE: This guide should not be used on Ubuntu 6.10 "Edgy Eft" or later. Follow the ueagle-atm guide instead.

Installation

There are problems with the eagle-usb packages included in Dapper and Breezy (and maybe earlier releases), but the source obtained here works well. It is highly recommended that you use the ueagle-atm driver instead if you are running Edgy or newer, and it is encouraged that you use that in Dapper as well. This guide is here for completeness and for anyone who may have problems with the ueagle-atm driver.

Installing From Source

Since the eagle-usb packages are broken the source code for the driver needs to be downloaded. You can get it from here then write it to a CD or USB stick to transfer it to your Ubuntu computer.

Once you have the driver copied into your home directory it would be wise to create a permanent home for it, as you may need to reinstall it for a new kernel in the future. A directory in your home such as "system-tools/drivers/eagle-usb" would keep it out of the way, but still easily accessible. It is always a good idea to keep source code in the same place once you have built it, since moving it may require a rebuild.

The first step is to install the programs required to build source code, and the information about your kernel needed to install drivers. These packages are called "build-essential" and "linux-headers-<kernelversion>" where <kernelversion> is the version of the Linux kernel you are using.

You can find out what version of Linux you are using by typing this command into a terminal window:

uname -r

These two packages can be installed using the Synaptic or Adept package managers, or with the command:

sudo apt-get install build-essential linux-headers-$(uname -r)

(The dollar sign and brackets mean that the output of uname -r, ie. your version, will be installed) Once you have these installed and you have extracted the source code in the desired location you should open a terminal and take it into that directory using the "cd" command. To move into the example folder mentioned earlier you would type:

cd system-tools/drivers/eagle-usb

If the text just before the "$" in the terminal has changed to the right location (~ is your home folder) then you have typed it correctly. If not then keep experimenting until you get it right (pressing the Tab key can complete partially typed folder names for you)

Once you are in the correct folder you need to configure the source code with the command:

./configure

(The dot and the slash are needed) It should give out a lot of writing. Read the last few lines it gives out. If it complains about "no compiler found" or "GCC not found" then you need to install the "build-essential" package. If it complains that "kernel sources cannot be found" then you need to install the correct "linux-headers" package.

If that step went OK and no errors were reported then you can now build the source code into an actual driver. This is done with the command:

make

This can take a while. If the bottom few lines of it's output reports an error then try the ./configure command again and read through it's output (the lines close to the bottom are the most important ones) in case you missed one of the problems I pointed out above.

If the build has been successful then the make command will exit without reporting an error. Now that the driver has been built it must be copied into the right place. This can be done by typing:

sudo make install

You will need to type your user's password here because you are modifying the system. This can only be done by users in the "admin" group (the first user created on your system should be in this group by default).

If that was successful then your driver is now installed and you can move onto the "Configuring" section. If it failed then make sure you typed the command correctly (if it says "permission denied" then you did not use sudo). Also check the previous commands. You can only run each command after the previous one has completed without an error. If your error is not documented here try looking in the forums.

Notes About Reinstalling Source And Updating Kernels

Because you are building the driver for a specific version of Linux you will lose your connection when you update your kernel. Your connection will still be accessible to the kernel you were previously using, so selecting this previous kernel in your GRUB boot menu will let you access the Internet again.

Once you are on the Internet again, make sure you still have the eagle-usb source code (and if not you need to download it again), that you have the correct linux-headers package for your new kernel and that you have not removed the build-essential package. Once you have all of these reboot into your new kernel.

Once in your new kernel you must reconfigure and rebuild the eagle-usb driver (this is why I recommended keeping the source code out of the way somewhere). If you deleted the source code and re-downloaded it then extract it and configure it like before with

./configure

Now that you have some configured source code (either re-downloaded or never deleted in the first place) you need to remove the driver from the old kernel. This is done with the command:

sudo make uninstall

Once again you need your user's password. If you are using the same source code that you used for your previous kernel then you must get rid of all of the files to do with that old kernel. This is done with the command:

make clean

You need to unplug your modem and then plug it back in now, to clear it's memory. Now you have removed all traces of your old eagle-usb driver installation, so you can start building the source code from scratch for your new kernel.

Note: You should look out for new kernels being installed when you update your system. They are called "linux-image-<kernelversion>". If you do not wish to rebuild your driver very often then you can remove the generic "linux", "linux-image-386", "linux-image-686" and "linux-image-k7" packages (DO NOT remove any "linux-image-<kernelversion>" packages or your system may not boot!). This will stop any newer kernels being installed, but you should keep an eye on what versions are made available in the Synaptic or Adept package managers. If there is a major update (the number will go up a lot) then you will probably want to get it. The ueagle-atm driver is built into Linux 2.6.16.

Configuring your connection

Now that you have installed the driver you must tell it a little about your connection, so you will need to type these commands.

To set up the connection you will need to type:

sudo eagleconfig

You need to enter you user's password here as you are modifying the system. The service providers known to work have been given codes, so you need to look through the list and enter the relevent code. For example, if you use a Tiscali account in the UK then you will enter "UK01".

Now you need to enter your login details given to you by your provider (username and password). The question about encrypting passwords depends on your provider. Choose an option and if it does not work then reconfigure the connection and choose the other option (I know UK Tiscali connections need "No" set here). Finally you will be asked whether you want the connection to start at boot or not. Choose no, since the script it uses is not particularly reliable. If you do want to start your connection at boot then I have written a script near the bottom of this page which should do a better job.

Connecting

First you will need to initialise the modem by using the command:

sudo eaglectrl -d

Now wait for the modem to finish initialising (usually lights will flash on the modem during initialisation), then to turn on your connection you need to type:

sudo startadsl

To get information about your connection at any time you can use the command:

sudo eaglestat

Now you should be on the Internet! You can test this by loading up a web browser, or by using the command:

ping google.com

Cancel this by pressing ctrl-c and look at the packet loss. If it is 100% then it is unlikely that you are connected to the Internet so you should check eaglestat to see what is going on (although this is not a definitive test)

Starting at boot

I have found that the bootup script included in the source code does not work properly. To fix this I have written a basic script which should work better. To use it just open the text editor (Applications>Accessories>Text Editor) and copy/paste this into a new file:

exit 0
case "$1" in
  start)
    stopadsl;
    eaglectrl -d;
    sleep 60;
    startadsl
    ;;
  stop)
    true
  ;;
  *)
    echo "Usage: $0 {start|stop}" >&2
    exit 3
    ;;
esac

If you save that file as something like "starteagleusb-custom" and give it execute permissions with:

chmod 755 starteagleusb-custom

And make it owned by the root user with:

sudo chown root.root starteagleusb-custom

Then copy it into the folder /etc/init.d by running:

sudo cp starteagleusb-custom /etc/init.d

And finally make it run on bootup by typing:

sudo update-rc.d starteagleusb-custom start 20 1 2 .

Now it should start at bootup in runlevels 1 (single user ["recover mode" in boot menu]) and 2 (multi user, graphical [the default]). You will now have the original copy of the script in your home folder, but not have permission to change or remove it. This can be fixed by running:

sudo chown <yourusername> starteagleusb-custom

To make a reconnect button you should edit the script in your Home folder to look like this:

stopadsl;
eaglectrl -d;
sleep 60;
startadsl
exit 0

Now copy this script to the folder /usr/local/bin with these commands:

sudo cp starteagleusb-custom /usr/local/bin
sudo chown root.root /usr/local/bin/starteagleusb-custom

Now you can create a program launcher with the Alacarte menu editor (Applications>Accessories>Alacarte Menu Editor, go on File>New Entry) which will reconnect your ADSL line if it is dropped. Just enter any name and comment, put the command to use as "gksudo starteagleusb-custom" and give it a nice networking-style icon from /usr/share/pixmaps or /usr/share/icons.

If you want to know what the script is doing while it runs then you can add lines like, for example:

zenity --info --text="Waiting for the modem to initialise"

To the file /usr/local/bin/starteagleusb-custom in between the other lines already there. This will popup a message box with the information enclosed in --text="" and you can change the messages to reflect what the script is doing (remember that the messages should describe the command on the line BELOW them, not above) By adding this between every line diagnosing problems can be made easier, since you know that the problem happens after the last message which gets displayed (although DON'T add these to /etc/init.d/starteagleusb-custom) You can edit the file by typing:

gksudo gedit /usr/local/bin/starteagleusb-custom

Ubuntu Documentation

UsbAdslModem/EagleUsb