\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{RCI RBT}{3}
\manSection{NAME}
{\tt \manName{RCI_RBT}}
-- RCI robot structure.
\manSection{DEFINITION}
\cverbatim
typedef struct _RCI_RBT {
        int id;
        JLS *jls;
        HOW *how;
        CHG *chg;
        KYN *kyn;
        void *var;
        int kynSize;
        int varSize;

        int class;
        char *name;

        int (*startup)();
        int (*release)();
        int (*input)();
        int (*output)();
        int (*wakeup)();
        int (*ready)();

        int wakeupArg;
        int readyArg;

        void *dev;
        int idev;

        int notice;
} RCI_RBT; @endcverbatim
\manSection{DESCRIPTION}
This data structure contains information and pointers describing a robot
connected to an RCI control task.
One is created for every robot attached to an RCI control task
(see {\tt rciAttachRobot(3)}), and a pointer to it can be
obtained using the macro {\tt TASKROBOT(td, num)}, where {\TT td}
is the task descriptor and {\TT num} is the number returned
by {\tt rciAttachRobot()}.

The {\tt CHG} macros which send commands to the robot take a pointer
to this structure as their first argument.
\manSection{FIELDS}
\manItem{{\tt id} --}
Robot ID number, defined to be the entry number of the robot in the
table {\tt rciRobotDataTable}, where 1 is the first entry.
\manItem{{\tt jls} --}
Pointer to the robot's {\tt JLS} structure (q.v.).
\manItem{{\tt how} --}
Pointer to the robot's {\tt HOW} structure (q.v.).
\manItem{{\tt chg} --}
Pointer to the robot's {\tt CHG} structure (q.v.). This is a command
blackboard whose entries are set by the various {\tt CHG} macros.
\manItem{{\tt kyn} --}
Pointer to the robot's {\tt KYN} structure (q.v.).
\manItem{{\tt var} --}
Pointer to the robot's {\tt VAR} structure (q.v.).
\manItem{{\tt kynSize} --}
Size of the {\tt ext} component of the {\tt KYN} structure.
\manItem{{\tt varSize} --}
Size of the (robot class-specific) {\tt VAR} structure.
\manItem{{\tt class} --}
The class of the robot (for instance, {\tt PUMA}). In general, each
set of robot interface functions (see {\tt robotComfxns(7)})
is associated with 
a class type.
\manItem{{\tt name} --}
The name of the robot.
\manItem{{\tt startup} --}
Pointer to the robot's startup function, usually called by the control
task's {\it startup} routine (see {\tt robotComfxns(7)}).
\manItem{{\tt release} --}
Pointer to the robot's release function, usually called by the control
task's {\it release} routine.
\manItem{{\tt input} --}
Pointer to the robot's input function, which reads data from the robot
controller into the {\tt HOW} structure (q.v.). This function is usually
called once every control cycle by the control task's {\it control} function.
\manItem{{\tt output} --}
Pointer to the robot's output function, which sends commands 
specified by the {\tt CHG} macros (q.v.) to the
robot controller. This function is usually
called once every control cycle by the control task's {\it control} function.
\manItem{{\tt wakeup} --}
Pointer to the robot's wakeup function. This function sends a 
signal to the robot controller telling it to start gathering data
for a control cycle; it is used when the control cycle timing is being
done by RCI (i.e., the control task is running using the {\tt ON_CLOCK} or
{\tt ON_TRIGGER} scheduling disciplines). The function is designed to be
called from the control task's trigger function with the value
in the {\tt wakeupArg} field as an argument:
\cverbatim
                 (*rbt->wakeup)(rbt->wakeupArg);
@endcverbatim
\manItem{}
This construction is provided by the {\tt ROBOT_WAKEUP(rbt)} macro (q.v.).
If the control task is operating
only one robot, then the robot wakeup function can be used directly as the
trigger function for the {\tt ON_TRIGGER} scheduling
discipline. Trigger functions are established with
the routine {\tt rciSetTrigger()}(q.v.), as in:
\cverbatim
                rciSetTrigger (rbt->wakeup, rbt->wakeupArg);
@endcverbatim
\manItem{}
The {\tt wakeup} function pointer (and its companion {\tt wakeupArg} field)
is normally initialized by the robot's
{\it startup} function, and so referencing it prior to that time will
have unpredictable results.
\manItem{{\tt ready} --}
Pointer to the robot's {\tt ready} function, which returns true
when the robot has collected its data and is ready to service
its {\it input} function. 
The function should be called using the 
{\tt readyArg} field as an argument:
\cverbatim
                (*rbt->ready)(rbt->readyArg);
@endcverbatim
\manItem{}
The {\tt ROBOT_READY(rbt)} macro (q.v.) performs this call automatically.
If the control task is operating
only one robot, and a polling function is required (as is the
case if the {\tt ON_FUNCTION} or {\tt ON_TRIGGER} scheduling disciplines
are being used), then the {\it ready} function itself can be
used as the control task's wakeup function. A 
wakeup function is established with the
routine {\tt rciWakeupOn()}(q.v.), as in:
\cverbatim
                rciWakeupOn (rbt->ready, rbt->readyArg);
@endcverbatim

\manItem{}
This will normally be done inside the control task's {\it startup}
function.
The {\tt ready} function pointer (and its companion {\tt readyArg} field)
is normally initialized by the robot's
{\it startup} function, so referencing it prior to that time will
have unpredicatble results.
\manItem{{\tt wakeupArg} --}
Argument for the robot's {\it wakeup} function
(see above).
\manItem{{\tt readyArg} --}
Argument supplied to the robot's {\it ready} function
(see above).
\manItem{{\tt dev} --}
Pointer to the robot's I/O device (see {\tt IOdevice(7)}). 
This field is only guaranteed to
be valid when referenced from the control task to which the robot
is attached. The field may be referenced using the macro
{\tt ROBOT_DEV(rbt)}.
\manItem{{\tt idev} --}
File descriptor for the robot's polling interrupt device. This is a UNIX RCI
device which will provide an interrupt on the arbiter CPU
whenever the robot is ready for the next control cycle (i.e.,
whenever the robot's {\tt ready} function will return true).
Hence {\tt idev} can be used as the last argument to {\tt rciScheduling()} to
provide an interrupt when the task controlling the robot is being run on the
arbiter. 
\manItem{}
{\tolerance=10000%
The UNIX RCI device associated with this descriptor is specified by the 
{\TT interrupt} keyword in the system file {\filefont conf/robots}. 
The {\tt rciAttachRobot()} routine opens this device and sets up the
descriptor if the device exists and is a valid RCI device.

}
\manItem{{\tt notice} --}
This a scratch variable which can be used for passing information
between the robot interface functions; it is assumed to be used internally
by them.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rciAttachRobot(3)}, {\tt TASKROBOT(3)}, 
{\tt HOW(3)}, {\tt CHG(3)}, {\tt JLS(3)}, {\tt KYN(3)},
{\tt robotComfxns(7)}, {\tt robotMacros(3)}, {\tt rciWakeupOn(3)},
{\tt robots(5)}.
\manEnd
\end
