\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{JLS}{3}
\manSection{NAME}
{\tt \manName{JLS}}
-- RCI data structure describing robot ``joint level stuff''.
\manSection{DEFINITION}
\cverbatim
#include <maxjnts.h>

typedef struct _JLS {

/* Basic stuff */

    int numJ;
    int numFC;
    int numIC;
    int forCouplings [MAXC][2];
    int invCouplings [MAXC][2];
  float forGearRatios [MAXJNTS+MAXC];
  float invGearRatios [MAXJNTS+MAXC];

/* Position stuff */

  float angtoenc [MAXJNTS+MAXC];
  float enctoang [MAXJNTS+MAXC];
    int encOffset [MAXJNTS];

/* Torque stuff */

  float mtorqueToCurrent [MAXJNTS];
  float currentToMtorque [MAXJNTS]; 
    int currentBias [MAXJNTS];

/* calibration stuff */

    int encWheelSize [MAXJNTS];
    int encCalvec [MAXJNTS];
    int encHome [MAXJNTS];
  float potSlope [MAXJNTS];
  float potIntercept [MAXJNTS];

/* Range information */

   char jtype [MAXJNTS+1];
  float jmin [MAXJNTS];
  float jmax [MAXJNTS];
  float jrng [MAXJNTS];
  float maxVel [MAXJNTS];
  float maxAcc [MAXJNTS];
  float maxJerk [MAXJNTS];

  float maxMtorque [MAXJNTS];
  float maxJtorque [MAXJNTS];

/* Utility information */

  float parkAngles [MAXJNTS];
  float bestAngles [MAXJNTS];
  float averageGearRatio;
  float averageAngtoenc;
  float nominalVel [MAXJNTS];
  float nominalAcc [MAXJNTS];
  float nominalJerk[MAXJNTS];
  float averageVel;
  float averageAcc;
  float averageJerk;
   long flags;

/* Conversion functions */

    int (*encoderToAngle)();
    int (*angleToEncoder)();
    int (*encoderToJoint)();
    int (*jointToEncoder)();
    int (*mtorqueToJtorque)();
    int (*jtorqueToMtorque)();
} JLS; @endcverbatim
\manSection{DESCRIPTION}
The {\tt JLS} data structure implements a simple database
of constants that effectively 
define the ``joint level'' of a particular robot. This includes things
such as gear ratios, encoder to position conversions, and
various operating limits. The structure does not define kinematic or
dynamic parameters; that is done in robot specific structures (see
{\tt KYN(3)}).

In a general program, the {\tt JLS} structure for a particular
robot is obtained by calling the function {\tt getJls()} (q.v.) with the name
of the robot in question. {\tt getJls()} will then call a robot specific
function that instantiates the data structure, reading in most
of the information from a binary ``{\tt .JLS}'' file assigned to the robot
in question. The {\tt .JLS} file lives in the directory 
{\filefont \$RCCL/conf},
and is automatically created from an ascii {\tt .jls} file by the program {\tt
makejls}. By changing constants in the {\tt .jls} file,
robot specific information can be modified without
having to recompile programs.

\manInset{{\bf NOTE}: In the VxWorks implementation, {\tt JLS}
information is read directly from the ascii {\tt .jls} file.
Use of the binary {\tt .JLS} file may disappear completely in future 
RCCL/RCI releases.} 

RCI programs which need to reference the {\tt JLS} structure from the
control level should use {\tt rciGetJls()} (q.v.) instead of {\tt getJls()}.

A {\tt JLS} structure is allocated automatically for robots
which are attached to an RCI control task, and a pointer to
this structure is placed in the {\tt jls} field
of the task's robot structure
{\tt RCI_RBT} (q.v.).
Thus, given a task descriptor {\tt td} and the index {\tt num}
returned by {\tt rciAttachRobot()}, the {\tt JLS} structure
can be obtained as follows:
\cverbatim
        JLS *jls;

        jls = TASKROBOT(td, num)->jls; @endcverbatim
\noindent
RCCL programs can obtain this pointer directly from the {\tt jls}
field of the robot's {\tt MANIP} structure.

Some of the items contained in the {\tt JLS} structure can be derived
from each other but are presented explicitly to save computation time.

\manSection{FIELDS}

\manItem{{\tt numJ} --}
The number of joints in the robot. The maximum number of joints that
any {\tt JLS} structure can handle is {\tt MAXJNTS}, defined
in {\tt <maxjnts.h>}.

