	*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
	|							|
	*    Welcome to the RWRCCL/RCI/JLS    distribution.     *
	|							|
	*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

The RWRCCL (Roger Williams RCCL) distribution is based on the RCCL/RCI 
system of Lloyd and Hayward and they deserve full credit for the bulk
of this distribution.  This version varies from their distribution in the
following ways:

* System uses RTLinux and a single PC for all aspects of control
* Use of the VAL LSI-11 processr is eliminated.  Processor can be removed from
  control chassis.
* Use of the VAL Joint Servo Cards is also eliminated.  These too can be 
  removed from the control chassis.
* This distribution directly accesses joint encoder signals and DAC output to
  the servo amplifiers.  we have used the TRC004/006 combination to iinterface
  with these signals and highly reccomend its use.  However, this distribution
  will work with any interface circuitry capable of providing the necessary
  functions.

This version of RCCL was developed by Matthew Stein at Roger Williams 
University. The remainder of this file is modified from the original README 
file of John Lloyd.

For a description on how to install the beast, please see the documents

"RCCL/RCI System Overview" in ./doc/overview/overview.ps
"RWRCCL/RCI Startup and Installation Guide" in  ./doc/install/install.html
"RWRCCL/RCI Hardware Installation Guige" in ./doc/hardware/hardware.html



Imakefile:
	Master Makefile for the whole system. The basic commands are

		make World	-- clean and rebuild *Everything*
		make system  	-- make all libraries and binaries
		make depend	-- make all dependencies
		make clean	-- clean away all object files

Now for a description of the main directories:

Xcompile:
	This contains a pdp11 cross compiler/assembler. It is used to 
	produce the program 'moper' (in the directory 'lsi11'), which is
	used by systems using PUMA robots. We cannot provide source for
	this software at the present time. 

arc:
	This directory contains the source code for 'arc', the robotics
	oriented calculator that lets you manipulate matrices, do
	robot kinematics, or just add two numbers together. It uses
	a matrix syntax like that for 'matlab', in deference both to
	matlab and users familiar with matlab.

auxkernel:
	This is the 'minikernel', written by Mike Parker, that is used by the
	multi-CPU microVAX version of the system. RCI is capable of creating
	control tasks on auxiliary CPUs residing on the same backplane as the 
	UNIX CPU. Those CPUs require a small O/S providing minimal services
	such as timing and console I/O. The minikernel provides these services
	for auxiliary microVAX CPUs. The kernel is demand-loaded into each CPU
	over the Q-bus by RCI software, and some support software configured 
	into the microVAX kernel.

bin:
	Binary executable programs associated with the RCCL/RCI system. This
	includes robot utility programs, as well as the private copy of the
	C compiler and loader used by RCI.

chase:
	This is a chasing-point based, joint level, trajectory generator 
	written on top of RCI and used to run the various utility programs
	in the system, such as 'free', 'pumacal', and 'calib'.

conf:
	System and site-dependant configuration files. Files describing the
	parameters for the various robots are contained here.

demo.rccl:
	Demonstration programs for RCCL proper. Most of these demo programs
	are described in the ``Mulit-RCCL User's Guide''.

demo.rci:
	Demonstration programs for RCI. Most of these programs appear in the
	``RCI User's Guide''.

doc:
	System documentation. Much of the original system documentation is
	unchanged from RCCL to RWRCCL as only the underlying hardware
	architecture is modified.  The source for the original manuals
	are written in LaTex.  I have tired without much success to use
	these files but the LaTex appears too old to be supported by 
	current versions of tex without a great deal of re-work.  The 
	directories beneath "doc" also contain the generated postscript 
	versions of the documents.  These are still useable and informative, so
	I have left these unchanged.  I have modified the installation document
	and converted to html (./doc/install/install.html) as well as the 
	hardware installation document (./doc/hardware/hardware.html).

drivers:
	All of the device drivers for the RCI devices; these are the packages
	which implement the RCI I/O device defined by IOdevice(7R).

fastmath:
	Source for the fast table-driven trig routines. These routines provide
	SIN, COS, SINCOS, and ATAN2 using table lookup with a genreal accuracy
	of about 1.0e-6 at speeds 5 to 10 times faster than the math 
	library trig routines.

