\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setConf}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setConf}}
-- RCCL routine to set the robot configuration.

}
\manSection{USAGE}
\cverbatim
setConf (mnp, conf);
  MANIP *mnp;
  const char *conf;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt conf} --}
String specifying the arm configuration.
\manSection{RESTRICTIONS}
This routine must be called from the planning level. 
\manSection{DESCRIPTION}
{\tt setConf()} specifies a change in the configuration of the 
manipulator, which will take effect with the next requested motion.
Any motion in which a configuration change takes place must be done
in joint-interpolated mode, since this involves moving through a
robot singularity.

The string {\tt conf} contains characters 
describing the new configuration. 
In the case of the
PUMA robot, the characters are defined as follows:
\cverbatim
     'r' or 'l' -- "right handed" or "left handed" 
     'u' or 'd' -- "elbow up" or "elbow down"
     'f' or 'n' -- "flip wrist" or "no flip wrist"
@endcverbatim
For example, to set the robot into a right handed, elbow down, 
wrist flipped configuration, we could issue the command
sequence
\cverbatim      
        setMod (mnp, 'j');
        setConf (mnp, "rdf");
        move (mnp, mnp->last);
@endcverbatim
\noindent
We ensure that we are operating in joint interpolated mode, set the new
desired configuration, and then issue a motion to the current location
using the manipulator's built-in {\tt last} position.

The configuration code characters for other classes of robots
can be determined by examining the definitions in the file
{\filefont h/<class>_kynvar.h}, where {\tt <class>} is the robot class name.

It is not necessary to specify all the characters in the configuration
string. Unspecified components of
the configuration will remain unchanged.

{\tt setConf()} returns an integer description of the complete
configuration.
Mapping between integer and string representations for configurations can be
done by the routines {\tt configToStr()} and {\tt strToConfig()}.

\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 ESyntax} --}
Syntax error in specification string.
\manItem{{\tt ENotDefined} --}
The routine was called for a virtual manipulator.

Performing a configuration change in {\tt Cartesian} mode is illegal. Doing
this will cause the trajectory generator to issue an RCI abort with
the code {\tt EBadMove}.

The routine will abort the program if called from the control level.
\manSection{BUGS}
We need to be able to set the configuration using only the integer code.
We haven't done this yet because the concept of the ``configuration code'' is
up for review.

We also don't have a routine to read back the configuration setting
because this is so volatile (configurations can be
partically specified, and can be
changed implicitly through commands such as {\tt movej()},
or the joint bias mechanism).
The command {\tt getActiveConf()} will read back the robot's
current configuration setting.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt getActiveConf(3)},
{\tt MANIP(3)}, {\tt move(3)}, {\tt movej(3)}, {\tt configToStr(3)}, {\tt
rcclSetOptions(3)}, {\tt errorStack(3)}. 
\manEnd
\end

