\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{HOW}{3}
\manSection{NAME}
{\tt \manName{HOW}}
-- RCI robot information structure.
\manSection{DEFINITION}
\cverbatim
#include <maxjnts.h>

typedef struct {
        int num;
        char com;
        unsigned char buf[HOW_SLUBUF];
} SLU;

typedef struct {
        int num;
        int val;
        unsigned long jnts;
} PARAMSPEC;

#define ulong unsigned long
#define ushort unsigned short

typedef struct _HOW {

/* ---- robot ID, interface version, and options ---- */

    int robotID;      /* ID of the robot */
    int controllerID;  /* ID of the controller (version) */
   long options;      /* available interface options */
   char numAdc;       /* no. of ADC channels available */
   char numDac;       /* no. of DAC channels available */
   char numPioIn;     /* no. of parallel input words avail. */
   char numPioOut;    /* no. of parallel output words avail. */
   char numSlu;       /* no. of serial line units available */

    int time;           /* time that how was last updated (ms) */

/* ---- robot position and torque information ---- */

    int controlLevel;           /* MOTOR or JOINT level ctrl */
  float ang[MAXJNTS];           /* joint angles */
    int enc[MAXJNTS];           /* encoder counts */

  float angVel[MAXJNTS];        /* joint velocities */
  float encVel[MAXJNTS];        /* encoder velocities */

  float angSet[MAXJNTS];        /* COMMANDED angle values */
    int encSet[MAXJNTS];        /* COMMANDED encoder value */

  ulong torqueMode;             /* torque controlled joints */

  float jtorque[MAXJNTS];       /* joint torques */
  float mtorque[MAXJNTS];       /* motor torques */

  float mtorqueSet[MAXJNTS];    /* COMMANDED joint torques */
  float jtorqueSet[MAXJNTS];    /* COMMANDED motor torques */

  float mtorqueBias[MAXJNTS];   /* COMMANDED joint bias torque */
  float jtorqueBias[MAXJNTS];   /* COMMANDED motor bias torque */

    int hand;                   /* hand position */
    int handForce;              /* hand force */

/* ---- robot and system state information ---- */

    int state;                  /* misc. robot information */
    int ctrlParams[HOW_MAXPARAM]
                  [MAXJNTS];    /* control parameters */

  ulong integration;    /* integration enabled (per joint) */
  ulong calibMode;      /* joint is in calibration mode */
  ulong markFound;      /* joint found its calibration mark */

   char power;          /* power is on */
   char calibrated;     /* robot is calibrated */

   char torqueOK;       /* joint torque readings present */
   char potOK;          /* potentiometer readings check out */
   char pendantOK;      /* teach pendant readings are OK */
   char forceOK;        /* force sensor readings OK */
   char jstickOK;       /* joystick sensor readings OK */
   long adc;            /* ADC channels with active readings */
   long slu;            /* SLU channels with active readings */

/* ---- calibration and IO information ---- */

    int potInput[MAXJNTS];      /* potentiometer readings */ 
   long pendantInput[HOW_PENDANT]; /* teach pendant */
  float forceInput[6];          /* force sensor values */
    int jstickInput[6];         /* six DOF joystick values */
    int adcInput[HOW_MAXADC];   /* ADC readings */
    SLU sluInput[HOW_MAXSLU];   /* SLU readings */

 ushort pioInput[HOW_MAXPIO];   /* input parallel ports */
 ushort pioOutput[HOW_MAXPIO];  /* output parallel ports */
    int dacOutput[HOW_MAXDAC];  /* DAC set values */

    SLU pendantMsg;             /* last msg sent to pendant */ 

   long checking;               /* enabled checking modes */
   char powerOnRelease;         /* keep robot power on */

/* ---- system internal stuff ----- */

  ulong loadSettings;           /* reload encSet and angSet */
  ulong newEncValues;           /* new encoder values */
} HOW;
@endcverbatim
\vfil\eject
\manSection{DESCRIPTION}
{\tt HOW} is a ``blackboard'' structure that contains run time and
feedback information
about the robot.
Much of the information in {\tt HOW} is read in from the
robot controller, usually once per control cycle. The contents of {\tt HOW}
are maintained automatically by the robot communication functions
(see {\tt robotComfxns(7)}).

