URG sensor control. More...

#include "urg_connection.h"

Data Structures
struct	urg_t
	URG sensor control structure. More...
Typedefs
typedef urg_measurement_type_t(*	urg_error_handler )(const char status, void urg)
	Error handler.
Enumerations
enum	urg_measurement_type_t { URG_DISTANCE, URG_DISTANCE_INTENSITY, URG_MULTIECHO, URG_MULTIECHO_INTENSITY, URG_STOP, URG_UNKNOWN }
	Measurement types. More...
enum	urg_range_data_byte_t { URG_COMMUNICATION_3_BYTE, URG_COMMUNICATION_2_BYTE }
	Distance data encoding types (number of bytes) More...
enum	{ URG_SCAN_INFINITY = 0, URG_MAX_ECHO = 3 }
Functions
int	urg_open (urg_t urg, urg_connection_type_t connection_type, const char device_or_address, long baudrate_or_port)
	Connect.
void	urg_close (urg_t *urg)
	Disconnection.
void	urg_set_timeout_msec (urg_t *urg, int msec)
	Defines the timeout value to use during communication.
int	urg_start_time_stamp_mode (urg_t *urg)
	Starts the timestamp mode (time adjustment state)
long	urg_time_stamp (urg_t *urg)
	Read timestamp data.
int	urg_stop_time_stamp_mode (urg_t *urg)
	Stops the timestamp mode (returning to idle state)
int	urg_start_measurement (urg_t *urg, urg_measurement_type_t type, int scan_times, int skip_scan)
	Start getting distance measurement data.
int	urg_get_distance (urg_t urg, long data[], long time_stamp)
	Gets distance data.
int	urg_get_distance_intensity (urg_t urg, long data[], unsigned short intensity[], long time_stamp)
	Gets distance and intensity data.
int	urg_get_multiecho (urg_t urg, long data_multi[], long time_stamp)
	Gets distance data (multiecho mode)
int	urg_get_multiecho_intensity (urg_t urg, long data_multi[], unsigned short intensity_multi[], long time_stamp)
	Gets distance and intensity data (multiecho mode)
int	urg_stop_measurement (urg_t *urg)
	Stops measurement process and turns off the laser.
int	urg_set_scanning_parameter (urg_t *urg, int first_step, int last_step, int skip_step)
int	urg_set_communication_data_size (urg_t *urg, urg_range_data_byte_t data_byte)
	Change the size (number of bytes) of measurement data used during communications.
int	urg_laser_on (urg_t *urg)
	Turns on the laser.
int	urg_laser_off (urg_t *urg)
	Turns off the laser.
int	urg_reboot (urg_t *urg)
	Reboots the sensor.
void	urg_sleep (urg_t *urg)
	Sets the sensor into low power mode (sleep state)
void	urg_wakeup (urg_t *urg)
	Returns from the low power mode (sleep state) to the normal mode (idle state)
int	urg_is_stable (urg_t *urg)
	Returns whether the sensor is stable to perform measurement or not.
const char *	urg_sensor_product_type (urg_t *urg)
	Returns the sensor model string.
const char *	urg_sensor_serial_id (urg_t *urg)
	Returns the sensor serial number string.
const char *	urg_sensor_firmware_version (urg_t *urg)
	Returns the current sensor firmware version string.
const char *	urg_sensor_status (urg_t *urg)
	Returns the current sensor status string.
const char *	urg_sensor_state (urg_t *urg)
	Returns the current sensor state string.
void	urg_set_error_handler (urg_t *urg, urg_error_handler handler)
	Registers an error handler for measurement functions.
long	urg_scip_decode (const char data[], int size)
	Decodes a SCIP message.

Detailed Description

URG sensor control.

Provides the basic functions for URG

Author:: Satofumi KAMIMURA

Id:: urg_sensor.h,v e5d1719877a2 2015/05/07 04:12:14 jun

Enumeration Type Documentation

anonymous enum

Enumerator:

URG_SCAN_INFINITY	Continuous data scanning.
URG_MAX_ECHO	Maximum number of echoes.

enum urg_measurement_type_t

