limit(3)

NAME
limit -- RCCL primitive to specify limit conditions for a motion.

USAGE
#include <rccl.h>

limit (mnp, spec, value1 ... [, valuen])
  MANIP *mnp;
  char *spec;
  double value1, ... valuen;

ARGUMENTS

mnp --
    Manipulator reference structure.

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

    "fx", "fy", "fz", "tx", "ty", "tz"

    Displacement limits along or about the same axes are indicated by

    "dx", "dy", "dz", "rx", "ry", "rz"

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.

RESTRICTIONS
This routine must be called from the planning level.

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 getActiveForceLimit() and getActiveDispLimit() (q.v.).

limit() has a format-string, var-args interface. As an alternative, one may use the primitives setForceLimit() and 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 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:

           limit (mnp, "fz dy", 10.0, 5.0);

Limit specifications are valid for the next motion only.

DIAGNOSTICS
This routine 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:

ESyntax --
    Syntax error in the description string.

The routine will abort the program if called from the control level.

SEE ALSO
move(3), setForceLimit(3), rcclSetOptions(3), errorStack(3).