Information contained in {\tt HOW} includes the position, velocity, and
torque of the robot joints, information read in from various sensors
attached to the robot controller, information about what such sensors
are available, and ``record'' information relating to commands which
have been sent to the robot controller. This information can be read at
any time by any part of the control program. 
Control tasks may use
the information in {\tt HOW} to compute commands for the next cycle;
these commands are specified with {\tt CHG} macros (q.v.).
Some of the fields are mainly intended for use by the robot interface
functions, and are not usually of concern to the programmer.
The maximum number of robot joints that {\tt HOW} can accept is the constant
{\tt HOW_MAXJNTS} (defined in {\tt <maxjnts.h>}); this value is used by
several of the packages that comprise the RCI system.

{\tt HOW} is referenced by pointer. A pointer to the {\tt HOW} structure is
contained in the robot structure {\tt RCI_RBT} (q.v.) of each robot 
attached to a control
task. Thus, given a task descriptor {\tt td}, and the index {\tt num}
returned by {\tt rciAttachRobot()}, the {\tt HOW} structure
can be obtained as follows:

\cverbatim
        HOW *how;

        how = TASKROBOT(td, num)->how; @endcverbatim

RCCL programs do not normally see the index {\tt num}; instead, a
{\tt HOW} structure pointer is contained within each robot's
{\tt MANIP} structure.

\manInset{{\bf NOTE:} The definition of the {\tt HOW} structure
is quite general, and in practice some of its fields may not
be implemented for a particular robot. All fields {\it are} implemented 
for {\tt PUMA} robots attached to Unimation controllers, although
not all sensor inputs may be available.}

\manSection{FIELDS}

\manItem{{\tt robotID} --}
Read back from the robot controller by the robot {\it startup} function.
Can be matched by the robot interface functions against the robot
ID or class information in the {\tt RCI_RBT} structure to make sure we are
talking to the ``right'' robot. This field is not always used.

\manItem{{\tt controllerID} --}
Read back from the robot controller by the robot {\it startup} function.
Can be used by the robot interface functions to make sure we are talking
to the ``right'' robot controller. This field is not always used.

\manItem{{\tt options} --}
Read back from the robot controller by the robot {\it startup} function.
Bitmask describing which of several sensor I/O options are available
from this robot controller. These options can then be enabled
used various {\tt SET} macros (see {\tt SET_TORQUE_READ(3)}).

\manItem{{\tt numAdc} --}
Read back from the robot controller by the robot {\it startup} function.
Describes the number of ADC channels available on this controller.
Input from one of these channels can be enabled using the
{\tt SET_\-ADC_\-CHAN()} macro.

\manItem{{\tt numDac} --}
Read back from the robot controller by the robot {\it startup} function.
Describes the number of DAC channels available on this controller.
Output to one of these channels can be set using the
{\tt PUT_DAC()} macro.

\manItem{{\tt numPioIn} --}
Read back from the robot controller by the robot {\it startup} function.
Describes the number of parallel input ports that are maintained
in the {\tt pioInput} field.

\manItem{{\tt numPioOut} --}
Read back from the robot controller by the robot {\it startup} function.
Describes the number of parallel output ports that are available;
these ports can be written to with the {\tt PUT_PIO()} macro.

\manItem{{\tt numSlu} --}
Read back from the robot controller by the robot {\it startup} function.
Describes the number of serial line units that are available.
Serial line units can be written to with the {\tt PUT_SLU()} macros;
reading from them is enabled with the {\tt SET_SLU_CHAN()} macro.

\manItem{{\tt controlLevel} --}
{\tolerance=10000
Set by the {\tt SET_MOTOR_LEVEL()} or {\tt SET_JOINT_LEVEL()}
macros. When the system is set to {\tt JOINT_LEVEL} mode
(the default), it will accept robot motions described at the
{\it joint level}, as described in {\tt MOVE_ANGLE(3)}.
When the system is set to {\tt MOTOR_LEVEL} mode,
it will accept robot motions described at the
{\it motor shaft level}, as described in {\tt MOVE_ENCODER(3)}.

}
\manItem{{\tt ang} --}
Read back from the robot controller, or computed from {\tt enc}, every
control cycle. The position of each robot joint angle (radians or
mm.).

