rcclTeach(3)

NAME
rcclTeach -- the RCCL teach routine.

USAGE
#include <rccl.h>

rcclTeach (mnp, prompt, tool)
  MANIP *mnp;
  const char *prompt;
  TRSF *tool;

ARGUMENTS

mnp --
    Manipulator reference structure.

prompt --
    Prompt string for the terminal interaction.

tool --
    Optional argument which, if not NULL, specifies a tool transform to be used for motions specified in tool coordinates.

RESTRICTIONS
This routine must be called from the planning level. It is not currently supported for virtual manipulators.

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 rcclStart()). When the routine is entered, the program enters the 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 doc/CtreeMatch.doc.

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

Leaving the routine may be accomplished by entering either the commands return or record at the keyboard, or by hitting the RECORD button on the teach pendant. When the routine returns as a result of a record keyboard command or hitting the pendant 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:
        while (rcclTeach(mnp, "TEACHDEMO> ", NULL) > 0)
         { printf ("Recording point:);
           storePoint (mnp->here);
         }

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

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

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):

CLAMP1, CLAMP2

    Open and close the hand.

RECORD
    Return from rcclTeach() with return code 1.

JOINT
    Put the routine into joint mode, in which the pendant motion buttons will cause motions in joint coordinates.

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

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

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

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

TICK
    Execute pendant commands very slowly.

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 + direction buttons while in this mode will cause the joint in question to be locked, while hitting the - button will cause it to be freed again.

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

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 ?). The following keyboard commands are recognized:

record
    Return from the routine with a return code of 1.

return
    Return from the routine with a return code of 0.

stop
    Stop any robot motion currently in progress.

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

show tool
    Print out the value of the TOOL transform that was passed to the routine.

show t6*tool
    Print the value of the composite end-effector transform T6 TOOL.

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

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

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

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.

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

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 rcclTeach() returns.

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

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

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

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

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

ENotSupported --
    An attempt was made to use the routine with a virtual manipulator.

ETaskActive --
    The function was called when the trajectory generator was not running.

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

SEE ALSO
rcclCreate(3), rcclStart(3), MANIP(3), teachdemo(1), rcclSetOptions(3), errorStack(3).