comply(3)

NAME
comply, lock -- RCCL compliance specification primitives (format string version).

USAGE
#include <rccl.h>

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

lock (mnp, axes)
  MANIP *mnp;
  const char *axes;

ARGUMENTS

mnp --
    Manipulator reference structure.

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:

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

    Each pair indicates a DOF either along (f) or about (t) the x, y, and z axes of the manipulator tool frame.

value --
    Force or torque value associated with a degree of freedom specified in axes. The units are Newtons for force, and Newton-millimeters for torque.

RESTRICTIONS
These routines must be called from the planning level.

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 getActiveComply() (q.v.).

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

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 comply commmand:
        comply ("fx tz", 10.0, 5.0);

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 comply() or a call to 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 getComply() (q.v.), while the specification in effect for the motion currently executing is obtained with getActiveComply().

DIAGNOSTICS
These routines return -1 in the event of an error. They 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 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.

BUGS
It would be nice to build compliance directly into RCCL.

SEE ALSO
setComply(3), getComply(3), getActiveComply(3), move(3), rcclSetOptions(3), errorStack(3).