\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{comply}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{comply}},
{\tt \manName{lock}}
-- RCCL compliance specification primitives (format string version).

}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

comply (mnp, axes, value1 ... [, valuen])
  MANIP *mnp;
  const char *axes;
  float value1, ... valuen;

lock (mnp, axes)
  MANIP *mnp;
  const char *axes; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt axes} --}
String describing which degrees of freedom (DOFs)
to either put into comply mode or lock.
This string should be a combination of the 
following character pairs, separated by spaces:
\manItem{}
\qquad ``{\tt fx}'', ``{\tt fy}'', ``{\tt fz}'', ``{\tt tx}'', 
``{\tt ty}'', ``{\tt tz}''
\manItem{}
Each pair indicates a DOF either along ({\tt f}) or about ({\tt t})
the $x$, $y$, and $z$ axes of the manipulator {\it tool} frame.
\manItem{{\tt value} --}
Force or torque value associated with a degree of freedom specified
in {\tt axes}.
The units are Newtons for force, and Newton-millimeters for torque.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
These routines allow compliance information to be provided for a motion, or
set of motions. 
RCCL does not currently implement the compliance;
that must be done by application software (presumably running
at the control level). This software can obtain
the comply specification for the current motion using the
routine {\tt getActiveComply()} (q.v.).

{\tt comply()} and {\tt lock()}
have a format-string, var-args interface. As an alternative,
one may use the primitives
{\tt setComply()} and {\tt getComply()} (q.v.), which have a
bitmask/vector interface.

{\tt comply()} selects compliance along or about certain
degrees of freedom (DOFs). Each
DOF is associated with a bias force/torque 
given by an extra argument to the routine.

For example, to request compliance with a force of
10 Newtons along the $x$ axis, and a torque of 5 about the $z$ axis, one would
issue the following {\tt comply} commmand:
\cverbatim
        comply ("fx tz", 10.0, 5.0); @endcverbatim

{\tt lock()} removes certain degrees of freedom from the
compliance specification.

The effect of these routines is ``sticky''; i.e., the specification
remains in place for all subsequent motions until changed with
either another call to {\tt comply()} or a call to {\tt lock()}.
Each motion request receives a copy of 
the compliance specification at the time the motion is queued.
The current specification (as set by the planning level)
may be read back with {\tt getComply()} (q.v.), while the
specification in effect for the motion currently executing is obtained with
{\tt getActiveComply()}.
\manSection{DIAGNOSTICS}
These routines return {\tt -1} in the event of an error.
They 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 ESyntax} --}
Syntax error in the description string for the degrees of freedom, or
an attempt was made to lock a degree of freedom that was not in comply mode.

These routines will abort the program if called from the control level.
\manSection{BUGS}
It would be nice to build compliance directly into RCCL.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt setComply(3)}, {\tt getComply(3)}, {\tt getActiveComply(3)},
{\tt move(3)}, {\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
