\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{RCCL params}{5}
\manSection{NAME}
{\tt \manName{RCCL_params}}
-- RCCL parameters set.
\manSection{DESCRIPTION}
This is the set of parameters defined in the file {\tt .rciparams}
which controls various default behaviours of a user's RCCL program. The 
parameter set is read in once by the program during the first call to {\tt
rcclCreate()}. 

The default {\tt .rciparams} file lives in {\filefont \$RCCL/conf}.
Private copies may be placed in the 
user's home directory or in the current directory. Definitions
in the latter files take precedence over definitions in the former
files.

Not everything in a {\tt .rciparams} file relates to RCCL. This file
contains definitions for all the parameter sets associated with the
general RCI parameter set utility.
RCCL parameters are contained within the {\tt RCCL} parameter set, 
which is marked within the file by the syntax {\tt name=RCCL}.

For general
information on the syntax by which parameters are defined
within a {\tt .rciparams} file, see {\tt rciParameters(3)}.

The keywords associated with the parameter set are:

\manItem{{\tt cpus} --}
If the RCCL system has been installed on top of an RCI system that
can control auxiliary CPUs, then these CPUs may be used to run the
RCCL trajectory generator.
{\tt cpus} is a bitmask describing exactly which CPUs the system has
available.
CPU 0 is the arbiter, or UNIX, cpu. Other numbers denote auxiliary
CPUs. For example, if no auxiliary CPUs are available,
this is indicated 
by the entry {\tt cpus=0x1}.
If auxiliary CPUs 1 and 2 are available, and it is desired to run the RCCL
trajectory generator on them and {\bf not} on the arbiter CPU,
then the entry {\tt cpus=0x6} would be appropriate.
A second cpu mask can be optionally specified as an argument
to {\tt rcclCreate()}. If this is done, then the two masks are
anded together to yield the set of CPUs that
can actually be used.

\manItem{{\tt simulate} --}
An optional parameter, which, if set to 1, instructs the RCCL program to run
in simulator mode. This means that it will execute as a
single RCI task on the arbiter
CPU, running in user mode and being driven by the UNIX {\tt SIGALRM} signal.
If the RCCL program is controlling real robots (as opposed to just
virtual manipulators), then the program will try to attach to a simulator
program for each real robot being controlled (see {\tt robotsim(1)}).
If the parameter {\tt simulate} is absent, then it is assumed we are {\bf not}
running in simulator mode.

\manItem{}
By default, when asked to run in simulator mode, RCCL will attempt to
connect to a simulator program running on the current machine under the
current user name. It is possible to specify a different simulator
program (such as one running on a remote machine) by setting the 
{\tt simulate} parameter to a string which identifies the desired
simulator. For a description of the format of this string, see
{\tt simAddress(5)}.

\manItem{{\tt interval} --} 
The default sample interval for the RCCL trajectory
generator to run at (in milliseconds).
This interval can be changed from within the program using the {\tt
rcclSetInterval()} command. When running in simulator mode, it is sometimes a 
good idea to use a longer interval, since the simulator software
is slow, and a lower sample rate will
allow it to still execute close to ``real-time''.
Entries of the following 
form are not uncommon:
\cverbatim
                simulate=1  interval=200
@endcverbatim
\manItem{}
This tells the program to run in simulator mode with a sample interval
of 200 milliseconds.

\manItem{{\tt timeout} --}
An optional integer parameter
describing the default timeout count for the RCCL trajectory
generator. This is the length of time that the control level
will wait to communicate with its external devices (usually
robot controllers) before timing out. The length of time is
given in units of nominal control cycles. 
For example, if the timeout count is 5, and the trajectory generator is
running
at a 30 msec. sample interval, then the system will wait up to 150 msec.
for its external devices to respond before
declaring a timeout.
Assuming that the timeout count is not set
unreasonably 
low (e.g., 1), about the only reason for a timeout to occur
is a failure on the external device.
Uneven control level execution,
such as caused by high priority system activity, might 
also cause some difficulties, although this can usually be defeated by setting
{\tt timeout} to some large number (like 10).
If {\tt timeout} is not defined, a default value of 2 is assumed.

