JLS(3)

NAME
JLS -- RCI data structure describing robot "joint level stuff".

DEFINITION
#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;

DESCRIPTION
The 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 KYN(3)).

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

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

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

A 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 jls field of the task's robot structure RCI_RBT (q.v.). Thus, given a task descriptor td and the index num returned by rciAttachRobot(), the JLS structure can be obtained as follows:
        JLS *jls;

        jls = TASKROBOT(td, num)->jls;

RCCL programs can obtain this pointer directly from the jls field of the robot's MANIP structure.

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

FIELDS

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

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

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. numFC is the number of off-diagonal terms in the forward gear ratio matrix.

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. numIC is the number of off-diagonal coupling terms in the inverse gear ratio matrix.

forCouplings --
    This is a list of the (i, j) coordinates of the forward kinematic couplings, arranged in row-column order.

invCouplings --
    This is a list of the (i, j) coordinates of the inverse kinematic couplings, arranged in row-column order.

forGearRatios --
    The terms of the forward gear ratio matrix. There are numJ diagonal terms, followed by numFC off-diagonal terms. The coordinates associated with the coupling terms are listed in forCouplings.

invGearRatios --
    The terms of the inverse gear ratio matrix. There are numJ diagonal terms, followed by numIC off-diagonal terms. The coordinates associated with the coupling terms are listed in invCouplings.

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 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.

enctoang --
    This is the inverse of the angtoenc matrix described above. It contains the same number of off-diagonal terms, in the same locations, as the inverse gear ratio matrix.

encOffset --
    Simply stated, these are the encoder values that correspond to joint values of 0.0.

mtorqueToCurrent --
    These ratios convert motor shaft force (Newton-meters or Newtons) into the corresponding output DAC value to control joint current.

currentToMtorque --
    These ratios convert input ADC values measuring joint current into the corresponding motor shaft force (Newton-meters or Newtons).

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.

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.)

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).

encHome --
    This can be used to store the encoder counts corresponding to the robot home position, if it has one, or the approximate location of some fixed calibration position (like the "nest" for the PUMA 260).

potSlope, potIntercept --
    On robots that have calibration potentiometers, this information is used to estimate the encoder position from the potentiometer readings. potSlope contains the ratio of encoder counts to potentiometer values, while potIntercept contains the encoder counts that would correspond to potentiometer readings of 0.

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.

jmin --
    Minimum joint values (radians or mm.).

jmax --
    Maximum joint values (radians or mm.).

jrng --
    Range of the joint (jmax - jmin).

maxVel --
    Maximum joint velocity (radians/sec. or mm./sec.).

maxAcc --
    Maximum joint acceleration (radians/sec^2 or mm./sec^2).

maxJerk --
    Maximum joint jerk (radians/sec^3 or mm./sec^3).

maxMtorque --
    Maximum motor shaft force (Newton-meters or Newtons).

maxJtorque --
    Maximum joint force (Newton-meters or Newtons).

parkAngles --
    Joint values (radians or mm.) corresponding to the robot's "park" position.

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.

averageGearRatio --
    This is the root-mean-square average of all the diagonal terms of the forward gear ratio matrix.

averageAngtoenc --
    This is the root-mean-square average of all the diagonal terms of the angtoenc matrix.

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.

nominalAcc --
    A set of nominal robot joint accelerations (radians or mm. per sec^2).

nominalJerk --
    A set of nominal robot joint jerks (radians or mm. per sec^3).

averageVel, averageAcc, averageJerk --
    Average values for the nominalVel, nominalAcc, and nominalJerk fields. Not necessarily useful, but we put it in any case.

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).

flags --
    Miscellaneous robot-specific flags. For the PUMA robot, the flag PUMA_260, defined in <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 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 getJls() routine. All functions placed in these fields should conform to the interface specification of the generic conversion functions (see encoderToAngle(3)).

encoderToAngle --
    Function that converts encoder counts to joint values.

angleToEncoder --
    Function that converts joint values to encoder counts.

encoderToJoint --
    Function that converts encoder displacements to joint displacements; i.e., a velocity transformation.

jointToEncoder --
    Function that converts joint displacements to encoder displacements; i.e., a velocity transformation.

mtorqueToJtorque --
    Function that converts motor shaft force to joint force.

jtorqueToMtorque --
    Function that converts joint force to motor shaft force.

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

SEE ALSO
getJls(3), rciGetJls(3), makejls(1), rciAttachRobot(3), TASKROBOT(3), encoderToAngle(3), RCI_RBT(3).