News flash! HOWTO made obsolete by speedbundle!

Go to the download page and install the "speedbundle". This contains everything you need to get a speedtouch modem working under linux, including configuration files. It should all "just work". For legal reasons you will need to get the firmware elsewhere. Please write to the mailing list if it does not work perfectly. There should be no need to consult this HOWTO.

Preface

After a serious session of postponing and not feeling like it, I wrote this HOWTO. It contains everything I can think of that you could/should/have to know to use this driver to it's fullest capabilities. This HOWTO has explicit support for PPPoA and PPPoE, but the driver can accommodate any ATM protocol available.

Copyright Information

This document is copyrighted  2001 by Johan Verrept.
Permission is granted to copy, distribute and/or modify this document  under the terms of the GNU Free Documentation License, Version 1.1  or any later version published by the Free Software Foundation;

Driver Description

This is a driver for the Alcatel SpeedTouch USB ADSL modem. The driver itself consists of two different parts. A kernel part and a user space part. Both parts were originally released by Alcatel's modem branch, now part of Thomson Multimedia. The kernel module is released under the GNU General Public License. The current maintainer is Duncan Sands. The kernel module is responsible for all data traffic. It is modeled as a Linux ATM card. This allows you to use a wide range of protocols like PPPoA, RFC2684 Bridging (allowing PPPoE), and others over PVC's and it supports ATM signaling (SVC's).
The original user space part (speedmgmt) is maintained by Alcatel/Thomson. It is distributed as a binary-only application. The Alcatel/Thomson application only does management and firmware downloading.  There is now an open-source replacement (modem_run).  It is available from the user space driver site.
The driver supports Plug-N-Play by using the Linux Hotplugging package.

The choice between PPPoA and PPPoE depends on you provider. Most providers support one protocol, some both.  Consult the FAQ to see which protocol is applicable to you. If you can choose, PPPoA has the least overhead and thus best performance...

The First Step: Downloading.

General

You will need to download quite a few packages to get this thing running.

• The binary management application speedmgmt from Alcatel/Thomson; or the latest CVS version of modem_run, an open-source replacement (part of the user space speedtouch drivers - an independent set of drivers for the speedtouch modem).
• The firmware to be loaded into the modem. You can either use the file mgmt.o that comes with speedmgmt, or the file alcaudsl.sys which comes with the windows drivers (it gets installed in \windows\system).
• The Open Source Kernel Module written by Johan Verrept and maintained by Duncan Sands. The current developement version is available via anonymous cvs (replace modulename with speedtouch).
• The Linux Hotplugging Package
• Linux Kernel 2.4.16 or above.

A number of these you will have to patch and/or compile yourself.

PPPoA

If your provider uses PPPoA you will need:

• For kernels older than 2.4.15, the PPPoA kernel patch (grab the most recent one smaller than your current kernel version) by Jens Axboe. Newer kernels already include this patch.
• A PPP over ATM aware PPP daemon. To see if you already have one, run the command

  find /usr/lib/pppd -name pppoatm.so

  If the result is "No such file or directory" then you will have to download an ATM aware PPP daemon. Try these packages.
  Remark: Debian users can use alien to change rpm packages into the Debian deb format.
  Remark: If dependency problems are stopping you from installing the SuSe packages, you can try recompiling the source rpms that SuSe provides.
  

PPPoE

If your provider uses PPPoE, you will need:

• A PPPoE aware PPP daemon, such as a recent version of the ppp package or Roaring Penguin PPPoE.
• RFC2684 Bridging kernel patch and configuration utility

The Second Step: Patching the kernel

Untarring the kernel

For this you will need root permissions.

Go to the directory where the kernel needs to be compiled.

cd /usr/src/

Now,  move the old Linux kernel away:

mv linux linux.old

Remark: usually this is a symbolic link that can also be deleted.

Untar your new kernel:
If this is linux-2.4.x.tar.gz :

tar zxvf linux-2.4.x.tar.gz

If this is linux-2.4.x.tar.bz2:

cat linux-2.4.x.tar.bz2 | bunzip2 - | tar xvf -

As a good measure, move your kernel and put a symbolic link.

mv linux linux-2.4.x
ln -s linux-2.4.x linux

Remark: Off course, do not forget to replace the 'x' with your version number!
Remark: Do not apply both the PPPoA and PPPoE patches!  They collide.
Remark: If you are using Mandrake 8.0, you can skip this part. The kernel supplied with Mandrake 8.0 already contains the nescessary patches.
Remark: If you are using Mandrake 8.1, you can skip this HOWTO! Mandrake 8.1 contains an rpm with the driver.
 

Applying PPPoA patches

Only necessary if you are going to use PPPoA! Only necessary if your kernel is older than 2.4.15!
Now, go to the kernel directory.

cd /usr/src/linux

Unzip the patch:

gzip -d pppoatm-1.gz

Apply the patch:

patch -p1 -s -E < /path/to/pppoatm-1

Ready.
 

Applying PPPoE patches

Only necessary if you are going to use PPPoE!
Now, go to the kernel directory.

cd /usr/src/linux

Unzip the patch:

gzip -d  br2684-against2.4.2.diff.gz

Apply the patch:

patch -p1 -s -E < /path/to/br2684-against2.4.2.diff

Ready.

The Third Step: Configuring the kernel

For easily configuring the kernel type:

cd /usr/src/linux/
make menuconfig

You will need to set the following options:

• Code Maturity Level Options
  • Prompt for development and/or incomplete code/drivers [Y]
• Loadable Module Support
  • Enable Loadable Module Support [Y]
• General Setup
  • Support for hot-pluggable devices [Y]
• Networking Options
  • Packet Socket [Y]
  • Asynchronous Transfer Mode (ATM) (EXPERIMENTAL) [Y]
• Network Device Support
  • PPP (Point-to-Point Protocol) Support [Y]
  • PPP Deflate Compression [Y]
• USB Support
  • Support for USB [Y]
  • Preliminary USB Device Filesystem [Y]
  • UHCI (Intel PIIX4, VIA,...) Support [M]
  • OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support [M]

For PPPoA you will need the following  options:

• Network Device Support
  • PPP Over ATM (EXPERIMENTAL) [Y]

For PPPoE you will need these options:

• Networking Options
  • RFC 1483/2684 Bridged protocols [Y]
• Network Device Support
  • PPP Over Ethernet (EXPERIMENTAL) [Y]
    

Remark: These are the options needed to get this driver running. you will also have to enable the other drivers you need for your system.  A good starting point to determine what these are are the (currently) loaded modules. For more information on how to build a kernel see the Linux Kernel HOWTO.

The Fourth Step: Building and Installing the Kernel

After configuring, this is easy!
Go to the kernel directory.

cd /usr/src/linux

Type:

make dep
make bzImage
make modules
make install
make modules_install

Congratulations with your new kernel!
Do not forget to reboot before you continue!
Remark: If your kernel refuses to build correctly, try to do a:

make mrproper

Before you try the above sequence.

As a quick check you can type:

 uname -a

to see if your new kernel has booted. It should return something like:

Linux infinty 2.4.4 #4 Sun May 6 04:09:45 CEST 2001 i686 unknown

If there are any problems in installing and getting your kernel to run, please consult the Linux Kernel HOWTO or the documentation of your distribution.

The Fifth Step: Building the SpeedTouch Kernel Module

Untar, build and install the SpeedTouch module:

tar zxvf speedtouch-1.x.tar.gz
cd speedtouch
make
make install

The last step needs to be done as root.  Ready!

Remark: If you are using speedtouch-1.0.tar.gz, you can edit speedtouch.c before building and installing it and remove the following line:

#define DEBUG_PACKET 1

This will cause the module to use a LOT less CPU resources.
 

The Sixth Step: Installing Hotplugging.

If you have downloaded the RPM, you do:

rpm --install hotplug-XXXXX-1.noarch.rpm

If you downloaded the source archive:

tar zxvf hotplug-XXXXX-1.tar.gz
make install

Remark: This only work smoothly for RedHat systems, installation instruction for other distributions can be found in the hotplug README file.

Now, to make sure your hotplugging subsystem is started at boot time:

cd /etc/rc.d/rc3.d
ln -s ../init.d/hotplug S07hotplug

To make sure hotpluggin is disabled at shutdown, add:

cd /etc/rc.d/rc3.d
ln -s ../init.d/hotplug K07hotplug

The Seventh Step: Installing the Binary Management Application

If you downloaded the speedmgmt package from Alcatel/Thomson, untar and install it:

tar zxvf speedmgmt-1.x.tar.gz
cd mgmt
make install

and go to step eight.


If you downloaded the CVS version of modem_run, the procedure is more complicated.
First, install modem_run:

cd speedtouch
./configure
make
make modem_run

(this last step needs to be done as root).

Next, as root, copy the firmware to /usr/local/lib:

mkdir /usr/local/lib

then

cp mgmt.o /usr/local/lib/firmware.bin

or

cp alcaudsl.sys /usr/local/lib/firmware.bin

or

cp firmware.bin /usr/local/lib/firmware.bin

depending on the version of the firmware you are using.

Finally, you will need to install an appropriate hotplugging script: create the directory /etc/hotplug/usb:

mkdir /etc/hotplug/usb

and (as root) place the following in /etc/hotplug/usb/speedtouch.usermap:

speedtouch 0x0003 0x06b9 0x4061 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 0x00000000

and the following in /etc/hotplug/usb/speedtouch:

#!/bin/bash

case $ACTION in

add)
    mesg "speedtch: uploading microcode."
    if /usr/local/sbin/modem_run -k -f /usr/local/lib/firmware.bin ; then
        sleep 5
        if /usr/sbin/pppd ; then
            mesg "speedtch: started pppd."
        fi
    fi
