\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{rcclTeach}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rcclTeach}}
-- the RCCL teach routine.

}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

rcclTeach (mnp, prompt, tool)
  MANIP *mnp;
  const char *prompt;
  TRSF *tool;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt prompt} --}
Prompt string for the terminal interaction.
\manItem{{\tt tool} --}
Optional argument which, if not {\tt NULL}, specifies a tool
transform to be used for motions specified in {\it tool}
coordinates.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
It is not currently supported for virtual manipulators.
\manSection{DESCRIPTION}
This routine can be called from within RCCL programs to move a robot
around interactively and teach it positions, using commands entered 
either from the keyboard or from
the teach pendant.

The routine requires that the trajectory generator
is active when called
(the trajectory generator is activated using {\tt rcclStart()}). 
When the routine 
is entered, the program enters the {\it C-tree matcher}
at the user's terminal, and will also accept commands from the
teach pendant.
The C-tree matcher is an automatic command completion utility,
documented in the file {\filefont doc/CtreeMatch.doc}.

When the routine returns,
the most recent manipulator T6 value is stored in the
{\tt here} field of the {\tt MANIP} structure (sort of as if
using {\tt rcclteach()} corresponded to a motion which is completed
when the routine returns. 

Leaving the routine may be accomplished 
by entering either the commands {\tt return} or {\tt record} at the keyboard,
or by hitting the {\tt RECORD} button on the teach pendant. When the
routine returns as a result of a {\tt record} keyboard command or hitting
the pendant {\tt RECORD} button, it returns 1; otherwise, it returns 0.
This allows code
that teaches multiple points to be easily written using a construction
like this:
\cverbatim
        while (rcclTeach(mnp, "TEACHDEMO> ", NULL) > 0)
         { printf ("Recording point:\n");
           storePoint (mnp->here);
         } @endcverbatim

This code fragment will continue to execute and record points until
{\tt rcclTeach()} returns as a result of a {\tt return} keyboard command.

The default speed at which manipulator commands are executed is determined
by the Cartesian and joint velocity settings of RCCL when {\tt rcclTeach()}
is called (as specified by {\tt setSpeed()}, {\tt setCartVel()},
{\tt setJointVel()}, etc.).

\manSection{PENDANT COMMANDS}
Pressing the following buttons on the teach pendant causes the indicated
actions (this description is specific to the standard 
Unimation/PUMA teach pendant):

\manItem{{\tt CLAMP1}, {\tt CLAMP2}} 
Open and close the hand.

\manItem{{\tt RECORD}}
Return from {\tt rcclTeach()} with return code 1.

\manItem{\tt JOINT}
Put the routine into {\it joint} mode, in which the pendant
motion buttons will cause motions in joint coordinates.

\manItem{\tt WORLD}
Put the routine into {\it world} mode, in which the pendant
motion buttons will cause either translations or rotations in
Cartesian {\it world} coordinates. 
This means that motions will take place
with respect to the frame at the base of the manipulator's
T6 transform.	

\manItem{\tt TOOL}
Put the routine into {\it tool} mode, in which the pendant
motion buttons will cause either translations or rotations in
Cartesian {\it tool} coordinates.
This means that motions will take place
with respect to the frame defined by the compound transform
${\rm T6}\; {\rm TOOL}$, where {\rm TOOL} is the transform
supplied by the routine's {\tt tool} parameter.

\manItem{{\tt +/- X/1}, {\tt Y/2}, {\tt Z/3}}
Perform either a translation along the $x$, $y$, or $z$ axes
(if in {\it tool} or {\it world} mode), or a joint motion along axis 1, 2, or
3 (if in {\it joint} mode). The direction of motion is specified by whether
the {\tt +} or {\tt -} side of the button is pressed. 

\manItem{{\tt +/- RX/1}, {\tt RY/2}, {\tt RZ/3}}
Perform either a rotation about the $x$, $y$, or $z$ axes
(if in {\it tool} or {\it world} mode), or a joint motion along axis 4, 5, or
6 (if in {\it joint} mode). The direction of motion is specified by whether
the {\tt +} or {\tt -} side of the button is pressed. 

\manItem{\tt TICK}
Execute pendant commands very slowly.

\manItem{\tt FREE}
Put the robot into a free (zero-gravity) mode where each joint has just
enough 
current applied to it to balance its gravity loading. The robot can hence be
moved around freely. Hitting the {\tt +} direction buttons while in this
mode will cause the joint in question to be locked, while
hitting the {\tt -} button will cause it to be freed again.

\manItem{}
{\bf Warning:} {\it free} mode will only work for a
particular robot if (1) a {\tt gravload} function is defined for that robot's
class and a pointer to it is contained in the {\tt KYN}
structure, and (2) the gravity loading coefficients for
the robot are known and available in the {\tt KYN} structure.
Make sure these conditions are met before using {\it free} mode.

\manSection{KEYBOARD COMMANDS}
Commands can be entered from the keyboard using the C-tree matcher,
which provides command completion (if one types ' ') and menuing
(if one types {\tt ?}). The following keyboard commands are recognized:

\manItem{\tt record}
Return from the routine with a return code of 1.

\manItem{\tt return}
Return from the routine with a return code of 0.

\manItem{\tt stop}
Stop any robot motion currently in progress.

\manItem{\tt show position}
Print out the value of the robot's present {\rm T6} transform
and joint values, as well as the present speed factor and whether or not
integration is enabled. 

\manItem{\tt show tool}
Print out the value of the {\rm TOOL}
transform that was passed to the routine.

\manItem{\tt show t6*tool}
Print the value of the composite end-effector transform 
${\rm T6}\; {\rm TOOL}$.

\manItem{\tt world <dir> by <amount>}
Translate (if {\tt <dir>} is {\tt x}, {\tt y}, or {\tt z})
or rotate (if {\tt <dir>} is {\tt rx}, {\tt ry}, or {\tt rz})
in {\it world} coordinates by the specified amount (either millimeters
or degrees).

\manItem{\tt tool <dir> by <amount>}
Translate (if {\tt <dir>} is {\tt x}, {\tt y}, or {\tt z})
or rotate (if {\tt <dir>} is {\tt rx}, {\tt ry}, or {\tt rz})
in {\it tool} coordinates by the specified amount (either millimeters
or degrees).

\manItem{\tt joint <num> [by|to] <value>}
Move the indicated joint either by (relative motion) or
to (absolute motion) the indicated value (in degrees).

\manItem{\tt goto joints}
Move the robot to a complete set of joint values typed in by the
user. Rotational joint values are given in degrees, and prismatic
joint values are given in millimeters.

\manItem{\tt set speed}
Set the default speed index within the range 0.0 to 100.0 (the default
speed is 1.0). This setting will {\bf not} be remembered when
{\tt rcclTeach()} returns.

\manItem{\tt integration [on|off]}
Turn integration in the robot controllers either on or off. 
This may improve the robot's steady state error behaviour,
although the option may not be available for some robots.
This setting is not remembered by RCCL when {\tt rcclTeach()} returns.

\manItem{\tt set translation <px> <py> <pz>}
Move the robot so that the translation component of its {\rm T6} transform
has the indicated values (in millimeters).

\manItem{\tt set rotation euler <phi> <theta> <psi>}
Move the robot so that the rotational component of its {\rm T6} transform
has the indicated value (specified as Euler angles, in degrees).

\manItem{\tt set rotation rpy <roll> <pitch> <yaw>}
Move the robot so that the rotational component of its {\rm T6} transform
has the indicated value (specified as roll-pitch-yaw angles, in degrees).

\manSection{SIDE EFFECTS}
Any RCCL motion in progress when {\tt rcclTeach()} is called is cancelled, and
the motion queue is flushed. The routine also takes over control 
of the UNIX signal
{\tt SIGUSR1}.

\manSection{DIAGNOSTICS}
This routine returns {\tt -1} in the event of an error.
It will automatically abort the program if the option {\tt RCCL_ERROR_EXIT} is
set (see {\tt rcclSetOptions(3)}).
Error codes and messages are placed on the {\it errorStack} (q.v.). 
The following error codes may be set:

\manItem{{\tt ENotSupported} --}
An attempt was made to use the routine with a virtual manipulator.
\manItem{{\tt ETaskActive} --}
The function was called when the trajectory generator was not running.

The routine will abort the program if called from the control level.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rcclCreate(3)}, {\tt rcclStart(3)}, {\tt MANIP(3)}, 
{\tt teachdemo(1)},
{\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