Measurement types.

Enumerator:

URG_DISTANCE	Distance (range)
URG_DISTANCE_INTENSITY	Distance (range) and intensity (strength)
URG_MULTIECHO	Multiecho distance.
URG_MULTIECHO_INTENSITY	Multiecho distance and intensity.
URG_STOP	Stop measurement.
URG_UNKNOWN	Unknown measurement type.

enum urg_range_data_byte_t

Distance data encoding types (number of bytes)

Enumerator:

URG_COMMUNICATION_3_BYTE	Use 3-bytes encoding for distance.
URG_COMMUNICATION_2_BYTE	Use 2-bytes encoding for distance.

Function Documentation

void urg_close ( urg_t * urg )

Disconnection.

Turns off the laser and closes the connection with the URG sensor.

Parameters:

[in,out] urg URG control structure

See also:: urg_open()

Examples:: calculate_xy.c, get_distance.c, get_distance_intensity.c, get_multiecho.c, get_multiecho_intensity.c, sensor_parameter.c, and sync_time_stamp.c.

int urg_get_distance	(	urg_t *	urg,
		long	data[],
		long *	time_stamp
	)

Gets distance data.

 Receives distance data from the sensor. The urg_start_measurement() function was called beforehand with #URG_DISTANCE as type argument.

 \param[in,out] urg URG control structure
 \param[out] data Distance data array [mm]
 \param[out] time_stamp Timestamp [msec]

 \retval >=0 Number of data points received
 \retval <0 Error

 Distance data received from the sensor are stored in data array. data array should be previously allocated to hold all the data points requested from the sensor. To know how many data points are received, use the urg_max_data_size() function.

 time_stamp will hold the timestamp value stored on the sensor. When not necessary just pass NULL as argument.


 Example

      long *data = (long*)malloc(urg_max_data_size(&urg) * sizeof(data[0]));

      ...

      \~japanese
      // データのみ取得する
      \~english
      // Gets only measurement data
      urg_start_measurement(&urg, URG_DISTANCE, 1, 0);
      int n = urg_get_distance(&urg, data, NULL);

      ...

      \~japanese
      // データとタイムスタンプを取得する
      \~english
      // Gets measurement data and timestamp
      long time_stamp;
      urg_start_measurement(&urg, URG_DISTANCE, 1, 0);
      n = urg_get_distance(&urg, data, &time_stamp);

  \see urg_start_measurement(), urg_max_data_size()

Examples:: calculate_xy.c, and get_distance.c.

int urg_get_distance_intensity	(	urg_t *	urg,
		long	data[],
		unsigned short	intensity[],
		long *	time_stamp
	)

Gets distance and intensity data.

 This is an extension to urg_get_distance() which allows to obtain also the intensity (strength) data. The urg_start_measurement() function was called beforehand with #URG_DISTANCE_INTENSITY as type argument.

 \param[in,out] urg URG control structure
 \param[out] data Distance data array [mm]
 \param[out] intensity Intensity data array
 \param[out] time_stamp Timestamp [msec]

 \retval >=0 Number of data points received
 \retval <0 Error

 Intensity data corresponds to the laser strength received during distance calculation. The characteristics of this value changes with sensor series. With some limitations, this property can be used to guess the reflectivity and color shade of an object.

 Regarding data and time_stamp arguments, refer to urg_get_distance().

 Intensity data received from the sensor are stored in intensity array. intensity array should be previously allocated to hold all the data points requested from the sensor. To know how many data points are received, use the urg_max_data_size() function.


 Example

      int data_size = urg_max_data_size(&urg);
      long *data = malloc(data_size * sizeof(long));
      long *intensity = malloc(data_size * sizeof(unsigned short));

      ...

      urg_start_measurement(&urg, URG_DISTANCE_INTENSITY, 1, 0);
      int n = urg_get_distance_intensity(&urg, data, intesnity, NULLL);

  \see urg_start_measurement(), urg_max_data_size()

Examples:: get_distance_intensity.c.

int urg_get_multiecho	(	urg_t *	urg,
		long	data_multi[],
		long *	time_stamp
	)

