\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setSpeed}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setSpeed}},
{\tt \manName{setCartVel}},
{\tt \manName{setJointVel}},
{\tt \manName{setJvelScale}}
-- RCCL velocity control routines.

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

float setSpeed (mnp, s)
  MANIP *mnp;
  float s;

setCartVel (mnp, tvel, rvel)
  MANIP *mnp;
  float tvel, rvel;

setJointVel (mnp, jvel)
  MANIP *mnp;
  JNTS *jvel;

float setJvelScale (mnp, jvscale)
  MANIP *mnp;
  float jvscale;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt s} --}
Speed scale factor (1.0 is nominal, less than 1.0 slows things
down, and more than 1.0 speeds things up).
\manItem{{\tt tvel} --}
Translational velocity (mm. per second).
\manItem{{\tt rvel} --}
Rotational velocity (degrees per second).
\manItem{{\tt jvel} --}
Set of joint velocities (degrees or mm. per second).
\manItem{{\tt jvscale} --}
Scaling factor for the joint velocities, for which the nominal value
is 1.0.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
{\tt setJointVel()} and {\tt setJvelScale()} are not defined for
virtual manipulators.
\manSection{DESCRIPTION}
These routines control the desired velocities
associated with a particular manipulator.

{\tt setSpeed()} sets the manipulator speed scale
and returns the previous value. The speed scale is a multiplier
which is applied to the base velocities.
A speed of
1.0 is nominal. Setting the
speed to 0.5 will cut the robot velocity in half, while setting it to 2.0 will
double the velocity.
Setting the speed to a non-positive value causes an error
(it won't make the robot go backwards).

The speed scale is multiplied internally by any speed scale 
specified in the {\tt .rciparams} file (see {\tt RCCL_params(5)}).

In addition to the speed scale, there are {\it base velocities} for both
Cartesian and joint interpolated motions. These are 
multiplied by the various scale factors to produce
the {\it net desired velocity} which the trajectory generator
uses to produce the motion. The motion is planned so
that it ramps up to net desired velocity but does not exceed it.
If the motion is very short, the net desired velocity may not be reached.
Also, the trajectory generator does not take into account additional 
velocities produced as the manipulator tracks changes in the
target position (which may occur if the target position contains variable
transforms or joint biases).

{\tt setCartVel()} sets the base translational and rotational
velocities for Cartesian motions. 
If either {\tt cvel} or {\tt jvel} is specified as {\tt F_UNDEF}, then the
setting for that value is not changed. Specifying either value as
{\tt F_DEFAULT} causes the default system value to be set. Other
non-positive values will cause an error.
Default values for the translational and rotational velocities are
obtained from either the {\tt tvel} and {\tt rvel} parameters, which may
be defined in the {\tt .rciparams} file (see {\tt RCCL_params(5)}), 
or from the defined constants {\tt DEFAULT_TRANS_VEL} and {\tt
DEFAULT_ROT_VEL}.  

{\tt setJointVel()} sets the base velocity of the manipulator
for joint interpolated motions. Values are placed in the
{\tt v} field of {\tt jvel}.
If any of these are set to {\tt F_UNDEF}, then the
setting for that value is not changed. Specifying any value as
{\tt F_DEFAULT} causes the default system value to be set. 
Other non-positive velocity values will cause an error.
If the {\tt jvel} argument is omitted entirely (specified as {\tt NULL}),
then the default joint velocities
are set for all the joints. 
Default values for the joint velocities are taken from
the {\tt nominalVel} field of the robot's {\tt JLS} structure (q.v.).

{\tt setJvelScale()} sets an additional scaling factor that is applied only
to joint interpolated motions, on top of the scale factors specified by {\tt 
setSpeed()} and the {\tt speed} parameter in the {\tt .rciparams} file.
Its nominal value is 1.0.
An error is returned if {\tt jvscale} is non-positive.

The net desired velocites specified by these primitives take effect at the
beginning of the next requested motion, and are valid for all subsequent
motions. The values set by the primitives can be read back immediately
using the corresponding {\it get} primitives (see {\tt getSpeed(3)}).
The net desired velocities for the currently executing motion can also
be read back with the routines {\tt getActiveCvel()} and 
{\tt getActiveJointVel()}.

\manSection{DIAGNOSTICS}
These routines return {\tt -1} (or {\tt -1.0}) in the event of an error.
They 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 ERange} --}
A non-positive value not equal to {\tt F_UNDEF} or {\tt
F_DEFAULT}) was specified. 
\medskip
{\tt setJointVel()} and {\tt setJvelScale()} may also set the following:

\manItem{{\tt ENotDefined} --}
The routine was called for a virtual manipulator.

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt getSpeed(3)}, {\tt getActiveVel(3)}, {\tt setAccel(3)}, {\tt move(3)},  
{\tt JLS(3)}, {\tt RCCL_params(5)}, {\tt rcclSetOptions(3)}, {\tt
errorStack(3)}.
\manEnd
\end
