HOW(3)

NAME
HOW -- RCI robot information structure.

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

DESCRIPTION
HOW is a "blackboard" structure that contains run time and feedback information about the robot. Much of the information in HOW is read in from the robot controller, usually once per control cycle. The contents of HOW are maintained automatically by the robot communication functions (see robotComfxns(7)).

Information contained in 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 HOW to compute commands for the next cycle; these commands are specified with 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 HOW can accept is the constant HOW_MAXJNTS (defined in <maxjnts.h>); this value is used by several of the packages that comprise the RCI system.

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

        HOW *how;

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

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

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

FIELDS

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

controllerID --
    Read back from the robot controller by the robot 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.

options --
    Read back from the robot controller by the robot 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 SET macros (see SET_TORQUE_READ(3)).

numAdc --
    Read back from the robot controller by the robot startup function. Describes the number of ADC channels available on this controller. Input from one of these channels can be enabled using the SET_ADC_CHAN() macro.

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

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

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

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

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

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

enc --
    Read back from the robot controller by the robot 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.

angVel --
    Computed by the robot input function. This is the velocity of each robot joint (radians/sec. or mm./sec.).

encVel --
    Computed by the robot input function. This is the velocity of each robot joint in units of encoder counts per sec.

angSet --
    Maintained by robot interface functions. Describes the last joint-level position requested for each joint by either MOVE_ANGLE() or 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 ang.

encSet --
    Maintained by robot interface functions. Describes the last motor-level position requested for each joint by either MOVE_ANGLE() or 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 enc.

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

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

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

mtorqueSet --
    Maintained by robot interface functions. Describes the last requested motor-level torque requested for joints in torque mode. A value of 0 is indicated for joints which are not in torque mode. If the system is operating at 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.

jtorqueSet --
    Maintained by robot interface functions. Describes the last requested joint-level torque requested for joints in torque mode. A value of 0 is indicated for joints which are not in torque mode. If the system is operating at 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.

mtorqueBias --
    Maintained by robot interface functions. Describes the last 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 JOINT_LEVEL, then a requested torque on one joint may result in a torque specification for several joints at the motor-level.

jtorqueBias --
    Maintained by robot interface functions. Describes the last 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 MOTOR_LEVEL, then a requested torque on one joint may result in a torque specification for several joints at the joint-level.

hand --
    Read back from the robot controller by the robot 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.

handForce --
    Read back from the robot controller by the robot input function. This feature is not implemented for many robots.

state --
    Read back from the robot controller by the robot input function. Contains miscellaneous state information about the robot. This field is currently not used.

ctrlParams --
    Maintained by the robot interface functions. Records parameter settings which were requested using the macros LOAD_CTRLPARAMS() and POST_CTRLPARAM(). Values are not recorded until the robot output function is called. Parameter loading is not supported for some robots.

integration --
    Maintained by the robot interface functions. A bitmask describing the joints for which integration has been enabled with SET_INTEGRATION(). Integration mode is not supported for some robots.

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

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 SET_ENCODER() or SET_ANGLE().

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

calibrated --
    Read back from the robot controller by the robot input function. The value of this variable is set by the 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).

torqueOK --
    Read back from the robot controller by the robot input function. Set true if valid data is present in mtorque and jtorque.

potOK --
    Read back from the robot controller by the robot input function. Set true if valid data is present in potInput.

pendantOK --
    Read back from the robot controller by the robot input function. Set true if valid data is present in pendantInput.

forceOK --
    Read back from the robot controller by the robot input function. Set true if valid data is present in forceInput.

jstickOK --
    Read back from the robot controller by the robot input function. Set true if valid data is present in jstickInput.

adc --
    Maintained by the robot interface functions. Describes which ADC channels are currently returning valid data. Channels are enabled with SET_ADC_CHAN().

slu --
    Maintained by the robot interface functions. Describes which serial line units are currently returning valid data. Channels are enabled with SET_SLU_CHAN().

potInput --
    (When enabled) read back from the robot controller by the robot 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 POTS_AVAIL is set in options, and is enabled with the SET_POT_READ() macro.

pendantInput --
    (When enabled) read back from the robot controller by the robot 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 PENDANT_AVAIL is set in options, and is enabled with the SET_PENDANT_READ() macro.

forceInput --
    (When enabled) read back from the robot controller by the robot 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 FORCE_AVAIL is set in options, and is enabled with the SET_FORCE_READ() macro.

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

adcInput --
    (When enabled) read back from the robot controller by the robot input function. Contains ADC readings for those channels which have been enabled using SET_ADC_CHAN(). The maximum number of ADC channels available is stored in the numAdc field.

sluInput --
    (When enabled) read back from the robot controller by the robot input function. Contains the byte packets received by serial line units whose inputs have been enabled with 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 numSlu field.

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

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

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

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

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

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 SET_POWER_ON_RELEASE() macro.

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

newEncValues --
    Maintained and used internally by the robot interface functions. Not currently used.

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

SEE ALSO
CHG(3), rciAttachRobot(3), TASKROBOT(3), RCI_RBT(3), robotComfxns(7).

CHG commands which have the effect of changing fields in the HOW structure are defined in the following pages: POST_CTRLPARAM(3), SET_CHECKING(3), SET_POWER_ON(3), PUT_PIO(3), MOVE_ENCODER(3), SET_STOP(3), MOVE_ANGLE(3), SET_HANDPOS(3), SET_TORQUE_READ(3).