rciAttachRobot(3)

NAME
rciAttachRobot, rciDetachRobot -- attach a robot to an RCI task.

USAGE
#include <rci.h>

num = rciAttachRobot (td, name, rdev)
   int num;
   RCI_DESC *td;
   const char *name;
   struct devAddr *rdev;

rciDetachRobot (td, num)
   RCI_DESC *td;
   int num;

ARGUMENTS

td --
    Pointer to task descriptor.

name --
    Name of the robot to attach to.

rdev --
    Optional address spec. for robot interface device.

num --
    Index of the robot within the task.

RESTRICTIONS
These routines must be called from the planning level.

DESCRIPTION
Robots may be attached to an RCI control task. Attaching entails allocating the various data structures and the physical interface required to control and interface to that robot. Once this is done, the control task is able to communicate with the robot using these data structures in conjunction with the robot interface functions (see robotComfxns(7)).

rciAttachRobot() attaches the named robot to an RCI task: it allocates and initializes the robot parameter blocks (JLS and KYN structures, etc.) and makes them accessible to the system; it locates the appropriate robot interface functions, and it sets up an I/O device for the robot. The memory for the parameter blocks is allocated on the CPU bearing the control task.

The argument "rdev", if not NULL, is used to specify the name and address of the interface device to be used by the robot. If this argument is not present, then this information is taken from the "device" and "address" keywords associated with the named robot in the system file $RCCL/conf/robots. For a description of the devAddr structure, see rciAllocDevice(3).

If successful, the function returns a small integer which indexes the robot within the task. The index number can be used to obtain a pointer to the RCI_RBT structure (q.v.), which is the handle for all operations concerning that robot; this is done with the macro TASKROBOT(td, num). The maximum number of robots that can be attached to an RCI task is MAX_TASKROBOTS. The number of robots attached at any particular time is given by the macro TASKNUMROBOTS(td).

In order for an rciAttachRobot() to succeed, the following conditions must be true: the robot must not be attached to any other RCI task and must not be locked by another RCI program (locks are implemented using lock files in the directory $RCCL/lock). The robot must be known to the system, which means that the system must be able to obtain interface functions and a JLS structure for it. The robot must also be defined in the configuration file $RCCL/conf/robots, which must define an I/O device and address for the robot. Optional arguments for the device driver may also be declared in the configuration file. The configuration file may also specify an interrupt device for use by tasks which run on the arbiter CPU. If an interrupt device is specified, then it is opened and the returned file descriptor is placed in the idev field of the RCI_RBT structure (this field is otherwise set to UNDEF).

The function rciDetachRobot() removes the robot from the task and frees up the data structures for later use.

DIAGNOSTICS
The functions return -1 in the event of failure. Error information is reported on the errorStack (q.v.). Returned error codes are accessible with getErrorCode().

Errors specific to rciAttachRobot() include:

ETooMany --
    The number of robots attached to the task is already MAX_TASKROBOTS.

EBusy --
    The robot or its interface device has been allocated by another RCI task (in the current program or another one).

ENotDefined --
    Specified robot is unknown to the system, or the robot device is not completely specified or is incorrect.

ENoIntrDev --
    The interrupt device specification in $RCCL/conf/robots is incorrect or incomplete.

EBadAccess --
    Can't open lock file, the support file $RCCL/conf/robots, or the interrupt device.

EBadObj --
    Malformed or corrupted support file in $RCCL/conf/robots.

EBadFxn --
    Support function used in accessing robot data base is missing.

EMemory --
    System is out of memory on either the planning CPU or one of the auxiliary CPUs.

Errors specific to rciDetachRobot() include:

EDescriptor --
    Specified robot not attached to task.

Errors common to both routines include:

ETaskActive --
    The task is currently active.

EInternal --
    Unexpected internal software error or loss of communication between processors.

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

SEE ALSO
robotComfxns(7), rciAllocDevice(3), TASKROBOT(3), RCI_RBT(3).