\manItem{{\tt enc} --}
Read back from the robot controller by the robot {\it input} function. The
value 
of each robot joint encoder reading. Joint encoders are the lowest
representation of joint position, and are almost always discrete; hence
we represent them with integers. 

\manItem{{\tt angVel} --}
Computed by the robot {\it input} function.
This is the velocity of each robot joint (radians\-/sec. or mm.\-/sec.).

\manItem{{\tt encVel} --}
Computed by the robot {\it input} function.
This is the velocity of each robot joint in units of encoder counts per sec.

\manItem{{\tt angSet} --}
Maintained by robot interface functions.
Describes the last joint-level position {\it requested\/} for 
each joint
by either {\tt MOVE_ANGLE()} or {\tt MOVE_ENCODER()}. 
This variable is maintained regardless of the
control level. For joints which are 
in torque mode, the values are set each cycle to be equal to the
values in {\tt ang}. 

\manItem{{\tt encSet} --}
Maintained by robot interface functions.
Describes the last motor-level position {\it requested\/} for 
each joint
by either {\tt MOVE_ANGLE()} or {\tt MOVE_ENCODER()}. 
This variable is maintained regardless of the
control level. For joints which are 
in torque mode, the values are set each cycle to be equal to the
values in {\tt enc}.

\manItem{{\tt torqueMode} --}
Maintained by robot interface functions.
A bitmask describing which joints are in {\it torque mode}. Joints
are put into torque mode with the {\tt SET_MTORQUE()} or 
{\tt SET_JTORQUE()} macros, and taken out of torque mode with
any of the {\tt STOP} or {\tt MOVE} macros. 

\manItem{{\tt jtorque} --}
(When enabled) read back from the robot controller, or computed 
from {\tt mtorque}, by the robot {\it input} function. 
Describes joint-level 
torque or force values on the robot joints (Newton meters or
Newtons). This feature is available if {\tt TORQUE_AVAIL} is set
in {\tt options}, and is enabled with the {\tt SET_TORQUE_READ()}
macro.

\manItem{{\tt mtorque} --}
(When enabled) read back from the robot controller by the robot {\it input}
function.
Describes motor-level 
torque or force values on the robot joints (Newton-meters or
Newtons). This feature operates in parallel with {\tt jtorque}:
it is available if {\tt TORQUE_AVAIL} is set
in {\tt options}, and is enabled with the {\tt SET_TORQUE_READ()}
macro.

\manItem{{\tt mtorqueSet} --}
Maintained by robot interface functions.
Describes the last {\it requested} motor-level torque requested for
joints in torque mode. A value of {\tt 0} is indicated for joints which
are not in torque mode. If the system is operating at {\tt JOINT_LEVEL},
then a requested torque on one joint may result in a torque specification
for several joints at the motor-level, even though these ``side-effect''
torques may not actually be implemented.

\manItem{{\tt jtorqueSet} --}
Maintained by robot interface functions.
Describes the last {\it requested} joint-level torque requested for
joints in torque mode. A value of {\tt 0} is indicated for joints which
are not in torque mode. If the system is operating at {\tt MOTOR_LEVEL},
then a requested torque on one joint may result in a torque specification
for several joints at the joint-level, even though these ``side-effect''
torques may not actually be implemented.

\manItem{{\tt mtorqueBias} --}
Maintained by robot interface functions.
Describes the last {\it requested} motor-level torque bias requested for
each joint. These biases are feedforward torques added to the
control outputs for joints which are in position mode.
If the system is operating at {\tt JOINT_LEVEL},
then a requested torque on one joint may result in a torque specification
for several joints at the motor-level.

\manItem{{\tt jtorqueBias} --}
Maintained by robot interface functions.
Describes the last {\it requested} joint-level torque bias requested for
each joint. These biases are feedforward torques added to the
control outputs for joints which are in position mode.
If the system is operating at {\tt MOTOR_LEVEL},
then a requested torque on one joint may result in a torque specification
for several joints at the joint-level.

