\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{CHG}{3}
\manSection{NAME}
{\tt \manName{CHG}} 
-- RCI robot command macros.
\manSection{USAGE}
\cverbatim
#include <rci.h> @endcverbatim
\manSection{DESCRIPTION}
The {\tt 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 {\tt 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 {\TT chg}. The present
implementation still uses a global data structure, (type {\tt 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 {\tt CHG} structure. The next
time the robot {\it output} function is called by the control task (see
{\tt robotComfxns(7)}), 
it examines the {\tt 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 {\tt
HOW} structure; that is also done at this time. 

This implementation of the {\tt 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 {\it not}
necessarily true of
functions which are called from the {\it 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
{\tt 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 {\tt RCI_RBT} as an argument; this structure may by
obtained from the task descriptor {\tt td} using {\tt TASKROBOT(td)}.
There is no need to reference the {\tt CHG} structure itself.

It is unadvisable to call the same command from different tasks (e.g.,
have both tasks issue {\tt 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 {\tt MOVE_ANGLE()} while the planning task issues
``now and then'' commands like {\tt SET_POWER_ON()}.

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

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

\manItem{{\tt EBadCmd} --}
Illegal or unimplemented command.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt TASKNUM(3)}, {\tt HOW(3)}.
\medskip
All of the commands are described in the following man pages:
\smallskip
{\tt POST_CTRLPARAM(3)}, {\tt SET_CHECKING(3)}, {\tt SET_POWER_ON(3)},
{\tt PUT_PIO(3)}, {\tt MOVE_ENCODER(3)}, {\tt SET_STOP(3)},
{\tt MOVE_ANGLE(3)}, {\tt SET_HANDPOS(3)}, {\tt SET_TORQUE_READ(3)}.
\manEnd
\end
