\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setComply}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setComply}},
{\tt \manName{getComply}}
-- RCCL compliance control primitives (bitmask specification).

}
\manSection{USAGE}
\cverbatim
#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;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt mask} --}
Bitmask describing which degrees of freedom are to be compliance controlled.
\manItem{{\tt 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 {\tt NULL})
in the case of {\tt getComply()}, or in the case of {\tt setComply()} if it
is called with {\tt mask} equal to 0.
\manItem{{\tt maskp} --}
Pointer for returning bit mask.
\manSection{RESTRICTIONS}
{\tt setComply()} must be called from the planning level.
\manSection{DESCRIPTION}
These routines establish
compliance directives along or about selected degrees of freedom
for a particular manipulator.
A similar set of routines, called {\tt comply()} and {\tt 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 {\tt getActiveComply()}.

{\tt setComply()} asks for compliance along or about
the axes specified by {\tt mask}. The bit definitions for the different
degrees of freedom are:
\cverbatim
        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 */
@endcverbatim
\noindent
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 {\tt force}.
This argument may be specifed as {\tt NULL} if all degrees of freedom are
being locked (i.e., {\tt mask} is 0).

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

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

\manSection{DIAGNOSTICS}
{\tt setComply()} returns {\tt -1} in the event of an error.
It will automatically abort the program if the option {\tt RCCL_ERROR_EXIT} is
set (see {\tt rcclSetOptions(3)}).
Error codes and messages are placed on the {\it errorStack} (q.v.). 
The following error codes may be set:

\manItem{{\tt EBadArg} --}
The {\tt force} argument was {\tt NULL} when the {\tt mask} argument
was non-zero.

No errors are currently implemented for {\tt getComply()}.

{\tt setComply()} will abort the program if called from the control level.
\manSection{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.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt comply(3)}, {\tt getActiveComply(3)}, {\tt move(3)}, {\tt
rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
