README

README (text/plain), 9.15 KB, created by Paul Bredbury on 2005-10-30 13:15:39 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.

It is recommended that an up-to-date 2.6-series kernel be used, because the SpeedTouch driver has been tweaked in kernel versions since 2.6.10, e.g.:
http://www.kernel.org/pub/linux/kernel/v2.6/testing/ChangeLog-2.6.12-rc6 (search for "Speedtouch")


User Configuration
==================

The following need to be set up manually, before the modem will work properly:

* Check the results of the emerge for warnings (press Shift+PgUp/PgDn to scroll) - very important

* Edit the "user" line and the last line in /etc/ppp/peers/adsl, and uncomment the "usepeerdns" line if you want /etc/resolv.conf to be automatically regenerated with the ISP's nameservers. If the "adsl" file already existed, then the ebuild will have placed its default configuration into "adsl.sample", for manual merging into "adsl".

* Add the username and password to a line in /etc/ppp/chap-secrets

* Configure /etc/conf.d/speedtouch if desired (the default configuration should be fine)

* Set up init script dependencies if required, e.g. add "apache2" to the "before" line within the "depend()" function of /etc/init.d/speedtouch, if apache is installed and should be started after the Internet connection. This is described in http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=4 (in addition, programs can be executed in /etc/ppp/ip-up.local and ip-down.local).

* Run "rc-update add speedtouch default" for the modem to connect to the Internet at startup.


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

Note that [*] 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, because then /etc/init.d/speedtouch will be started automatically if the modem is plugged in *after* the PC has been booted up.

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.

The following kernel options are required (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

 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 (not *absolutely* required, but may speed up the connection)
   [M] PPP BSD-Compress compression - CONFIG_PPP_BSDCOMP (not *absolutely* required, but may speed up the connection)
   [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


Methodology
===========

The combination of the kernel modules, udev and hotplug are involved:

1. The kernel notices when the modem is connected, if the appropriate kernel modules are loaded, and begins loading the firmware
2. Udev looks up /etc/hotplug/usb/speedtch.usermap, and from it knows to execute /etc/hotplug/usb/speedtch
3. /etc/hotplug/usb/speedtch executes "/etc/init.d/speedtouch start" (the standard startup script)
4. /etc/init.d/speedtouch executes "pppd call adsl", to submit the login from /etc/ppp/chap-secrets
5. /etc/init.d/speedtouch either succeeds or fails, after performing its checks (configured in /etc/conf.d/speedtouch)

Symlinks are used within /lib/firmware, to enable easy switching between different SpeedTouch modems (i.e. switching between the two sets of firmware files).


Connecting to the Internet
==========================

* Ensure that the SpeedTouch modem is connected both to the PC and an ADSL phone socket
* Run:  /etc/init.d/speedtouch start
* Wait around 10 seconds for the speedtouch service to either succeed or fail


Manually Dropping the Connection
================================

ADSL lines are normally intended to be continously up. If the connection is desired to be closed for whatever reason, then run:
/etc/init.d/speedtouch stop


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

The ebuild itself performs several checks of the kernel configuration and firmware files. To perform all these checks, and set the links in /lib/firmware for the correct version of the SpeedTouch modem (while it is connected to the PC) run:
	emerge --config speedtouch-usb
Alternatively, to switch to the older firmware files, run:
	cd /lib/firmware && ln -sfn speedtch-KQD6-1 speedtch-1.bin && ln -sfn speedtch-KQD6-2 speedtch-2.bin

It is very important to look carefully over the results of the emerge (press Shift+PgUp/PgDn to scroll).

If the ADSL signal from the ISP is temporarily lost, the kernel driver should automatically reconnect, as long as the kernel version is >=2.6.12.

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

To check the modem's progress, run:  tail -f /var/log/messages

/var/log/messages should show (for PPPoATM) 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 two "found stage n firmware speedtch-n.bin" messages do not appear, or pppoatm.so is not being loaded, then run the command above to check the kernel configuration. If the firmware files are still not found, then emerge a different version of udev, and run:  /sbin/udevstart

If the error "Resource temporarily unavailable" is shown, then see the "Troubleshooting" section regarding setting the firmware links.

If the errors "pppd is unable to open the /dev/ppp device" or "ppoatm.so: cannot open shared object file: No such file or directory" are shown, then run the command above to check the kernel configuration.

If the authentification fails, then check that the logins in the first column of /etc/ppp/peers/adsl and /etc/ppp/chap-secrets match exactly.

If the ADSL connection is not established, then check the options in /etc/ppp/peers/adsl. "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 refer to the "usepeerdns" line in /etc/ppp/peers/adsl. 

The message "rc-scripts: WARNING:  speedtouch has already been started" can be ignored - it is caused by /etc/init.d/speedtouch being executed for each of the two firmware files.

If the problem is still not resolved, 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 this ebuild disables compression in /etc/ppp/peers/adsl by default. Few ISPs support ADSL compression. 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)
* Remove or comment-out the following options in /etc/ppp/peers/adsl:  noaccomp, nobsdcomp, noccp, nodeflate, nopcomp, novj, novjccomp
* Optionally enable the "debug" option in /etc/ppp/peers/adsl, 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