\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{limit}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{limit}}
-- RCCL primitive to specify limit conditions for a motion.

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

limit (mnp, spec, value1 ... [, valuen])
  MANIP *mnp;
  char *spec;
  double value1, ... valuen;@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt spec} --}
String describing the limit conditions.
This should be composed of the 
following character pairs, separated by spaces:

Forces along, and torques about, the $x$, $y$, and $z$ axes are
indicated by

\manItem{}
\qquad  ``{\tt fx}'', ``{\tt fy}'', ``{\tt fz}'', 
``{\tt tx}'', ``{\tt ty}'', ``{\tt tz}''

\manItem{}
Displacement limits along or about the same axes are indicated by

\manItem{}
\qquad  ``{\tt dx}'', ``{\tt dy}'', ``{\tt dz}'', 
``{\tt rx}'', ``{\tt ry}'', ``{\tt rz}''

\manItem{{\tt value} --}
Threshold values
associated with each limit condition described in the
specification string.
Force thresholds are given in Newtons or Newton-millimeters.
Displacement thresholds are given in millimeters or degrees.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
This routine allows limit conditions to be specified for the next
requested motion. The idea is that if and when one of these
limit conditions is exceeded, the motion is cancelled.
RCCL does not (currently) implement the limit
monitoring;
that must be done by application software (presumably running
at the control level). This software 
can obtain the limit specification for the current motion using the routines
{\tt getActiveForceLimit()} and {\tt getActiveDispLimit()} (q.v.).

{\tt limit()} has
a format-string, var-args interface. As an alternative,
one may use the primitives
{\tt setForceLimit()} and {\tt setDispLimit()} (q.v.), which have a
bitmask/vector interface.

Since the limit monitoring is done by
application software, the limit conditions themselves can be interpretted
in any way desired. The suggested interpretation is as follows:

Force limits cause motion termination when a force or torque 
exceeds a prescribed limit in the manipulator's TOOL frame.
These are useful for implementing guarded contact motions.
Displacement limits cause motion termination when the
manipulator trajectory deviates from the planned trajectory by more
than a certain amount (along or about a particular TOOL frame axis).
These are useful, for instance, in situations where 
the manipulator is complying to, or tracking, a surface, and
we want to guard against it ``falling off the edge''.

As an example of using {\tt limit()}, suppose that we wish 
to monitor for a force limit of 10 Newtons along the $z$
axis, and a position error of 5 millimeters along the $y$ axis.
The corresponding call would look like this:

\cverbatim
           limit (mnp, "fz dy", 10.0, 5.0); @endcverbatim

Limit specifications are valid for the next motion only.

\manSection{DIAGNOSTICS}
This routine 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 ESyntax} --}
Syntax error in the description string.

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt move(3)}, {\tt setForceLimit(3)}, {\tt rcclSetOptions(3)}, 
{\tt errorStack(3)}.
\manEnd
\end
