hokuyo_aist::Sensor Class Reference

Hokuyo laser scanner class. More...

#include <sensor.h>

List of all members.

Public Member Functions

void open (std::string port_options)

Open the laser scanner and begin scanning.

unsigned int open_with_probing (std::string port_options)

Open the laser scanner and begin scanning, probing the baud rate.

void close ()

Close the connection to the laser scanner.

bool is_open () const

Checks if the connection to the laser scanner is open.

void set_power (bool on)

Switch the laser scanner on or off.

void set_baud (unsigned int baud)

Change the baud rate when using a serial connection.

void set_ip (IPAddr const &addr, IPAddr const &subnet, IPAddr const &gateway)

Change the IP address information.

void reset ()

Reset the laser scanner to its default settings.

void semi_reset ()

Reset everything except motor and serial speed.

void set_motor_speed (unsigned int speed)

Set the speed at which the scanner's sensor spins.

void set_high_sensitivity (bool on)

Switch the scanner between normal and high sensitivity modes.

void get_sensor_info (SensorInfo &info)

Get various information about the scanner.

unsigned int get_time ()

Get the value of the scanner's clock in milliseconds.

unsigned int get_raw_time ()

Get the raw value of the scanner's clock in milliseconds.

long long calibrate_time (unsigned int skew_sleep_time=0, unsigned int samples=10)

Calibrate the time offset between the laser and computer.

long long time_offset () const

Retrieve the calculated time offset (0 if not calibrated).

void set_time_offset (long long time_offset)

Set the time offset (if the calculated value is bad).

float drift_rate () const

Retrieve the current clock drift rate (0 if not set).

void set_drift_rate (float drift_rate)

float skew_alpha () const

Get the calculated skew line slope (default: 0).

void set_skew_alpha (float alpha)

unsigned int get_ranges (ScanData &data, int start_step=-1, int end_step=-1, unsigned int cluster_count=1)

Get the latest scan data from the scanner.

unsigned int get_ranges_by_angle (ScanData &data, double start_angle, double end_angle, unsigned int cluster_count=1)

Get the latest scan data from the scanner.

unsigned int get_ranges_intensities (ScanData &data, int start_step=-1, int end_step=-1, unsigned int cluster_count=1)

Get the latest scan data from the scanner with intensities.

unsigned int get_ranges_intensities_by_angle (ScanData &data, double start_angle, double end_angle, unsigned int cluster_count=1)

Get the latest scan data from the scanner with intensities.

unsigned int get_new_ranges (ScanData &data, int start_step=-1, int end_step=-1, unsigned int cluster_count=1)

Get a new scan from the scanner.

unsigned int get_new_ranges_by_angle (ScanData &data, double start_angle, double end_angle, unsigned int cluster_count=1)

Get a new scan from the scanner.

unsigned int get_new_ranges_intensities (ScanData &data, int start_step=-1, int end_step=-1, unsigned int cluster_count=1)

Get a new scan from the scanner with intensity data.

unsigned int get_new_ranges_intensities_by_angle (ScanData &data, double start_angle, double end_angle, unsigned int cluster_count=1)

Get a new scan from the scanner with intensity data.

uint8_t scip_version () const

Return the major version of the SCIP protocol in use.

void set_verbose (bool verbose)

Turns on and off printing of verbose operating information to stderr. Default is off.

void ignore_unknowns (bool ignore)

Enables/disables ignoring unknown lines in sensor info messages. Default is off.

void set_multiecho_mode (MultiechoMode mode)

Set the multi-echo mode to use. Default is ME_OFF.

double step_to_angle (unsigned int step)

A convenience function to convert a step index to an angle.

unsigned int angle_to_step (double angle)

A convenience function to convert an angle to a step (rounded towards the front).

Detailed Description

Hokuyo laser scanner class.

Provides an interface for interacting with a Hokuyo laser scanner using SCIP protocol version 1 or 2. The FlexiPort library is used to implement the data communications with the scanner. See its documentation for details on controlling the connection.

