rcclCreate(3)

NAME
rcclCreate, rcclDelete -- RCCL routines for attaching and detaching manipulators.

USAGE
#include <rccl.h>

MANIP *rcclCreate(name, cpuMask)
  const char *name;
  unsigned long cpuMask;

rcclDelete (mnp)
  MANIP *mnp;

ARGUMENTS

name --
    Name of the manipulator to be attached.

cpuMask --
    A bitmask describing which CPUs the system may use in selecting a CPU to run the manipulator's trajectory generator. If this argument is 0, then the system will choose the CPU itself.

mnp --
    Pointer to the MANIP structure returned by rcclCreate().

RESTRICTIONS
These routines must be called from the planning level, and the trajectory generator must not be running.

DESCRIPTION
These routines create and delete manipulator objects within an RCCL program.

rcclCreate() creates a manipulator object for the named robot, and establishes a trajectory generator for it on one of the CPUs specified by cpuMask. If cpuMask is 0, then the CPU is chosen arbitrarily by the system, using the set of available CPUs. The set of available CPUs is given by the RCCL parameter cpus in the .rciparams file (see RCCL_params(5)). If cpuMask is not 0, then it is logically "anded" with the set of available CPUs to determine those that the system may choose from. rcclCreate() returns a pointer to a manipulator structure (see MANIP(3)). Subsequent commands issued to the manipulator will use this pointer for reference.

If the name given to rcclCreate() does not match the name of a robot configured into the RCI system, then a virtual manipulator is created. This is a coordinate frame in space, with no robot attached, that is controlled by the trajectory generator and can be moved around with RCCL motion primitives. The trajectory generator simply skips the robot kinematic and communication steps. Because a virtual manipulator has no joint-level interpretation, some motion commands are undefined with respect to it (such as setMod() or movej()).

A manipulator may be deleted with the command rcclDelete().

rcclCreate() and rcclDelete() cannot be called while the trajectory generator is active. The trajectory generator is activated with the command rcclStart(), and is deactivated with the command rcclRelease().

DIAGNOSTICS
rcclCreate() returns NULL, and rcclDelete() returns -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:

ETaskActive --
    RCCL trajectory generator is running.

EInternal --
    Unexpected internal software or communication failure.

rcclCreate() may also set the following (warning: this list may be incomplete):

EDuplicate --
    A manipulator with the same name already exists.

EAuxHalted --
    One of the auxiliary CPUs is in a halted state; probably in console mode.

ENotAvail --
    None of the requested CPUs are available.

EEnviron --
    Environment variable RCCL not set.

EMemory --
    System is out of memory, on either the arbiter CPU or on one of the auxiliaries.

These routines will abort the program if called from the control level.

SEE ALSO
MANIP(3), rcclStart(3), rcclSetInterval(3), RCCL_params(5).