gnuMake:
	A version of GNU-make, which is needed for RCCL/RCI Makefiles.

h:	
	System-wide include files.


jls:
	New directory in this distribution.  Contains the source code for the
	Joint-Level Servo controller and puma interface through the TRC004/006
	cards.  These files compile to real-time linux (RTLinux) modules that
	are loaded into the kernel.

lib:
	System library, including all archives.

libCtree:
	Source code for Mike Parker's Ctree matcher utility.

localbin:
	Source for some of the non-robot programs go in $RCCL/lib.
	These include the local copies of the C compiler and loader, used
	by RCI, as well as the program 'down' which loads software into
	the Unimation robot controller (see 'lsi11', below).

locallib:
	Source to some miscelaneous additions that were made to libC at 
	McGill have been included here as insurance to make sure everything
	will compile. These routines are contained in the library routine
	lib/libC.a. The routines also include the entry points for the
	system dependent 

lock:
	Directory used by the RCI software to keep lock files for various
	robots and devices, to guard against multiple access by different
	programs.

lsi11:
	Obsolete in this distribution but retained for reference purposes.
	This directory contains a wealth of information about how the
	original VAL system worked.  Original Text follows:

	Source code for the software that is used to replace VAL in the 
	PUMA Mark I, Mark II, and Mark III controllers. This software,
	called 'moper', is downloaded into the Unimation controller were
	it acts as a software interface between the RCI robot control task
	and the joint micros and various I/O devices attached to the
	robot (such as force sensors, joysticks, teach pendants, etc.)

man:
	UNIX style manual pages for the various RCCL and RCI routines.

programs:
	Utility robot programs to calibrate the robot, free its joints,
	and move it to a defined position.

puma:
	Routines specific to the PUMA robots, which perform kinematic 
	computations, set up parameter blocks, and real-time interfacing
	to the controller.

rccl:
	The RCCL trajectory generator and robot control package. 

rci:	The RCI Real-Time Control Interface package, which allows a user
	to create multiple control tasks attached to a UNIX process.

robotTypes:
	Packages which implement various robot data types such as transforms,
	vectors, quaternions, etc.
	
robots:	
	The robot support routines for RCI. These maintain a database of
	robot specific parameters, and also provide access to the
	robot specific interface routines that maintain the data
	structure HOW, which describes the state of the robot,
	and service the various CHG macros which are used to request
	commands of the robot.

robotsim:
	Source code for 'robotsim', the simulator for the PUMA robots. 
	'robotsim' runs as a UNIX process that pretends it is 'moper',
	the software normally loaded into the PUMA robot controller.
	An RCI robot control task can then connect to this program using
	the device 'sim', which opens a socket to 'robotsim' and uses
	this socket to communicate.

rtlinux:
	Not part of the RWRCCL system but retained as potentially useful.
	Contains test utilities and low-level programs for interacting with the
	TRC004/006 card and for creating real-time modules for control.  
	This directory can be used for testing out joint-level control
	programs, testing out loading and unloading modules and testing
	the accuracy of the real-time clock.

servoCode:
	Some listings of assembly code for the joint servos of various
	Unimate Mark X controllers. All of these ``listings'' were obtained
	by disassembling code and then trying our best to figure out what
	is going on.

speedtest:
	Directory containing a standalone program 'speed' for benchmarking 
	robot related computations (specically, forward and inverse 
	kinematics, transform multiplication and inversion, Jacobian
	multiplication, and sine/cosine of an angle.

	The directory is set up to be totally self contained; you just move
	the directory onto a (Berkeley UNIX) system and type 'make'. This
	will create the program 'speed', which is run with one argument
	describing the number of iterations to be made in doing the timing 
	loop.

sys.Sun4:
	RCI system kernel support for SunOS 4.1

sys.uVAX:
	RCI system kernel support for MicroVAX 4.3 BSD

toolbox:
	Miscelanous utility programs used in configuring the system.

util:	Various library utility routines used by the RCI system. These
	routines provide things such as error message handling, 
	generalized vector routines, etc.
