Ontrak USB Devices under Linux
===============================
Version 0.0.5   Dec. 16, 2003

adutux.ko is an experimental driver for Ontrak USB devices 
running under Linux 2.6.0.

It is distributed in source code only. You must compile and 
install it yourself.

WARNING:
========
Ontrak Control Systems Inc. does not support Linux. The adutux 
driver was developed outside of Ontrak. Do not call Ontrak for 
support, they are unable to provide assistance.

adutux is provided for expermentation purposes only. Use it at
your own risk.


Environment:
============
The adutux driver was tested with:
Linux kernel 2.6.0
Linux kernel 2.6.1
gcc 3.2-7


Installation:
=============
navigate to the directory containing the adutux driver
run
/sbin/insmod adutux.ko

/dev/usb/adutux device entries:
===============================
cd to the /dev/usb directory.
Create the device entries with the mknod command.
sudo mknod c 180 179 adutux0
sudo mknod c 180 180 adutux1
sudo mknod c 180 181 adutux2
sudo mknod c 180 182 adutux3
sudo mknod c 180 183 adutux4
sudo mknod c 180 184 adutux5
sudo mknod c 180 185 adutux6
sudo mknod c 180 186 adutux7
sudo mknod c 180 187 adutux8
sudo mknod c 180 188 adutux9

Grant read/write permision on the /dev/usb/adutux0 to
your users.
sudo chmod 666 /dev/usb/adutux*

Plug the USB cable into your ADU device.
Check the contents of /proc/bus/usb to ensure that the USB
protocol stack detected the ADU device. 
If no entries appear then the host controller drivers must
be started. (search the Web for an FAQ about this).

Testing:
========
Compile the aducmd application.
The aducmd program runs from the command line:
 ./aducmd <index>
where index is a sequential number assigned to the ADU
board by the Linux kernel.

Commands are then entered in the format:
 <pipe> <action> [string]
where:

pipe = [1|2|3]
Pipe 1 directs [string] to the ADU device.
Pipe 2 passes [string] to the RS232 port on the
  ADU device.
Pipe 3 is a streaming pipe for input from the ADU device.
  Streaming has not been tested under Linux.
  
action = [r|w|s]
Action r is a request to read the pipe.
Action w is a request to write "string" to the pipe.
Action s is a request for the serial number string of the
  ADU device.
  
string = the [string] to be written to the ADU device
(the string is ignored for read or serial# actions.)

Notes:
======
The adutux driver makes no effort to queue up I/O, however
the standard Linux USB drivers appear to have an I/O
queue of 3 buffers. Thus you should avoid requesting
input from the ADU device without reading the result.
In other words, each command written to the ADU device
must be followed by a read (if the command requests
data from the ADU device).
EG. if the "rpk" command (request port status) is written 
to the ADU device then the program should read the
response before writing another command to the ADU device.

Trouble Shooting:
=================
Function not supported - perhaps the adutux driver is not
loaded. Try using /sbin/insmod to load adutux.ko 

Note: The 2.6.0 kernel requires updated module-init-tools.

Deprecation:
============
Do not try to submit the adutux driver for acceptance into 
the Linux kernel. It has already been denied entry.

Be advised that kernel versions prior to 2.6.0 had
unspecified "issues" with their USB stack. The adutux
driver will not work reliably if back-ported.

Adding adutux To Your Kernel Tree
=================================
The diff.txt file contains a patch that can be used to
insert the adutux driver into your copy of the kernel source tree.

Navigate to the directory containing your kernel source.
Run the patch command
    patch -p0 < /path/to/diff.txt
substituting the path to diff.txt for "/path/to"

It makes the following changes in
your kernel source tree.

-places the adutux.c source file into the drivers/usb/misc
directory 

-edits drivers/usb/Makefile and adds

obj-$<CONFIG_USB_ADUTUX)	+= misc/

-edits the Kconfig file in the drivers/usb/misc 
sub-directroy and adds

config USB_ADUTUX
	tristate "ONTRAK ADU Devices (adutux)"
	depends on USB + EXPERIMENTAL
	help
	  Driver (adutux) for Ontrak Control Systems devices
	  
-edits the Makefile in the drivers/usb/misc sub-directory
and adds

obj-$(CONFIG_USB_ADUTUX) += adutux.o

Once the patch has been applied run make menuconfig and set 
adutux to "M".
When you next build your kernel the adutux driver
will compile as a module.










