rplidar_open :: Quanser C Functions

navigation bar

rplidar_open

Opens an RPLidar ranging sensor.

Description

The rplidar_open function opens a particular RPLidar sensor. The handle to the sensor returned by this function is used by the other RPLidar functions in the Devices API to refer to the LIDAR sensor. This handle must be closed using the rplidar_close function when the sensor is no longer in use.

Prototype

t_error
rplidar_open(const char * uri, t_ranging_distance range, t_ranging_sensor * sensor);

Parameters

const char * uri

A string containing the URI identifying the communication protocol and associated parameters to use to communicate with the ranging sensor. For example, serial://localhost:1?baud=115200 connects to the LIDAR through serial port 1 (e.g. COM1 or /dev/ttyS1) at 115200 baud.

On the QCar, for example, a suitable URI for the RPLidar A2 M8 is serial-cpu://localhost:2?baud='115200',word='8',parity='none',stop='1',flow='none',dsr='on'. The option allows the DTR and RTS signals to be manually controlled, which is required for the RPLidar sensor because the RTS line is used to control the LIDAR's motor.

The following table lists suitable URIs for RPLidar sensors on different platforms:

Target(s)	Sensor	URI
QCar 2	RPLidar S2 LIDAR	serial-cpu://localhost:1?baud='1000000',word='8',parity='none',stop='1',flow='none',dsr='on'
QCar 2	RPLidar A3 LIDAR	serial-cpu://localhost:1?baud='256000',word='8',parity='none',stop='1',flow='none',dsr='on'
QCar 2	RPLidar A2 M12 LIDAR	serial-cpu://localhost:1?baud='256000',word='8',parity='none',stop='1',flow='none',dsr='on'
QCar	RPLidar A2 M8 LIDAR	serial-cpu://localhost:2?baud='115200',word='8',parity='none',stop='1',flow='none',dsr='on'

t_ranging_distance range

The ranging distance parameter is used to optimize the sensor settings for a particular range of distances. For each sensor, the corresponding ranges will differ. For example, for the VL53L1X Time-of-Flight sensor, the distance ranges for a 100 ms timing budget are:

Ranging Distance	Maximum distance in dark (cm)	Maximum distance under strong ambient light (cm)
RANGING_DISTANCE_SHORT	136	135
RANGING_DISTANCE_MEDIUM	290	76
RANGING_DISTANCE_LONG	360	73

t_ranging_sensor * sensor

A handle to the sensor is returned in the t_ranging_sensor variable passed in this parameter. This argument cannot be NULL. Pass the address of a variable of type t_ranging_sensor.

Return value

The return value is 0 if the sensor is opened successfully. 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_CPU_GPIO_IN_USE

The GPIO used to enable the LIDAR motor is being used by another process.

QERR_DEVICE_IO_ERROR

The RPLidar sensor is communicating but is reporting an unhealthy status.

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

QERR_INVALID_PACKET

The sensor responded with an invalid packet. Check that the URI represents the interface to an RPLidar sensor.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

QERR_TIMED_OUT

The function timed out waiting for the sensor to respond. Make sure the URI represents the proper interface to the sensor and that the sensor is connected.

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) {
    ...
    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);
}