\manItem{{\tt speed} --}
An optional floating point parameter defining a program speed
scale.
The speeds of all robot motions are mutiplied by this number,
which gives the user the ability to change program speed without
recompiling. The scaling effect of this parameter is applied
over and above the speed scale set within the program by the
{\tt setSpeed()} primitive.
If the parameter is not defined, a default value of 1.0 is assumed.
A negative value will {\bf not} make the robot go backwards;
it is converted to a positive value instead.

\manItem{{\tt tvel} --}
An optional parameter giving the default translational velocity for
manipulators in units of millimeters per second. This applies only to
Cartesian interpolated motions. If this parameter is not specified,
the defined constant {\tt DEFAULT_TRANS_VEL} is used instead.

\manItem{{\tt rvel} --}
An optional parameter giving the default rotational velocity for manipulators
in units of degrees per second. This applies only to
Cartesian interpolated motions. If this parameter is not specified,
the defined constant {\tt DEFAULT_ROT_VEL} is used instead.

\manItem{{\tt scheduling} --}
Specifies the scheduling discipline for the trajectory generator.
This determines the mechanism by which the trajectory generator is
``woken up'' for each control cycle, and should be one of the following
strings:

\manItem{{\tt ON_FUNCTION} --}
The timing for the trajectory generator is provided
by the robot controller instead
of the RCI system clock. This means that the 
parameter {\tt interval}, mentioned above, should be
consistent with the control intervals that the robot controller is capable of
delivering. The typical Unimation PUMA controller can deliver accurate control
intervals of 7, 14, 28, 56, or 128 milliseconds.

\manItem{}{\bf NOTE: {\tt ON_FUNCTION} is not designed to work properly
for programs that are controlling more than one robot. It will also
not work if no real robot is attached (i.e., only virtual
manipulators are being controlled).}

\manItem{{\tt ON_CLOCK} --}
{\tolerance=10000
The trajectory generator timing is determined by the RCI
system clock. When the trajectory task is woken up, it
signals the robot controllers to collect
feedback data, and then waits for them to return this
data. 
Using this scheduling
discipline means that the {\tt interval} parameter should be set to some
multiple of the RCI system clock resolution. On most present
systems, this resolution is around 10 milliseconds. The resolution
may be smaller if RCI has the support of a hardware clock device.

}
\manItem{{\tt ON_TRIGGER} --}
{\tolerance=10000
The trajectory generator timing is determined by the RCI
system clock, but indirectly: the system clock invokes a short
function that ``kicks'' the robot controllers and tells them to
start the next control cycle. After they have prepared their
feedback data, the robot controllers then wake up the
trajectory task itself, with the same interrupt
mechanism used by {\tt ON_FUNCTION}
scheduling. This way, the trajectory generator does not waste time
waiting for the robot controllers to finish collecting their feedback data
(a process which can take one or two milliseconds).
Using this scheduling
discipline means that the {\tt interval} parameter should be set to some
multiple of the RCI system clock resolution. 

}

\manItem{{\tt leavePowerOn} --}
An optional integer parameter which, if set to a true (non-zero) value,
causes the option {\tt RCCL_LEAVE_POWER_ON} to be set during
the first call to {\tt rcclCreate()}. This will in turn prevent 
the robot arm power from being switched off when the control
level is released, regardless of the value of the {\tt powerOff}
argument passed to {\tt rcclRelease()}. The power will still be switched off
if the control level terminates with an RCI abort.
The default value for this parameter is false.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rcclCreate(3)}, {\tt rciParameters(3)}, {\tt robotsim(1)},
{\tt rcclSetInterval(3)}, {\tt setSpeed(3)}.

\manEnd
\end