\manItem{{\tt hand} --}
Read back from the robot controller by the robot {\it input} function.
Describes the hand position. For many robot grippers, a value of one 
indicates the hand is open, while zero indicates it is closed.

\manItem{{\tt handForce} --}
Read back from the robot controller by the robot {\it input} function.
This feature is not implemented for many robots.

\manItem{{\tt state} --}
Read back from the robot controller by the robot {\it input} function.
Contains miscellaneous state information about the robot. This field
is currently not used.

\manItem{{\tt ctrlParams} --}
Maintained by the robot interface functions.
Records parameter settings which were requested using the
macros {\tt LOAD_\-CTRL\-PAR\-AMS()} and {\tt POST_\-CTRL\-PAR\-AM()}.
Values are not recorded until the robot {\it output} function is called.
Parameter loading is not supported for some robots.

{\tolerance=10000
\manItem{{\tt integration} --}
Maintained by the robot interface functions.
A bitmask describing the joints for which {\it integration} has been
enabled with {\tt SET_INTEGRATION()}. Integration mode is not
supported for some robots.

}
\manItem{{\tt calibMode} --}
{\tolerance=10000
Maintained by the robot interface functions.
A bitmask describing the joints which have been placed in
calibration mode with {\tt SET_CALIBMODE()}. Set bits are cleared
automatically when the corresponding joint is set with
{\tt SET_ENCODER()} or {\tt SET_ANGLE()}. RCI control over
calibration is not supported for some robots.

}
\manItem{{\tt markFound} --}
Maintained by the robot interface functions and the robot controller.
A bitmask indicating which joints (in calibration mode) have located
their reference mark. Set bits are cleared
automatically when the corresponding joint is set with
{\tt SET_ENCODER()} or {\tt SET_ANGLE()}.

\manItem{{\tt power} --}
Read back from the robot controller by the robot {\it input} function.
A value of {\tt 1} indicates robot power is on, {\tt 0} indicates it is off.
Power is controlled using {\tt SET_POWER_ON()} or {\tt SET_POWER_OFF()}.

\manItem{{\tt calibrated} --}
Read back from the robot controller by the robot {\it input} function.
The value of this variable is set by the {\tt SET_CALIBFLAG()} macro,
and is intended to indicate whether the robot arm is calibrated.
This variable will be cleared when the robot is powered up (and is
hence uncalibrated).

\manItem{{\tt torqueOK} --}
Read back from the robot controller by the robot {\it input} function.
Set true if valid data is present in {\tt mtorque} and {\tt jtorque}.

\manItem{{\tt potOK} --}
Read back from the robot controller by the robot {\it input} function.
Set true if valid data is present in {\tt potInput}.

\manItem{{\tt pendantOK} --}
Read back from the robot controller by the robot {\it input} function.
Set true if valid data is present in {\tt pendantInput}.

\manItem{{\tt forceOK} --}
Read back from the robot controller by the robot {\it input} function.
Set true if valid data is present in {\tt forceInput}.

\manItem{{\tt jstickOK} --}
Read back from the robot controller by the robot {\it input} function.
Set true if valid data is present in {\tt jstickInput}.

\manItem{{\tt adc} --}
Maintained by the robot interface functions.
Describes which ADC channels are currently returning valid data.
Channels are enabled with {\tt SET_\-ADC_\-CHAN()}.

\manItem{{\tt slu} --}
Maintained by the robot interface functions.
Describes which serial line units are currently
returning valid data. Channels are enabled with
{\tt SET_\-SLU_\-CHAN()}.

\manItem{{\tt potInput} --}
(When enabled) read back from the robot controller 
by the robot {\it input} function.
Contains potentiometer readings for each joint. Some robots maintain
potentiometers to roughly indicate the location of each joint. This
can then be used as part of the calibration process.
This feature is available if {\tt POTS_AVAIL} is set
in {\tt options}, and is enabled with the {\tt SET_POT_READ()}
macro.

