README

README (text/plain), 7.51 KB, created by Paul Bredbury on 2006-02-27 01:18:41 UTC

Introduction
============

This ebuild enables kernel-space support for Alcatel/Thomson SpeedTouch USB modems, which first appeared in kernel 2.6.10 as a replacement for the user-space driver. For earlier kernels, the "speedtouch" ebuild must be emerged instead.


Configuration
=============

It is necessary to choose an interface number for the connection. This is arbitrary - the only requirement is that the connection number is not already in use. Good numbers to choose are 0 (the first available number) or 330 (the model number of the common silver SpeedTouch USB modem). For the purposes of this example, 0 will be chosen.

Add the following lines to /etc/conf.d/net, then customize them as per the inline comments:

config_ppp0=( 'ppp' )  # Runs /lib/rcscripts/net.modules.d/pppd
link_ppp0='/dev/null'  # Not required by pppd, but must be specified
# The 2 numbers change by country. They are separated by a dot. Choose at:
#   http://www.linux-usb.org/SpeedTouch/faq/index.html#q12
plugins_ppp0=( 'pppoa 0.38' )
# 'man pppd' shows other options. Compression is disabled because it is
# rarely taken advantage of, and may interfere with the connection.
# Add option 'usepeerdns' to automatically populate /etc/ppp/resolv.conf
pppd_ppp0=( updetach debug defaultroute noaccomp nobsdcomp noccp nodeflate nopcomp novj novjccomp )
username_ppp0='[e-mail]'  # E.g. '[e-mail]'
password_ppp0='password'  # ADSL connection password, assigned by your ISP


The "debug" option adds some extra commentary from pppd regarding the connection to /var/log/messages, e.g. "sent [LCP ConfReq id=0x1 <magic 0x7bea6ef1>]". It is wise to keep the option on permanently, due to its usefulness when debugging.

If the kernel modules are not built-in, then add the following to /etc/modules.autoload.d/kernel-2.6, in the same vertical order:

pppoatm
speedtch


Create a symlink for the new network interface, for it to be enabled by baselayout:
  cd /etc/init.d && ln -sfn net.lo net.ppp0


Set RC_NET_STRICT_CHECKING="yes" in /etc/conf.d/rc, to prevent Internet services in /etc/init.d/ from starting before the Internet connection is established. Other options are to start/stop programs in /etc/ppp/ip-{up,down}.local, and to customize initscript dependencies as described in:
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=4


Starting the Connection
=======================

To start manually, with the modem connected:
  /etc/init.d/net.ppp0 start

To start automatically when the PC boots:
  rc-update add net.ppp0 default


Kernel Configuration
====================

The ebuild, during an emerge, checks that the required kernel modules are present.

Note that in the list below, "[*]" means that the option is compiled into the kernel, whereas "[M]" means that the option can either be compiled into the kernel, or as a module. Compiling them into the kernel is preferable, to guarantee that the modules are already loaded when they are needed.

In "make menuconfig", you can press "/" and search on e.g. "speedtouch" to see exactly where an option is - the location of an option and its dependencies can change between kernel versions.

Check that the following kernel options are configured as shown (this list includes the prerequisites, e.g. USB_SPEEDTOUCH depends on USB):

 Code maturity level options  --->
  [*] Prompt for development and/or incomplete code/drivers - CONFIG_EXPERIMENTAL

 General setup  --->
  [*] Kernel Userspace Events - CONFIG_KOBJECT_UEVENT (for kernels < 2.6.16 *ONLY*)

 Device Drivers  --->
  Generic Driver Options  --->
   [ ] Select only drivers that don't need compile-time external firmware (*unselected*) - CONFIG_STANDALONE
   [*] Hotplug firmware loading support - CONFIG_FW_LOADER

 Networking  --->
   [*] Networking support - CONFIG_NET
   Networking options  --->
    [*] Packet socket - CONFIG_PACKET
    [M] Asynchronous Transfer Mode (ATM) - CONFIG_ATM
   
 Device Drivers  --->
  Network device support  --->
   [*] Network device support - CONFIG_NETDEVICES
   [M] PPP (point-to-point protocol) support - CONFIG_PPP
   [M] PPP Deflate compression - CONFIG_PPP_DEFLATE (only useful if compression is supported - rare)
   [M] PPP BSD-Compress compression - CONFIG_PPP_BSDCOMP (only useful if compression is supported - rare)
   [M] PPP over ATM - CONFIG_PPPOATM
  USB support  --->
   [*] Support for Host-side USB - CONFIG_USB
   [*] USB device filesystem - CONFIG_USB_DEVICEFS
   [M] (O or U)HCI HCD support
   USB DSL modem support  ---> 
    [M] USB DSL modem support - CONFIG_USB_ATM
    [M] Speedtouch USB support - CONFIG_USB_SPEEDTOUCH



