src/lidars/hokuyo/lib/urg_ctrl.h

   1 #ifndef QRK_C_URG_CTRL_H
   2 #define QRK_C_URG_CTRL_H
   3
   4 /*!
   5   \file
   6   \brief URG control
   7
   8   \author Satofumi KAMIMURA
   9
  10   $Id: urg_ctrl.h 1723 2010-02-24 23:30:34Z satofumi $
  11
  12   \todo Define examples for each functions
  13 */
  14
  15 #include "urg_t.h"
  16
  17
  18 /*!
  19   \brief Parameter for object
  20 */
  21 enum {
  22   UrgLineWidth = 64 + 1 + 1,    /*!< Maximum length of a line */
  23   UrgInfinityTimes = 0,         /*!< continuous data transmission */
  24 };
  25
  26
  27 /*!
  28   \brief Command type of URG
  29 */
  30 typedef enum {
  31   URG_GD,                       /*!< GD command */
  32   URG_GD_INTENSITY,             /*!< GD command(Inclusing intensity data) */
  33   URG_GS,                       /*!< GS command */
  34   URG_MD,                       /*!< MD command */
  35   URG_MD_INTENSITY,             /*!< MD command(Inclusing intensity data) */
  36   URG_MS,                       /*!< MS command */
  37 } urg_request_type;
  38
  39
  40 /*!
  41   \brief To omit URG data range specification
  42 */
  43 enum {
  44   URG_FIRST = -1, /*!< starting position when complete data is to be acquired */
  45   URG_LAST = -1, /*!< end position when complete data is to be acquired */
  46
  47   UrgInvalidTimestamp = -1,     /*!< Error value of timestamp */
  48 };
  49
  50
  51 extern void urg_initialize(urg_t *urg);
  52
  53
  54 /*!
  55   \brief Connection
  56
  57   \param[in,out] urg Structure of URG control
  58   \param[in] device Connection device
  59   \param[in] baudrate Baudrate
  60
  61   \retval 0 Normal
  62   \retval <0 Error
  63
  64   \see gd_scan.c, md_scan.c
  65
  66   Example
  67   \code
  68 urg_t urg;
  69
  70 // Coonnection
  71 if (urg_connect(&urg, "COM3", 115200) < 0) {
  72   printf("urg_connect: %s\n", urg_error(&urg));
  73   return -1;
  74 }
  75
  76 ...
  77
  78 urg_disconnect(&urg); \endcode
  79 */
  80 extern int urg_connect(urg_t *urg, const char *device, long baudrate);
  81
  82
  83 /*!
  84   \brief Disconnection
  85
  86   \param[in,out] urg Structure of URG control
  87
  88   \see urg_connect()
  89   \see gd_scan.c, md_scan.c
  90 */
  91 extern void urg_disconnect(urg_t *urg);
  92
  93
  94 /*!
  95   \brief Checks whether connected or not and returns the result
  96
  97   \param[in,out] urg Structure of URG control
  98
  99   \retval 0 if connected
 100   \retval <0 if disconnected
 101
 102   \see urg_connect(), urg_disconnect()
 103
 104   Example
 105   \code
 106 if (urg_isConnected(&urg) < 0) {
 107   printf("not connected.\n");
 108 } else {
 109   printf("connected.\n");
 110 } \endcode
 111 */
 112 extern int urg_isConnected(const urg_t *urg);
 113
 114
 115 /*!
 116   \brief Get error message
 117
 118   \param[in,out] urg Structure of URG control
 119
 120   \return Error message
 121
 122   \see urg_connect()
 123   \see gd_scan.c, md_scan.c
 124 */
 125 extern const char *urg_error(const urg_t *urg);
 126
 127
 128 /*!
 129   \brief Get string containing version information
 130
 131   \param[in,out] urg Structure of URG control
 132   \param[out] lines Buffer having version information
 133   \param[in] lines_max Maximum lines in buffer
 134
 135   \retval 0 Normal
 136   \retval <0 Error
 137
 138   \attention The length of a line in the buffer should be equal to more than # UrgLineWidth[byte].
 139
 140   \see get_version_lines.c
 141 */
 142 extern int urg_versionLines(urg_t *urg, char* lines[], int lines_max);
 143
 144
 145 /*!
 146   \brief URG Returns parameter
 147
 148   \param[in,out] urg Structure of URG control
 149   \param[out] parameters Structure of URG parameter
 150
 151   \retval 0 Normal
 152   \retval <0 Error
 153
 154   \see urg_maxDistance(), urg_minDistance(), urg_scanMsec(), urg_dataMax()
 155
 156   Execution example of get_parameters.c  (Classic-URG)
 157   \verbatim
 158 % ./get_parameters
 159 urg_getParameters: No Error.
 160 distance_min: 20
 161 distance_max: 5600
 162 area_total: 1024
 163 area_min: 44
 164 area_max: 725
 165 area_front: 384
 166 scan_rpm: 600
 167
 168 urg_getDistanceMax(): 5600
 169 urg_getDistanceMin(): 20
 170 urg_getScanMsec(): 100
 171 urg_getDataMax(): 726 \endverbatim
 172 */
 173 extern int urg_parameters(urg_t *urg, urg_parameter_t* parameters);
 174
 175
 176 /*!
 177   \brief URG Returns the sensor type
 178
 179   \param[in,out] urg Structure of URG control
 180
 181   \retval URG sensor type
 182
 183   \code
 184 printf("URG type: %s\n", urg_model(&urg)); \endcode
 185 */
 186 extern const char* urg_model(const urg_t *urg);
 187
 188
 189 /*!
 190   \brief Returns the number of maximum data obtained in one scan
 191
 192   \param[in,out] urg Structure of URG control
 193
 194   \retval >=0 number of maximum data obtained in one scan
 195   \retval <0 Error
 196
 197   \see gd_scan.c
 198
 199   Example
 200   \code
 201 enum { BufferSize = 2048 };
 202 long data[BufferSize];
 203
 204 ...
 205
 206 // Checks whether number of maximum data obtained by URG sensor does not exceeds receive buffer
 207 // (This is not necessary if size of buffer is dynamically allocated.)
 208 int data_max = urg_dataMax(&urg);
 209 ASSERT(BufferSize >= data_max);
 210 \endcode
 211 */
 212 extern int urg_dataMax(const urg_t *urg);
 213
 214
 215 /*!
 216   \brief Returns measurement time taken for one scan
 217
 218   Returns measurement time when motor speed is 100% as specified.
 219
 220   \param[in,out] urg Structure of URG control
 221
 222   \retval >=0 measurement time taken for one scan [msec]
 223   \retval <0 Error
 224
 225   \see urg_setMotorSpeed()
 226
 227   \see md_scan.c
 228 */
 229 extern int urg_scanMsec(const urg_t *urg);
 230
 231
 232 /*!
 233   \brief Maximum measurable distance
 234
 235   \param[in,out] urg Structure of URG control
 236
 237   \retval >=0 Maximum measurable distance [mm]
 238   \retval <0 Error
 239
 240   \see expand_2d.c
 241
 242   Example
 243   \code
 244 ...
 245 n = urg_receiveData(&urg, data, data_max);
 246
 247 min_distance = urg_minDistance(&urg);
 248 max_distance = urg_minDistance(&urg);
 249
 250 // Output only valid data
 251 for (i = 0; i < n; ++i) {
 252   long length = data[i];
 253   if ((length > min_distance) && (length < max_distance)) {
 254     printf("%d:%d\n", i, length);
 255   }
 256 }
 257 \endcode
 258 */
 259 extern long urg_maxDistance(const urg_t *urg);
 260
 261
 262 /*!
 263   \brief Minimum measureable distance
 264
 265   \param[in,out] urg Structure of URG control
 266
 267   \retval >=0 Minimum measurable distance [mm]
 268   \retval <0 Error
 269
 270   \see expand_2d.c
 271 */
 272 extern long urg_minDistance(const urg_t *urg);
 273
 274
 275 /* ---------------------------------------------------------------------- */
 276
 277
 278 /*!
 279   \brief Sets the number of lines to be skiped.
 280
 281   The volume of acquire data can be reduced by skipping the lines .
 282
 283   \param[in,out] urg Structure of URG control
 284   \param[in] lines Number of lines to be skiped.
 285
 286   \retval 0 Normal
 287   \retval <0 Error
 288 */
 289 extern int urg_setSkipLines(urg_t *urg, int lines);
 290
 291
 292 /*!
 293   \brief Sets number of scans to be skipped.
 294
 295   \param[in,out] urg Structure of URG control
 296   \param[in] frames Number of skipped frames.
 297
 298   \retval 0 Normal
 299   \retval <0 Error
 300
 301   \attention Valid only with MD/MS command.
 302 */
 303 extern int urg_setSkipFrames(urg_t *urg, int frames);
 304
 305
 306 /*!
 307   \brief Sets  number of times the data to be acquired .
 308
 309   \param[in,out] urg Structure of URG control
 310   \param[in] times Number of scan data
 311
 312   \retval 0 Normal
 313   \retval <0 Error
 314
 315   \attention Valid only with MD/MS command
 316   \attention Specify #UrgInfinityTimes to acquire data more than 100 times
 317
 318   Example
 319   \code
 320 // Data is supplied indefinitely
 321 urg_setCaptureTimes(&urg, UrgInfinityTimes);
 322
 323 ...
 324
 325 // Data acquistion is stopped if laser is switched off.
 326 urg_laserOff(&urg);
 327   \endcode
 328 */
 329 extern int urg_setCaptureTimes(urg_t *urg, int times);
 330
 331
 332 /*!
 333   \brief Get number of remaining times on MD/MS capture
 334
 335   \param[in,out] urg Structure of URG control
 336
 337   \retval remaining times. (100 means infinity times)
 338
 339   \see md_scan.c
 340 */
 341 extern int urg_remainCaptureTimes(const urg_t *urg);
 342
 343
 344 /*!
 345   \brief Request for distance data
 346
 347   Request for distance data of [first_index, last_index].  Return all scan data when specified URG_FIRST, URG_LAST.
 348
 349   \param[in,out] urg Structure of URG control
 350   \param[in] request_type Received data type.
 351   \param[in] first_index Index of the first data stored
 352   \param[in] last_index Index of the last received data stored.
 353
 354   \retval 0 Normal
 355   \retval <0 Error
 356
 357   \see urg_receiveData()
 358   \see gd_scan.c, md_scan.c
 359
 360   Example
 361   \code
 362 // Get one scan data from GD command
 363 urg_requestData(&urg, URG_GD, URG_FIRST, URG_LAST);
 364 n = urg_receiveData(&urg, data, data_max);
 365
 366 // Get data continuously from MD scan
 367 urg_requestData(&urg, URG_MD, URG_FIRST, URG_LAST);
 368 while (1) {
 369   n = urg_receiveData(&urg, data, data_max);
 370   if (n > 0) {
 371     // Display data etc
 372     ...
 373   }
 374 } \endcode
 375 */
 376 extern int urg_requestData(urg_t *urg,
 377                            urg_request_type request_type,
 378                            int first_index,
 379                            int last_index);
 380
 381
 382 /*!
 383   \brief Receive URG data
 384
 385   \param[in,out] urg Structure of URG control
 386   \param[out] data Storage location of received data
 387   \param[in] data_max Maximum number of data that can be received
 388
 389   \retval 0 > Number of data received
 390   \retval <0 Error
 391
 392   \see urg_requestData()
 393 */
 394 extern int urg_receiveData(urg_t *urg, long data[], int data_max);
 395
 396
 397 /*!
 398   \brief Get data with intensity.
 399
 400   \param[in,out] urg Structure of URG control
 401   \param[out] data Storage location of received data
 402   \param[in] data_max Maximum number of data that can be received
 403   \param[out] intensity Storage location of intensity of received data.
 404
 405   \attention Applicable only to Classic-URG  (currently 2008-12-24)
 406 */
 407 extern int urg_receiveDataWithIntensity(urg_t *urg, long data[], int data_max,
 408                                         long intensity[]);
 409
 410
 411 /*!
 412   \brief Get partial URG data
 413
 414   \param[in,out] urg Structure of URG control
 415   \param[out] data Storage location of received data
 416   \param[in] data_max Maximum number of data that can be received
 417   \param[in] first_index Index of the first data stored.
 418   \param[in] last_index Index of the last data stored
 419
 420   \retval 0 > Number of data received
 421   \retval <0 Error
 422
 423   \see gd_scan.c, md_scan.c
 424 */
 425 extern int urg_receivePartialData(urg_t *urg, long data[], int data_max,
 426                                   int first_index, int last_index);
 427
 428
 429 /*!
 430   \brief Receive time stamp
 431
 432   \param[in,out] urg Structure of URG control
 433
 434   \retval Time stamp [msec]
 435
 436   \see md_scan.c
 437
 438   Example
 439   \code
 440 urg_requestData(&urg, URG_GD, URG_FIRST, URG_LAST);
 441 n = urg_receiveData(&urg, data, data_max);
 442 if (n > 0) {
 443   long timestamp = urg_recentTimestamp(&urg);
 444   printf("timestamp: %d\n", timestamp);
 445
 446   // Display data etc
 447   // !!!
 448 } \endcode
 449 */
 450 extern long urg_recentTimestamp(const urg_t *urg);
 451
 452
 453 /* ---------------------------------------------------------------------- */
 454
 455
 456 /*!
 457   \brief  Change index value into angle (radian)
 458
 459   \image html urg_sensor_radian.png Front of the sensor is a positive in X axis
 460
 461   \param[in,out] urg Structure of URG control
 462   \param[in] index Index value
 463
 464   \return angle[radian]
 465
 466   Example
 467   \code
 468 // To operate urg_index2rad(), data from 0 to last_index is stored.
 469 // The data of the step not measured becomes -1.
 470 urg_requestData(&urg, URG_GD, first_index, last_index);
 471 n = urg_receiveData(&urg, data, data_max);
 472 for (i = 0; i < n; ++i) {
 473   long l = data[i];
 474   if (l > min_distance) {
 475     double rad = urg_index2rad(&urg, i);
 476     double x = data[i] * cos(rad);
 477     double y = data[i] * sin(rad);
 478     printf("%f, %f\n", x, y);
 479   }
 480 } \endcode
 481
 482   \see index_convert.c
 483 */
 484 extern double urg_index2rad(const urg_t *urg, int index);
 485
 486
 487 /*!
 488   \brief Change index into angle(degree)
 489
 490   \param[in,out] urg Structure of URG control
 491   \param[in] index Index value
 492
 493   \return Angle [degree]
 494
 495   \see index_convert.c
 496 */
 497 extern int urg_index2deg(const urg_t *urg, int index);
 498
 499
 500 /*!
 501   \brief Angle(radian) is converted to index value
 502
 503   \image html urg_sensor_radian.png Front of the sensor is a positive in X axis
 504
 505   \param[in,out] urg Structure of URG control
 506   \param[in] Angle(radian)
 507
 508   \return Index
 509
 510   \see index_convert.c
 511 */
 512 extern int urg_rad2index(const urg_t *urg, double radian);
 513
 514
 515 /*!
 516   \brief Angle(degree) is converted into index
 517
 518   \param[in,out] urg Structure of URG control
 519   \param[in] Angle(degre)
 520
 521   \return Index value
 522
 523   \see index_convert.c
 524 */
 525 extern int urg_deg2index(const urg_t *urg, int degree);
 526
 527
 528 /* ---------------------------------------------------------------------- */
 529
 530
 531 /*!
 532   \brief Directs laser to switch on
 533
 534   \param[in,out] urg Structure of URG control
 535
 536   \retval 0 Normal
 537   \retval <0 Error
 538
 539   \see gd_scan.c
 540 */
 541 extern int urg_laserOn(urg_t *urg);
 542
 543
 544 /*!
 545   \brief Directs laser to switch off
 546
 547   \param[in,out] urg Structure of URG control
 548
 549   \retval 0 Normal
 550   \retval <0 Error
 551 */
 552 extern int urg_laserOff(urg_t *urg);
 553
 554
 555 /*!
 556   \brief reboot
 557
 558   \retval 0 Normal
 559   \retval <0 Error
 560
 561   \attention Only Top-URG (2010-02-04)
 562 */
 563 extern int urg_reboot(urg_t *urg);
 564
 565
 566 /*!
 567   \deprecated use reboot() function.
 568 */
 569 extern int urg_reset(urg_t *urg);
 570
 571
 572 /* ---------------------------------------------------------------------- */
 573
 574
 575 /*!
 576   \brief Enters into time stamp mode
 577
 578   \param[in,out] urg Structure of URG control
 579
 580   \retval 0 Normal
 581   \retval <0 Error
 582 */
 583 extern int urg_enableTimestampMode(urg_t *urg);
 584
 585
 586 /*!
 587   \brief Comes out of time stamp mode
 588
 589   \param[in,out] urg Structure of URG control
 590
 591   \retval 0 Normal
 592   \retval <0 Error
 593 */
 594 extern int urg_disableTimestampMode(urg_t *urg);
 595
 596
 597 /*!
 598   \brief Get time stamp
 599
 600   Returns TM1 response.
 601
 602   \param[in,out] urg Structure of URG control
 603
 604   \retval >=0 Timestamp [msec]
 605   \retval <0 Error
 606
 607   Example
 608   \code
 609 // Enters into time stamp
 610 urg_enableTimestampMode(&urg);
 611
 612 // Get URG time stamp continuously.
 613 for (i = 0; i < 5; ++i) {
 614   long timestamp = urg_currentTimestamp(&urg);
 615   printf("timestamp: %ld\n", timestamp)
 616 }
 617
 618 // leave tiemstamp mode
 619 urg_disableTimestampMode(&urg); \endcode
 620 */
 621 extern long urg_currentTimestamp(urg_t *urg);
 622
 623 #endif /* !QRK_C_URG_CTRL_H */