;;

esac

The Eight Step:  Installing PPPoA/PPPoE

Installing PPPoA

First  we need the pppd.
If /dev/ppp does not exist, we need to create it ourself:

cd /dev
 ./MAKEDEV ppp

If your distribution does not include the MAKEDEV script, or it fails to create the correct device,
you can use the following command:

mknod /dev/ppp c 108 0

Now we install the pppd daemon:

rpm --install ppp-2.4.0b2-2.i386.rpm

Remark:    Problems have been reported with package ppp-2.4.0-2.i386.rpm, that is why I list a beta package here.
Remark: If installation of this package fails because PAM has not been installed (for example on a  SuSE 7.1), please download the source archive and compile the pppd by hand.

Installing PPPoE

First we install the ATM Package:

tar zxvf atm-0.78.tar.gz
cd atm
make
make install

Remark: In RH 7.0, this package will probably fail the compiling process. Do not worry, we only need the header files.

Now we compile and install the br2684ctl utility,

cc -o br2684ctl brctl-010226.c -latm
cp br2684ctl /usr/sbin/

Make sure you do not have a pppd installed on your system. It will be overwritten!
Now we install the pppd daemon:

tar zxvf ppp-2.4.0-pppoe4.tgz
cd ppp-2.4.0.pppoe4
./configure
make
make install

