setSpeed(3)

NAME
setSpeed, setCartVel, setJointVel, setJvelScale -- RCCL velocity control routines.

USAGE
#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;

ARGUMENTS

mnp --
    Manipulator reference structure.

s --
    Speed scale factor (1.0 is nominal, less than 1.0 slows things down, and more than 1.0 speeds things up).

tvel --
    Translational velocity (mm. per second).

rvel --
    Rotational velocity (degrees per second).

jvel --
    Set of joint velocities (degrees or mm. per second).

jvscale --
    Scaling factor for the joint velocities, for which the nominal value is 1.0.

RESTRICTIONS
These routines must be called from the planning level. setJointVel() and setJvelScale() are not defined for virtual manipulators.

DESCRIPTION
These routines control the desired velocities associated with a particular manipulator.

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 .rciparams file (see RCCL_params(5)).

In addition to the speed scale, there are base velocities for both Cartesian and joint interpolated motions. These are multiplied by the various scale factors to produce the 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).

setCartVel() sets the base translational and rotational velocities for Cartesian motions. If either cvel or jvel is specified as F_UNDEF, then the setting for that value is not changed. Specifying either value as 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 tvel and rvel parameters, which may be defined in the .rciparams file (see RCCL_params(5)), or from the defined constants DEFAULT_TRANS_VEL and DEFAULT_ROT_VEL.

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

setJvelScale() sets an additional scaling factor that is applied only to joint interpolated motions, on top of the scale factors specified by setSpeed() and the speed parameter in the .rciparams file. Its nominal value is 1.0. An error is returned if 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 get primitives (see getSpeed(3)). The net desired velocities for the currently executing motion can also be read back with the routines getActiveCvel() and getActiveJointVel().

DIAGNOSTICS
These routines return -1 (or -1.0) in the event of an error. They 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:

ERange --
    A non-positive value not equal to F_UNDEF or F_DEFAULT) was specified.

    setJointVel() and setJvelScale() may also set the following:

ENotDefined --
    The routine was called for a virtual manipulator.

These routines will abort the program if called from the control level.

SEE ALSO
getSpeed(3), getActiveVel(3), setAccel(3), move(3), JLS(3), RCCL_params(5), rcclSetOptions(3), errorStack(3).