MANIP(3)

NAME
MANIP -- RCCL manipulator structure.

DEFINITION
We describe here only those parts of the MANIP data structure which are of interest to the RCCL programmer.
   /* Cartesian level information */

   TRSF *t6;
   TRSF *t6o;
   TRSF *here;
   TRSF *tool;
   TRSF *rest;
   TRSF *lastTC;

   POS *park;
   POS *last;

   /* Joint level information, for real robots only */

   JNTS *j6;
   JNTS *j6o;
   JNTS *jvel;
   JNTS *jbias;
   int handPos;

   /* robot interface structures */

   RCI_RBT *rbt;
   HOW *how;
   JLS *jls;
   KYN *kyn;
   void *var;

DESCRIPTION
The MANIP structure is the handle that an RCCL program uses to control a particular manipulator. A MANIP structure is allocated and returned by rcclCreate(). It is then used to reference the manipulator in subsequent calls to the various motion primitives.

The fields in the MANIP structure which are visible to the programmer are maintained by the trajectory generator and are intended to be read-only.

In the case of virtual manipulators (abstract Cartesian frames that can be moved around like robots but have no real robot attached to them), some fields in MANIP which are robot specific will not be relevant and their values will be set to zero.

FIELDS

t6 --
    The output manipulator T6 transform, computed by the trajectory generator for each control cycle. The transform itself is allocated internally using allocTrans() (q.v.).

t6o --
    The actual observed value of T6 read back from the manipulator each control cycle. This field is only updated if the mode "T6O_EVAL" is set for the manipulator (see rcclSetModes(3)). The transform itself is allocated internally using allocTrans() (q.v.).

here --
    A copy of t6 made at the end of the most recently completed motion, during the transition to the current motion. If the mode COMPLETE_AT_TB is set (which it is by default; see rcclSetModes(3)) then the copy is made at the midpoint of the transition. Otherwise, the copy is made at the beginning of the transition. here is also updated whenever the manipulator becomes "idle" (i.e., all requested motions have finished and it has halted). The here transform is used to define the manipulator-specific position equation last (see below). The transform itself is allocated internally using allocTrans().

tool --
    The manipulator TOOL transform, maintained and constantly updated by the trajectory generator. The tool transform is defined to be that part of the target position equation between T6 and the TOOL frame. If no tool frame is defined, or the current motion target is not specified by a position equation (e.g., the motion was specified using movej()), then tool is assigned the value of the identity transform. The transform itself is allocated internally using allocTrans().

rest --
    The value of T6 corresponding to the robot's park position, which is defined by the park joint values in the robot's JLS data structure (q.v.). The rest transform is computed by applying forward kinematics to these park joint values. For virtual manipulators, the rest transform is given the value of the identity matrix (although more imaginative ideas are welcomed!). The value of the transform does not change. It is used to define the manipulator-specific position equation park (see below). The transform itself is allocated internally using allocTrans().

lastTC --
    This is the T6 target value for the most recently completed motion. It differs from the here field in that it represents the desired target for the last motion request. The difference is due to the smooth transition from one motion to another, which may prevent T6 from actually passing through the target point of the first motion. For more insight into this, consult the "RCCL User's Guide". lastTC is always updated at the beginning of the transition to the current motion. The transform itself is allocated internally using allocTrans().

park --
    A position data structure describing the equation
            T6 = REST,

    which defines a default park position for the manipulator.

last --
    A position data structure describing the equation
            T6 = HERE.

    This defines the location in space that the manipulator occupied at the completion of the last path segment, and can be used in conjunction with distance() (or setDistance()) to specify relative motions.

The following fields are maintained only for manipulators associated with a real robot; their values are either undefined or zero for virtual manipulators.

j6 --
    The output joint values, computed by the trajectory for each control cycle. j6 points to an internally allocated RCI memory object.

j6o --
    The actual observed values of the joint values, read back from the robot controller each control cycle. This field is updated only if the mode "T6O_EVAL" is set for the manipulator in question (see rcclSetModes(3)). j6o points to an internally allocated RCI memory object.

jvel --
    Output joint velocity, computed by the trajectory generator by differencing successive values of j6. Note that the units are radians (or mm.) per control cycle, and not radians per second. jvel points to an internally allocated RCI memory object.

jbias --
    A set of joint values that define an offset bias to be applied to the manipulator's current setpoint. This provides a joint-space equivalent to having variable Cartesian transforms in the target position. Joint biasing is enabled only if invoked explicitly using jbiasSelect() (q.v.), and related functions.

handPos --
    An integer describing the robot's hand position. For simple open-close grippers, a value of 0 indicates a closed gripper, and a value of 1 indicates an open gripper.

The next set of fields point to the various information structures associated with a real robot. For virtual manipulators, these pointers are set to NULL.

rbt --
    The RCI robot descriptor for the robot associated with the MANIP structure. This is the RCI level interface to the robot. It contains pointers to various structures describing robot parameters and feedback information (although duplicate pointers to these structures are also provided in the MANIP structure). The RCI_RBT structure is also the handle used for sending low level commands to the robot, and its attached sensors, with the CHG macros (q.v.).

how --
    Pointer to the robot's HOW structure (q.v.). This contains run-time feedback information from the robot controller, such as the current joint and sensor input values. Note that some of the HOW structure information is automatically transfered into other MANIP fields. For instance, the current joint values can be obtained from the j6o field.

jls --
    Pointer to the robot's JLS structure (q.v.). This contains fixed parameters describing the robot at the joint level, such as gear ratios and actuator limits.

kyn --
    Pointer to the robot's KYN structure (q.v.). This contains fixed parameters describing the robot at the kinematic/dynamic level, such as "A" matrix offsets and various dynamical terms. The KYN structure is also the main reference argument to the various kinematic and dynamic computation routines (such as fwdKinematics() or invJacob()).

var --
    Pointer to a VAR structure (q.v.) for the robot. This contains run-time computed terms associated with the kinematic and dynamic computations, such as the sines and cosines of the joint values and Jacobian coefficients. Generally, these terms depend on the robot's position. By keeping them around in a structure, they only have to be recomputed when the robot's position changes. Certain kinematic and dynamic computation routines accept the VAR structure in lieu of position values, and can use its information for faster computation of results. Because the exact definition of the VAR structure depends on the robot's class, it is referenced using a generic pointer.

    NOTE: The VAR structure provided in the MANIP structure should only be referenced by the user, and never modified, because it is used and automatically updated by the RCCL trajectory generator.

SEE ALSO
rcclCreate(3), allocTrans(3), RCI_RBT(3), HOW(3), JLS(3), KYN(3), VAR(3), allocMem(3), rcclSetModes(3).