To use a serial connection, ensure that you do not also have a USB cable connected, as this will force the scanner into USB mode, preventing the serial connection from functioning correctly.

All functions may throw instances of BaseError or its children. Exceptions from FlexiPort may also occur.

Member Function Documentation

long long hokuyo_aist::Sensor::calibrate_time	(	unsigned int	skew_sleep_time = `0`,
		unsigned int	samples = `10`
	)

Calibrate the time offset between the laser and computer.

This function performs several checks of the communications between the laser and the computer. Its goal is to calculate the communications lag between the two devices, and so determine as accurately as possible what the offset is from the computer's clock to the laser's clock. This offset is necessary to calculate the time stamp of scans in terms of the computer's clock.

Because this function sends a lot of data to and from the laser, it may take some time to complete. It will never be called automatically; until it is called, the offset defaults to zero.

Note that the laser's clock is a 24-bit millisecond timer. It wraps approximately every 9.5 hours. This class will detect wrapped time stamps and adjust them accordingly.

Parameters:

	skew_sleep_time	Whether to approximate the laser clock skew. This requires sleeping for the specified time, then calibrating again. The results of the two calibrations are used to approximate the clock skew as a straight line between the two points. This is very approximate; in order to overcome noise in the signal you will need to calibrate over a period of up to several minutes. Set this to 0 to not approximate the skew.
	samples	The number of samples to use in calculating latencies.

Returns:: The calculated offset in nanoseconds.

References hokuyo_aist::median().

unsigned int hokuyo_aist::Sensor::get_new_ranges	(	ScanData &	data,
		int	start_step = `-1`,
		int	end_step = `-1`,
		unsigned int	cluster_count = `1`
	)

Get a new scan from the scanner.

Unlike get_ranges, which returns the most recent scan the scanner took, this function will request a new scan. This means it will wait while the scanner performs the scan, which means the rate at which scans can be retrieved using this function is less than with get_ranges. Otherwise behaves identicallty to get_ranges.

Not available with the SCIP v1 protocol.

Note:: The command used to retrieve a fresh scan is also used for the continuous scanning mode (not yet supported by this library). After completing a scan, it will turn the laser off (in anticipation of another continuous scan command being sent, which will automatically turn the laser back on again). If you want to mix get_new_ranges and get_ranges, you will need to turn the laser on after each call to get_new_ranges.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.
	start_step	The first step to get ranges from. Set to -1 for the first scannable step.
	end_step	The last step to get ranges from. Set to -1 for the last scannable step.

Returns:: The number of range readings read into data.

References hokuyo_aist::ScanData::laser_time_, hokuyo_aist::ScanData::ranges_length_, and hokuyo_aist::ScanData::system_time_.

Referenced by get_new_ranges_by_angle().

unsigned int hokuyo_aist::Sensor::get_new_ranges_by_angle	(	ScanData &	data,
		double	start_angle,
		double	end_angle,
		unsigned int	cluster_count = `1`
	)

Get a new scan from the scanner.

Not available with the SCIP v1 protocol.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	start_angle	The angle to get range readings from. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	end_angle	The angle to get range readings to. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.

Returns:: The number of range readings read into data.

References angle_to_step(), and get_new_ranges().

unsigned int hokuyo_aist::Sensor::get_new_ranges_intensities	(	ScanData &	data,
		int	start_step = `-1`,
		int	end_step = `-1`,
		unsigned int	cluster_count = `1`
	)

Get a new scan from the scanner with intensity data.

Unlike get_ranges, which returns the most recent scan the scanner took, this function will request a new scan. This means it will wait while the scanner performs the scan. Otherwise behaves identicallty to get_ranges.

Not available with the SCIP v1 protocol.

Note:: The command used to retrieve a fresh scan is also used for the continuous scanning mode (not yet supported by this library). After completing a scan, it will turn the laser off (in anticipation of another continuous scan command being sent, which will automatically turn the laser back on again). If you want to mix get_new_ranges and get_ranges, you will need to turn the laser on after each call to get_new_ranges.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.
	start_step	The first step to get ranges from. Set to -1 for the first scannable step.
	end_step	The last step to get ranges from. Set to -1 for the last scannable step.