If you chose to use roaring penguin PPPoE, please consult the included install instructions.

The Ninth Step: Configuring the system

Configuring the usb subsystem

Add the following line to /etc/fstab:

/dev/usb /proc/bus/usb/ usbdevfs defaults 0 0

This will mount usbdevfs at boot time.

Remark:  If you are using mgmt version 1.3.1 or older, you must mount is under /proc/bus/usb/
Version 1.3.2 will also look in /dev/usb/.
Remark:  If this gives errors during booting, check whether /dev/usb is not already there. If it already exists, replace /dev/usb in the above line with /dev/invalid . The exact name does not matter, as long as it does not exist.

To mount it now type:

mount -a

Configuring PPPoA

Edit the file /etc/ppp/options and replace its contents with the following:

lock
defaultroute
noipdefault
noauth
holdoff 4
maxfail 25
persist
asyncmap 0
lcp-echo-interval  2
lcp-echo-failure   7
name user@domain
user user@domain

plugin /usr/lib/pppd/plugins/pppoatm.so
0.38

These settings will cause pppd to check the link state and time out a connection after 14 seconds if the link is broken. I chose this value because If  the ADSL line looses sync, it will take about 10 seconds to resync.

Remarks:
You will need to replace the two "user@domain"s with your ADSL username.

 Also, in the above example "0.38" is the VPI/VCI ATM pair for the author's provider. You  will need to know what the correct values are for your provider, and substitute those. If these values are incorrect, you may sync, but will not be able to connect to your ISP's IP  layer, and probably be frustrated. These values can be obtained from the Window's  Alcatel client, your ISP or the FAQ

Edit the file /etc/ppp/chap-secrets and replace its contents with the following:

# Secrets for authentication using CHAP
# client        server  secret                  IP addresses
user@domain     *       password

Now put the same contents in /etc/ppp/pap-secrets.

Remark:   You will need to replace "user@domain" with your ADSL username and "password" with your ADSL password.

Configuring PPPoE

Edit the file /etc/ppp/options and replace its contents with the following:

lock
defaultroute
noipdefault
noauth
holdoff 4
maxfail 25
persist
asyncmap 0
name user@domain
user user@domain
lcp-echo-interval 2
lcp-echo-failure   7
plugin /usr/lib/pppd/plugins/pppoe.so
nas0

These settings will cause pppd check the link state and to time out a connection after 14 seconds if the link is broken. I chose this value because If  the ADSL line looses sync, it will take about 10 seconds to resync.

Remark: You will need to replace the two "user@domain"s with your ADSL username.

Edit the file /etc/ppp/chap-secrets and replace its contents with the following:

# Secrets for authentication using CHAP
# client        server  secret                  IP addresses
user@domain     *       password

Now put the same contents in /etc/ppp/pap-secrets.

Remark: You will need to replace the "user@domain"s with your ADSL username and "password" with your real password..
 

The Tenth Step: Running the driver

If everything went according to plan, the driver should start as soon as you plug in the SpeedTouch USB modem. If the driver is installed correctly, you will see the following sequence when plugging in the modem:

1. Both LED's green for a very short period.
2. Left LED is blinking, right LED is green.
3. Left LED is green, right LED is green/red
4. Left LED is green, right LED is blinking
5. Both LED's are green.

In your /var/log/messages file or on your console you will see at plugin:

Speedmgmt[1234]: Alcatel SpeedTouch USB Management daemon started.
Speedmgmt[1234]: (C) Alcatel 2001, Version 1.3.1

Remark: If you are not seeing the version number, you are using version 1.3 and you MUST upgrade. The 1.3 version has a bug that will severely limit your upstream bandwidth.

At then end of the sequence when both LED's are green  something like the following will appear:

 Speedmgmt[1234]: Modem initialized at 1120 kbit/s downstream and 128 kbit/s upstream

Remark: the numbers in the message are purely dependent on your ISP and your subscription.

If you want to dial in to your ISP, do the following:
For PPPoE only:

br2684ctl -b -c 0 -a 0.VP.VC

Remark: VP and VC are to be replaced with the VP/VC values of your ISP. You  will need to know what the correct values are for your provider, and substitute those. If these values are incorrect, you may sync, but will not be able to connect to your ISP's IP  layer, and probably be frustrated. These values can be obtained from the Window's  Alcatel client, your ISP or the FAQ

For PPPoE and PPPoA:

pppd

You can check your /var/log/messages to see if everything went ok.

For PPPoA this should be something like this:

pppd[1234]: Plugin /usr/lib/pppd/plugins/pppoatm.so loaded.
pppd[1234]: PPPoATM plugin_init
pppd[1324]: PPPoATM setdevname_pppoatm
pppd[1324]: PPPoATM setdevname_pppoatm - SUCCESS
pppd[1235]: pppd 2.4.0b1 started by root, uid 0
pppd[1235]: Using interface ppp0
pppd[1235]: Connect: ppp0 <--> 0.38
pppd[1235]: local  IP address xxx.xxx.xxx.xxx
pppd[1235]: remote IP address yyy.yyy.yyy.yyy

For  PPPoE this gives something like:

pppd[1234]: PPPoE Plugin Initialized
pppd[1235]: pppd 2.4.0 started by root, uid 0
pppd[1235]: Sending PADI
pppd[1235]: HOST_UNIQ successful match
pppd[1235]: HOST_UNIQ successful match
pppd[1235]: Got connection: 3b8
pppd[1235]: Connecting PPPoE socket: 00:90:1a:10:11:bd b803 nas0 0x807bdc0
pppd[1235]: Using interface ppp0
pppd[1235]: Connect: ppp0 <--> nas0
pppd[1235]: local IP address xxx.xxx.xxx.xxx
pppd[1235]: remote IP address yyy.yyy.yyy.yyy

Congratulations! You are online!
Remark:  If ppp refuses to connect, please consult the Linux PPP HOWTO.
 

Appendix A: Troubleshooting

When I plug in my modem, nothing happens.

Check whether hotplugging is working. If you plug in a USB device, the console should give something like:

/sbin/hotplug: arguments (usb) env (PWD=/etc/hotplug HOSTNAME=infinty DEVICE=/proc/bus/usb/001/002 ACTION=remove DEBUG=yes MACHTYPE=i386-redhat-linux-gnu OLDPWD=/ DEVFS=/proc/bus/usb TYPE=9/0/0 SHLVL=1 SHELL=/bin/zsh HOSTTYPE=i386 OSTYPE=linux-gnu HOME=/ TERM=dumb PATH=/bin:/sbin:/usr/sbin:/usr/bin PRODUCT=451/1446/100 _=/usr/bin/env)

If this is not happening, check whether hotplugging was enabled in the kernel.

If the LED's of the modem do not start their sequence, check whether the usb subsystem is started.

lsmod

This command should return something like:

Module                  Size  Used by
speedtch               10128   2  (autoclean)
uhci                   18496   0  (unused)
usb-ohci               16160   0  (unused)

If  the uhci or usb-ohci is missing, try modprobing them:

modprobe uhci
modprobe usb-ohci

Remark:  You will need only one of them to get things working!

If modprobe complains about not finding the modules, go back to the section about configuring the kernel, verify the configuration of the USB subsystem. If nothing is wrong, go the section of making the kernel and rerun:

make install
make install_modules
reboot

If this is all ok, check whether mgmt is running.

ps -ef | grep mgmt

This should return a line like:

root      3215     1  0 19:41 ?        00:00:00 /usr/sbin/speedmgmt

If it does not, then check your /var/log/messages.
If this shows something like:

kernel: usb.c: registered new driver Alcatel SpeedTouch USB
Speedmgmt[1234]: Alcatel SpeedTouch USB Management daemon started.
Speedmgmt[1234]: (C) Alcatel 2001, Version 1.3.1
Speedmgmt[1234]: bulk_write: Invalid argument
Speedmgmt[1234]: bulk_read: Invalid argument
Speedmgmt[1234]: bulk_write: Invalid argument
Speedmgmt[1234]: bulk_read: Invalid argument
Speedmgmt[1234]: USBDEVFS_SUBMITURB: Invalid argument

Then you forgot to mount usbdevfs on /proc/bus/usb/!
Check whether you added the line to /etc/fstab. If you have, type:

mount -a

If this does not work, check whether you have enabled the usbdevice filesystem in you kernel configuration.

When I plug in my modem, the LED sequence finishes ok, but I cannot log on.

Check your console or /var/log/messages file to see when ppp says.
If it says something like this:

pppd[1234]: LCP: timeout sending Config-Requests

Go to /proc/net/atm and do:

cat "/proc/net/atm/speedtch:0"

If this file is not there, the speedtouch module is missing.  Repeat step 5.
The output should be something like:

Speed Touch USB  (usb-00:10.1-2)
MAC: 00:90:d0:2c:2c:5a
AAL5: tx 25599 ( 0 err ), rx 37419 ( 0 err, 0 drop )
Line up, firmware loaded

If the numbers are all 0's, the ppp daemon is wrongly configured and it is not sending data to the modem.
If the numbers are NOT zero, check whether you have used the correct VP/VC settings and the correct protocol!

When I plug in the modem the LED sequence stops when the left one is green and the right one is red/green.

You are using the Alcatel managment tool Version 1.3.2, which does not work correctly. Please upgrade to 1.3.3 or a  more recent version.

When I plugin my modem, the LED sequence never goes beyond step two and the syslog gives something like:

Speedmgmt[1234]: Alcatel SpeedTouch USB Management daemon started.
Speedmgmt[1234]: (C) Alcatel 2001, Version 1.3.3
kernel: usb_control/bulk_msg: timeout
Speedmgmt[1234]: bulk_write: Connection timed out
kernel: usbdevfs: USBDEVFS_BULK failed dev 3 ep 0x5 len 991 ret -110
kernel: usb_control/bulk_msg: timeout

Please install the Alcatel management tool version 1.3.4 or later.

When I plug in the modem and it reaches sync, the system hangs.

Sounds like a bug in the kernel module.  Please send details and system logs to the mailing list.

The connection comes up, but it is very slow, especially upstream.

Upgrade your mgmt module to the latest version.

Everything seems to work ok, but ppp refuses to connect.

Please consult the Linux PPP HOWTO.

pppd connects fine, but when I try to reach webpage, it doesn't work.

You can try two things.
First, try to add the following option to your /etc/ppp/options file.

usepeerdns

OR  figure out the dns server of your provider (see Windows).
and edit your /etc/resolv.conf file.
It should look something like:
nameserver

nameserver aaa.bbb.ccc.ddd
nameserver eee.fff.ggg.hhh

with aaa.bbb.ccc.ddd  and eee.fff.ggg.hhh mathcing the ip addresses of your providers primary and secondary dns.
Remark: If you have only one ip address, just leave out the second line.

Appendix B: Some possible tweaks

Running without hotplugging.

It is entirely possible to run this driver without using the hotplugging package.  You can then disable the kernel option and not install the hotplugging package.
If you wish to do this, you have to insert the speedtch.o module by hand and start the mgmt daemon by hand.

modprobe speedtch.o
/usr/sbin/speedmgmt &

There are no real rules. Just make sure you insert the module before the line is in sync. From speedmgmt version 1.3.3 onwards, it no longer matters when you insert the kernel module.

Automatically dialing in at modem plugin.

It is possible to have your system automatically dial in when your modem is plugged in.
To do this you will have to edit the /etc/hotplug/usb/speedtouch file.
For PPPoA it should look something like:

#!/bin/bash

# configuration and startup-script for the Alcatel SpeedTouch USB modem

case $ACTION in

add)

# start
mesg SpeedTouch Inserting module.
modprobe -k speedtch

mesg SpeedTouch Attempting to start management deamon
/usr/sbin/mgmt &

# allow the modem to come into sync.
sleep 20;

# startup pppd
pppd
;;

remove)

killall mgmt
;;

esac

For PPPoE It should be something like:

#!/bin/bash

# configuration and startup-script for the Alcatel SpeedTouch USB modem

case $ACTION in

add)

# start
mesg SpeedTouch Inserting module.
modprobe -k speedtch

mesg SpeedTouch Attempting to start management deamon
/usr/sbin/mgmt &

# allow the modem to come into sync.
sleep 20;

# startup pppd
br2684ctl -b -c 0 -a 0.VP.VC
pppd
;;

remove)

killall mgmt
;;

esac

Remark: don't forget to adjust the VP/VC values!

Important: There is a catch here though. The hotplugging system does not yet support remove events. This means you will have to kill your pppd or br2684ctl utility by hand otherwise you have problems when plugging the modem in again.
 

Appendix C: Links

The following links can prove useful:

• There is a FAQ available.
• Some other HOWTO's are also available:
  • French PPPoA mini-HOWTO
• SuSe has a SpeedTouch webpage.
• The SpeedTouch Kernel Homepage
• Linux-USB homepage
• Linux-ATM homepage
• Linux PPP HOWTO
• Linux Kernel HOWTO

Appendix C: Credits

This HOWTO was based on the mini-HOWTO's of Chris Jones and Pedro Ramos Silva.