In the following descriptions, the {\it forward
gear ratio matrix} describes the matrix that transforms joint displacements
into motor shaft displacements. The inverse of this matrix
is the {\it inverse gear ratio matrix}.

\manItem{{\tt numFC} --}
The number of forward kinematic couplings.
It sometimes happens
in a robot that a motor shaft will not be coupled directly to its
corresponding joint, but rather is kinematically coupled to several joints.
Put formally, this means the gear ratio matrix
contains off diagonal-terms.
A common example of this occurs in the
wrist joints of several types of robots, including the PUMA. 
{\tt numFC} is the number of off-diagonal terms in the
forward gear ratio matrix.
\manItem{{\tt numIC} --}
The number of inverse kinematic couplings.
If the forward gear ratio matrix contains off-diagonal terms, then
the inverse gear ratio matrix will as well. {\tt numIC} is the
number of off-diagonal coupling terms in the inverse gear ratio
matrix.
\manItem{{\tt forCouplings} --}
This is a list of the ($i$, $j$) 
coordinates of the forward kinematic couplings, arranged in
row-column order.
\manItem{{\tt invCouplings} --}
This is a list of the ($i$, $j$) 
coordinates of the inverse kinematic couplings, arranged in
row-column order.
\manItem{{\tt forGearRatios} --}
The terms of the forward gear ratio matrix. There are {\tt numJ}
diagonal terms, followed by {\tt numFC} off-diagonal terms. The coordinates
associated with the coupling terms are listed in {\tt forCouplings}.
\manItem{{\tt invGearRatios} --}
The terms of the inverse gear ratio matrix. There are {\tt numJ}
diagonal terms, followed by {\tt numIC} off-diagonal terms. The coordinates
associated with the coupling terms are listed in {\tt invCouplings}.
\manItem{{\tt angtoenc} --}
The terms of the matrix that converts from joint values 
(given in radians or mm.) to encoder counts. This matrix is formed
by pre-multiplying the forward gear ratio matrix by a diagonal matrix
whose elements are {\tt encWheelSize[j]} (see field below) divided by
$\pi$. It hence contains the same number of off-diagonal terms, in the same
locations, as the forward gear ratio matrix.
\manItem{{\tt enctoang} --}
This is the inverse of the {\tt angtoenc} matrix described above.
It contains the same number of off-diagonal terms, in the same
locations, as the inverse gear ratio matrix.
\manItem{{\tt encOffset} --}
Simply stated, these are the encoder values that correspond to
joint values of 0.0.
\manItem{{\tt mtorqueToCurrent} --}
These ratios convert motor shaft force (Newton-meters or Newtons)
into the corresponding output DAC value to control joint current.
\manItem{{\tt currentToMtorque} --}
These ratios convert input ADC values measuring joint
current into the corresponding motor shaft force
(Newton-meters or Newtons).
\manItem{{\tt currentBias} --}
In case the motor current outputs are biased, these values give the
output DAC values which result in zero output torque. In other
words, these are the DAC values which produce a true zero output 
current.
\manItem{{\tt encWheelSize} --}
The number of encoder counts per motor shaft revolution. (We assume that
we are working with rotary motors, although this assumption is not
critical.)
\manItem{{\tt encCalvec} --}
Encoder calibration vector. How this information is used for calibration
can vary from robot to robot. On robots which calibrate using shaft
encoder reference points (like the PUMA), each of
these values represents the reference point nearest to some constant
value (32768, or 0100000, for the PUMA).
\manItem{{\tt encHome} --}
This can be used to store the encoder counts corresponding to the
robot {\it home} position, if it has one, or the approximate location of
some fixed calibration position (like the ``nest'' for the PUMA 260).
\manItem{{\tt potSlope}, {\tt potIntercept} --}
On robots that have calibration potentiometers, this information is
used to estimate the encoder position from the potentiometer readings.
{\tt potSlope} contains the ratio of encoder counts to potentiometer values,
while {\tt potIntercept} contains the encoder counts that would correspond
to potentiometer readings of 0.
\manItem{{\tt jtype} --}
Joint type. The character 'P' indicates a prismatic joint, and the
character 'R' indicates a revolute joint. The array is null terminated so that
it can be printed as a string.
\manItem{{\tt jmin} --}
Minimum joint values (radians or mm.).
\manItem{{\tt jmax} --}
Maximum joint values (radians or mm.).
\manItem{{\tt jrng} --}
Range of the joint ({\tt jmax} - {\tt jmin}).
\manItem{{\tt maxVel} --}
Maximum joint velocity (radians/sec. or mm./sec.).
\manItem{{\tt maxAcc} --}
Maximum joint acceleration (radians/sec$^2$ or 
mm./sec$^2$).
\manItem{{\tt maxJerk} --}
Maximum joint jerk (radians/sec$^3$ or 
mm./sec$^3$).
\manItem{{\tt maxMtorque} --}
Maximum motor shaft force (Newton-meters or Newtons).
\manItem{{\tt maxJtorque} --}
Maximum joint force (Newton-meters or Newtons).
\manItem{{\tt parkAngles} --}
Joint values (radians or mm.) corresponding to the robot's ``park'' position.
\manItem{{\tt bestAngles} --}
Joint values (radians or mm.) corresponding to a position where the robot
is very well-conditioned; i.e., its Jacobian is well behaved and Cartesian
velocities can be converted to joint velocities easily. This position should
also be far away from the joint limits. It
represents an ``ideal'' work position
for the robot, and can be used by application
software in computing various default velocity and acceleration
characteristics.
\manItem{{\tt averageGearRatio} --}
This is the root-mean-square
average of all the diagonal terms of the forward gear ratio
matrix.
\manItem{{\tt averageAngtoenc} --}
This is the root-mean-square
average of all the diagonal terms of the {\tt angtoenc}
matrix.
\manItem{{\tt nominalVel} --}
A set of nominal robot joint velocities (radians or mm.
per second).
This is intended for use by programs that want to look up what a
``reasonable'' speed is for a particular robot.
\manItem{{\tt nominalAcc} --}
A set of nominal robot joint accelerations (radians or mm.
per sec$^2$).
\manItem{{\tt nominalJerk} --}
A set of nominal robot joint jerks (radians or mm. per sec$^3$).
\manItem{{\tt averageVel}, {\tt averageAcc}, {\tt averageJerk} --}
Average values for the {\tt nominalVel}, {\tt nominalAcc}, and
{\tt nominalJerk} fields. Not necessarily useful, but we put it in
any case.
\manItem{{\tt velScale} --}
Scaling factors for the robot joint velocities. If the robot joint
speed is given by a single number `x', then these values are the
amount that `x' should be scaled by to obtain the actual desired
speed for each joint. This information is useful
because individual robot joints often differ greatly in proportion
(and correspondingly in desired speed).
\manItem{{\tt flags} --}
{\tolerance=10000
Miscellaneous robot-specific flags. For the PUMA robot, the flag
{\tt PUMA_260}, defined in {\tt <puma_jls.h>}, indicates that the
robot is a PUMA 260 (this information is needed for calibration
purposes).

}

