CHG(3)

NAME
CHG -- RCI robot command macros.

USAGE
#include <rci.h>

DESCRIPTION
The CHG macro package is used by robot control programs to send instructions to the robot. Commands are available for moving joints to designated locations, setting torques on the actuators, adjusting robot operating characteristics, and performing a variety of operations with various I/O devices like parallel ports, analog-to-digital converters, and serial line units attached to the robot controller. The robot commands are very low level in nature, in the sense that they control things like current or perform incremental joint positioning. They may be called from either the planning or control level of an RCI program.

The name CHG is historical: in the original version of RCCL (Vincent Hayward, 1983) all robot commands were specified by writing directly into a global data structure called "chg". The present implementation still uses a global data structure, (type CHG), although access to it is hidden from the user by a comprehensive set of macros.

Calling one of the macros does not result in an immediate transfer of data to the robot controller. Instead, the macro simply writes command information into an appropriate field of the CHG structure. The next time the robot output function is called by the control task (see robotComfxns(7)), it examines the CHG structure, determines what commands have been requested, and builds a command packet that is shipped off to the robot controller. Often, information about the command is recorded in the HOW structure; that is also done at this time.

This implementation of the CHG macros has a few subtle implications that are not overwhelmingly important but should be mentioned. From within a control function, no commands are actually executed until the function returns. Specifying a command twice with two different arguments (during the same cycle) will simply cause the first request to be overwritten with the second. This is not necessarily true of functions which are called from the planning level, since the planning level is not explicitly synchronized with the control cycles. When the macros are called from the planning level, and one wishes to wait until the command has been "sent", then the best way to do this is call rciBlock().

The macros may be called from a program that is running an RCI task. The macros always take a pointer to the robot structure RCI_RBT as an argument; this structure may by obtained from the task descriptor td using TASKROBOT(td). There is no need to reference the CHG structure itself.

It is unadvisable to call the same command from different tasks (e.g., have both tasks issue MOVE_ANGLE() requests) unless strict synchronization is arranged to make sure the commands do not clash. On the other hand, independent commands can be issued from different tasks at any time. For instance, it is common for the control task to issue the robot motion commands such as MOVE_ANGLE() while the planning task issues "now and then" commands like SET_POWER_ON().

DIAGNOSTICS
Errors in the usage of the CHG macros are generally detected by the robot interface functions (specifically, the robot output function), at which point an abort is issued. General abort codes currently used in connection with CHG macros include:

ETooMany --
    Too many commands were specified for one cycle, causing an overflow of the buffer of commands to send to the robot.

EBadCmd --
    Illegal or unimplemented command.

SEE ALSO
TASKNUM(3), HOW(3).

All of the commands are described in the following man pages: POST_CTRLPARAM(3), SET_CHECKING(3), SET_POWER_ON(3), PUT_PIO(3), MOVE_ENCODER(3), SET_STOP(3), MOVE_ANGLE(3), SET_HANDPOS(3), SET_TORQUE_READ(3).