setComply(3)

NAME
setComply, getComply -- RCCL compliance control primitives (bitmask specification).

USAGE
#include <rccl.h>

long setComply (mnp, mask, force)
  MANIP *mnp;
  unsigned long mask;
  FORCE *force;

getComply (mnp, maskp, force)
  MANIP *mnp;
  unsigned long *maskp;
  FORCE *force;

ARGUMENTS

mnp --
    Manipulator reference structure.

mask --
    Bitmask describing which degrees of freedom are to be compliance controlled.

force --
    Structure describing the bias forces/torques to be associated with the compliance (in units of either Newtons or Newton-meters). This argument is optional (may be specified as NULL) in the case of getComply(), or in the case of setComply() if it is called with mask equal to 0.

maskp --
    Pointer for returning bit mask.

RESTRICTIONS
setComply() must be called from the planning level.

DESCRIPTION
These routines establish compliance directives along or about selected degrees of freedom for a particular manipulator. A similar set of routines, called comply() and lock() (q.v.), provide a similar interface only using a format-string, var-args interface.

RCCL does not (at present) implement compliance itself. These are interfacing primitives only. These routines only set directives which can be read by control level application functions that implement a compliance control law. Some discussion of how this may be done is given in the "RCCL User's Guide". The control functions responsible for implementing the compliance may read back the compliance specification for the present motion using the routine getActiveComply().

setComply() asks for compliance along or about the axes specified by mask. The bit definitions for the different degrees of freedom are:
        ALONG_X         /* force along the X axis */
        ALONG_Y         /* force along the Y axis */
        ALONG_Z         /* force along the Z axis */
        ABOUT_X         /* torque about the X axis */
        ABOUT_Y         /* torque about the Y axis */
        ABOUT_Z         /* torque about the Z axis */

It returns a bitmask specifying the previous mask values. For each degree of freedom selected, a corresponding force/torque bias value should be set in the appropriate field of force. This argument may be specifed as NULL if all degrees of freedom are being locked (i.e., mask is 0).

Once set, compliance requests remain in effect for all subsequent motions until changed by another call to setComply() (or its companion routines, comply() and lock()).

getComply() returns (through maskp) a bitmask specifying what degrees of freedom are currently specified for compliance. The associated bias force values are returned in force, if this argument is supplied.

DIAGNOSTICS
setComply() returns -1 in the event of an error. It 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:

EBadArg --
    The force argument was NULL when the mask argument was non-zero.

No errors are currently implemented for getComply().

setComply() will abort the program if called from the control level.

BUGS
The compliance mechanism has not been implemented for the most recent version of RCCL. The implementation that existed in the old version was based on the Paul-Shimano algorithm that goes back to 1972.

SEE ALSO
comply(3), getActiveComply(3), move(3), rcclSetOptions(3), errorStack(3).