Gets distance data (multiecho mode)

 Receives multiecho distance data from the sensor. The urg_start_measurement() function was called beforehand with #URG_MULTIECHO as type argument.

 \param[in,out] urg URG control structure
 \param[out] data_multi Distance data array [mm]
 \param[out] time_stamp Timestamp [msec]

 \retval >=0 Number of data points received
 \retval <0 Error

 Multiecho means multiple range responses (echoes). For a single laser beam, multiple laser returns reflected from different targets may be received, and thus multiple range values are calculated.

 \image html multiecho_image.png shows multiecho measurement

 time_stamp will hold the timestamp value stored on the sensor, same as with urg_get_distance().

 The array data_multi will hold the multiecho range data, up to a maximum of #URG_MAX_ECHO (3) echoes per step. In case the echo does not exists then -1 will be stored on the array.

      data_multi[0] ... step n range data (1st echo)
      data_multi[1] ... step n range data (2nd echo)
      data_multi[2] ... step n range data (3rd echo)
      data_multi[3] ... step (n + 1) range data (1st echo)
      data_multi[4] ... step (n + 1) range data (2nd echo)
      data_multi[5] ... step (n + 1) range data (3rd echo)
      ...

In the array, the cells numbered (3n + 0) will hold the range data for first echo (same data as for the urg_get_distance() function), for the other cells (3n + 1) and (3n + 2) data is stored in descending order.
This is, the order data_multi[3n + 1] >= data_multi[3n + 2] is assured, however the relation between data_multi[3n + 0] and data_multi[3n + 1] is not defined. (When data_multi[3n + 1] == data_multi[3n + 2] it means the echo does not exists and the stored value is -1.)

  Example

      long *data_multi = malloc(3 * urg_max_data_size(&urg) * sizeof(long));

      ...

      urg_start_measurement(&urg, URG_MULTIECHO, 1, 0);
      int n = urg_get_distance_intensity(&urg, data_multi, NULLL);

  \see urg_start_measurement(), urg_max_data_size()

Examples:: get_multiecho.c.

int urg_get_multiecho_intensity	(	urg_t *	urg,
		long	data_multi[],
		unsigned short	intensity_multi[],
		long *	time_stamp
	)

Gets distance and intensity data (multiecho mode)

 This is an extension to urg_get_multiecho() which allows to obtain also the intensity (strength) data for multiple echoes. The urg_start_measurement() function was called beforehand with #URG_MULTIECHO_INTENSITY as type argument.

 \param[in,out] urg URG control structure
 \param[out] data_multi Distance data array [mm]
 \param[out] intensity_multi Intensity data array
 \param[out] time_stamp Timestamp [msec]

 \retval >=0 Number of data points received
 \retval <0 Error

 data_multi and time_stamp are as described in urg_get_multiecho() function.

 The order of data in the array intensity_multi is defined by how the data_multi array was sorted. The size of the intensity_multi can be obtained using urg_max_data_size().

 Example

      int data_size = urg_max_data_size(&urg);
      long *data_multi = malloc(3 * data_size * sizeof(long));
      long *intensity_multi = malloc(3 * data_size * sizeof(unsigned short));

      ...

      urg_start_measurement(&urg, URG_DISTANCE_INTENSITY, 1, 0);
      int n = urg_get_multiecho_intensity(&urg, data_multi,
      intesnity_multi, NULLL);

  \see urg_start_measurement(), urg_max_data_size()

Examples:: get_multiecho_intensity.c.

int urg_is_stable ( urg_t * urg )

Returns whether the sensor is stable to perform measurement or not.

Return values:

1	The sensor can do measurement
0	The sensor cannot do measurement

Right after power on the motor rotation is not yet stable for measurement, or if any failure condition was detected, 0 is returned.

int urg_open	(	urg_t *	urg,
		urg_connection_type_t	connection_type,
		const char *	device_or_address,
		long	baudrate_or_port
	)