Returns:: The number of range readings read into data.

References hokuyo_aist::ScanData::laser_time_, hokuyo_aist::ScanData::ranges_length_, and hokuyo_aist::ScanData::system_time_.

Referenced by get_new_ranges_intensities_by_angle().

unsigned int hokuyo_aist::Sensor::get_new_ranges_intensities_by_angle	(	ScanData &	data,
		double	start_angle,
		double	end_angle,
		unsigned int	cluster_count = `1`
	)

Get a new scan from the scanner with intensity data.

Not available with the SCIP v1 protocol.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	start_angle	The angle to get range readings from. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	end_angle	The angle to get range readings to. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.

Returns:: The number of range readings read into data.

References angle_to_step(), and get_new_ranges_intensities().

unsigned int hokuyo_aist::Sensor::get_ranges	(	ScanData &	data,
		int	start_step = `-1`,
		int	end_step = `-1`,
		unsigned int	cluster_count = `1`
	)

Get the latest scan data from the scanner.

This function requires a pointer to a ScanData object. It will allocate space in this object as necessary for storing range data. If the passed-in ScanData object already has the correct quantity of space to store the range data, it will not be re-allocated. If it does not have any space, it will be allocated. If it has space, but it is the wrong size, it will be re-allocated. This means you can repeatedly send the same ScanData object without having to worry about allocating its data, whether it will change or not, while also avoiding excessive allocations.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.
	start_step	The first step to get ranges from. Set to -1 for the first scannable step.
	end_step	The last step to get ranges from. Set to -1 for the last scannable step.

Returns:: The number of range readings read into data.

References hokuyo_aist::ScanData::laser_time_, hokuyo_aist::ScanData::ranges_length_, and hokuyo_aist::ScanData::system_time_.

Referenced by get_ranges_by_angle().

unsigned int hokuyo_aist::Sensor::get_ranges_by_angle	(	ScanData &	data,
		double	start_angle,
		double	end_angle,
		unsigned int	cluster_count = `1`
	)

Get the latest scan data from the scanner.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	start_angle	The angle to get range readings from. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	end_angle	The angle to get range readings to. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.

Returns:: The number of range readings read into data.

References angle_to_step(), and get_ranges().

unsigned int hokuyo_aist::Sensor::get_ranges_intensities	(	ScanData &	data,
		int	start_step = `-1`,
		int	end_step = `-1`,
		unsigned int	cluster_count = `1`
	)

Get the latest scan data from the scanner with intensities.

This function requires a pointer to a ScanData object. It will allocate space in this object as necessary for storing range data. If the passed-in ScanData object already has the correct quantity of space to store the range data, it will not be re-allocated. If it does not have any space, it will be allocated. If it has space, but it is the wrong size, it will be re-allocated. This means you can repeatedly send the same ScanData object without having to worry about allocating its data, whether it will change or not, while also avoiding excessive allocations.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.
	start_step	The first step to get ranges from. Set to -1 for the first scannable step.
	end_step	The last step to get ranges from. Set to -1 for the last scannable step.

Returns:: The number of range readings read into data.

References hokuyo_aist::ScanData::laser_time_, hokuyo_aist::ScanData::ranges_length_, and hokuyo_aist::ScanData::system_time_.

Referenced by get_ranges_intensities_by_angle().

unsigned int hokuyo_aist::Sensor::get_ranges_intensities_by_angle	(	ScanData &	data,
		double	start_angle,
		double	end_angle,
		unsigned int	cluster_count = `1`
	)

Get the latest scan data from the scanner with intensities.

Parameters:

	data	Pointer to a ScanData object to store the range readings in.
	start_angle	The angle to get range readings from. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	end_angle	The angle to get range readings to. Exclusive; if this falls between two steps the step inside the angle will be returned, but the step outside won't.
	cluster_count	The number of readings to cluster together into a single reading. The minimum value from a cluster is returned as the range for that cluster.

Returns:: The number of range readings read into data.

References angle_to_step(), and get_ranges_intensities().

