\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{MOVE ENCODER}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{MOTOR_LEVEL_CONTROL}},
{\tt \manName{MOVE_ENCODER}},
{\tt \manName{SET_MTORQUE}},
{\tt \manName{SET_ENCODER}},
{\tt \manName{SET_MTORQUE_BIAS}} --
RCI {\it CHG} macros to move the robot at the motor level.

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

MOTOR_LEVEL_CONTROL(rbt)
   RCI_RBT *rbt;

MOVE_ENCODER(rbt, enc, jnt)
   RCI_RBT *rbt;
   int enc, jnt;

SET_MTORQUE(rbt, tor, jnt)
   RCI_RBT *rbt;
   float tor;
   int jnt;

SET_ENCODER(rbt, enc, jnt)
   RCI_RBT *rbt;
   int enc, jnt;

SET_MTORQUE_BIAS(rbt, tor, jnts)
   RCI_RBT *rbt;
   float tor;
   int jnt;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt rbt} --}
Pointer to RCI robot structure.
\manItem{{\tt enc} --}
Encoder value.
\manItem{{\tt jnt} --}
Robot joint number.
\manItem{{\tt tor} --}
Motor shaft torque or force value, Newton-meters or Newtons.
\manSection{DESCRIPTION}
This is a set of {\it CHG} macros that post motor-level commands to the
robot interface. {\it Motor-level} refers to joint operation directly
at the acuator/encoder level, {\it before} the gear train. Hence positions
are specified by encoder values rather than joint values, and requested
torques are reduced by the appropriate gear ratio. It should be noted
that there may also be gear {\it couplings} between the joint and motor
levels, as is commonly the case with robot wrists: moving a single actuator
at the motor level may cause more than one joint to move, and vice versa.

These macros may be called from any part of an RCI program.
The RCI interface must first be placed into motor-level mode, using
the {\tt MOTOR_LEVEL_CONTROL()} macro, before the other macros will
be accepted.

{\tt MOTOR_LEVEL_CONTROL()} puts the robot interface into
motor-level mode, requiring that only motor-level motion
commands be issued
to the robot during the same and subsequent control cycles.
The {\tt controlLevel} field of the {\tt HOW} structure is set
to {\tt MOTOR_LEVEL}.

{\tt MOVE_ENCODER()} instructs the robot to move the joint specified
by {\tt jnt} to the encoder value specified by {\tt enc}
during the next control cycle.
The requested value is written into
the {\tt encSet} field of the {\tt HOW} structure.

{\tt SET_MTORQUE()} instructs the robot to put the joint specified
by {\tt jnt} into {\it torque mode} with a force specified by {\tt tor}.
The requested value is written into
the {\tt mtorqueSet} field of the {\tt HOW} structure.
The joints which are currently in torque mode are indicated
by a bitmask in the {\tt torqueMode} field.

{\tt SET_ENCODER()} instructs the robot to explicitly set the value for the
joint specified by {\tt jnt} to the value {\tt enc};
this is mainly of interest when calibrating the robot.
The set value is written into
the {\tt encSet} field of the {\tt HOW} structure.

{\tt SET_MTORQUE_BIAS()} instructs the robot to add a 
feedforward bias current
to the control output for the joint indicated by {\tt jnt}.
The set value will be written into
the {\tt mtorqueBias} field of the {\tt HOW} structure.
This bias current will normally not have any effect when the joint
is in {\it torque mode}.

Each motion command will override all previous motion
commands given to the same joint during the same cycle.

\manSection{DIAGNOSTICS}
Errors will result in an abort condition. Defined abort conditions include:

\manItem{{\tt EBadCmd} --}
One of the above commands was requested with the interface not in 
motor-level mode, or a command was requested that is not currently
supported. 

\manItem{{\tt EReqPos} --}
The requested encoder value was out of range.

\manItem{{\tt EReqVel} --}
The velocity resulting from the request would exceed limits.

\manItem{{\tt EReqTor} --}
The requested torque exceeds limits.

The limit and range checking can be switched on or off with the
{\tt SET_CHECKING()} macro.
\manSection{SEE ALSO}
\raggedright
{\tt CHG(3)}, {\tt HOW(3)}, {\tt MOVE_ANGLE(3)}, {\tt SET_CHECKING(3)}.
\manEnd
\end
