\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{MANIP}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{MANIP}}
-- RCCL manipulator structure.
}
\manSection{DEFINITION}
We describe here only those parts of the {\tt MANIP} data structure
which are of interest to the RCCL programmer.
\cverbatim

   /* 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;
@endcverbatim
\manSection{DESCRIPTION}
The {\tt MANIP} structure is the handle that an RCCL program uses
to control a particular manipulator.
A {\tt MANIP} structure is allocated
and returned by {\tt rcclCreate()}.  It is then 
used to reference 
the manipulator in subsequent calls to the various motion
primitives.

The fields in the {\tt 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 {\it virtual} manipulators (abstract
Cartesian frames that can be moved around like robots but have
no real robot attached to them), some fields in {\tt MANIP}
which are robot specific will not be relevant and their values will be
set to zero.

\manSection{FIELDS}

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

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

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

\manItem{{\tt 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 {\tt movej()}), then
{\tt tool} is assigned the value of the identity transform.
The transform itself is allocated internally
using {\tt allocTrans()}.

\manItem{{\tt rest} --}
The value of T6 corresponding to the
robot's park position, which is defined by the park joint values in the
robot's {\tt JLS} data structure (q.v.). The {\tt rest} transform is computed
by applying forward kinematics to these park joint values.
For virtual manipulators, the {\tt 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 {\tt park} (see below).
The transform itself is allocated internally
using {\tt allocTrans()}.

\manItem{{\tt lastTC} --}
This is the T6 {\it target} value for the most
recently completed motion. It differs from the
{\tt here} field in that it represents the {\it 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''.
{\tt lastTC} is always updated at the {\it beginning} of the transition to
the current motion.
The transform itself is allocated internally
using {\tt allocTrans()}.

\manItem{{\tt park} --}
A position data structure describing the equation
\manIfTeX
$$
{\rm T6} \;=\; {\rm REST},
$$
\manElse
\cverbatim
        T6 = REST,
@endcverbatim
\manFi
which defines a default park position for the manipulator.

\manItem{{\tt last} --}
A position data structure describing the equation
\manIfTeX
$$
{\rm T6} \;=\; {\rm HERE}.
$$
\manElse
\cverbatim
        T6 = HERE.
@endcverbatim
\manFi
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 {\tt distance()} (or {\tt 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.

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

\manItem{{\tt 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 {\TT T6O_EVAL} is set for the manipulator in
question (see {\tt rcclSetModes(3)}).
{\tt j6o} points to an internally allocated RCI memory object.

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

\manItem{{\tt 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 {\tt jbiasSelect()}
(q.v.), and related functions.

\manItem{{\tt handPos} --}
An integer describing the robot's hand position. For simple open-close
grippers, a value of {\tt 0} indicates a closed gripper, and a value of {\tt 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 {\tt NULL}.

\manItem{{\tt rbt} --}
The RCI robot descriptor for the robot associated with the {\tt 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 {\tt MANIP}
structure). 
The {\tt RCI_RBT} structure is also the handle used for sending low level
commands to the robot, and its attached sensors,
with the {\tt CHG} macros (q.v.).

\manItem{{\tt how} --}
Pointer to the robot's {\tt 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 {\tt HOW} structure information is automatically transfered into
other {\tt MANIP} fields. For instance, the current joint values
can be obtained from the {\tt j6o} field.

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

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

\manItem{{\tt var} --}
Pointer to a {\tt 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 {\tt VAR} structure in
lieu of position values, and can use its information
for faster computation of results. Because the exact definition
of the {\tt VAR} structure depends on the robot's class,
it is referenced using a generic pointer. 

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

\manSection{SEE ALSO}
\raggedright
{\tt rcclCreate(3)}, {\tt allocTrans(3)}, {\tt RCI_RBT(3)}, {\tt HOW(3)},
{\tt JLS(3)}, {\tt KYN(3)}, {\tt VAR(3)}, {\tt allocMem(3)},
{\tt rcclSetModes(3)}.
\manEnd
\end
