RCI RBT(3)

NAME
RCI_RBT -- RCI robot structure.

DEFINITION
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;

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 rciAttachRobot(3)), and a pointer to it can be obtained using the macro TASKROBOT(td, num), where "td" is the task descriptor and "num" is the number returned by rciAttachRobot().

The CHG macros which send commands to the robot take a pointer to this structure as their first argument.

FIELDS

id --
    Robot ID number, defined to be the entry number of the robot in the table rciRobotDataTable, where 1 is the first entry.

jls --
    Pointer to the robot's JLS structure (q.v.).

how --
    Pointer to the robot's HOW structure (q.v.).

chg --
    Pointer to the robot's CHG structure (q.v.). This is a command blackboard whose entries are set by the various CHG macros.

kyn --
    Pointer to the robot's KYN structure (q.v.).

var --
    Pointer to the robot's VAR structure (q.v.).

kynSize --
    Size of the ext component of the KYN structure.

varSize --
    Size of the (robot class-specific) VAR structure.

class --
    The class of the robot (for instance, PUMA). In general, each set of robot interface functions (see robotComfxns(7)) is associated with a class type.

name --
    The name of the robot.

startup --
    Pointer to the robot's startup function, usually called by the control task's startup routine (see robotComfxns(7)).

release --
    Pointer to the robot's release function, usually called by the control task's release routine.

input --
    Pointer to the robot's input function, which reads data from the robot controller into the HOW structure (q.v.). This function is usually called once every control cycle by the control task's control function.

output --
    Pointer to the robot's output function, which sends commands specified by the CHG macros (q.v.) to the robot controller. This function is usually called once every control cycle by the control task's control function.

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 ON_CLOCK or ON_TRIGGER scheduling disciplines). The function is designed to be called from the control task's trigger function with the value in the wakeupArg field as an argument:
                     (*rbt->wakeup)(rbt->wakeupArg);

    This construction is provided by the 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 ON_TRIGGER scheduling discipline. Trigger functions are established with the routine rciSetTrigger()(q.v.), as in:
                    rciSetTrigger (rbt->wakeup, rbt->wakeupArg);

    The wakeup function pointer (and its companion wakeupArg field) is normally initialized by the robot's startup function, and so referencing it prior to that time will have unpredictable results.

ready --
    Pointer to the robot's ready function, which returns true when the robot has collected its data and is ready to service its input function. The function should be called using the readyArg field as an argument:
                    (*rbt->ready)(rbt->readyArg);

    The 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 ON_FUNCTION or ON_TRIGGER scheduling disciplines are being used), then the ready function itself can be used as the control task's wakeup function. A wakeup function is established with the routine rciWakeupOn()(q.v.), as in:
                    rciWakeupOn (rbt->ready, rbt->readyArg);

    This will normally be done inside the control task's startup function. The ready function pointer (and its companion readyArg field) is normally initialized by the robot's startup function, so referencing it prior to that time will have unpredicatble results.

wakeupArg --
    Argument for the robot's wakeup function (see above).

readyArg --
    Argument supplied to the robot's ready function (see above).

dev --
    Pointer to the robot's I/O device (see 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 ROBOT_DEV(rbt).

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 ready function will return true). Hence idev can be used as the last argument to rciScheduling() to provide an interrupt when the task controlling the robot is being run on the arbiter.

    % The UNIX RCI device associated with this descriptor is specified by the "interrupt" keyword in the system file conf/robots. The rciAttachRobot() routine opens this device and sets up the descriptor if the device exists and is a valid RCI device.

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.

SEE ALSO
rciAttachRobot(3), TASKROBOT(3), HOW(3), CHG(3), JLS(3), KYN(3), robotComfxns(7), robotMacros(3), rciWakeupOn(3), robots(5).