jbiasMotionEval(3)

NAME
jbiasSelect, jbiasMotionEval, setJbiasConst, setJbiasVarb -- RCCL joint bias control routines.

USAGE
#include <rccl.h>

jbiasSelect (mnp, on)
   MANIP *mnp;
   int on;

jbiasMotionEval (fxn, arg, mnp)
   int (*fxn)();
   int arg;
   MANIP *mnp;

setJbiasConst (mnp)
   MANIP *mnp;

setJbiasVarb (mnp)
   MANIP *mnp;

ARGUMENTS

mnp --
    Manipulator reference structure.

on --
    Set to true (non-zero) to enable joint biasing.

fxn --
    Pointer to a real-time function used to modify the joint bias values.

arg --
    User provided argument to the real-time function.

RESTRICTIONS
These routines must be called from the planning level. They are not defined for virtual manipulators. Joint biasing is currently available for joint interpolated motions only.

DESCRIPTION
RCCL allows motion targets to vary by changing the values of the transforms that define those targets. It is also possible to change the value of a target by applying a bias to the target joint values. These bias values are stored in the jbias field of the MANIP structure. By default, these are set to zero and do not change. However, a programmer can put values in the joint biases or attach them to a real time function that modifies the values in real time. This function binding is similar to the function binding for transforms, except that it is at the joint level, and there is only one set of joint biases for each manipulator.

To use joint biasing, it is necessary to enable it for each desired robot by calling jbiasSelect() with on set to a true (non-zero) value. Joint biasing will then remain in effect until disabled with another call to jbiasSelect(). Joint biasing is currently available only for joint interpolated motions.

The joint biases are stored in the jbias field of the robot's MANIP structure, and can be read or written atomically using the shared memory primitives readMem() and writeMem() (q.v.).

By default, when joint biasing is enabled, each motion request receives a private fixed copy of the joint bias values at the time the motion request is made. The trajectory generator then uses these private values to offset the motion's target position. Subsequent changes made to the original joint bias values will affect only later motions.

It is possible to change this default behaviour in two ways:

1.
     By declaring the joint biases to be variable. Motion requests will then not receive a private copy of the joint biases, but will instead track the original values directly.

2.
     By attaching the joint biases to a control level function, called by the trajectory generator, which modifies their values.

The first option is controlled by the following two routines:

setJbiasVarb() declares the joint biases to be variable. Subsequent motion requests will track the values of the joint biases directly.

setJbiasConst() resets the joint biases to be constant. Subsequent motion requests will use a private fixed copy of the joint biases instead of tracking them.

Binding the joint biases to a function is done using an additional routine:

jbiasMotionEval() attaches the function fxn() to the joint biases for the duration of the next motion. arg is an application argument passed to the function. After the next motion request, the binding of the joint biases reverts to what it was previously (either constant or variable).

The modifying function is called as follows:
        fxn (jbias, arg, mnp)
        JNTS *jbias;
        int arg;
        MANIP *mnp;
        {
                ....
        }

jbias points to the joint biases (or, more precisely, a copy of them which is written into mnp->jbias as soon as the routine returns). arg is the application argument specifed by jbiasMotionEval(), and mnp is a pointer to the manipulator.

DIAGNOSTICS
These routines return -1 in the event of an error. They will automatically abort the program if the option RCCL_ERROR_EXIT is set (see rcclSetOptions(3)). Error codes and messages are placed on the errorStack (q.v.). The following error codes may be set:

ENotDefined --
    The functions were called for a virtual manipulator.

These routines will abort the program if called from the control level.

SEE ALSO
setTransBinding(3), errorStack(3), rcc(1), readMem(3).