INTRODUCTION
------------
This software is a driver for the Apache(R) ADSL-USB modem, model AB-DSL/C, 
manufactured by Apache MicroPeripherals, Inc. (http://www.apache-micro.com).
The apache-adsl-c.jpg file, included in tgis package, shows a picture of this
modem. This modem is (or used to be) supplied for free by Actcom. The 
manufacturer of this modem (Apache MicroPeripherals, but actually the 
chipset manufacturer is Conexant) provides support only for Windows operating 
systems. This driver allows using this modem under Linux operating systems. 


MAIN FEATURES
-------------
-fully user-space solution -- no kernel patching and/or compilation is 
 necessary
-only the PPPoA VC/MUX protocol is supported


REQUIREMENTS
------------
-linux kernel with USB and PPP support (hopefully most distros will do)
-libusb-0.1.7 which can be downloaded from http://libusb.sf.net or 
 from the same site you downloaded this package
-reasonable amount of memory, disk space and CPU speed


COMPILING
---------
1. If libusb is not installed on your system, install it before installing
the driver. Follow the instructions in that package (for the impatient
./configure; make; make install will do the job)

2. Unpack the tarball
 
3. cd adsl-up-0.1.1

4. Edit Makefile and adjust the INSTALL_DIR variable to point to the place 
   where you want the software to be installed.

5. make

6. make install (probably you need to be root to do that)


CONFIGURING AND RUNNING FOR THE FIRST TIME (TESTING)
----------------------------------------------------
1. Make sure that the installation directory (the directory specified by
the INSTALL_DIR macro in the Makefile) is included in the PATH.

2. Edit (probably as root) the startadsl script from the installation directory
and adjust the USER, VCI, and VPI variables. Your ISP provided you with the
correct values. 

3. Edit the /etc/ppp/options file and make it look like the options.sample
file provided with this package.

4. Create a file named /etc/ppp/pap-secrets like the pap-secrets.sample file
provided with this package. Adjust the username and password accordingly. 
Change the permissions of the file so that only root can access it.

5. Make sure the modem is connected.

6. As root, start the driver, using the startadsl script. This immediately 
launches the adsl-up executable, which should go through the following stages:
	a) Scan the USB bus and find the modem 
	b) Download the firmware on the modem. After this stage the Ready LED
           on the modem will blink.
	c) Set up some configuration registers.
	d) Attempt to bring the line up. This stage takes the longest time. 
           During this stage, you will see the READY and LINK LEDs blinking. 
           The current line status displayed every second. When the line status 
           is read as UP for 5 times consecutively, it is assumed that the line 
           is up, and execution continues from the next step. Otherwise the 
           attempts to bring the line up are repeated.
	e) If we reached this stage, the LINK LED  should light continuously. 
           At this stage pppd is launched. The notty option is passed 
           automatically to pppd. All the command line options which follow
           the -vci option are passed unchanged to pppd.
	f) Two threads are created, one transferring data from the modem to
           the pppd, while the other thread transferring data in the other 
           direction
	g) The main thread goes in an infinite loop, checking the line status
           every second. The output on the screen should be similar to stage d).

Leave the current window alone, until you want to bring the connection down.

At this stage you're supposed to be connected. In another window, issue the 
following command:

/sbin/ifconfig -a


You should see an output like the following:

...
ppp0      Link encap:Point-to-Point Protocol  
          inet addr:192.117.103.188  P-t-P:192.114.47.251  Mask:255.255.255.255
          UP POINTOPOINT RUNNING NOARP MULTICAST  MTU:1500  Metric:1
          RX packets:6 errors:0 dropped:0 overruns:0 frame:0
          TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:3 
          RX bytes:220 (220.0 b)  TX bytes:294 (294.0 b)
...

Try to ping the local and the remote addresses. If this works, check whether
the DNS is working OK by issuing a command like:

host <hostname>

If this also works, what can I say!? Start a browser, or whatever TCP/IP 
application you want and enjoy the ride.


RUNNING THE DRIVER
------------------
If you have already configured the driver, you just have to make sure that
the modem is connected and run the startadsl script in a terminal window. 
That's all. 


SHUTTING DOWN
-------------
To shut down the driver, hit Ctrl-C in the window where the driver runs.
When prompted, unplug the modem. If you fail to do this, you will experience
unmount problems when shutting down Linux, because the usb filesystem
does not get unmounted correctly. I do understand that this is ugly. 
Some future version will fix this. Which one? Good question. The answer
is left as an exercise to the reader. Don't forget to re-plug the modem 
if you want to restart the driver.


FEEDBACK WANTED
---------------
The current version of the driver is 0.1.1  This means that the code is far
from being mature, but it should be usable. Therefore, your feedback is 
of utmost importance for the future development of the software. Please
send requests, problems, comments, encouragement letters, flames, etc.
to emild@cs.technion.ac.il
Yeah, few things changed within this respect since version 0.1 ;-).


THANKS
------
I wish to thank Benoit Papillaut for his Windows USB sniffer 
http://benoit.papillault.free.fr/usbsnoop/index.en.php
Without this software, writing this driver would have been
close to impossible. Thanks to Johannes Erdfelt, <johannes@erdfelt.com>
and Thomas Sailer, <sailer@ife.ee.ethz.ch> for libusb. This
library greatly simplifies the communication with USB devices.
I also wish to thank the Haifa Linux Club (http://www.haifux.org)
for their encouragement. Thanks to Orr Dunkelman and Shlomi Fish
for hosting my driver files. Thanks to the open standards of the
Internet and let's hope that they will remain like this.