Conversion functions are made available in the {\tt JLS} structure
because different robots may use different functions. The main
reason for doing this is speed
(and possibly some characteristic not well described by the
explicit information the structure). Robot specific functions can
be highly optimized (for instance, they can be ``unrolled'': all
of the looping can be removed since the number of joints is known).
The function pointers are instantiated by the robot specific
{\tt getJls()} routine. All functions placed in these fields
should conform to the interface specification of the generic conversion
functions (see {\tt encoderToAngle(3)}).
\manItem{{\tt encoderToAngle} --}
Function that converts encoder counts to joint values.
\manItem{{\tt angleToEncoder} --}
Function that converts joint values to encoder counts.
\manItem{{\tt encoderToJoint} --}
Function that converts encoder {\it displacements} to joint displacements;
i.e., a velocity transformation.
\manItem{{\tt jointToEncoder} --}
Function that converts joint {\it displacements} to encoder displacements;
i.e., a velocity transformation.
\manItem{{\tt mtorqueToJtorque} --}
Function that converts motor shaft force to joint force.
\manItem{{\tt jtorqueToMtorque} --}
Function that converts joint force to motor shaft force.

Not all of the limit information described by {\tt JLS} is necessarily
used; what checking is actually performed is up to the robot interface 
functions and the application software.

\manSection{SEE ALSO}
\raggedright
{\tt getJls(3)}, {\tt rciGetJls(3)}, {\tt makejls(1)}, {\tt
rciAttachRobot(3)}, {\tt TASKROBOT(3)},  
{\tt encoderToAngle(3)}, {\tt RCI_RBT(3)}.
\manEnd
\end
