Nclient.h
00001 /* 
00002  * Copyright (C) 1991-2000  Nomadic Technologies
00003  *
00004  * This program is free software; you can redistribute it and/or modify
00005  * it under the terms of the GNU General Public License as published by
00006  * the Free Software Foundation; either version 2, or (at your option) 
00007  * any later version.
00008  *  
00009  * This program is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of 
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  
00012  * GNU General Public License for more details.
00013  *  
00014  * You should have received a copy of the GNU General Public License
00015  * along with this program; if not, write to the Free Software
00016  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  
00017  * 02111-1307, USA.
00018  */
00019 
00020 /*
00021  * Nclient.h
00022  *
00023  * Interface file for direct connections to the robot or for
00024  * connections to Nserver.
00025  */
00026 
00027 /*
00028  * $Log: Nclient.h,v $
00029  * Revision 1.1.1.1  2001/08/23 19:05:14  bananajr
00030  * initial commit
00031  *
00032  */
00033 
00034 #ifndef _HOST_CLIENT_NCLIENT_H_
00035 #define _HOST_CLIENT_NCLIENT_H_
00036 
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif
00040 
00041 /* constants */
00042 
00043 #ifndef FALSE
00044 #define FALSE                   0
00045 #endif
00046 #ifndef TRUE
00047 #define TRUE                    1
00048 #endif
00049 #ifndef NULL
00050 #define NULL                    0
00051 #endif
00052 #define MAX_VERTICES     10
00053 #define NUM_STATE        45
00054 #define NUM_MASK         44 
00055 #define NUM_LASER        482 
00056 #define BUFSIZE          4096
00057 #define MAX_USER_BUF     0xFFFF
00058 
00059 /* Robot models. */
00060 #define MODEL_N200   0
00061 #define MODEL_N150   1
00062 #define MODEL_SCOUT  2
00063 #define MODEL_SCOUT2 2
00064 
00065 /* the number of sonars and infrareds */
00066 #define SONARS           16
00067 #define INFRAREDS        16
00068 
00069 /*
00070  * The following defines allow you to access the State vector in a 
00071  * more readable way.
00072  */
00073 
00074 #define STATE_SIM_SPEED            0
00075 
00076 #define STATE_IR_0                 1
00077 #define STATE_IR_1                 2
00078 #define STATE_IR_2                 3
00079 #define STATE_IR_3                 4
00080 #define STATE_IR_4                 5
00081 #define STATE_IR_5                 6
00082 #define STATE_IR_6                 7
00083 #define STATE_IR_7                 8
00084 #define STATE_IR_8                 9
00085 #define STATE_IR_9                 10
00086 #define STATE_IR_10                11
00087 #define STATE_IR_11                12
00088 #define STATE_IR_12                13
00089 #define STATE_IR_13                14
00090 #define STATE_IR_14                15
00091 #define STATE_IR_15                16
00092 
00093 #define STATE_SONAR_0              17
00094 #define STATE_SONAR_1              18
00095 #define STATE_SONAR_2              19
00096 #define STATE_SONAR_3              20
00097 #define STATE_SONAR_4              21
00098 #define STATE_SONAR_5              22
00099 #define STATE_SONAR_6              23
00100 #define STATE_SONAR_7              24
00101 #define STATE_SONAR_8              25
00102 #define STATE_SONAR_9              26
00103 #define STATE_SONAR_10             27
00104 #define STATE_SONAR_11             28
00105 #define STATE_SONAR_12             29
00106 #define STATE_SONAR_13             30
00107 #define STATE_SONAR_14             31
00108 #define STATE_SONAR_15             32
00109  
00110 #define STATE_BUMPER               33
00111 #define STATE_CONF_X               34
00112 #define STATE_CONF_Y               35
00113 #define STATE_CONF_STEER           36
00114 #define STATE_CONF_TURRET          37
00115 #define STATE_VEL_TRANS            38
00116 #define STATE_VEL_RIGHT            38   /* for scout */
00117 #define STATE_VEL_STEER            39
00118 #define STATE_VEL_LEFT             39   /* for scout */
00119 #define STATE_VEL_TURRET           40
00120 #define STATE_MOTOR_STATUS         41
00121 #define STATE_LASER                42
00122 #define STATE_COMPASS              43
00123 #define STATE_ERROR                44
00124 
00125 /*
00126  * The following defines allow you to access the Smask vector in a 
00127  * more readable way.
00128  */
00129 
00130 #define SMASK_POS_DATA             0
00131 
00132 #define SMASK_IR_1                 1
00133 #define SMASK_IR_2                 2
00134 #define SMASK_IR_3                 3
00135 #define SMASK_IR_4                 4
00136 #define SMASK_IR_5                 5
00137 #define SMASK_IR_6                 6
00138 #define SMASK_IR_7                 7
00139 #define SMASK_IR_8                 8
00140 #define SMASK_IR_9                 9
00141 #define SMASK_IR_10                10
00142 #define SMASK_IR_11                11
00143 #define SMASK_IR_12                12
00144 #define SMASK_IR_13                13
00145 #define SMASK_IR_14                14
00146 #define SMASK_IR_15                15
00147 #define SMASK_IR_16                16
00148 
00149 #define SMASK_SONAR_1              17
00150 #define SMASK_SONAR_2              18
00151 #define SMASK_SONAR_3              19
00152 #define SMASK_SONAR_4              20
00153 #define SMASK_SONAR_5              21
00154 #define SMASK_SONAR_6              22
00155 #define SMASK_SONAR_7              23
00156 #define SMASK_SONAR_8              24
00157 #define SMASK_SONAR_9              25
00158 #define SMASK_SONAR_10             26
00159 #define SMASK_SONAR_11             27
00160 #define SMASK_SONAR_12             28
00161 #define SMASK_SONAR_13             29
00162 #define SMASK_SONAR_14             30
00163 #define SMASK_SONAR_15             31
00164 #define SMASK_SONAR_16             32
00165  
00166 #define SMASK_BUMPER               33
00167 #define SMASK_CONF_X               34
00168 #define SMASK_CONF_Y               35
00169 #define SMASK_CONF_STEER           36
00170 #define SMASK_CONF_TURRET          37
00171 #define SMASK_VEL_TRANS            38
00172 #define SMASK_VEL_STEER            39
00173 #define SMASK_VEL_TURRET           40
00174 #define SMASK_RESERVED             41
00175 #define SMASK_LASER                42
00176 #define SMASK_COMPASS              43
00177 
00178 /*
00179  * These defines are used for specifying the control modes in the
00180  * robot motion command 'mv'. If MV_IGNORE is specified for an axis
00181  * the current motion command for it will remain active. Specifying
00182  * MV_VM or MV_PR will select velocity and position control as in 
00183  * the vm and pr robot motion commands 
00184  */
00185 
00186 #define MV_IGNORE 0
00187 #define MV_VM     1 /* velocity mode */
00188 #define MV_PR     2 /* position relative mode */
00189 #define MV_LP     3 /* limp mode */
00190 #define MV_AC     4 /* set acceleration for vm, pr, pa modes*/
00191 #define MV_SP     5 /* set velocity for pr, pa modes */
00192 #define MV_PA     6 /* position absolute mode */
00193 #define MV_TQ     7 /* torque mode */
00194 #define MV_MT     8 /* set maximum torque for vm, pr, pa, tq modes */
00195 
00196 /*
00197  * zeroing modes for arm
00198  */
00199 
00200 #define ZR_CHECK         1
00201 #define ZR_ORIENT        2
00202 #define ZR_NO_N_GRIPPER  4
00203 
00204 /* 
00205  * user packet constants for arm 
00206  */
00207 
00208 #define ARM_ZR 40
00209 #define ARM_WS 41
00210 #define ARM_MV 42
00211 
00212 /*
00213  * function prototypes for arm
00214  */
00215 long arm_mv(long l_mode, long l_v, long g_mode, long g_v);
00216 long arm_ws(short lift, short grip, long timeout, long *time_remain);
00217 long arm_zr(short mode);
00218 
00219 /*
00220  * For requesting the PosData the following defines should be used.
00221  * Each sensor has a bit, if it is set the pos-data is attached
00222  * when the sensory data is returned.
00223  */
00224 
00225 #define POS_NONE          ( 0 << 0 )
00226 #define POS_INFRARED      ( 1 << 0 )
00227 #define POS_SONAR         ( 1 << 1 )
00228 #define POS_BUMPER        ( 1 << 2 )
00229 #define POS_LASER         ( 1 << 3 )
00230 #define POS_COMPASS       ( 1 << 4 )
00231 
00232 /* 
00233  * these macros enable the user to determine if the pos-attachment
00234  * is requested for a specific sensor. 1 is returned if the 
00235  * attachment is requested, 0 otherwise
00236  * 
00237  * Note that the function posDataCheck() is called (see below)
00238  */
00239 
00240 #define POS_INFRARED_P  ( ( (posDataCheck()) & POS_INFRARED ) ? 1 : 0 )
00241 #define POS_SONAR_P     ( ( (posDataCheck()) & POS_SONAR    ) ? 1 : 0 )
00242 #define POS_BUMPER_P    ( ( (posDataCheck()) & POS_BUMPER   ) ? 1 : 0 )
00243 #define POS_LASER_P     ( ( (posDataCheck()) & POS_LASER    ) ? 1 : 0 )
00244 #define POS_COMPASS_P   ( ( (posDataCheck()) & POS_COMPASS  ) ? 1 : 0 )
00245 
00246 /*
00247  * The user will be able to call a function that fills out a 
00248  * list of position data for a specific sensor reading. 
00249  * To access the sensors in that structure the following defines 
00250  * should be used. They should also be used if data for a single
00251  * infrared sensor / sonar is requested.
00252  */
00253 
00254 #define POS_IR_1             0
00255 #define POS_IR_2             1
00256 #define POS_IR_3             2
00257 #define POS_IR_4             3
00258 #define POS_IR_5             4
00259 #define POS_IR_6             5
00260 #define POS_IR_7             6 
00261 #define POS_IR_8             7
00262 #define POS_IR_9             8
00263 #define POS_IR_10            9
00264 #define POS_IR_11           10
00265 #define POS_IR_12           11
00266 #define POS_IR_13           12
00267 #define POS_IR_14           13
00268 #define POS_IR_15           14
00269 #define POS_IR_16           15
00270 
00271 #define POS_SONAR_1          0
00272 #define POS_SONAR_2          1
00273 #define POS_SONAR_3          2
00274 #define POS_SONAR_4          3
00275 #define POS_SONAR_5          4
00276 #define POS_SONAR_6          5 
00277 #define POS_SONAR_7          6  
00278 #define POS_SONAR_8          7
00279 #define POS_SONAR_9          8
00280 #define POS_SONAR_10         9
00281 #define POS_SONAR_11        10
00282 #define POS_SONAR_12        11
00283 #define POS_SONAR_13        12
00284 #define POS_SONAR_14        13
00285 #define POS_SONAR_15        14
00286 #define POS_SONAR_16        15
00287 
00288 
00289 /* Define the length of the user buffer (Maximal short).
00290  * Due to Protocol bytes, the effective length is 65526 
00291  */
00292 #define USER_BUFFER_LENGTH      0xFFFF
00293 
00294 
00295 /* these definitions apply to the Scout and SuperScout */
00296 #define ROTATION_CONSTANT       0.118597  /* inches/degree (known to 100 ppm) */
00297 
00298 #define RIGHT(trans, steer)     (trans + (int)((float)steer*ROTATION_CONSTANT))
00299 #define LEFT(trans, steer)      (trans - (int)((float)steer*ROTATION_CONSTANT))
00300 
00301 #define scout_vm(trans, steer)  vm(RIGHT(trans, steer), LEFT(trans, steer), 0)
00302 
00303 /********************
00304  *                  *
00305  * Type definitions *
00306  *                  *
00307  ********************/
00308 
00309 /*
00310  * The following type definitions are used for the PosData.
00311  * PosData is an information packet that is attached to 
00312  * each sensor reading, if requested. Note that the use of 
00313  * PosData could cause compatibility problems when different
00314  * releases of the software are used on the robot and on the
00315  * server side. 
00316  *
00317  * The information packet can be used to determine how up-to-date
00318  * a sensory reading is. It contains the configuration of the robot.
00319  * This is the most updated configuration at the time of the sensor
00320  * reading. However, it is possible that the sensory reading
00321  * was taken after the integration of the coniguration.
00322  * To determine the interval that has passed two timestamps are in-
00323  * cluded in this information package: a timestamp for the computation
00324  * of the configuration and another timestamp for the actual capturing
00325  * of the senor reading.
00326  *
00327  * The timestamps are in milliseconds of the internal clock of the 
00328  * board that handles the sensors (Intellisys 100 sensor-board).
00329  */
00330 
00331 /*
00332  * TimeData contains the current time of the Intellisys 100 
00333  * in milliseconds
00334  */
00335 
00336 typedef unsigned long TimeData;
00337 
00338 /*
00339  * ConfigData is where the i486 writes the current configuration
00340  * of the robot, so that the Intellisys 100 can attach current
00341  * integration values to the sensor readings.
00342  * It is also used inside of the Pos data.
00343  */
00344 
00345 typedef struct _ConfigData
00346 {
00347     /* the configuration of the robot */
00348     long          configX;
00349     long          configY;
00350     long          configSteer;
00351     long          configTurret;
00352 
00353     /* the velocities of the robot*/
00354     long          velTrans;
00355     long          velSteer;
00356     long          velTurret;
00357 
00358     /* time of integration in milliseconds (Intellisys 100 time) */
00359     TimeData      timeStamp;
00360 
00361 } ConfigData;
00362 
00363 
00364 /* 
00365  * PosData contains information that is attached to a sensor
00366  * reading in order to determine how recent it is.
00367  */
00368 
00369 typedef struct _PosData
00370 {
00371     /* the configuration of the robot at the time of the reading */
00372     ConfigData config;
00373 
00374     /* the time of the sensing in milliseconds (Intellisys 100 time) */
00375     TimeData   timeStamp;
00376 
00377 } PosData;
00378 
00379 /* these type definitions are for user defined package processing */
00380 
00381 typedef union
00382 {
00383   char            bytes[8];
00384   double          data;
00385 } double_union;
00386 
00387 typedef union
00388 {
00389   char          bytes[4];
00390   short         words[2];
00391   long          data;
00392 } long_union;
00393 
00394 typedef union
00395 {
00396   unsigned char bytes[2];
00397   short         data;
00398 } short_union;
00399 
00400 typedef union
00401 {
00402   unsigned char   bytes[2];
00403   unsigned short  data;
00404 } ushort_union;
00405 
00406 typedef union
00407 {
00408   unsigned char bytes[4];
00409   unsigned short        words[2];
00410   unsigned long data;
00411 } ulong_union;
00412 
00413 struct request_struct
00414 {
00415   short type;
00416   unsigned short size;
00417   long  mesg[USER_BUFFER_LENGTH];
00418 };
00419 
00420 struct reply_struct
00421 {
00422   short type;
00423   unsigned short size;
00424   long  mesg[USER_BUFFER_LENGTH];
00425 };
00426 
00427 /********************
00428  *                  *
00429  * Global Variables *
00430  *                  *
00431  ********************/
00432 
00433 /* The State vector is an array of 45 long integers:
00434  *
00435  *   State[0] - stores actual simulation speed with 10 being realtime 
00436  *              (20 meaning twice as fast as realtime and 5 meaning half the 
00437  *              speed of realtime).
00438  *   State[1 ... 16] - stores the 16 infrared data.
00439  *   State[17 ... 32] - stores the 16 sonar data.
00440  *   State[33] - stores bumper data
00441  *   State[34 ... 37] - stores robot configuration
00442  *   State[38 ... 40] - stores robot's current velocities
00443  *   State[41] - motor status: the lowest bit is set to 1 if the translational
00444  *               motor is active; the second lowest bit is set to 1 if the 
00445  *               steering motor is active; the third lowest bit is set to 1 if 
00446  *               the turret motor is active.
00447  *   State[42] - laser mode: the mode of the laser.
00448  *   State[43] - compass value.
00449  *   State[44] - error number.
00450  */
00451 extern long State[NUM_STATE];
00452 
00453 /* The Smask vector is an array of 44 integers:
00454  *
00455  *   Smask[0] - used for the posData attachment to sensory data
00456  *   Smask[1 ... 16] - infrared mask
00457  *   Smask[17 ... 32] - sonar mask
00458  *   Smask[33] - bumper mask
00459  *   Smask[34 ... 37] - configuration mask
00460  *   Smask[38 ... 40] - velocity mask
00461  *   Smask[41] - irrelevant.
00462  *   Smask[42] - laser mask
00463  *   Smask[43] - compass mask
00464  */
00465 extern int Smask[NUM_MASK];
00466 
00467 /* Mask is now just a pointer to Smask. This is because Mask is a declared
00468  * variable in X11 library. So if you are not using X11, you can uncomment
00469  * the following line and keep using Mask as before. However, if you want
00470  * to use X11 graphic in your application program, you can simply use Smask
00471  * instead. 
00472  */
00473 /* static int *Mask = Smask; */
00474 
00475 /* The Laser vector is an array of 965 elements. The Laser vector
00476  * can contain laser data in one of the three formats: pixel, point, or line.
00477  *
00478  *    In pixel mode (not available in simulation, Laser[0] keeps the number of 
00479  *    pixels in the Laser vector. The can be a maximum of 482 pixels.
00480  *
00481  *    In point mode, Laser[0] keeps the number of points. Each point is 
00482  *    specified y the two numbers: the x and y coordinates of the point in 
00483  *    the robot's local coordinate. There can be a maximum of 482 points 
00484  *    (thus 964 numbers).
00485  *
00486  *    In line mode, Laser[0] keeps the number of lines. Each line segment is 
00487  *    specified by its two end points and each end point is specified by its 
00488  *    x and y coordinates in the robot's local coordinate. There can be a 
00489  *    maximum of 241 points. 
00490  */
00491 extern int Laser[2*NUM_LASER+1];
00492 
00493 /* If linking the application program with Nclient.o, it will connect 
00494  * to Nserver. To specify to which machine to connect and which port
00495  * to use the following variables can be redefined, otherwise default 
00496  * values are used:
00497  *     SERVER_MACHINE_NAME
00498  *     SERV_TCP_PORT
00499  *
00500  * If linking the application program with Ndirect.o, it will connect
00501  * directly to the robot. To specify to which robot to connect and
00502  * which parameters to use for the connection the following variables
00503  * can be redefined, otherwise default vaues are used:
00504  *     ROBOT_MACHINE_NAME
00505  * usually don't need to be changed:
00506  *     CONN_TYPE
00507  *     SERIAL_PORT
00508  *     SERIAL_BAUD
00509  *     ROBOT_TCP_PORT
00510  *
00511  * If an application program should run with Nclient.o and Ndirect.o
00512  * all of the above variables should be initialized.
00513  *
00514  * The concerend variables are define below.
00515  */
00516 
00517 /* SERVER_MACHINE_NAME is the name of the machine where the server is 
00518  * running. You should specify the server machine name in your
00519  * program if the server is running on a computer different from 
00520  * where the client is running 
00521  */
00522 extern char SERVER_MACHINE_NAME[80];
00523 
00524 /* SERV_TCP_PORT is an arbitrary port number the server listens to for 
00525  * request of connection. It should be the same as that specified in the 
00526  * world.setup file. You may modify this number and that in the world.setup 
00527  * file to allow multiple servers running on the same machine. 
00528  */
00529 extern int SERV_TCP_PORT;
00530 
00531 /* ROBOT_MACHINE_NAME is the name of the machine on the robot 
00532  */
00533 extern char ROBOT_MACHINE_NAME[80];
00534 
00535 /* CONN_TYPE is the selection between using a serial port or a TCP/IP port.
00536  * If set to 1, serial port is used.  If set to 2 (the default), TCP/IP port
00537  * is used.  If set to any other value, connection will fail.
00538  */
00539 extern int CONN_TYPE;
00540 
00541 /* SERIAL_PORT is a string containing the filename of the serial port you
00542  * choose to communicate to the robot on.  The default is "/dev/ttyS0".
00543  */
00544 extern char SERIAL_PORT[40];
00545 
00546 /* SERIAL_BAUD is the baud rate to set the serial communication to.  It
00547  * defaults to 9600.
00548  */
00549 extern int SERIAL_BAUD;
00550 
00551 /* ROBOT_TCP_PORT is the port number the robot listens on for request of
00552  * connection.  It defaults (and should always be set) to 65001 for the
00553  * standard binary port.
00554  */
00555 extern int ROBOT_TCP_PORT;
00556 
00557 /* LASER_CALIBRATION and LASER_OFFSET are the values that the laser
00558  * calibration software returns to you in the file Laser.cal, and that
00559  * are normally stored in the file robot.setup under [laser]calibration
00560  * and [laser]offset when Nserver is present.  Set these values with
00561  * the properly calculated values for your laser system if you have one.
00562  * This is only needed for linking with Ndirect.o. 
00563  */
00564 
00565 extern double LASER_CALIBRATION[8];
00566 extern double LASER_OFFSET[2];
00567 
00568 /*****************************
00569  *                           *
00570  * Robot Interface Functions *
00571  *                           *
00572  *****************************/
00573 
00574 /*
00575  * create_robot - requests the server to create a robot with
00576  *                id = robot_id and establishes a connection with
00577  *                the robot. This function is disabled in this
00578  *                version of the software.
00579  * 
00580  * parameters:
00581  *    long robot_id -- id of the robot to be created. The robot
00582  *                     will be referred to by this id. If a process
00583  *                     wants to talk (connect) to a robot, it must
00584  *                     know its id.
00585  */
00586 int create_robot(long robot_id);
00587 
00588 /*
00589  * connect_robot - requests the server to connect to the robot
00590  *                 with id = robot_id. In order to talk to the server,
00591  *                 the SERVER_MACHINE_NAME and SERV_TCP_PORT must be
00592  *                 set properly. If a robot with robot_id exists,
00593  *                 a connection is established with that robot. If
00594  *                 no robot exists with robot_id, no connection is
00595  *                 established.
00596  *
00597  * parameters:
00598  *    long robot_id -- robot's id. In this multiple robot version, in order
00599  *                     to connect to a robot, you must know it's id.
00600  *         model    -- robot type: 0 = Nomad 200, 1 = Nomad 150, 2 = Scout
00601  *         *dev     -- hostname for TCP, device file for serial ("/dev/" prefix
00602  *                     or ":" suffix means serial)
00603  *         conn     -- TCP port for TCP, baud rate for serial
00604  */
00605 int connect_robot(long robot_id, ...);
00606 
00607 /*
00608  * disconnect_robot - requests the server to close the connect with robot
00609  *                    with id = robot_id. 
00610  *
00611  * parameters:
00612  *    long robot_id -- robot's id. In order to disconnect a robot, you
00613  *                     must know it's id.
00614  */
00615 int disconnect_robot(long robot_id);
00616 
00617 /* 
00618  * ac - sets accelerations of the robot. Currently it has no effect in 
00619  *      simulation mode.
00620  *
00621  * parameters:
00622  *    int t_ac, s_ac, r_ac -- the translation, steering, and turret
00623  *                            accelerations. t_ac is in 1/10 inch/sec^2
00624  *                            s_ac and r_ac are in 1/10 degree/sec^2.
00625  */
00626 int ac(int t_ac, int s_ac, int r_ac);
00627 
00628 /*
00629  * sp - sets speeds of the robot, this function will not cause the robot to
00630  *      move. However, the set speed will be used when executing a pr()
00631  *      or a pa().
00632  *
00633  * parameters:
00634  *    int t_sp, s_sp, r_sp -- the translation, steering, and turret
00635  *                            speeds. t_sp is in 1/10 inch/sec and
00636  *                            s_sp and r_sp are in 1/10 degree/sec.
00637  */
00638 int sp(int t_sp, int s_sp, int r_sp);
00639 
00640 /*
00641  * pr - moves the motors of the robot by a relative distance, using the speeds
00642  *      set by sp(). The three parameters specify the relative distances for
00643  *      the three motors: translation, steering, and turret. All the three
00644  *      motors move concurrently if the speeds are not set to zero and the 
00645  *      distances to be traveled are non-zero. Depending on the timeout 
00646  *      period set (by function conf_tm(timeout)), the motion may 
00647  *      terminate before the robot has moved the specified distances
00648  *
00649  * parameters:
00650  *    int t_pr, s_pr, r_pr -- the specified relative distances of the
00651  *                            translation, steering, and turret motors.
00652  *                            t_pr is in 1/10 inch and s_pr and r_pr are
00653  *                            in 1/10 degrees.
00654  */
00655 int pr(int t_pr, int s_pr, int r_pr);
00656 
00657 /*
00658  * vm - velocity mode, command the robot to move at translational
00659  *      velocity = tv, steering velocity = sv, and rotational velocity =
00660  *      rv. The robot will continue to move at these velocities until
00661  *      either it receives another command or this command has been
00662  *      timeout (in which case it will stop its motion).
00663  *
00664  * parameters: 
00665  *    int t_vm, s_vm, r_vm -- the desired translation, steering, and turret
00666  *                            velocities. tv is in 1/10 inch/sec and
00667  *                            sv and rv are in 1/10 degree/sec.
00668  */
00669 int vm(int t_vm, int s_vm, int r_vm);
00670 
00671 /*
00672  * mv - move, send a generalized motion command to the robot.
00673  *      For each of the three axis (translation, steering, and
00674  *      turret) a motion mode (t_mode, s_mode, r_mode) can be 
00675  *      specified (using the values MV_IGNORE, MV_AC, MV_SP,
00676  *      MV_LP, MV_VM, and MV_PR defined above):
00677  *
00678  *         MV_IGNORE : the argument for this axis is ignored
00679  *                     and the axis's motion will remain 
00680  *                     unchanged.
00681  *         MV_AC :     the argument for this axis specifies
00682  *                     an acceleration value that will be used
00683  *                     during motion commands.
00684  *         MV_SP :     the argument for this axis specifies
00685  *                     a speed value that will be used during
00686  *                     position relative (PR) commands.
00687  *         MV_LP :     the arguemnt for this axis is ignored
00688  *                     but the motor is turned off.
00689  *         MV_VM :     the argument for this axis specifies
00690  *                     a velocity and the axis will be moved
00691  *                     with this velocity until a new motion
00692  *                     command is issued (vm,pr,mv) or 
00693  *                     recieves a timeout.
00694  *         MV_PR :     the argument for this axis specifies
00695  *                     a position and the axis will be moved
00696  *                     to this position, unless this command
00697  *                     is overwritten by another (vm,pr,mv).
00698  *
00699  * parameters: 
00700  *    int t_mode - the desired mode for the tranlation axis
00701  *    int t_mv   - the value for that axis, velocity or position,
00702  *                 depending on t_mode
00703  *    int s_mode - the desired mode for the steering axis
00704  *    int s_mv   - the value for that axis, velocity or position,
00705  *                 depending on t_mode
00706  *    int r_mode - the desired mode for the turret axis
00707  *    int r_mv   - the value for that axis, velocity or position,
00708  *                 depending on t_mode
00709  */
00710 int mv(int t_mode, int t_mv, int s_mode, int s_mv, int r_mode, int r_mv);
00711 
00712 /*
00713  * ct - send the sensor mask, Smask, to the robot. You must first change
00714  *      the global variable Smask to the desired communication mask before
00715  *      calling this function. 
00716  */
00717 int ct(void);
00718 
00719 /*
00720  * gs - get the current state of the robot according to the mask (of 
00721  *      the communication channel)
00722  */
00723 int gs(void);
00724 
00725 /*
00726  * st - stops the robot (the robot holds its current position)
00727  */
00728 int st(void);
00729 
00730 /*
00731  * lp - set motor limp (the robot may not hold its position).
00732  */
00733 int lp(void);
00734 
00735 /*
00736  * tk - sends the character stream, talk_string, to the voice synthesizer
00737  *      to make the robot talk.
00738  *
00739  * parameters:
00740  *    char *talk_string -- the string to be sent to the synthesizer.
00741  */
00742 int tk(char *talk_string);
00743 
00744 /*
00745  * dp - define the current position of the robot as (x,y)
00746  * 
00747  * parameters:
00748  *    int x, y -- the position to set the robot to.
00749  */
00750 int dp(int x, int y);
00751 
00752 /*
00753  * zr - zeroing the robot, align steering and turret with bumper zero.
00754  *      The position, steering and turret angles are all set to zero.
00755  *      This function returns when the zeroing process has completed.
00756  */
00757 int zr(void);
00758 
00759 /*
00760  * conf_ir - configure infrared sensor system.
00761  *
00762  * parameters: 
00763  *    int history -- specifies the percentage dependency of the current 
00764  *                   returned reading on the previous returned reading.
00765  *                   It should be set between 0 and 10: 0 = no dependency 
00766  *                   10 = full dependency, i.e. the reading will not change
00767  *    int order[16] --  specifies the firing sequence of the infrared 
00768  *                      (#0 .. #15). You can terminate the order list by a 
00769  *                      "255". For example, if you want to use only the 
00770  *                      front three infrared sensors then set order[0]=0,
00771  *                      order[1]=1, order[2]=15, order[3]=255 (terminator).
00772  */
00773 int conf_ir(int history, int order[16]);
00774 
00775 /*
00776  * conf_sn - configure sonar sensor system.
00777  *
00778  * parameters:
00779  *    int rate -- specifies the firing rate of the sonar in 4 milli-seconds 
00780  *                interval; 
00781  *    int order[16] -- specifies the firing sequence of the sonar (#0 .. #15).
00782  *                     You can terminate the order list by a "255". For 
00783  *                     example, if you want to use only the front three 
00784  *                     sensors, then set order[0]=0, order[1]=1, order[2]=15, 
00785  *                     order[3]=255 (terminator).
00786  */
00787 int conf_sn(int rate, int order[16]);
00788 
00789 /*
00790  * conf_cp - configure compass system.
00791  * 
00792  * parameters:
00793  *    int mode -- specifies compass on/off: 0 = off ; 1 = on; 2 = calibrate.
00794  *                When you call conf_cp (2), the robot will rotate slowly 360
00795  *                degrees. You must wait till the robot stops rotating before
00796  *                issuing another command to the robot (takes ~3 minutes).
00797  */
00798 int conf_cp(int mode);
00799 
00800 /*
00801  * conf_ls - configure laser sensor system:
00802  *
00803  * parameters:
00804  *    unsigned int mode -- specifies the on-board processing mode of the laser 
00805  *                         sensor data which determines the mode of the data 
00806  *                         coming back: 
00807  *                           the first bit specifies the on/off;
00808  *                           the second bit specifies point/line mode;
00809  *                           the third to fifth bits specify the 
00810  *                           returned data types: 
00811  *                             000 = peak pixel, 
00812  *                             001 = rise pixel, 
00813  *                             010 = fall pixel, 
00814  *                             011 = magnitude,
00815  *                             100 = distance;
00816  *                           the sixth bit specifies data integrity checking.
00817  *
00818  *   unsigned int threshold -- specifies the inverted acceptable brightness
00819  *                             of the laser line. 
00820  *
00821  *   unsigned int width -- specifies the acceptable width in terms
00822  *                         of number of pixels that are brighter than the 
00823  *                         set threshold.
00824  *  
00825  *   unsigned int num_data -- specifies the number of sampling points. 
00826  *   unsigned int processing --  specifies the number of neighboring 
00827  *                               pixels for averaging
00828  *
00829  * If you don't understand the above, try this one:
00830  *   conf_ls(51, 20, 20, 20, 4)
00831  */
00832 int conf_ls(unsigned int mode,
00833             unsigned int threshold,
00834             unsigned int width,
00835             unsigned int num_data,
00836             unsigned int processing);
00837 
00838 /*
00839  * conf_tm - sets the timeout period of the robot in seconds. If the
00840  *           robot has not received a command from the host computer
00841  *           for more than the timeout period, it will abort its 
00842  *           current motion
00843  * 
00844  * parameters:
00845  *    unsigned int timeout -- timeout period in seconds. If it is 0, there
00846  *                            will be no timeout on the robot.
00847  */
00848 int conf_tm(unsigned char timeout);
00849 
00850 /*
00851  * get_ir - get infrared data, independent of mask. However, only 
00852  *          the active infrared sensor readings are valid. It updates
00853  *          the State vector.
00854  */
00855 int get_ir(void);
00856 
00857 /*
00858  * get_sn - get sonar data, independent of mask. However, only 
00859  *          the active sonar sensor readings are valid. It updates
00860  *          the State vector.
00861  */
00862 int get_sn(void);
00863 
00864 /*
00865  * get_rc - get robot configuration data (x, y, th, tu), independent of 
00866  *          mask. It updates the State vector.
00867  */
00868 int get_rc(void);
00869 
00870 /*
00871  * get_rv - get robot velocities (translation, steering, and turret) data,
00872  *          independent of mask. It updates the State vector.
00873  */
00874 int get_rv(void);
00875 
00876 /*
00877  * get_ra - get robot acceleration (translation, steering, and turret) data,
00878  *          independent of mask. It updates the State vector.
00879  */
00880 int get_ra(void);
00881 
00882 /*
00883  * get_cp - get compass data, independent of mask. However, the
00884  *          data is valid only if the compass is on. It updates the
00885  *          State vector.
00886  */
00887 int get_cp(void);
00888 
00889 /*
00890  * get_ls - get laser data point mode, independent of mask. However the
00891  *          data is valid only of the laser is on. It updates the Laser 
00892  *          vector.
00893  */
00894 int get_ls(void);
00895 
00896 /*
00897  * get_bp - get bumper data, independent of mask. It updates the State
00898  *          vector.
00899  */
00900 int get_bp(void);
00901 
00902 /*
00903  * conf_sg - configure laser sensor system line segment processing mode:
00904  *
00905  * parameters:
00906  *    unsigned int threshold -- specifies the threshold value for least-square
00907  *                             fitting. When the error term grows above the 
00908  *                             threshold, the line segment will be broken
00909  *    unsigned int min_points -- specifies the acceptable number of points
00910  *                              to form a line segment.
00911  *    unsigned int gap -- specifies the acceptable "gap" between two segments
00912  *                        while they can still be treated as one (in 1/10 inch)
00913  *
00914  * If you don't understand the above, try this one:
00915  *    conf_sg(50, 4, 30)
00916  */
00917 int conf_sg(unsigned int threshold, 
00918             unsigned int min_points, 
00919             unsigned int gap);
00920 
00921 /*
00922  * get_sg - get laser data line mode, independent of mask. It updates
00923  *          the laser vector.
00924  */
00925 int get_sg(void);
00926 
00927 /*
00928  * da - define the current steering angle of the robot to be th
00929  *      and the current turret angle of the robot to be tu.
00930  * 
00931  * parameters:
00932  *    int th, tu -- the steering and turret orientations to set the
00933  *                  robot to.
00934  */
00935 int da(int th, int tu);
00936 
00937 /*
00938  * ws - waits for stop of motors of the robot. This function is intended  
00939  *      to be used in conjunction with pr() and pa() to detect the desired
00940  *      motion has finished
00941  *
00942  * parameters:
00943  *    unsigned char t_ws, s_ws, r_ws -- These three parameters specify 
00944  *                                      which axis or combination of axis 
00945  *                                      (translation, steering, and turret) 
00946  *                                      to wait. 
00947  *    unsigned char timeout -- specifies how long to wait before timing out 
00948  *                             (return without stopping the robot).
00949  */
00950 int ws(unsigned char t_ws, unsigned char s_ws,
00951        unsigned char r_ws, unsigned char timeout);
00952 
00953 /*
00954  * get_rpx - get the position of all nearby robots
00955  */
00956 int get_rpx(long *robot_pos);
00957 
00958 /*****************************
00959  *                           *
00960  * World Interface Functions *
00961  *                           *
00962  *****************************/
00963 
00964 /*
00965  * add_obstacle - creates an obstacle and adds it to the obstacle list
00966  *                of the robot environment. 
00967  * 
00968  * No effect in direct mode.
00969  * 
00970  * parameters:
00971  *    long obs[2*MAX_VERTICES+1] -- 
00972  *                The first element of obs specifies the number of 
00973  *                vertices of the polygonal obstacle (must be no greater 
00974  *                than MAX_VERTICES). The subsequent elements of obs 
00975  *                specifies the x and y coordinates of the vertices, 
00976  *                in counter-clockwise direction.
00977  */
00978 int add_obstacle(long obs[2*MAX_VERTICES+1]);
00979 
00980 /*
00981  * add_Obs - is the same as add_obstacle, for backward compatibility
00982  */
00983 int add_Obs(long obs[2*MAX_VERTICES+1]);
00984 
00985 
00986 /*
00987  * delete_obstacle - deletes an obstacle specified by obs from the robot 
00988  *                   environment 
00989  * parameters:
00990  *    long obs[2*MAX_VERTICES+1] -- 
00991  *                The first element of obs specifies the number of 
00992  *                vertices of the polygonal obstacle (must be no greater 
00993  *                than MAX_VERTICES). The subsequent elements of obs 
00994  *                specifies the x and y coordinates of the vertices, 
00995  *                in counter-clockwise direction.
00996  */
00997 int delete_obstacle(long obs[2*MAX_VERTICES+1]);
00998 
00999 /*
01000  * delete_Obs - is the same as delete_obstacle, for backward compatibility
01001  */
01002 int delete_Obs(long obs[2*MAX_VERTICES+1]);
01003 
01004 /*
01005  * move_obstacle - moves the obstacle obs by dx along x direction and 
01006  *                 dy along y direction. obs is modified.
01007  *
01008  * No effect in direct mode.
01009  * 
01010  * parameters:
01011  *    long obs[2*MAX_VERTICES+1] -- 
01012  *                The first element of obs specifies the number of 
01013  *                vertices of the polygonal obstacle (must be no greater 
01014  *                than MAX_VERTICES). The subsequent elements of obs 
01015  *                specifies the x and y coordinates of the vertices, 
01016  *                in counter-clockwise direction.
01017  *    long dx, dy -- the x and y distances to translate the obstacle
01018  */
01019 int move_obstacle(long obs[2*MAX_VERTICES+1], long dx, long dy);
01020 
01021 /*
01022  * move_Obs - is the same as move_obstacle, for backward compatibility
01023  *
01024  * No effect in direct mode.
01025  * 
01026  */
01027 int move_Obs(long obs[2*MAX_VERTICES+1], long dx, long dy);
01028 
01029 /*
01030  * new_world - deletes all obstacles in the current robot world
01031  *
01032  * No effect in direct mode.
01033  * 
01034  */
01035 int new_world(void);
01036 
01037 /****************************
01038  *                          *
01039  * Graphics refresh control *
01040  *                          *
01041  ****************************/
01042 
01043 /*
01044  * refresh_all - causes all temporary drawing in graphics window, including
01045  *               traces, sensors, and client graphics to be erased
01046  */
01047 int refresh_all(void);
01048 
01049 /*
01050  * refresh_all_traces - causes all robot traces in graphics to be erased
01051  */
01052 int refresh_all_traces(void);
01053 
01054 /*
01055  * refresh_actual_trace - causes actual robot trace in graphics to be erased
01056  */
01057 int refresh_actual_trace(void);
01058 
01059 /*
01060  * refresh_encoder_trace - causes encoder robot trace in graphics to be erased
01061  */
01062 int refresh_encoder_trace(void);
01063 
01064 /*
01065  * refresh_all_sensors - causes all sensor drawings in graphics to be erased
01066  */
01067 int refresh_all_sensors(void);
01068 
01069 /*
01070  * refresh_bumper_sensor - causes bumper drawings in graphics to be erased
01071  */
01072 int refresh_bumper_sensor(void);
01073 
01074 /*
01075  * refresh_infrared_sensor - causes infrared drawings in graphics to be erased
01076  */
01077 int refresh_infrared_sensor(void);
01078 
01079 /*
01080  * refresh_sonar_sensor - causes sonar drawings in graphics to be erased
01081  */
01082 int refresh_sonar_sensor(void);
01083 
01084 /*
01085  * refresh_laser_sensor - causes laser drawings in graphics to be erased
01086  */
01087 int refresh_laser_sensor(void);
01088 
01089 /*
01090  * refresh_client_graphics - causes drawings performed by any clients into
01091  *                           graphics window to be erased
01092  */
01093 int refresh_client_graphics(void);
01094 
01095 /*******************************
01096  *                             *
01097  * Miscellaneous robot control *
01098  *                             *
01099  *******************************/
01100 
01101 /*
01102  * init_mask - initialize the sensor mask, Smask.
01103  */
01104 void init_mask(void);
01105 
01106 /*
01107  * init_sensors - initialize the sensor mask, Smask, and send it to the
01108  *                robot. It has no effect on the sensors 
01109  */
01110 int init_sensors(void);
01111 
01112 /*
01113  * place_robot - places the robot at configuration (x, y, th, tu). 
01114  *               In simulation mode, it will place both the Encoder-robot
01115  *               and the Actual-robot at this configuration. In real robot
01116  *               mode, it will call dp(x, y) and da(th, tu).
01117  * 
01118  * parameters:
01119  *    int x, y -- x-y position of the desired robot configuration
01120  *    int th, tu -- the steering and turret orientation of the robot
01121  *                  desired configuration
01122  */
01123 int place_robot(int x, int y, int th, int tu);
01124 
01125 /*
01126  * special_request - sends a special request (stored in user_send_buffer) 
01127  *                   to the robot and waits for the robot's response (which
01128  *                   will be stored in user_receive_buffer). 
01129  * 
01130  * parameters:
01131  *    unsigned char *user_send_buffer -- stores data to be sent to the robot
01132  *                                       Should be a pointer to an array of
01133  *                                       1024 elements
01134  *    unsigned char *user_receive_buffer -- stores data received from the robot
01135  *                                          Should be a pointer to an array of 
01136  *                                          1024 elements
01137  */
01138 int special_request(unsigned char *user_send_buffer,
01139                     unsigned char *user_receive_buffer);
01140 
01141 /*******************************
01142  *                             *
01143  * Graphic Interface Functions *
01144  *                             *
01145  *******************************/
01146 
01147 /*
01148  * draw_robot - this function allows the client to draw a robot at
01149  *              configuration x, y, th, tu (using the robot world 
01150  *              coordinates). 
01151  * 
01152  * No effect in direct mode.
01153  * 
01154  * parameters:
01155  *    long x, y -- the x-y position of the robot.
01156  *    int th, tu -- the steering and turret orientation of the robot
01157  *    int mode - the drawing mode. If mode = 1, the robot is drawn in 
01158  *              BlackPixel using GXxor (using GXxor you can erase the trace 
01159  *              of robotby drawing over it). If mode = 2, the robot is 
01160  *              drawn in BlackPixel using GXxor and in addition, a small arrow
01161  *              is drawn at the center of the robot using GXcopy (using this 
01162  *              mode you can leave a trace of small arrow). If mode = 3, 
01163  *              the robot is drawn in BlackPixel using GXcopy. When mode > 3,
01164  *              the robot is drawn in color (GXxor) using color(mode-3), see
01165  *              Color table below.
01166  */
01167 int draw_robot(long x, long y, int th, int tu, int mode);
01168 
01169 
01170 /*
01171  * draw_line - this function allows the client to draw a line from
01172  *             (x_1, y_1) to (x_2, y_2) (using the robot world coordinates). 
01173  *
01174  * No effect in direct mode.
01175  * 
01176  * parameters:
01177  *    long x_1, y_1, x_2, y_2 -- the two end-points of the line
01178  *    int mode -- the mode of drawing: when mode is 1, the drawing is 
01179  *                done in BlackPixel using GXcopy; when mode is 2, the drawing
01180  *                is done in BlackPixel using GXxor, when mode > 2, the drawing
01181  *                is done in color (GXxor) using color(mode-2), see Color table
01182  *                below.
01183  */
01184 int draw_line(long x_1, long y_1, long x_2, long y_2, int mode);
01185 
01186 
01187 /*
01188  * draw_arc - this function allows the client to draw arc which is part
01189  *            of an ellipse (using the robot world coordinates). 
01190  *
01191  * No effect in direct mode.
01192  * 
01193  * parameters:
01194  *    long x_0, y_0, w, h -- (x_0, y_0) specifies the upper left corner of the 
01195  *                          rectangle bounding the ellipse while w and h
01196  *                          specifies the width and height of the bounding 
01197  *                          rectangle, respectively.
01198  *    int th1, th2 -- th1 and th2 specifies the angular range of the arc.
01199  *    int mode -- the mode of drawing: when mode is 1, the drawing is 
01200  *                done in BlackPixel using GXcopy; when mode is 2, the drawing
01201  *                is done in BlackPixel using GXxor, when mode > 2, the drawing
01202  *                is done in color (GXxor) using color(mode-2), see Color table
01203  *                below.
01204  */
01205 int draw_arc(long x_0, long y_0, long w, long h, int th1, int th2, int mode);
01206 
01207 /* 
01208  * Color table:
01209  *   color1             = Blue
01210  *   color2             = NavyBlue
01211  *   color3             = RoyalBlue
01212  *   color4             = SteelBlue
01213  *   color5             = CadetBlue
01214  *   color6             = Green
01215  *   color7             = SeaGreen
01216  *   color8             = ForestGreen
01217  *   color9             = DarkGreen
01218  *   color10            = LimeGreen
01219  *   color11            = Yellow
01220  *   color12            = Orange
01221  *   color13            = LightCoral
01222  *   color14            = DeepPink
01223  *   color15            = OrangeRed
01224  *   color16            = Red
01225  *   color17            = IndianRed
01226  *   color18            = VioletRed
01227  *   color19            = DeepPink
01228  *   color20            = Maroon
01229  */
01230 
01231 /*************************************
01232  *                                   *
01233  * Miscellaneous Interface Functions *
01234  *                                   *
01235  *************************************/
01236 
01237 /*
01238  * server_is_running - this function queries the server to see
01239  *                     if it is up and running.  If so, this function
01240  *                     returns a TRUE, otherwise it returns FALSE.
01241  *                     This function is replaced by connect_robot, but 
01242  *                     is defined here for backward compatibility
01243  *
01244  * No effect in direct mode.
01245  * 
01246  */
01247 int server_is_running(void);
01248 
01249 /*
01250  * quit_server - this function allows the client to quit the server
01251  *               assuming this feature is enabled in the setup file
01252  *               of the server
01253  *
01254  * No effect in direct mode.
01255  * 
01256  */
01257 int quit_server(void);
01258 
01259 /*
01260  * real_robot - this function allows the client to switch to
01261  *              real robot mode in the server
01262  *
01263  * No effect in direct mode.
01264  * 
01265  */
01266 int real_robot(void);
01267 
01268 /*
01269  * simulated_robot - this function allows the client to switch to
01270  *                   simulated robot mode in the server
01271  *
01272  * No effect in direct mode.
01273  * 
01274  */
01275 int simulated_robot(void);
01276 
01277 /*
01278  * predict_sensors - this function predicts the sensor reading of
01279  *                   the robot assuming it is at position (x, y)
01280  *                   and orientation th and tu using the map of the
01281  *                   simulated robot environment. The predicted sensor
01282  *                   data values are stored in "state" and "laser".
01283  * 
01284  * No effect in direct mode.
01285  * 
01286  * parameters:
01287  *    int x, y, th, tu -- the configuration of the robot
01288  *    long *state -- where to put the predicted state data
01289  *    int *laser -- where to put the predicted laser data
01290  */
01291 int predict_sensors(int x, int y, int th, int tu, long *state, int *laser);
01292 
01293 /* 
01294  * motion_check - this function computes the intersection of a path
01295  *                specified by the parameters: type, a1, ..., a7 with
01296  *                the obstacles in the robot's environment. If there is
01297  *                collision, the function returns 1 and the x-y configuration
01298  *                of the robot is stored in collide[0] and collide[1] while
01299  *                collide[2] stores the inward normal of the obstacle edge
01300  *                that the robot collides with (this information can be
01301  *                used to calculate which bumper is hit.). If there is no
01302  *                collision, the function returns 0.
01303  *
01304  * No effect in direct mode.
01305  * 
01306  * parameters:
01307  *    long type - 0 if the path is a line segment
01308  *                1 if the path is an arc of circle
01309  *    double a1 a2 - x-y coordinates of the first point of the path (the path
01310  *                   is directional).
01311  *    depending on the value of type, a3 - a7 have different meanings.
01312  *    if (type == 0), line segment mode
01313  *      double a3 a4 are the x-y coordinates of the second point of the path
01314  *      a5, a6, a7 have no meaning
01315  *    if (type == 1), arc of circle mode
01316  *      double a3 is the angle (in radiance) of the vector connecting the 
01317  *                center of the circle to the first end-point of the arc
01318  *      double a4 is the angle of the vector connecting the center
01319  *                of the circle to the second end-point of the arc
01320  *      double a5 is the radius of the circle
01321  *      double a6 a7 are the x-y coordinate of the center of the circle
01322  */
01323 int motion_check(long type, double a1, double a2, double a3, double a4, 
01324                  double a5, double a6, double a7, double collide[3]);
01325 
01326 /*
01327  * get_robot_conf - interactively getting the robot's conf, by clicking
01328  *                  the mouse in the server's Robot window
01329  * 
01330  * No effect in direct mode.
01331  * 
01332  * parameters:
01333  *    long *conf -- should be an array of 4 long integers. The configuration
01334  *                  of the robot is returned in this array.
01335  */
01336 int get_robot_conf(long *conf);
01337 
01338 /*******************************************
01339  *                                         *
01340  * The following are helper functions for  *
01341  * developing user defined host <-> robot  *
01342  * communication                           *
01343  *                                         *
01344  *******************************************/
01345 
01346 /*
01347  *  init_receive_buffer - sets the index to 4 which is the point
01348  *  at which data should begin to be extracted
01349  * 
01350  *  parameters:
01351  *     unsigned short *index -- is the buffer index
01352  */
01353 int init_receive_buffer(unsigned short *index);
01354 
01355 /*
01356  *  extract_receive_buffer_header - extracts the header information:
01357  *  length, serial_number, and packettype from the beginning of the
01358  *  receive buffer.
01359  *
01360  *  parameters:
01361  *     short *length -- is the returns the number of chars in the buffer
01362  *
01363  *     unsigned char *serial_number -- returns the serial number to be
01364  *                                     assigned to the packet
01365  *     unsigned char *packet_type -- returns the type number to be
01366  *                                   assigned to the packet
01367  *     unsigned char *buffer -- is the receive buffer
01368  */
01369 int extract_receive_buffer_header(unsigned short *length, 
01370                                   unsigned char *serial_number, 
01371                                   unsigned char *packet_type, 
01372                                   unsigned char *buffer);
01373 
01374 /*
01375  *  init_send_buffer - sets the index to 4 which is the point
01376  *  at which data should be inserted
01377  *
01378  *  parameters:
01379  *     unsigned short *index -- is the buffer index
01380  */
01381 int init_send_buffer(unsigned short *index);
01382 
01383 /*
01384  *  stuff_send_buffer_header - loads the header information,
01385  *  length,serial_number, and packettype into the beginning of the
01386  *  buffer.  It should be called after the data has been stuffed,
01387  *  i.e. index represents the length of the packet.
01388  *
01389  *  parameters:
01390  *     int index -- is the buffer index which holds the number of chars
01391  *                  in the buffer
01392  *     unsigned char serial_number -- holds the serial number to be
01393  *                                    assigned to the packet
01394  *     unsigned char packet_type -- holds the type number to be
01395  *                                 assigned to the packet
01396  *
01397  *     unsigned char *buffer -- is the send buffer
01398  */
01399 int stuff_send_buffer_header(unsigned short index, unsigned char serial_number, 
01400                              unsigned char packet_type, unsigned char *buffer);
01401 
01402 /*
01403  *  stuffchar -  stuffs a 1 byte char into the send buffer
01404  *
01405  *  parameters:
01406  *     signed char data -- is the char to be stuffed
01407  *     unsigned char *buffer -- is the send buffer
01408  *     unsigned short *index -- is the buffer index which will be incremented
01409  *                              to reflect the bytes stuffed into the buffer
01410  */
01411 int stuffchar(signed char data, unsigned char *buffer, unsigned short *index);
01412 
01413 /*
01414  *  stuff2byteint - stuffs a short int(2 bytes) into the send buffer
01415  *
01416  *  parameters:
01417  *     signed int data -- is the value which will be split apart and stuffed
01418  *                        bytewise into the send buffer
01419  *     unsigned char *buffer -- is the send buffer
01420  *     unsigned short *index -- is the buffer index which will be incremented
01421  *                              to reflect the bytes stuffed into the buffer
01422  */
01423 int stuff2byteint(signed short data,
01424                   unsigned char *buffer, unsigned short *index);
01425 
01426 /*
01427  *  stuff4byteint - stuffs a long int(4 bytes) into the send buffer
01428  *
01429  *  parameters:
01430  *     signed long data -- is the value which will be split apart and stuffed
01431  *                         bytewise into the send buffer
01432  *     unsigned char *buffer -- is the send buffer
01433  *     unsigned short *index -- is the buffer index which will be incremented
01434  *                              to reflect the bytes stuffed into the buffer
01435  */
01436 int stuff4byteint(signed long data,
01437                   unsigned char *buffer, unsigned short *index);
01438 
01439 /*
01440  *  stuffuchar -  stuffs an unsigned char into the send buffer
01441  *
01442  *  parameters:
01443  *     unsigned char data -- is the char to be stuffed
01444  *     unsigned char *buffer -- is the send buffer
01445  *     unsigned short *index -- is the buffer index which will be incremented
01446  *                              to reflect the bytes stuffed into the buffer
01447  */
01448 int stuffuchar(unsigned char data,
01449                unsigned char *buffer, unsigned short *index);
01450 
01451 /*
01452  *  stuff2byteuint - stuffs an unsigned short int(2 bytes) into the send buffer
01453  *
01454  *  parameters:
01455  *     unsigned short data -- is the value which will be split apart and 
01456  *                            stuffed bytewise into the send buffer
01457  *     unsigned char *buffer -- is the send buffer
01458  *     unsigned short *index -- is the buffer index which will be incremented
01459  *                              to reflect the bytes stuffed into the buffer
01460  */
01461 int stuff2byteuint(unsigned short data, unsigned char *buffer, unsigned short *index);
01462 
01463 /*
01464  *  stuff4byteuint - stuffs an unsigned long int(4 bytes) into the send buffer
01465  *
01466  *  parameters:
01467  *     unsigned long data -- is the value which will be split apart and stuffed
01468  *                           bytewise into the send buffer
01469  *     unsigned char *buffer -- is the send buffer
01470  *     unsigned short *index -- is the buffer index which will be incremented
01471  *                              to reflect the bytes stuffed into the buffer
01472  */
01473 int stuff4byteuint(unsigned long data, unsigned char *buffer, unsigned short *index);
01474 
01475 /*
01476  *  stuffdouble - stuffs a double(8 bytes) into the send buffer
01477  *
01478  *  parameters:
01479  *     double data -- is the value which will be split apart and stuffed
01480  *                    bytewise into the send buffer
01481  *     unsigned char *buffer -- is the send buffer
01482  *     unsigned short *index -- is the buffer index which will be incremented
01483  *                              to reflect the bytes stuffed into the buffer
01484  */
01485 int stuffdouble(double data, unsigned char *buffer, unsigned short *index);
01486 
01487 /*
01488  *  extractchar -  extracts a char from the receive buffer
01489  *
01490  *  parameters:
01491  *     unsigned char *buffer -- is the receive buffer which holds the data
01492  *     unsigned short *index -- is the receive buffer index which will be
01493  *                              incremented to reflect the position of the
01494  *                              next piece of data to be extracted
01495  */
01496 signed char extractchar(unsigned char *buffer, unsigned short *index);
01497 
01498 /*
01499  *  extract2byteint -  extracts a short int(2 bytes) from the receive buffer
01500  *
01501  *  parameters:
01502  *     unsigned char *buffer -- is the receive buffer which holds the data
01503  *     unsigned short *index -- is the receive buffer index which will be
01504  *                              incremented to reflect the position of the
01505  *                              next piece of data to be extracted
01506  */
01507 signed short extract2byteint(unsigned char *buffer, unsigned short *index);
01508 
01509 /*
01510  *  extract4byteint -  extracts a long int(4 bytes) from the receive buffer
01511  *
01512  *  parameters:
01513  *     unsigned char *buffer -- is the receive buffer which holds the data
01514  *     unsigned short *index -- is the receive buffer index which will be
01515  *                              incremented to reflect the position of the
01516  *                              next piece of data to be extracted
01517  */
01518 signed long extract4byteint(unsigned char *buffer, unsigned short *index);
01519 
01520 /*
01521  *  extractuchar -  extracts an unsigned char from the receive buffer
01522  *
01523  *  parameters:
01524  *     unsigned char *buffer -- is the receive buffer which holds the data
01525  *     unsigned short *index -- is the receive buffer index which will be
01526  *                              incremented to reflect the position of the
01527  *                              next piece of data to be extracted
01528  */
01529 unsigned char extractuchar(unsigned char *buffer, unsigned short *index);
01530 
01531 /*
01532  *  extract2byteuint -  extracts an unsigned short int(2 bytes) from the 
01533  *                      receive buffer
01534  *
01535  *  parameters:
01536  *     unsigned char *buffer -- is the receive buffer which holds the data
01537  *     unsigned short *index -- is the receive buffer index which will be
01538  *                              incremented to reflect the position of the
01539  *                              next piece of data to be extracted
01540  */
01541 unsigned short extract2byteuint(unsigned char *buffer, unsigned short *index);
01542 
01543 /*
01544  *  extract4byteuint -  extracts an unsigned long int(4 bytes) from the 
01545  *                      receive buffer
01546  *
01547  *  parameters:
01548  *     unsigned char *buffer -- is the receive buffer which holds the data
01549  *     unsigned short *index -- is the receive buffer index which will be
01550  *                              incremented to reflect the position of the
01551  *                              next piece of data to be extracted
01552  */
01553 unsigned long extract4byteuint(unsigned char *buffer, unsigned short *index);
01554 
01555 /*
01556  *  extractdouble -  extracts a double(8 bytes) from the receive buffer
01557  *
01558  *  parameters:
01559  *     unsigned char *buffer -- is the receive buffer which holds the data
01560  *     unsigned short *index -- is the receive buffer index which will be
01561  *                              incremented to reflect the position of the
01562  *                              next piece of data to be extracted
01563  */
01564 double extractdouble(unsigned char *buffer, unsigned short *index);
01565 
01566 /************************************************
01567  *                                              *
01568  * Global variable access functions for Allegro * 
01569  * Common Lisp interface                        *
01570  *                                              *
01571  ************************************************/
01572 
01573 int get_state(long state[NUM_STATE]);
01574 
01575 int get_laser(int laser[2*NUM_LASER+1]);
01576 
01577 int get_mask(int mask[NUM_MASK]);
01578 
01579 int set_mask(int mask[NUM_MASK]);
01580 
01581 int set_server_machine_name(char *sname);
01582 
01583 int set_serv_tcp_port(int port);
01584 
01585 
01586 /*************************************************
01587  *                                               *
01588  * Functions for the attachment of position      *
01589  * data to sensory readings.                     *
01590  *                                               *
01591  *************************************************/
01592 
01593 /***************
01594  * FUNCTION:     posDataRequest
01595  * PURPOSE:      request position information for sensors
01596  * ARGUMENTS:    int posRequest : 
01597  *               The argument of this function specifies the sensors 
01598  *               for which the position information (PosData) should 
01599  *               be attached to the sensory reading.
01600  *               Its value is obtained by ORing the desired defines. 
01601  * EXAMPLE:      To attach PosData to sonars and laser:
01602  *               posDataRequest ( POS_SONAR | POS_LASER );
01603  * ALGORITHM:    currently sets the global variable Smask[0] and
01604  *               then calls ct() to transmit the change to the server
01605  * RETURN:       TRUE if the argument was correct, else FALSE
01606  * SIDE EFFECT:  Smask[0]
01607  * CALLS:        
01608  * CALLED BY:    
01609  ***************/
01610 int posDataRequest ( int posRequest );
01611 
01612 
01613 /***************
01614  * FUNCTION:     posDataCheck
01615  * PURPOSE:      return the sensors for which the PosData attachment
01616  *               is currently requested. 
01617  * ARGUMENTS:    None
01618  * ALGORITHM:    returns the usedSmask that is not globally accessible
01619  *               (is set by ct() to be the value of Smask[0])
01620  * RETURN:       int, see posDataRequest
01621  *               the macros POS_*_P can be used to examine the value
01622  * SIDE EFFECT:  
01623  * CALLS:        
01624  * CALLED BY:    
01625  ***************/
01626 int posDataCheck ( void );
01627 
01628 
01629 /***************
01630  * FUNCTION:     posInfraredRingGet
01631  * PURPOSE:      copy the PosData for all infrareds to accessible memory
01632  * ARGUMENTS:    PosData posData [INFRAREDS] :
01633  *               an array of PosData structures that is filled with 
01634  *               PosData. The position information for each infrared
01635  *               containts the configuration of the robot at the time 
01636  *               of the sensory reading and a timestamp for the 
01637  *               configuration and the senosry reading .
01638  * ALGORITHM:    copies blocks of memory
01639  * RETURN:       int, return always TRUE
01640  * SIDE EFFECT:  
01641  * CALLS:        
01642  * CALLED BY:    
01643  ***************/
01644 int posInfraredRingGet ( PosData posData[INFRAREDS] );
01645 
01646 
01647 /***************
01648  * FUNCTION:     posInfraredGet
01649  * PURPOSE:      copy the PosData for a specific infrared to accessible 
01650  *               memory
01651  * ARGUMENTS:    PosData *posData : the memory location that the information
01652  *                                  will be copied to 
01653  *               int infraredNumber : the number of the infrared
01654  * ALGORITHM:    copies block of memory
01655  * RETURN:       int, always returns TRUE
01656  * SIDE EFFECT:  
01657  * CALLS:        
01658  * CALLED BY:    
01659  ***************/
01660 int posInfraredGet     ( PosData *posData , int infraredNumber );
01661 
01662 
01663 /***************
01664  * FUNCTION:     posSonarRingGet
01665  * PURPOSE:      copy the PosData for all sonars to accessible memory
01666  * ARGUMENTS:    PosData posData [SONARS] :
01667  *               an array of PosData structures that is filled with 
01668  *               PosData. The position information for each sonar
01669  *               containts the configuration of the robot at the time 
01670  *               of the sensory reading and a timestamp for the 
01671  *               configuration and the senosry reading .
01672  * ALGORITHM:    copies blocks of memory
01673  * RETURN:       int, return always TRUE
01674  * SIDE EFFECT:  
01675  * CALLS:        
01676  * CALLED BY:    
01677  ***************/
01678 int posSonarRingGet    ( PosData posData[SONARS] );
01679 
01680 
01681 /***************
01682  * FUNCTION:     posSonarGet
01683  * PURPOSE:      copy the PosData for a specific sonar to accessible memory
01684  * ARGUMENTS:    PosData *posData : the memory location that the information
01685  *                                  will be copied to 
01686  *                        int sonarNumber : the number of the sonar 
01687  * ALGORITHM:    copies block of memory
01688  * RETURN:       int, always returns TRUE
01689  * SIDE EFFECT:  
01690  * CALLS:        
01691  * CALLED BY:    
01692  ***************/
01693 int posSonarGet        ( PosData *posData , int sonarNumber );
01694 
01695 
01696 /***************
01697  * FUNCTION:     posBumperGet
01698  * PURPOSE:      copy PosData for the bumper to accessible memory
01699  * ARGUMENTS:    PosData *posData : where the data is copied to 
01700  * ALGORITHM:    copies a block of memory
01701  * RETURN:       int, always returns TRUE
01702  * SIDE EFFECT:  
01703  * CALLS:        
01704  * CALLED BY:    
01705  * NOTE:         The bumper differs from other sensors in that the 
01706  *               posData is only updated after one of the bumper sensors 
01707  *               change its value from zero to one. This means that the 
01708  *               posData for the bumper always contains the position and 
01709  *               timeStamps of the latest hit, or undefined information 
01710  *               if the bumper was not hit yet.
01711  ***************/
01712 int posBumperGet       ( PosData *posData );
01713 
01714 
01715 /***************
01716  * FUNCTION:     posLaserGet
01717  * PURPOSE:      copy PosData for the laser to accessible memory
01718  * ARGUMENTS:    PosData *posData : where the data is copied to 
01719  * ALGORITHM:    copies a block of memory
01720  * RETURN:       int, always returns TRUE
01721  * SIDE EFFECT:  
01722  * CALLS:        
01723  * CALLED BY:    
01724  * NOTE:         The laser is updated at a frequency of 30Hz.
01725  ***************/
01726 int posLaserGet        ( PosData *posData );
01727 
01728 
01729 /***************
01730  * FUNCTION:     posCompassGet
01731  * PURPOSE:      copy PosData for the compass to accessible memory
01732  * ARGUMENTS:    PosData *posData : where the data is copied to 
01733  * ALGORITHM:    copies a block of memory
01734  * RETURN:       int, always returns TRUE
01735  * SIDE EFFECT:  
01736  * CALLS:        
01737  * CALLED BY:    
01738  * NOTE:         The compass is updated ad a frequency of 10Hz.
01739  ***************/
01740 int posCompassGet      ( PosData *posData );
01741 
01742 
01743 /***************
01744  * FUNCTION:     posTimeGet
01745  * PURPOSE:      get the PosData time (Intellisys 100) in milliseconds
01746  * ARGUMENTS:    None
01747  * ALGORITHM:    ---
01748  * RETURN:       int 
01749  * SIDE EFFECT:  
01750  * CALLS:        
01751  * CALLED BY:    
01752  * NOTE:         The resolution of this timer is 16.4 milliseconds;
01753  *               the timer starts out at zero when the system is 
01754  *               turned on and will flow over after 49 days.
01755  ***************/
01756 int posTimeGet         ( void );
01757 
01758 
01759 /*************************************************
01760  *                                               *
01761  * Functions to determine the charge level       *
01762  * of the batteries for the cpu and the motors.  *
01763  *                                               *
01764  *************************************************/
01765 
01766 /***************
01767  * FUNCTION:     voltCpuGet
01768  * PURPOSE:      get the voltage of the power supply for the CPU
01769  * ARGUMENTS:    None
01770  * ALGORITHM:    ---
01771  * RETURN:       float (the voltage in volt)
01772  * SIDE EFFECT:  
01773  * CALLS:        
01774  * CALLED BY:    
01775  * NOTE:         This should never drop below 10.8 volts.
01776  ***************/
01777 float voltCpuGet       ( void );
01778 
01779 
01780 /***************
01781  * FUNCTION:     voltMotorGet
01782  * PURPOSE:      get the voltage of the power supply for the motors
01783  * ARGUMENTS:    None
01784  * ALGORITHM:    ---
01785  * RETURN:       float (the voltage in volt)
01786  * SIDE EFFECT:  
01787  * CALLS:        
01788  * CALLED BY:    
01789  * NOTE:         This should never drop below 10.8 volts.
01790  *               Returns average of the two motor batteries.
01791  ***************/
01792 float voltMotorGet     ( void );
01793 
01794 #ifdef __cplusplus
01795 }
01796 #endif
01797 
01798 #endif /* _HOST_CLIENT_NCLIENT_H_ */

Last updated 12 September 2005 21:38:45