\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{KYN,VAR}{3}
\manSection{NAME}
{\tt \manName{KYN}},
{\tt \manName{VAR}}
-- RCI data structures describing kinematic parameters and terms.

\manSection{DEFINITION}

\cverbatim
typedef struct _KYN {
   GEN_KYN *gen; /* generic component */
   void *ext;    /* robot specific component */
} KYN;

void *var;       /* whole thing is robot specific */

@endcverbatim

\manSection{DESCRIPTION}

\manSubSection{The KYN Structure}

The {\tt KYN} data structure is a read-only structure which defines
(1) parameters relating to the kinematic and dynamic characteristics
of the robot (such as ``A'' matrix offsets), and (2) pointers to
internal routines which implement kinematic and dynamic calculations
for that robot's class. 

The {\tt KYN} structure itself contains two sub-fields:

\manItem{{\tt gen} --}
References a {\tt GEN_KYN} structure, which contains
certain types of information generic to all serial-link robots.
This includes the Denavit-Hartenburg parameters for the links,
as well as friction terms. Terms such as the link inertias
and masses are being added at the time of this writing.
The {\tt GEN_KYN} structure also contains pointers to the internal calculation
routines. It is defined in the file {\filefont h/robot_kynvar.h}.

\manItem{{\tt ext} --}
References a block of data whose definition depends on the particular
robot class. This typically includes constants specific to 
the robot class geometry, as well as precomputed terms for
saving time in the computation routines.
The data structure for a particular class of robot is named
{\tt <CLASS>_KYN}, and is defined in the file 
{\filefont h/<class>_kynvar.h}. For example, the structure specific
to {\tt PUMA} robots is called {\tt PUMA_KYN} and is defined
in {\filefont h/puma_kynvar.h}.

\manInset{{\bf NOTE:} Some of the information in the 
{\tt KYN} structure for a particular robot may not always
be available, and hence may be set to zero. This is 
often true of information such as friction coefficients,
which usually have to be measured 
for each manipulator. The information used
to instantiate each robot's 
{\tt KYN} structure is contained in the file
{\tt \$RCCL/\-conf/\-<robotName>.kyn} and is read by a
robot class-specific routine when the structure is first
allocated. When refering to the {\tt KYN}
structure for a particular robot, care should be
taken to make sure that the necessary information is available
and/or valid.}

Often, the programmer only uses the {\tt KYN} structure as a handle
for the generic kinematic and dynamic functions, and does not need 
to know the structure internals at all.

When writing applications that require access to the
robot class-specific {\tt ext} field,
it is necessary to cast the generic pointer to the pointer type
for the appropriate robot class.

The routine pointers are contained in the {\tt GEN_KYN}
structure. Each pointer references a class-specific implementation
routine for one of the generic kinematic/dynamic functions.
The following functions are currently implemented:
\cverbatim
        fwdKinematics (t6,c,j6,kyn,var)
        invKinematics (j6,t6,c,refj,kyn,jls,var)
        solveConf (c,j6,kyn)

        fwdJacob (dc,dj,j6,kyn)
        invJacob (dj,dc,j6,kyn,epsilon)
        fwdJacobT (t,f,j6,kyn)
        invJacobT (f,t,j6,kyn,epsilon)

        gravload (t,j6,kyn)

        strToConfig (c,s,kyn)
        configToStr (s,c,kyn)

        fwdJacobVar (dc,dj,var,kyn)
        invJacobVar (dj,dc,var,kyn,epsilon)
        fwdJacobTVar (t,f,var,kyn)
        invJacobTVar (f,t,var,kyn,epsilon)
        gravloadVar (t,var,kyn)

        updateVar (var,ang,kyn)
        updateVarXsincos (var,ang,kyn) @endcverbatim
\noindent
Detailed descriptions of each these can be found in the manual pages.

In general, the {\tt KYN} structure defines all the kinematic and
dynamic parameters needed to do these computations.

The {\tt KYN} structure for a particular
robot is obtained by calling the function {\tt getKyn()} (q.v.) with the name
of the robot in question. {\tt getKyn()} calls a robot specific
function that instantiates the data structure, reading most
of the information it needs from the ascii file 
{\tt \$RCCL/\-conf/\-<robotName>.kyn}. 

RCI programs which need to reference the {\tt KYN} structure from the
control level should use {\tt rciGetKyn()} (q.v.) instead.

A {\tt KYN} 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 kyn} 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 KYN} structure
can be obtained as follows:
\cverbatim
        KYN *kyn;

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

\manSubSection{The VAR Structure}

A {\tt VAR} structure is used to store computed terms that are
functions of the joint position, such as the sines and cosines of the 
joint angles, or certain terms of the Jacobian. 
Storing these quantities in a seperate structure allows them to
be reused by different routines without having to be recomputed.
The kinematic/dynamic routines whose names end in {\tt Var} (such
as {\tt fwdJacobVar()}) are designed to take advantage of this capability.

The actual type of the {\tt VAR} structure depends on the
robot class.
The data structure for a particular class of robot is named
{\tt <CLASS>_VAR}, and is defined in the file 
{\filefont h/<class>_kynvar.h}. For example, the structure specific
to {\tt PUMA} robots is called {\tt PUMA_VAR} and is defined
in {\filefont h/puma_kynvar.h}. 
In general, the data structure is referenced using a generic pointer,
which is cast to the appropriate type when necessary.

Before being used with any function, the {\tt VAR} structure must be updated
for the current robot position. This can be done using the routines
{\tt updateVar()} or {\tt updateVarXsincos()} (q.v.). The sine and cosine
terms in the {\tt VAR} structure can also be updated by the routines
{\tt fwdKinematics()} and {\tt invKinematics()}. It is necessary to 
update the {\tt VAR} structure only when it is uninitialized, or
the robot position changes.

Allocation of space for the {\tt VAR} structure is up to the user. The routine
{\tt getVarSize()} (q.v.) returns the size of the {\tt VAR} structure
required by a particular robot. A {\tt VAR} structure for a robot
named {\tt "Zeus"} could thus be allocated
with the following code fragment:
\cverbatim
        void *var;

        var = malloc (getVarSize("Zeus")); @endcverbatim
\noindent
Memory allocated from within, or for use by,
the RCI control level should be obtained using {\tt rciMalloc()}
instead of {\tt malloc()}.

A {\tt VAR} 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 var} 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()}, a {\tt VAR} structure
can be obtained as follows:
\cverbatim
        void *var;

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

\manInset{{\bf Warning:} Care should be taken when using this automatically
allocated {\tt VAR} structure, since it may be maintained and used by 
supplied control packages such as RCCL or CHASE. Do not update this
particular {\tt VAR} structure unless you are writing your own RCI
control functions from scratch.}

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt getKyn(3)}, {\tt rciGetKyn(3)}, {\tt JLS(3)}, {\tt rciAttachRobot(3)},
{\tt TASKROBOT(3)},  {\tt RCI_RBT(3)}, {\tt fwdKinematics(3)}, {\tt
fwdJacobVar(3)}. 

\manEnd
\end

