rplidar_read :: Quanser C Functions

navigation bar

rplidar_read

Reads one scan from the RPLidar.

Description

The rplidar_read function reads LIDAR data from the ranging sensor.

When the measurement mode is RANGING_MEASUREMENT_MODE_NORMAL, the "raw" sensor readings from the LIDAR are returned (but the values are scaled to the SI units expected). In this case, the number of measurements may vary and the angles may not be consistent between scans. Furthermore, while the angles will be in ascending order, the first angle may not be zero. It will, however, be close to zero. If the size of the measurements buffer provided is not large enough then -QERR_BUFFER_TOO_SMALL will be returned. In this case, the function may be called again with a larger buffer.

When the measurement mode is RANGING_MEASUREMENT_MODE_INTERPOLATED, the raw sensor readings from the LIDAR are not returned. Instead, the number of "measurements" requested will be returned, in which the angles are 360/N degrees apart (in radians), where N is the number of measurements requested and the first angle is zero. The distances will be interpolated from the raw data, as will the standard deviation and quality. Interpolation is only performed between two consecutive valid readings. The advantage of this mode is that the angles are always consistent, as are the number of measurements, so the data is easier to process.

If no new scan data is available then -QERR_WOULD_BLOCK is returned.

If the quality is zero then it indicates an invalid measurement (no reflected laser pulse).

Prototype

t_int
rplidar_read(t_ranging_sensor sensor, t_ranging_measurement_mode mode, t_double maximum_interpolated_distance, t_double maximum_interpolated_angle,
                t_ranging_measurement * measurements, t_uint num_measurements);

Parameters

t_ranging_sensor sensor

A handle to the sensor, as returned by rplidar_open.

t_ranging_measurement_mode mode

The mode to use when returning LIDAR data. One of the following modes may be selected:

Mode	Description
RANGING_MEASUREMENT_MODE_NORMAL	Return actual measurement data. Number of measurements will vary and angles will not be consistent between scans. Angles will start close to zero.
RANGING_MEASUREMENT_MODE_INTERPOLATED	Returns the number of measurements, N, requested. Angles will start at zero and be 360/N apart. Raw measurements will be interpolated to estimate distance at each angle.

t_double maximum_interpolated_distance

This parameter is only used when the mode is set to . If the difference in the distances r1 and r2 between two consecutive LIDAR samples (r1, theta1) and (r2, theta2) is less than this parameter then the corresponding output element(s) will be interpolated from the two samples. If the distance is greater than this parameter then the distance corresponding to the closest angle will be used.

Setting this parameter to zero causes the distance corresponding to the closest angle to always be used. Setting it to INFINITY causes linear interpolation to always be used.

t_double maximum_interpolated_angle

This parameter is only used when the mode is set to . If the difference in the angles theta1 and theta2 between two consecutive LIDAR samples (r1, theta1) and (r2, theta2) is less than this parameter then the corresponding output element(s) will be interpolated from the two samples. If the difference is greater than this parameter then the distance and quality will be set to zero for the samples in that span.

Setting this parameter to INFINITY causes linear interpolation to always be used. Setting it to a value less than the angle between any two consecutive LIDAR samples will result in the distances and quality always being zero, so this is not recommended.

t_ranging_measurement * measurements

A buffer in which the actual measurement data is stored. If this buffer is too small then the return value will be -QERR_BUFFER_TOO_SMALL. Each element of the array is a structure with the following fields:

Data Type	Field	Description
t_double	distance	The distance in metres from the LIDAR of this point.
t_double	distance_sigma	An estimate of the standard deviation in the current distance measurement.
t_double	heading	The heading in radians of the point (will be zero for 1D ranging sensors).
t_uint8	quality	An indication of the quality of the measurement (0 to 100%).

t_uint num_measurements

The number of elements in the measurements array.

Return value

Returns the number of measurements actually copied to the measurements buffer on success. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_BUFFER_TOO_SMALL

The supplied measurements buffer is not large enough to hold the scan data.

QERR_WOULD_BLOCK

No new data is available since the last call.

Requirements

Include Files	Libraries
quanser_ranging_sensor.h	quanser_devices.lib;quanser_communications.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_ranging_sensor lidar;
t_error result = 
    rplidar_open("serial-cpu://localhost:1?baud='256000',word='8',parity='none',stop='1',flow='none',dsr='on'", RANGING_DISTANCE_LONG, &lidar);
if (result == 0) {
    while (!stop) {
        t_ranging_measurement measurements[1024];        
        t_int samples = rplidar_read(lidar, RANGING_MEASUREMENT_MODE_NORMAL, 0.0, 0.0, measurements, ARRAY_LENGTH(measurements));
        ...
    }
    rplidar_close(lidar);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open RPLidar. %s (error %d)\n"), message, -result);
}