Troubleshooting
===============

Try "emerge speedtouch-usb" again, because the ebuild checks that the required kernel modules are present (showing a warning message if appropriate), and creates the firmware files and symlinks in /lib/firmware/

If the modem is unresponsive, then run "/etc/init.d/net.ppp0 stop" and unplug the modem for 30 seconds, to drain its memory. Then reconnect the modem to the PC and run "/etc/init.d/net.ppp0 start"

To check the modem's connection progress, run:  tail -f /var/log/messages
/var/log/messages should show e.g.:

usb n-n: new full speed USB device using xxxx_hcd and address n
usb n-n: found stage 1 firmware speedtch-1.bin
usb n-n: found stage 2 firmware speedtch-2.bin
pppd[nnn]: Plugin pppoatm.so loaded.
pppd[nnn]: pppd n.n.n started by root, uid 0
pppd[nnn]: Using interface ppp0
pppd[nnn]: Connect: ppp0 <--> n.nn
ADSL line is synchronising
DSL line goes up
ADSL line is up (nnn Kib/s down | nnn Kib/s up)
pppd[nnn]: CHAP authentication succeeded
pppd[nnn]: local  IP address nnn.nnn.nnn.nnn
pppd[nnn]: remote IP address nnn.nnn.nnn.nnn


If the authentification fails, then check username_ppp0 and password_ppp0.

If the ADSL connection is not established, then check the options in pppd_ppp0. "man pppd" explains all the options in that file.

If the ADSL connection seems to have worked, but no websites can be contacted, then check that /etc/resolv.conf is populated, and possibly add the "usepeerdns" option to pppd_ppp0. 

If the problem is still not resolved, then describe the problem in the "discussion and bugs" tab at http://gentoo-wiki.com/HOWTO_Speedtouch_modem, or post to the Gentoo Forums at http://forums.gentoo.org/ - ultimately, if there is no answer, then file a bug at http://bugs.gentoo.org/


Compression
===========

Some ISPs require compression to be disabled in order for the connection to work, so the default configuration described above disables compression. Few ISPs support ADSL compression anyway. If you are lucky enough to have an ISP which *does* support compression (Google is your best friend for determining this), then compression can be enabled by following these steps:

* Compile the kernel modules CONFIG_PPP_DEFLATE and CONFIG_PPP_BSDCOMP (only one is strictly necessary - pppd prefers "deflate" compression). Add them to /etc/modules.autoload.d/kernel-2.6 above the "pppoatm" line, if they are not built-in.
* Remove the following options in pppd_ppp0:  noaccomp nobsdcomp noccp nodeflate nopcomp novj novjccomp
* Ensure that "debug" is in the pppd_ppp0 options, to check that compression is being utilized. Note that "module registered" in /var/log/messages only confirms that the kernel module is loaded - it does not indicate that the connection is compressed.


Links
=====

Gentoo wiki:          http://gentoo-wiki.com/HOWTO_Speedtouch_modem
SpeedTouch ebuilds:   http://packages.gentoo.org/search/?sstring=speedtouch
SpeedTouch hardware:  http://www.speedtouch.com/support.htm
SpeedTouch firmware:  http://www.speedtouch.com/driver_upgrade_lx_3.0.1.2.htm