KYN,VAR(3)

NAME
KYN, VAR -- RCI data structures describing kinematic parameters and terms.

DEFINITION

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

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

DESCRIPTION

The KYN Structure

The 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 KYN structure itself contains two sub-fields:

gen --
    References a 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 GEN_KYN structure also contains pointers to the internal calculation routines. It is defined in the file h/robot_kynvar.h.

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 <CLASS>_KYN, and is defined in the file h/<class>_kynvar.h. For example, the structure specific to PUMA robots is called PUMA_KYN and is defined in h/puma_kynvar.h.

NOTE: Some of the information in the 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 KYN structure is contained in the file $RCCL/conf/<robotName>.kyn and is read by a robot class-specific routine when the structure is first allocated. When refering to the 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 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 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 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:
        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)

Detailed descriptions of each these can be found in the manual pages.

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

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

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

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

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

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

The VAR Structure

A 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 Var (such as fwdJacobVar()) are designed to take advantage of this capability.

The actual type of the VAR structure depends on the robot class. The data structure for a particular class of robot is named <CLASS>_VAR, and is defined in the file h/<class>_kynvar.h. For example, the structure specific to PUMA robots is called PUMA_VAR and is defined in 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 VAR structure must be updated for the current robot position. This can be done using the routines updateVar() or updateVarXsincos() (q.v.). The sine and cosine terms in the VAR structure can also be updated by the routines fwdKinematics() and invKinematics(). It is necessary to update the VAR structure only when it is uninitialized, or the robot position changes.

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

        var = malloc (getVarSize("Zeus"));

Memory allocated from within, or for use by, the RCI control level should be obtained using rciMalloc() instead of malloc().

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

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

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

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

SEE ALSO
getKyn(3), rciGetKyn(3), JLS(3), rciAttachRobot(3), TASKROBOT(3), RCI_RBT(3), fwdKinematics(3), fwdJacobVar(3).