Connect.

 Connects to the given device and enables measurement

 \param[in,out] urg URG control structure
 \param[in] connection_type Type of the connection
 \param[in] device_or_address Name of the device
 \param[in] baudrate_or_port Connection baudrate [bps] or TCP/IP port number

 \retval 0 Successful
 \retval <0 Error

 The following values can be used in connection_type:

 - #URG_SERIAL
 - Serial, USB connection

 - #URG_ETHERNET
 - Ethernet connection

 Example

      urg_t urg;

      if (urg_open(&urg, URG_SERIAL, "/dev/ttyACM0", 115200) < 0) {
      return 1;
      }

      ...

      urg_close(&urg);

  \attention Call this function before using any other function on the URG library.


  \see urg_close()

long urg_scip_decode	(	const char	data[],
		int	size
	)

Decodes a SCIP message.

Parameters:

[in]	data	the SCIP message to decode
[in]	size	the data encoding types (number of bytes for encoding)

Return values:

Value after decoding

const char* urg_sensor_firmware_version ( urg_t * urg )

Returns the current sensor firmware version string.

Returns the string message corresponding to the current sensor firmware version. This message is sensor dependent.

Parameters:

[in] urg URG control structure

Returns:: firmware version string

Examples:: sensor_parameter.c.

const char* urg_sensor_product_type ( urg_t * urg )

Returns the sensor model string.

Returns the string message corresponding to the sensor model. This message is sensor dependent.

Parameters:

[in] urg URG control structure

Returns:: sensor model string

Examples:: sensor_parameter.c.

const char* urg_sensor_serial_id ( urg_t * urg )

Returns the sensor serial number string.

Returns the string message corresponding to the sensor serial number. This message is sensor dependent.

Parameters:

[in] urg URG control structure

Returns:: serial number string

Examples:: sensor_parameter.c.

const char* urg_sensor_state ( urg_t * urg )

Returns the current sensor state string.

Returns the string message corresponding to the current sensor state. This message is sensor dependent.

Parameters:

[in] urg URG control structure

Returns:: current sensor state string

Attention:: For details, please refer to the SCIP communication protocol specification.

Examples:: sensor_parameter.c.

const char* urg_sensor_status ( urg_t * urg )

Returns the current sensor status string.

Returns the string message corresponding to the current sensor status. This message is sensor dependent.

Parameters:

[in] urg URG control structure

Returns:: current sensor status string

Examples:: sensor_parameter.c.

int urg_set_communication_data_size	(	urg_t *	urg,
		urg_range_data_byte_t	data_byte
	)

Change the size (number of bytes) of measurement data used during communications.

When receiving data from the sensor, changes the number of bytes used to represent measurement data.

Parameters:

[in,out]	urg	URG control structure
[in]	data_byte	Number of bytes used to represent measurement data

Return values:

0	Successful
<0	Error

data_byte can be:

URG_COMMUNICATION_3_BYTE ... to represent data in 3 bytes
- URG_COMMUNICATION_2_BYTE ... to represent data in 2 bytes
The initial (default) data size is 3 bytes. If the number of bytes is changed to 2, the actual received message length becomes around 2/3 of the original length. However, using 2 bytes means the maximum measurement range is 4095, therefore use it only when measurement targets are 4 [m] from the sensor.

void urg_set_error_handler	(	urg_t *	urg,
		urg_error_handler	handler
	)

Registers an error handler for measurement functions.

The error handler will be called for the Gx, Mx commands when the response code is not "00" or "99".

int urg_set_scanning_parameter	(	urg_t *	urg,
		int	first_step,
		int	last_step,
		int	skip_step
	)

 Example

      urg_set_scanning_parameter(&urg, urg_deg2step(&urg, -45),
      urg_deg2step(&urg, +45), 1);
      urg_start_measurement(&urg, URG_DISTANCE, 0);
      int n = urg_get_distance(&urg, data, NULL);
      for (int i = 0; i < n; ++i) {
      printf("%d [mm], %d [deg]\n", data[i], urg_index2deg(&urg, i));
      }

  \see urg_step_min_max(), urg_rad2step(), urg_deg2step()

Examples:: get_distance.c.

void urg_set_timeout_msec	(	urg_t *	urg,
		int	msec
	)

Defines the timeout value to use during communication.