\manItem{{\tt pendantInput} --}
(When enabled) read back from the robot controller 
by the robot {\it input} function.
In principle, this data represents a bit map of the teach pendant,
where a set bit indicates that a certain button is being pressed.
This feature is available if {\tt PENDANT_AVAIL} is set
in {\tt options}, and is enabled with the {\tt SET_PENDANT_READ()}
macro.

\manItem{{\tt forceInput} --}
(When enabled) read back from the robot controller 
by the robot {\it input} function.
This contains up to 6 force readings from a (presumably Cartesian)
force sensor, ideally arranged as 3 translational forces (Newtons)
followed by 3 torques (Newton-meters).
This feature is available if {\tt FORCE_AVAIL} is set
in {\tt options}, and is enabled with the {\tt SET_FORCE_READ()}
macro.

\manItem{{\tt jstickInput} --}
(When enabled) read back from the robot controller 
by the robot {\it input} function.
This contains up to 6 inputs from a joystick interface.
This feature is available if {\tt JSTICK_AVAIL} is set
in {\tt options}, and is enabled with the {\tt SET_JSTICK_READ()}
macro.

\manItem{{\tt adcInput} --}
(When enabled) read back from the robot controller 
by the robot {\it input} function.
Contains ADC readings for those channels which have been enabled
using {\tt SET_\-ADC_\-CHAN()}. The maximum number of ADC channels available
is stored in the {\tt numAdc} field.

\manItem{{\tt sluInput} --}
(When enabled) read back from the robot controller 
by the robot {\it input} function.
Contains the byte packets received by serial line units
whose inputs have been enabled with {\tt SET_SLU_CHAN()}.
Byte packet information reflects only those bytes received during the
last control cycle and is constantly refreshed; it is hence up to
the control functions to record the bytes when they appear.
The maximum number of serial line units available
is stored in the {\tt numSlu} field.

\manItem{{\tt pioInput} --}
Read back from the robot controller 
by the robot {\it input} function.
The number of 
ports which are active is described in the {\tt numPioIn} field.

\manItem{{\tt pioOutput} --}
Read back from the robot controller 
by the robot {\it input} function.
The values on the parallel output ports, which are set
using {\tt PUT_PIO()}.

\manItem{{\tt dacOutput} --}
Maintained by the robot interface functions
The DAC value setting sent to the robot controller with
{\tt PUT_DAC()}. The number of available channels is described in the
{\tt numDac} field.

\manItem{{\tt pendantMsg} --}
Maintained by the robot interface functions.
Contains the last message sent to the teach pendant with the
{\tt PUT_PENDANT_MSG()} macro.

\manItem{{\tt checking} --}
Maintained by the robot interface functions.
Describes which checking modes are currently enabled.
Checking modes and how they are set are described in
{\tt SET_CHECKING(3)}.

\manItem{{\tt powerOnRelease} --}
Maintained by the robot interface functions.
If this field is true, then robot power will not be shut off when the
control task is released. This field is set with the 
{\tt SET_\-POWER_\-ON_\-RELEASE()} macro.

\manItem{{\tt loadSettings} --}
Maintained and used internally by the robot interface functions.
A bitmask which indicates when the {\tt setEnc} and
{\tt setAng} fields for a particular joint
should be loaded from {\tt enc} and {\tt ang}.

\manItem{{\tt newEncValues} --}
Maintained and used internally by the robot interface functions.
Not currently used.

\manItem{{\tt time} --}
Maintained by robot interface functions. Ideally, the last time
that {\tt HOW} was updated. This field is not currently used.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt CHG(3)}, {\tt rciAttachRobot(3)}, {\tt TASKROBOT(3)}, {\tt
RCI_RBT(3)}, {\tt robotComfxns(7)}. 
\medskip
{\tt CHG} commands which have the effect of changing fields in the
{\tt HOW} structure are defined in the following pages:
\smallskip
{\tt POST_CTRLPARAM(3)}, {\tt SET_CHECKING(3)}, {\tt SET_POWER_ON(3)},
{\tt PUT_PIO(3)}, {\tt MOVE_ENCODER(3)}, {\tt SET_STOP(3)},
{\tt MOVE_ANGLE(3)}, {\tt SET_HANDPOS(3)}, {\tt SET_TORQUE_READ(3)}.
\manEnd
\end
