robotComfxns(7)

NAME
robotComfxns -- RCI robot communication function interface.

INTERFACE
(rbt->startup)(td, rbt)
   RCI_DESC *td;
   RCI_RBT *rbt;

(rbt->input)(td, rbt)
   RCI_DESC *td;
   RCI_RBT *rbt;

(rbt->output)(td, rbt)
   RCI_DESC *td;
   RCI_RBT *rbt;

(rbt->release)(td, rbt, code)
   RCI_DESC *td;
   RCI_RBT *rbt;
   int code;

(rbt->ready)(rbt->readyArg)
   RCI_RBT *rbt;

(rbt->wakeup)(rbt->wakeupArg)
   RCI_RBT *rbt;

ARGUMENTS

td --
    Pointer to RCI task descriptor.

rbt --
    Pointer to the robot descriptor.

code --
    Code describing the conditions associated with the release.

DESCRIPTION
The robot interface functions constitute a package that interfaces an RCI control task to a particular robot. In general, each type of robot will require a different set of functions. Pointers to the interface functions are contained in the RCI_RBT structure, which is set up whenever a robot is attached to a task (see rciAttachRobot(3)).

The general characteristic and "duties" of the interface functions are described here.

The principle purpose of the interface functions is to maintain the HOW structure and process the CHG macros for the robot in question. They should be called from an appropriate place within the task control functions (see rciControlFxns(7)). They can make use of the information in the RCI_RBT structure and the robot constants defined in the JLS structure (q.v.). To communicate with the robot, they usually use a physical device interfaced to by an RCI device driver (see IOdevice(7)). An RCI device driver is allocated to each robot by the rciAttachRobot() routine, and a pointer to it can be obtained from the RCI_RBT structure with the macro ROBOT_DEV(rbt). Functions can pass information to each other by writing in the notice field of the robot descriptor.

The robot startup function should be called from within the control task's startup function. It should connect to the robot controller (the RCI driver attach routine is designed for this) and then read back whatever information is required from the robot to initialize the HOW structure. This will typically include the robotID and controllerID fields (which are used to check that we are talking to the "right" robot), and the options, numAdc, numDac, numPioIn, numPioOut, and numSlu fields, which define what devices and I/O features are available on the robot (see HOW(3)). The robot startup function should also send to the robot necessary information such as the sample rate that the control is to be run at (the function can obtain this information be reading the RCI_TCB structure (q.v.)). If the sample rate changes during the control session, of course, the robot should presumably be advised; the RCI_TCB field newRate can be used to determine when this happens. The RCI driver functions read and write are intended for doing data transfers with the robot interface device. Lastly, the startup function is responsible for instantiating the function pointers rbt->ready and rbt->wakeup, along with their call arguments rbt->readyArg and rbt->wakeupArg. This is done by the startup function to provide greater flexibility: for instance, it may be desired to make direct use of the RCI driver function testRead as the wakeup function.

The input function is normally called once during every control cycle, from the control task's control function. It is responsible for reading back from the robot all the data being updated in the HOW structure. It is also responsible for doing limit checking (see SET_CHECKING(3)). Many of the fields in HOW are not read directly back from the robot but computed based on other information read in from the robot. For instance, the function puma_input() reads in encoder values from the PUMA robot and places them directly into the enc field. It then computes the ang field by using the encoderToAngle() conversion function contained in the JLS structure. The velocities are also computed by differencing old and new position values.

The output function is also normally called once every control cycle from the control function. It is responsible for scanning commands which have been entered into the CHG structure (q.v.) with the various CHG macros, checking that they meet the required range and limit requirements, and shipping the commands off to the robot. The CHG macros work by storing the information required for the command in the appropriate field of the "CHG" structure, and then, lastly, setting the subfield .com to indicate to the output function that a command has been entered. The setting of the .com field is atomic, so that commands can be called from tasks outside of the task to which the structure belongs. The output() function must poll the required the field.

The release function is called whenever the task is released, for whatever reason; it is normally called from the task's release function. The release function will usually just interrupt the robot and let it know that the control session is over, and (if the powerOnRelease field of the HOW structure is clear) tell it to turn the power off. It expects a release code to be passed to it as a third argument. The different values of these release codes are:

RBT_NORMAL --
    The task is releasing normally (as would be indicated by the task's release function receiving a RELEASE_REQ code).

RBT_SOFTERROR --
    An error has occured but the robot can be released with the power turned on, if such a request is indicated by how->powerOnRelease.

RBT_HARDERROR --
    An error has occured and the robot power should be shut off.

The ready function, and its argument readyArg, is instantiated by the startup function. It is a polling function that returns 1 if the robot is ready to handle an input function, and 0 if it is not.

The wakeup function, and its argument wakeupArg, is instantiated by the startup function. Its purpose is to send a wakeup signal to the robot controller telling it to beging gathering data for another control cycle. This function is only used when the RCI system is regulating the control cycle timing (which is the case when the control task is running ON_CLOCK or ON_TRIGGER).

INSTALLATION

As with device drivers, the easiest way to write a set of robot interface functions is to clone an existing set. The functions for the PUMA are defined in the file puma/puma_comfxns.c.

It is recommended that all functions relating to a particular type of robot be kept in a directory specific to that robot. Typically, the communication functions reside in the directory for their associated robot. The make command "make libs" causes the communication function module(s) to be compiled and loaded into the library lib/rciCtrl.a.

The robot interface functions also have to be declared in the table rciRobotDataTable, in the file robots/robotDataTab.c. The table consists of a set of entries for each robot configured into the system. Each entry contains (1) the name of the robot, (2) its class, (3) functions to help instantiate the robot's JLS and KYN structures, (4) the sizes of the robot class-specific components of the KYN and VAR structures, and (5) pointers to the startup, input, output, and release functions. NULLF function pointers are permitted; they simply state that there is no function to call.

DIAGNOSTICS
The robot interface functions return a negative value if they detect an error; in this case, they should also issue an RCI abort prior to returning.

Abort codes which are specifically intended for RCI aborts issued by the robot interface functions include:

ERobotError --
    The robot itself reported an error condition.

ELimit --
    A indicator that some sort of general limit condition was met.

EBadCmd --
    Bad command or illegal command values set via the CHG macros.

EMaxPos --
    Position bounds exceeded on a robot joint.

EMaxVel --
    Velocity limits exceeded on a robot joint.

EMaxTor --
    Torque limits exceeded on a robot joint.

EReqPos --
    Robot command would move the robot out of bounds.

EReqVel --
    Robot command would cause maximum velocity limits to be exceeded.

EReqTor --
    Robot command would cause maximum torque limits to be exceeded.

ETooMany --
    Too many commands were issued to the CHG interface at once; command buffer overflow.

EEStop --
    Emergency halt switch set for robot (this error code is not implemented for the PUMA).

SEE ALSO
HOW(3), CHG(3), JLS(3), RCI_TCB(3), IOdevice(7), rciControlFxns(3), rciAbort(3), rciAttachRobot(3), SET_CHECKING(3).