Parameters:

[in,out]	urg	URG control structure
[in]	msec	Timeout value [msec]

Attention:: The urg_open() function always sets the timeout value to its default, if necessary call this function after urg_open().

void urg_sleep ( urg_t * urg )

Sets the sensor into low power mode (sleep state)

During low power mode, the scanner motor stops and so measurement is interrupted.

Low power mode
- Laser is turned off and so measurement is stopped
- The scanner motor is stopped.

To recover from low power mode call the function urg_wakeup()

See also:: urg_wakeup()

int urg_start_measurement	(	urg_t *	urg,
		urg_measurement_type_t	type,
		int	scan_times,
		int	skip_scan
	)

Start getting distance measurement data.

 Starts measurement data acquisition. The actual data can be retrieved using urg_get_distance(), urg_get_distance_intensity(), urg_get_multiecho(), urg_get_multiecho_intensity().

 \param[in,out] urg URG control structure
 \param[in] type Measurement type
 \param[in] scan_times Number of scans to request
 \param[in] skip_scan Interval between scans

 \retval 0 Successful
 \retval <0 Error

 The following values are possible for the type argument

 - #URG_DISTANCE ... Distance (range) data
 - #URG_DISTANCE_INTENSITY ... Distance (range) and intensity (strength) data
 - #URG_MULTIECHO ... Multiecho distance data
 - #URG_MULTIECHO_INTENSITY ... Multiecho distance and intensity data

 scan_times defines how many scans to capture from the sensor: >0 means a fixed number of scans, 0 or #URG_SCAN_INFINITY means continuous (infinite) scanning.
 To interrupt measurement at any time use urg_stop_measurement().

 skip_scan means, after obtaining one scan, skip measurement for the following X mirror (motor) revolutions.
 The values for skip_scan are from the range [0, 9].

 \image html skip_scan_image.png shows scan skip

 For example, for a sensor with one mirror (motor) revolution is 100 [msec] and skip_scan is set to 1, measurement data will be obtained with an interval of 200 [msec].


 Example

      enum { CAPTURE_TIMES = 10 };
      urg_start_measurement(&urg, URG_DISTANCE, CAPTURE_TIMES, 0);

      for (i = 0; i < CAPTURE_TIMES; ++i) {
      int n = urg_get_distance(&urg, data, &time_stamp);

      \~japanese
      // 受信したデータの利用
      \~english
      // Processing of obtained data
      \~
      ...
      }

  \see urg_get_distance(), urg_get_distance_intensity(), urg_get_multiecho(), urg_get_multiecho_intensity(), urg_stop_measurement()

Examples:: calculate_xy.c, get_distance.c, get_distance_intensity.c, get_multiecho.c, and get_multiecho_intensity.c.

int urg_stop_measurement ( urg_t * urg )

Stops measurement process and turns off the laser.

 It stops the measurement started with \ref urg_start_measurement() function.

 \param[in,out] urg URG control structure

 \retval 0 Successful
 \retval <0 Error


 Example

      urg_start_measurement(&urg, URG_DISTANCE, URG_SCAN_INFINITY, 0);
      for (int i = 0; i < 10; ++i) {
      urg_get_distance(&urg, data, NULL);
      }
      urg_stop_measurement(&urg);

  \see urg_start_measurement()

long urg_time_stamp ( urg_t * urg )

Read timestamp data.

 \param[in,out] urg URG control structure

 \retval >=0 Timestamp value [msec]
 \retval <0 Error


 Example

      urg_start_time_stamp_mode(&urg);

      before_ticks = get_pc_msec_function();
      time_stamp = urg_time_stamp(&urg);
      after_ticks = get_pc_msec_function();

      \~japanese
      // タイムスタンプについての計算
      \~english
      // Processing of timestamp data
      \~
      ...

      urg_stop_time_stamp_mode(&urg);

  For a detailed use consult the \ref sync_time_stamp.c example

Examples:: sync_time_stamp.c.

void urg_wakeup ( urg_t * urg )

Returns from the low power mode (sleep state) to the normal mode (idle state)

See also:: urg_sleep()

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation