URG sensor Driver. More...

#include "urg_connection.h"

Data Structures
struct	urg_t
	URG Sensor Driver. More...

Typedefs
typedef urg_measurement_type_t(*	urg_error_handler )(const char status, void urg)

Enumerations
enum	urg_measurement_type_t { URG_DISTANCE, URG_DISTANCE_INTENSITY, URG_MULTIECHO, URG_MULTIECHO_INTENSITY, URG_STOP, URG_UNKNOWN }
	Measurement type. More...

enum	urg_range_data_byte_t { URG_COMMUNICATION_3_BYTE, URG_COMMUNICATION_2_BYTE }
	This function sets the number of bytes that represent the distance. 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)
	Open the connection. More...

void	urg_close (urg_t *urg)
	Close the connection. More...

void	urg_set_timeout_msec (urg_t *urg, int msec)
	Set connection timeout. More...

int	urg_start_time_stamp_mode (urg_t *urg)
	Enter Time_adjustment mode.

long	urg_time_stamp (urg_t *urg)
	Retrieve Timestamp value. More...

int	urg_stop_time_stamp_mode (urg_t *urg)
	Leave Time_adjustment mode.

int	urg_start_measurement (urg_t *urg, urg_measurement_type_t type, int scan_times, int skip_scan)
	Start measurement. More...

int	urg_get_distance (urg_t urg, long data[], long time_stamp)
	Retrieve Distance data. More...

int	urg_get_distance_intensity (urg_t urg, long data[], unsigned short intensity[], long time_stamp)
	Retrieve Distance and Intensity data. More...

int	urg_get_multiecho (urg_t urg, long data_multi[], long time_stamp)
	Retrieve Distance data (Multi-echo version) More...

int	urg_get_multiecho_intensity (urg_t urg, long data_multi[], unsigned short intensity_multi[], long time_stamp)
	Retrieve Distance and Intensity data (Multi-echo version) More...

int	urg_stop_measurement (urg_t *urg)
	Stop measurement and turn off laser. More...

int	urg_set_scanning_parameter (urg_t *urg, int first_step, int last_step, int skip_step)
	Set the measurement range. More...

int	urg_set_communication_data_size (urg_t *urg, urg_range_data_byte_t data_byte)
	Set the size of communication data. More...

int	urg_laser_on (urg_t *urg)
	Turn on laser.

int	urg_laser_off (urg_t *urg)
	Turn off laser.

int	urg_reboot (urg_t *urg)
	Reboot sensor.

void	urg_sleep (urg_t *urg)
	センサを低消費電力の状態に遷移させる More...

void	urg_wakeup (urg_t *urg)
	センサを低消費電力のモードから通常の状態に遷移させる More...

int	urg_is_stable (urg_t *urg)
	センサが計測できる状態かを返す More...

const char *	urg_sensor_product_type (urg_t *urg)
	Get product type string. More...

const char *	urg_sensor_serial_id (urg_t *urg)
	Get Serial ID. More...

const char *	urg_sensor_firmware_version (urg_t *urg)
	Get firmware version. More...

const char *	urg_sensor_status (urg_t *urg)
	Get sensor status string. More...

const char *	urg_sensor_state (urg_t *urg)
	Get sensor state string. More...

void	urg_set_error_handler (urg_t *urg, urg_error_handler handler)
	Set error handler. More...

long	urg_scip_decode (const char data[], int size)
	Decode SCIP string. More...

Detailed Description

URG sensor Driver.

This module provides basic functions for URG sensor.

Author: Satofumi KAMIMURA

Id:: urg_sensor.h,v 540bc11f70c8 2011/05/08 23:04:49 satofumi

Typedef Documentation

typedef urg_measurement_type_t(* urg_error_handler)(const char *status, void *urg)

Error handler

Enumeration Type Documentation

enum urg_measurement_type_t

Measurement type.

Enumerator
URG_DISTANCE	Distance
URG_DISTANCE_INTENSITY	Distance + Intensity
URG_MULTIECHO	Multiecho Distance
URG_MULTIECHO_INTENSITY	Multiecho (Distance + Intensity)
URG_STOP	Stop measurement
URG_UNKNOWN	Unknown

enum urg_range_data_byte_t

This function sets the number of bytes that represent the distance.

Enumerator
URG_COMMUNICATION_3_BYTE	Represented by 3 bytes
URG_COMMUNICATION_2_BYTE	Represented by 2 bytes

anonymous enum

Enumerator
URG_SCAN_INFINITY	Scan infinity times
URG_MAX_ECHO	Maximum number of multiecho

Function Documentation

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

Open the connection.

Connect to the specified device, to be able to measure the distance.

Parameters

[in,out]	urg	URG resource
[in]	connection_type	connection type
[in]	device_or_address	connection device name / IP address
[in]	baudrate_or_port	baudrate [bps] / TCP/IP port

Return values

0	Success
<0	Error

Connection types

URG_SERIAL
- Serial or USB device

URG_ETHERNET
- Ethernet device

Example

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

Attention: You need to call this function, before calling other functions in this library.

See Also: urg_close()

void urg_close ( urg_t * urg )

Close the connection.

Turn off the laser, and close the connection with the URG.

Parameters

[in,out] urg URG resource

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.

void urg_set_timeout_msec	(	urg_t *	urg,
		int	msec
	)

Set connection timeout.

Parameters

[in,out]	urg	URG resource
[in]	msec	Timeout [msec]

Attention: The timeout settings is initialized when you call urg_open(). Then you should call this function after urg_open() is called.

long urg_time_stamp ( urg_t * urg )

Retrieve Timestamp value.

Parameters

[in,out] urg URG resource

Return values

>=0	Timestamp value [msec]
<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();
// handle Timestamp
...
urg_stop_time_stamp_mode(&urg);

Examples:: sync_time_stamp.c.

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

Start measurement.

Start measurement. The actual data you can get in urg_get_distance(), urg_get_distance_intensity(), urg_get_multiecho(), urg_get_multiecho_intensity().

Parameters

[in,out]	urg	URG resource
[in]	type	Measurement type
[in]	scan_times	Measurement times
[in]	skip_scan	Measurement interval

Return values

0	Success
<0	Error

the argument of 'type' can specify the type of data you want to retrieve.

URG_DISTANCE ... Distance data
URG_DISTANCE_INTENSITY ... Measurement and Intensity data
URG_MULTIECHO ... Multiecho Distance data
URG_MULTIECHO_INTENSITY ... Multiecho (Distance + Intensity) data

'scan_times' is specified by the number of zero or more times or to get the data. However, if you specify 0 or # URG_SCAN_INFINITY, you will get the data for an unlimited number of times.
Call urg_stop_measurement() to stop the measurement.

'skip_scan' means the number of rotation of the mirror, or do not want to scan many times after a single scan. the range skip_scan is [0, 9].

Scan interval image

For example, if the rotation of the mirror is the 1 specified in skip_scan sensor of 100 [msec], data acquisition interval is 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);
    // handle receive data
    ...
}

See Also: 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_get_distance	(	urg_t *	urg,
		long	data[],
		long *	time_stamp
	)

Retrieve Distance data.

Retrieve distance data from the sensor distance. You must specify URG_DISTANCE to call urg_start_measurement() in advance.

Parameters

[in,out]	urg	URG resource
[out]	data	Distance data [mm]
[out]	time_stamp	Timestamp [msec]

Return values

>=0	Number of retrieve data
<0	Error

'data', the distance data obtained from the sensor is stored. 'data' must be set aside to store the data size. Number of data to be stored in the data can be obtained in urg_max_data_size().

'time_stamp', the time stamp is stored inside the sensor. Please specify NULL if you do not want to get time_stamp.

Example

long *data = (long*)malloc(urg_max_data_size(&urg) * sizeof(data[0]));
...
// Retrieve Distance data
urg_start_measurement(&urg, URG_DISTANCE, 1, 0);
int n = urg_get_distance(&urg, data, NULL);
...
// Retrieve Distance data and Tiemstamp
long time_stamp;
urg_start_measurement(&urg, URG_DISTANCE, 1, 0);
n = urg_get_distance(&urg, data, &time_stamp);

See Also: 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
	)

Retrieve Distance and Intensity data.

It is a function of the distance and intensity data that can be acquired. You must call urg_start_measurement() with URG_DISTANCE_INTENSITY in advance.

Parameters

[in,out]	urg	URG resource
[out]	data	Distance data [mm]
[out]	intensity	Intensity data [1]
[out]	time_stamp	Timestamp [msec]

Return values

>=0	Number of retrieve data
<0	Error

Reflection intensity waveform is used to calculate the distance and intensity data are different for each series of the sensor characteristics. By using the intensity data, you can guess the rough shading of the reflectance of the object and the environment.

'data' and 'time_stamp' is the same behavior urg_get_distance().

in 'intensity', the intensity data obtained from the sensor is stored. 'intensity' should be set aside to store the data size. Number of data to be stored in the 'intensity' can be obtained by urg_max_data_size().

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 Also: 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
	)

Retrieve Distance data (Multi-echo version)

This function is multiecho version of urg_get_distance(). You must call urg_start_measurement() with URG_MULTIECHO in advance.

Parameters

[in,out]	urg	URG resource
[out]	data_multi	Distance data (Multiecho) [mm]
[out]	time_stamp	Timestamp [msec]

Return values

>=0	Number of retrieve data
<0	Error

The multi-echo means multi-distance data. Multiple echoes are obtained when a plurality of distance data obtained in one laser emission.

Multiecho image

'time_stamp' is the same behavior urg_get_distance().

'data_multi', the distance data obtained from the sensors are stored per URG_MAX_ECHO(=3) in one step. Multi-echo data value of the item does not exist, -1 is stored.

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

Data is stored in ascending order.

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 Also: 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
	)

Retrieve Distance and Intensity data (Multi-echo version)

This function is multiecho version of urg_get_distance_intensity(). You must call urg_start_measurement() with URG_MULTIECHO_INTENSITY in advance.

Parameters

[in,out]	urg	URG resource
[out]	data_multi	Distance data [mm]
[out]	intensity_multi	Intensity data [1]
[out]	time_stamp	Timestamp [msec]

Return values

>=0	Number of retrieve data
<0	Error

'data_multi', 'time_stamp' is the same behavior urg_get_multiecho().

'intensity_multi' sequence data is the same as data_multi. Number of data to be stored in the 'intensity_multi' can be obtained by 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 Also: urg_start_measurement(), urg_max_data_size()

Examples:: get_multiecho_intensity.c.

int urg_stop_measurement ( urg_t * urg )

Stop measurement and turn off laser.

Cancel the operation of urg_start_measurement().

Parameters

[in,out] urg URG resource

Return values

0	Success
<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 Also: urg_start_measurement()

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

Set the measurement range.

This function specified the sensor measures range. The amount of data returned by the function of the distance data acquisition such as urg_get_distance() is limited to the extent that you specify here.

Parameters

[in,out]	urg	URG resource
[in]	first_step	first step
[in]	last_step	last step
[in]	skip_step	number of grouping steps

Return values

0	Success
<0	Error

センサの step は、センサ正面を 0 とし、センサ上部から見て反時計まわりの向きが正の値となる順に割り振られます。

センサと step の関係

step の間隔と、最大値、最小値はセンサ依存です。step 値の最大値、最小値は urg_step_min_max() で取得できます。

first_step, last_step でデータの計測範囲を指定します。計測範囲は [first_step, last_step] となります。

skip_step は、計測データをグルーピングする個数を指定します。指定できる値は [0, 99] です。
skip_step は、指定された数のデータを 1 つにまとめることで、センサから受信するデータ量を減らし、距離取得を行う関数の応答性を高めるときに使います。ただし、データをまとめるため、得られるデータの分解能は減ります。

例えば以下のような距離データが得られる場合に

100, 101, 102, 103, 104, 105, 106, 107, 108, 109

skip_step に 2 を指定すると、得られるデータは以下のようになります。

100, 102, 104, 106, 108

データは、まとめるデータのうち、一番小さな値のデータが用いられます。

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 Also: urg_step_min_max(), urg_rad2step(), urg_deg2step()

Examples:: get_distance.c.

int urg_set_communication_data_size	(	urg_t *	urg,
		urg_range_data_byte_t	data_byte
	)

Set the size of communication data.

距離データをセンサから受信の際のデータサイズを変更します。

Parameters

[in,out]	urg	URG センサ管理
[in]	data_byte	距離値を表現するデータのバイト数

Return values

0	Success
<0	Error

data_byte には

URG_COMMUNICATION_3_BYTE ... 距離を 3 byte で表現する
URG_COMMUNICATION_2_BYTE ... 距離を 2 byte で表現する

を指定できます。
初期状態では距離を 3 byte で表現するようになっています。この設定を 2 byte に設定することで、センサから受信するデータ数は 2/3 になります。ただし、取得できる距離の最大値が 4095 になるため、観測したい対象が 4 [m] 以内の範囲に存在する場合のみ利用して下さい。

void urg_sleep ( urg_t * urg )

センサを低消費電力の状態に遷移させる

低消費電力のモードでは、スキャナの回転が停止し計測も中断されます。

低消費電力のモード
- レーザが消灯して計測が中断される。
- スキャナの回転が停止する。

低消費電力のモードから抜けるためには urg_wakeup() 関数を呼び出して下さい。

See Also: urg_wakeup()

void urg_wakeup ( urg_t * urg )

センサを低消費電力のモードから通常の状態に遷移させる

See Also: urg_sleep()

int urg_is_stable ( urg_t * urg )

センサが計測できる状態かを返す

Return values

1	センサが計測できる状態にある
0	センサが計測できる状態にない

起動直後でスキャナの回転が安定していない場合や、何らかのエラーで計測できない場合、この関数は 0 を返します。

const char* urg_sensor_product_type ( urg_t * urg )

Get product type string.

センサの型式を文字列で返す。返される文字列はセンサ依存となる。

Parameters

[in] urg URG センサ管理

Returns: センサ型式の文字列

Examples:: sensor_parameter.c.

const char* urg_sensor_serial_id ( urg_t * urg )

Get Serial ID.

センサのシリアル ID 文字列を返す。返される文字列はセンサ依存となる。

Parameters

[in] urg URG センサ管理

Returns: シリアル ID 文字列

Examples:: sensor_parameter.c.

const char* urg_sensor_firmware_version ( urg_t * urg )

Get firmware version.

センサのソフトウェア・バージョン文字列を返す。返される文字列はセンサ依存となる。

Parameters

[in] urg URG センサ管理

Returns: バージョン文字列

Examples:: sensor_parameter.c.

const char* urg_sensor_status ( urg_t * urg )

Get sensor status string.

センサのステータス文字列を返す。返される文字列はセンサ依存となる。

Parameters

[in] urg URG センサ管理

Returns: ステータス文字列

Examples:: sensor_parameter.c.

const char* urg_sensor_state ( urg_t * urg )

Get sensor state string.

センサのステータス文字列を返す。返される文字列はセンサ依存となる。

Parameters

[in] urg URG センサ管理

Returns: 状態を示す文字列

Attention: 状態については SCIP の通信仕様書を参照のこと。

Examples:: sensor_parameter.c.

void urg_set_error_handler	(	urg_t *	urg,
		urg_error_handler	handler
	)

Set error handler.

エラーハンドラは Gx, Mx 系のコマンドの応答が "00" か "99" 以外のときに呼び出される。

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

Decode SCIP string.

Parameters

[in]	data	SCIP string
[in]	data	number of data byte

Return values

decoded value

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation