\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{makejls}{1}
\manSection{NAME}
{\tt \manName{makejls}}
-- build {\tt JLS} files for robots.
\manSection{USAGE}
\cverbatim
makejls [-v] <inputFile> <outputFile>
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt -v} --}
Verbose mode. The entire {\tt JLS} structure is printed out as
it is created.
\manItem{{\tt inputFile} --}
An input file containing an ascii specification for a {\tt JLS}
structure.
\manItem{{\tt outputFile} --}
An output file containing the compiled binary data for a 
{\tt JLS} structure.
\manSection{DESCRIPTION}
This program builds the binary file used to store {\tt JLS} structure 
information for different robots.  The binary file is read by the
{\tt <class>_jls} routine for the class of the robot in question, and is
conventionally named 
{\tt <robotName>.JLS}.  The text specification file is usually
named {\tt <robotName>.jls}.

The reason for precompiling the {\tt JLS} information is to increase the
speed and reduce the complexity associated with the {\tt <class>_jls} routine.
A {\tt JLS} specification can be rather elaborate, and compilation
involves parsing many ascii values, computing other values from them,
and (possibly) doing consistency checks.  At the moment, information 
associated with the {\it kinematic} structures is {\bf not} kept in
binary form but is read by the directly by {\tt getKyn} from a text file
(conventionally given a name ending in {\tt .kyn}). 

The format for the ascii {\tt .jls} file is now discussed.

\manInset{NOTICE: The format currently used is rather primitive
and consequently might change at some point.}

In the discussion following, $N$ defines the number of joints,
$C_f$ describes the number of forward coupling constants (off-diagonal
terms of the forward gear ratio matrix),
and $C_i$ describes the number of inverse
coupling constants (off-diagonal terms of the inverse gear ratio matrix).
The forward gear ratio matrix maps joint level displacements into
motor level displacements with the same units (see {\tt JLS(3)}).
{\it integer} implies a decimal integer unless otherwise stated.
{\it float} implies a floating point number acceptable to {\tt scanf()}.
All the following values must be presented, in the order given,
separated by white space.
Values which are not needed for a particular robot should be given as zero.
The character {\tt \#} comments out everything up to the end of the line.

A template {\tt .jls} file is provided in 
{\filefont \$RCCL/conf/template.jls}.
Each file contains the following values in the following order:

\manItem{{\it 1 integer}:}
The number of robot joints, $N$.
\manItem{{\it $N$ characters}:}
The type of each joint, where 'P' indicates a prismatic joint and 'R' 
indicates a revolute one.
\manItem{{\it 1 integer}:}
The number of forward kinematic couplings, $C_f$.
\manItem{{\it $C_f$ integer pairs}:}
The $(i, j)$ coordinates of the off-diagonal terms
of the forward gear ratio matrix.
\manItem{{\it 1 integer}:}
The number of inverse kinematic couplings, $C_i$.
\manItem{{\it $C_i$ integer pairs}:}
The $(i, j)$ coordinates of the off-diagonal terms
of the inverse gear ratio matrix. (These could be computed by the program, but
then it would have to search the inverse matrix and
decide, based on some epsilon value, which numbers were large enough to
qualify as inverse couplings and which weren't. This was more bother than it
was worth.)
\manItem{{\it $N$ + $C_f$ floats}:}
The terms of the forward gear ratio matrix, consisting of the
diagonal terms (in order), followed by the off-diagonal terms
(in the order of the coupling coordinate list).
\manItem{{\it $N$ interger/float pairs}:}
A set of encoder and joint values
used to compute the {\tt encOffset} field. Each encoder value
is followed by the corresponding joint value. Usually the encoder
mid-range values are used, which is 32768 for 16 bit encoders.
\manItem{{\it $N$ integers}:}
The encoder ``wheel size'': the number of encoder counts per motor
shaft revolution.
\manItem{{\it $N$ floats}:}
Motor force to current conversion factor, i.e., the ratio 
that converts motor force (Newton-meters or Newtons) to the output
DAC values for the corresponding current.
\manItem{{\it $N$ floats}:}
Current to motor force conversion factor, i.e., the ratio
that converts input ADC values measuring current into the
corresponding motor force (Newton-meters or Newtons).
\manItem{{\it $N$ integers}:}
The output current bias. If the output currents are not biased, then these
values should all be zero. If any of the output currents are biased, then
the corresponding values should be the output DAC values
that produce a true output current of zero.
\manItem{{\it $N$ integers}:}
The encoder calibration vector.  This is a reference vector used by the
calibration software; its definition depends on the robot in question and how
that robot is calibrated.  For the PUMA robots, these values describe the
location of the first encoder reference point past the encoder value 32768
(0100000).
\manItem{{\it $N$ integers}:}
Calibration reference position.
This contains more calibration information, again with
the exact definition depending on the
robot and the calibration software. For the PUMAs, this field is used only
for the PUMA 260, where it describes the approximate encoder values of the
robot when it is in the nest position.
\manItem{{\it $N$ floats}:}
Slope of the potentiometer-encoder relationship.
On robots that contain calibration potentiometers, the numbers
in this field are the ratios of encoder counts to potentiometer values. 
\manItem{{\it $N$ floats}:}
Intercept of the potentiometer-encoder relationship.
On robots that contain calibration potentiometers, the numbers
in this field are the encoder values that would correspond to 
potentiometer readings of 0.
\manItem{{\it $N$ floats}:}
The minimum position for each joint, in either degrees or mm.\
\manItem{{\it $N$ floats}:}
The maximum position for each joint, in either degrees or mm.\
\manItem{{\it $N$ floats}:}
The maximum velocity for each joint, in either degrees or mm.\ per sec.
\manItem{{\it $N$ floats}:}
The maximum acceleration for each joint, in either degrees 
or mm.\ per sec$^2$ (the values in this field are not presently
used, and so can be roughly guessed or left as 0).
\manItem{{\it $N$ floats}:}
The maximum jerk for each joint, in either degrees or mm.\ per sec$^3$
(the values in this field are not presently
used, and so can be roughly guessed or left as 0).
\manItem{{\it $N$ floats}:}
The maximum motor force for each joint (Newton-meters or Newtons).
\manItem{{\it $N$ floats}:}
The maximum joint force for each joint (Newton-meters or Newtons).
\manItem{{\it $N$ floats}:}
The park position for the robot, in either degrees or mm.\
\manItem{{\it $N$ floats}:}
The ``best'' position for the robot, in either degrees or mm.\
This is an optimal position where the robot is far from joint limits and very
well conditioned. It can be used as a reference position by application
software in computing default control characteristics.
\manItem{{\it $N$ floats}:}
A set of nominal desired velocities for the robot, 
in degrees or mm.\ per sec.
\manItem{{\it $N$ floats}:}
A set of nominal desired accelerations for the robot, 
in degrees or mm.\ per sec$^2$.
\manItem{{\it $N$ floats}:}
A set of nominal desired jerks for the robot, in degrees or mm.\ per sec$^3$.
\manItem{{\it 1 hex int}:}
Robot specific flags.

The number of joints $N$ 
must not exceed {\tt MAXJNTS} ({\tt <maxjnts.h>}),
and the number of forward or inverse
kinematic couplings must not exceed {\tt MAXC} ({\tt
<robot_jls.h>}).

\manSection{DIAGNOSTICS}
Diagnostic messages are printed if the program fails for any reason.
\manSection{SEE ALSO}
\raggedright
{\tt JLS(3)}, {\tt getJls(3)}.
\manEnd
\end