unsigned int hokuyo_aist::Sensor::get_raw_time ( )

Get the raw value of the scanner's clock in milliseconds.

Not available with the SCIP v1 protocol.

Referenced by get_time().

void hokuyo_aist::Sensor::get_sensor_info ( SensorInfo & info )

Get various information about the scanner.

Much of the information is not available with the SCIP v1 protocol.

unsigned int hokuyo_aist::Sensor::get_time ( )

Get the value of the scanner's clock in milliseconds.

Not available with the SCIP v1 protocol.

References get_raw_time().

unsigned int hokuyo_aist::Sensor::open_with_probing ( std::string port_options )

Open the laser scanner and begin scanning, probing the baud rate.

If the port is a serial connection and communication with the laser fails at the given baud rate, the alternative baud rates supported by the device are tried (see set_baud for these) in order from fastest to slowest.

Returns:: The baud rate at which connection with the laser succeeded, or 0 for non-serial connections.

References flexiport::Port::Flush(), flexiport::Port::GetPortType(), flexiport::Port::GetStatus(), and flexiport::Port::Open().

void hokuyo_aist::Sensor::reset ( )

Reset the laser scanner to its default settings.

Not available with the SCIP v1 protocol.

void hokuyo_aist::Sensor::semi_reset ( )

Reset everything except motor and serial speed.

Requires SCIP v2.1 or higher.

void hokuyo_aist::Sensor::set_baud ( unsigned int baud )

Change the baud rate when using a serial connection.

Valid rates are 19.2Kbps, 38.4Kbps, 57.6Kbps, 115.2Kbps, 250.0Kbps, 500.0Kbps, 750.0Kbps (dependent on those available in FlexiPort).

References flexiport::Port::GetPortType().

void hokuyo_aist::Sensor::set_drift_rate ( float drift_rate ) [inline]

Set the current clock drift rate.

The drift rate is used when correcting laser time stamps to computer time. It is factored into the equation as: Tc = ((1 - drift)Tl + offset + beta) / (1 - alpha) where Tc is the computer time and Tl is the laser time. See set_skew_alpha for the values of alpha and beta.

If the drift rate is zero, it means the laser's clock does not drift. This is extremely unlikely, but the laser's drift may not matter for your application.

Drift should usually be provided by the manufacturer. If it is not, you can calculate it by calibrating the laser many times over a long period and looking at the change in the calculated offset.

void hokuyo_aist::Sensor::set_ip	(	IPAddr const &	addr,
		IPAddr const &	subnet,
		IPAddr const &	gateway
	)

Change the IP address information.

This function only works on devices providing an ethernet connection.

Once this function has successfully completed, the laser must be restarted for it to take effect.

References hokuyo_aist::IPAddr::first, hokuyo_aist::IPAddr::fourth, hokuyo_aist::IPAddr::second, and hokuyo_aist::IPAddr::third.

void hokuyo_aist::Sensor::set_motor_speed ( unsigned int speed )

Set the speed at which the scanner's sensor spins.

Set the speed to 0 to have it reset to the default value, and 99 to reset it to the initial (startup) value. Values between 1 and 10 specify a ratio of the default speed. The speeds in revolutions per minute that these correspond to will depend on the scanner model. For example, for a URG-04LX, they are (from 1 to 10) 594, 588, 576, 570, 564, 558, 552, 546, and 540 rpm.

Not available with the SCIP v1 protocol.

void hokuyo_aist::Sensor::set_skew_alpha ( float alpha ) [inline]

Set a skew line slope value.

The skew is used when correcting laser time stamps to computer time. It is factored into the equation as: Tc = ((1 - drift)Tl + offset + beta) / (1 - alpha) where Tc is the computer time and Tl is the laser time. See drift_rate for the value of the drift. Beta, the line's y crossing, is assumed to be 0 since we always use a two-point line fit instead of something like least squares.

The effect of this is to cancel out the skew caused by the different frequencies of the computer clock and the laser clock.

The documentation for this class was generated from the following files:

sensor.h
sensor.cpp