Detailed Description

Defines the Lidar sensor methods.

Data Structures
struct	dwLidarDecodedPacket
	Defines the structure for a decoded lidar packet. More...

struct	dwLidarDecodedReturn
	Defines the return structure for an extended decoded lidar packet. More...

struct	dwLidarPointRTHI
	Holds a Lidar point cloud RTHI and the associated intensity. More...

struct	dwLidarPointXYZI
	Holds a Lidar point cloud XYZ and the associated intensity. More...

struct	dwLidarProperties
	Defines the properties of the lidar. More...

Macros
#define	DW_SENSORS_LIDAR_MAX_RETURNS 10
	Maximum number of distinct lidar returns a point cloud can contain. More...

#define	DW_SENSORS_LIDAR_MAX_ROWS 256

Typedefs
typedef struct _dwLidarDecodedSSI	dwLidarDecodedSSI
	Not available as of current release. Will be added in future release. More...

Enumerations
enum	dwLidarAuxDataType { DW_LIDAR_AUX_DATA_TYPE_SNR = 0 , DW_LIDAR_AUX_DATA_TYPE_PULSEWIDTH_PS = 1 , DW_LIDAR_AUX_DATA_TYPE_TIME = 2 , DW_LIDAR_AUX_DATA_TYPE_V_MPS = 3 , DW_LIDAR_AUX_DATA_TYPE_EXISTENCEPROB = 4 , DW_LIDAR_AUX_DATA_TYPE_CROSSTALKPROB = 5 , DW_LIDAR_AUX_DATA_TYPE_NOISELEVEL = 6 , DW_LIDAR_AUX_DATA_TYPE_ZONEID = 7 , DW_LIDAR_AUX_DATA_TYPE_DETECTORID = 8 , DW_LIDAR_AUX_DATA_TYPE_LINEID = 9 , DW_LIDAR_AUX_DATA_TYPE_DATAQUALITY = 10 , DW_LIDAR_AUX_DATA_TYPE_SCANCHECKPOINT = 11 , DW_LIDAR_AUX_DATA_TYPE_BLOCKAGEFLAG = 12 , DW_LIDAR_AUX_DATA_TYPE_SENSORID = 13 , DW_LIDAR_AUX_DATA_TYPE_AZIMUTH = 14 , DW_LIDAR_AUX_DATA_TYPE_ELEVATION = 15 , DW_LIDAR_AUX_DATA_TYPE_DISTANCE = 16 , DW_LIDAR_AUX_DATA_TYPE_ROI = 17 , DW_LIDAR_AUX_DATA_TYPE_VALIDITY = 18 , DW_LIDAR_AUX_DATA_TYPE_INVALIDITYFLAG = 19 , DW_LIDAR_AUX_DATA_TYPE_COUNT = 20 , DW_LIDAR_AUX_DATA_TYPE_FORCE32 = 0x7FFFFFFF }
	An enum for every data element we could possibly return. More...

enum	dwLidarInvalidityFlag { DW_LIDAR_INVALIDITY_NONE = 0 , DW_LIDAR_INVALIDITY_DW = 1 << 0 , DW_LIDAR_INVALIDITY_VEND = 1 << 1 , DW_LIDAR_INVALIDITY_BLOCKAGE = 1 << 2 , DW_LIDAR_INVALIDITY_INVALID }
	An enum for specifying invalidity flags. More...

enum	dwLidarReturnType { DW_LIDAR_RETURN_TYPE_ANY = 0 , DW_LIDAR_RETURN_TYPE_FIRST = 1 << 0 , DW_LIDAR_RETURN_TYPE_LAST = 1 << 1 , DW_LIDAR_RETURN_TYPE_STRONGEST = 1 << 2 , DW_LIDAR_RETURN_TYPE_ABS_STRONGEST = 1 << 3 , DW_LIDAR_RETURN_TYPE_1 = 1 << 4 , DW_LIDAR_RETURN_TYPE_2 = 1 << 5 , DW_LIDAR_RETURN_TYPE_3 = 1 << 6 , DW_LIDAR_RETURN_TYPE_4 = 1 << 7 , DW_LIDAR_RETURN_TYPE_5 = 1 << 8 , DW_LIDAR_RETURN_TYPE_6 = 1 << 9 }
	Enum to indicate a single return type. More...

Functions
DW_API_PUBLIC dwStatus	dwSensorLidar_disableDecoding (dwSensorHandle_t const sensor)
	Disable the decoding of the Lidar packets, which frees additional CPU load. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_enableDecoding (dwSensorHandle_t const sensor)
	Enables the decoding of the Lidar packets, which incurs an additional CPU load. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_getAuxElementSize (uint32_t *const sizeBytes, dwLidarAuxDataType const auxType)
	Returns size of auxiliary data element in bytes. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_getProperties (dwLidarProperties *const lidarProperties, dwSensorHandle_t const sensor)
	Gets information about the Lidar sensor. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_isDecodingEnabled (bool *const enable, dwSensorHandle_t const sensor)
	Retrieves the state of packet decoding. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_processRawData (dwLidarDecodedPacket const *const data, uint8_t const const rawData, size_t const size, dwSensorHandle_t const sensor)
	Decodes RAW data previously read and returns a pointer to it. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_readPacket (dwLidarDecodedPacket const **const data, dwTime_t const timeoutUs, dwSensorHandle_t const sensor)
	Reads one scan packet. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_returnPacket (dwLidarDecodedPacket const *const data, dwSensorHandle_t const sensor)
	Returns the data read to the internal pool. More...

DW_API_PUBLIC dwStatus	dwSensorLidar_sendMessage (uint32_t const cmd, uint8_t const *const data, size_t const size, dwSensorHandle_t const sensor)
	Sends a message to Lidar sensor. More...

Data Structure Documentation

◆ dwLidarDecodedPacket

struct dwLidarDecodedPacket

Data Fields
float32_t	azimuthOffsetRad	Azimuth offset angle in the packet, in rads
dwTime_t	duration	Time difference between the first measurement and the last, in microseconds.
float32_t	elevationOffsetRad	Elevation offset angle in the packet, in rads
dwTime_t	hostTimestamp	Timestamp measured on the host, in microseconds.
dwLidarDecodedSSI const *	lidarSSI	lidar supplement status info such as misc and health info
float32_t	maxHorizontalAngleRad	Maximum horizontal angle in the packet, in rads
uint32_t	maxPoints	Maximum number of points in the `pointsRTHI` and `pointsXYZI` arrays in the packet.
float32_t	maxVerticalAngleRad	Maximum vertical angle in the packet, in rads
float32_t	minHorizontalAngleRad	Minimum horizontal angle in the packet, in rads
float32_t	minVerticalAngleRad	Minimum vertical angle in the packet, in rads
uint32_t	nPoints	Current number of valid points in the `pointsRTHI` and `pointsXYZI` arrays in the packet.
uint8_t	numReturns	Number of returns present in this packet
dwLidarPointRTHI const *	pointsRTHI	Pointer to the array of points in polar coordinates.
dwLidarPointXYZI const *	pointsXYZI	Pointer to the array of points in cartesian coordinates.
dwLidarDecodedReturn	returnData[DW_SENSORS_LIDAR_MAX_RETURNS]	An array contains data for each return in this packet
bool	scanComplete	Flag to identify if the scan is complete.
dwTime_t	sensorTimestamp	Timestamp of the first point in the point cloud packet, in microseconds.

◆ dwLidarDecodedReturn

struct dwLidarDecodedReturn

Data Fields
void const *	auxData[DW_LIDAR_AUX_DATA_TYPE_COUNT]	Array of pointers to auxiliary data Supported aux data types are listed in lidar properties. Size of auxiliary data element can be found in auxDataSize[] array below. Number of elements equals to numPoints
uint32_t	auxDataSize[DW_LIDAR_AUX_DATA_TYPE_COUNT]	Data element size for each type of aux data. 0 means this aux data type is not configured in lidarProperties.validAuxInfos
uint32_t	maxPoints	Maximum number of points in this return
uint32_t	numPoints	Current number of valid points in the return
dwLidarPointRTHI const *	pointsRTHI	Pointer to the array of points (polar)
dwLidarReturnType	type	Type of this return

◆ dwLidarPointRTHI

struct dwLidarPointRTHI

Data Fields
float32_t	intensity	Reflection intensity in the 0 to 1 range.
float32_t	phi	Lidar right-handed polar coord system, vertical direction, in rads unit.
float32_t	radius	Lidar right-handed polar coord system, distance, in m unit.
float32_t	theta	Lidar right-handed polar coord system, planar direction, in rads unit.

◆ dwLidarPointXYZI

struct dwLidarPointXYZI

Data Fields
float32_t	intensity	Reflection intensity in the 0 to 1 range.
float32_t	x	Lidar right-handed coord system, planar direction, in meters unit.
float32_t	y	Lidar right-handed coord system, planar direction, in meters unit.
float32_t	z	Lidar right-handed coord system, vertical direction, in meters unit.

◆ dwLidarProperties

struct dwLidarProperties

Data Fields
dwLidarReturnType	availableReturns	Bitmask of return types the lidar is configured to.
char8_t	deviceString[256]	ASCII string identifying the device.
float32_t	horizontalAngles[DW_SENSORS_LIDAR_MAX_ROWS]	Lidar right-handed polar coord system, intrinsic horizontal angle offsets in spin frame, in rads, length of array with valid values is defined by 'numberOfRows' above.
float32_t	horizontalFOVEnd	Lidar right-handed polar coord system, end angle in planar direction, in rads.
float32_t	horizontalFOVStart	Lidar right-handed polar coord system, start angle in planar direction, in rads.
size_t	lidarSSISizeInBytes	LidarSSI size in bytes, so user know the memory to be allocated for dwLidarDecodedPacket.lidarSSI.
uint32_t	numberOfRows	Number of Rows in a spin Frame
uint32_t	packetsPerSecond	Number of packets per second the sensor produces.
uint32_t	packetsPerSpin	Number of packets per sensor full spin.
uint32_t	pointsPerPacket	Maximum number of points in a packet.
uint32_t	pointsPerSecond	Number of points per second the sensor provides.
uint32_t	pointsPerSpin	Maximum number of points on a full sensor spin.
uint32_t	pointStride	Number of 'float32' elements between points and points which lidar send.
float32_t	spinFrequency	Current spin frequency, in HZ.
uint64_t	validAuxInfos	Bitmask of valid aux info fields based on enum dwLidarAuxDataType.
float32_t	verticalAngles[DW_SENSORS_LIDAR_MAX_ROWS]	Lidar right-handed polar coord system, vertical angles in spin frame, in rads, length of array with valid values is defined by 'numberOfRows' above.
float32_t	verticalFOVEnd	Lidar right-handed polar coord system, end angle in vertical direction, in rads.
float32_t	verticalFOVStart	Lidar right-handed polar coord system, start angle in vertical direction, in rads.

Macro Definition Documentation

◆ DW_SENSORS_LIDAR_MAX_RETURNS

#define DW_SENSORS_LIDAR_MAX_RETURNS 10

Maximum number of distinct lidar returns a point cloud can contain.

Definition at line 137 of file Lidar.h.

◆ DW_SENSORS_LIDAR_MAX_ROWS

#define DW_SENSORS_LIDAR_MAX_ROWS 256

maximal number of rows in dwLidarProperties

Definition at line 157 of file Lidar.h.

Typedef Documentation

◆ dwLidarDecodedSSI

typedef struct _dwLidarDecodedSSI dwLidarDecodedSSI

Not available as of current release. Will be added in future release.

Definition at line 228 of file Lidar.h.

Enumeration Type Documentation

◆ dwLidarAuxDataType

enum dwLidarAuxDataType

An enum for every data element we could possibly return.

Enumerator
DW_LIDAR_AUX_DATA_TYPE_SNR
DW_LIDAR_AUX_DATA_TYPE_PULSEWIDTH_PS
DW_LIDAR_AUX_DATA_TYPE_TIME
DW_LIDAR_AUX_DATA_TYPE_V_MPS
DW_LIDAR_AUX_DATA_TYPE_EXISTENCEPROB
DW_LIDAR_AUX_DATA_TYPE_CROSSTALKPROB
DW_LIDAR_AUX_DATA_TYPE_NOISELEVEL
DW_LIDAR_AUX_DATA_TYPE_ZONEID
DW_LIDAR_AUX_DATA_TYPE_DETECTORID
DW_LIDAR_AUX_DATA_TYPE_LINEID
DW_LIDAR_AUX_DATA_TYPE_DATAQUALITY
DW_LIDAR_AUX_DATA_TYPE_SCANCHECKPOINT
DW_LIDAR_AUX_DATA_TYPE_BLOCKAGEFLAG
DW_LIDAR_AUX_DATA_TYPE_SENSORID
DW_LIDAR_AUX_DATA_TYPE_AZIMUTH
DW_LIDAR_AUX_DATA_TYPE_ELEVATION
DW_LIDAR_AUX_DATA_TYPE_DISTANCE
DW_LIDAR_AUX_DATA_TYPE_ROI
DW_LIDAR_AUX_DATA_TYPE_VALIDITY
DW_LIDAR_AUX_DATA_TYPE_INVALIDITYFLAG
DW_LIDAR_AUX_DATA_TYPE_COUNT
DW_LIDAR_AUX_DATA_TYPE_FORCE32

Definition at line 87 of file Lidar.h.

◆ dwLidarInvalidityFlag

enum dwLidarInvalidityFlag

An enum for specifying invalidity flags.

Enumerator
DW_LIDAR_INVALIDITY_NONE	No flags are set.
DW_LIDAR_INVALIDITY_DW	DriveWorks-specific validity flags.
DW_LIDAR_INVALIDITY_VEND	Vendor-specific validity flags.
DW_LIDAR_INVALIDITY_BLOCKAGE	Blockage validity flags.
DW_LIDAR_INVALIDITY_INVALID	Point is not valid if any of flags are set.

Definition at line 115 of file Lidar.h.

◆ dwLidarReturnType

enum dwLidarReturnType

Enum to indicate a single return type.

Bitmasks of this enum can be used to specify return configurations of lidars, requested returns from the accumulator, or returns available in a point cloud

Enumerator
DW_LIDAR_RETURN_TYPE_ANY	API default for whatever returns happen to be present
DW_LIDAR_RETURN_TYPE_FIRST	First return
DW_LIDAR_RETURN_TYPE_LAST	Last return
DW_LIDAR_RETURN_TYPE_STRONGEST	Strongest return (vendor-specific)
DW_LIDAR_RETURN_TYPE_ABS_STRONGEST	Derived type: if multiple returns are present, whichever is strongest
DW_LIDAR_RETURN_TYPE_1	Generic enum to capture lidars for which an array of returns is present
DW_LIDAR_RETURN_TYPE_2	Generic enum to capture lidars for which an array of returns is present
DW_LIDAR_RETURN_TYPE_3	Generic enum to capture lidars for which an array of returns is present
DW_LIDAR_RETURN_TYPE_4	Generic enum to capture lidars for which an array of returns is present
DW_LIDAR_RETURN_TYPE_5	Generic enum to capture lidars for which an array of returns is present
DW_LIDAR_RETURN_TYPE_6	Generic enum to capture lidars for which an array of returns is present

Definition at line 66 of file Lidar.h.

Function Documentation

◆ dwSensorLidar_disableDecoding()

DW_API_PUBLIC dwStatus dwSensorLidar_disableDecoding ( dwSensorHandle_t const sensor )

Disable the decoding of the Lidar packets, which frees additional CPU load.

Method fails if the sensor has been started and is capturing data. Stop the sensor first. The default state is to have decoding on. If on, dwSensor_readRawData(see reference [15]) returns DW_CALL_NOT_ALLOWED.

Parameters

[in] sensor Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_INVALID_HANDLE	The input handle is not a lidar handle.
DW_CALL_NOT_ALLOWED	The sensor is not stopped.
DW_SUCCESS	Successful deal.

◆ dwSensorLidar_enableDecoding()

DW_API_PUBLIC dwStatus dwSensorLidar_enableDecoding ( dwSensorHandle_t const sensor )

Enables the decoding of the Lidar packets, which incurs an additional CPU load.

Method fails if the sensor has been started and is capturing data. Stop the sensor first. The default state is to have decoding on. If on, dwSensor_readRawData(see reference [15]) returns DW_CALL_NOT_ALLOWED.

Parameters

[in] sensor Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_INVALID_HANDLE	The input handle is not a lidar handle.
DW_CALL_NOT_ALLOWED	The sensor is not stopped.
DW_SUCCESS	Successful deal.

◆ dwSensorLidar_getAuxElementSize()

DW_API_PUBLIC dwStatus dwSensorLidar_getAuxElementSize	(	uint32_t *const	sizeBytes,
		dwLidarAuxDataType const	auxType
	)

Returns size of auxiliary data element in bytes.

Parameters

[out]	sizeBytes	element size
[in]	auxType	auxiliary data type

Return values

DW_INVALID_ARGUMENT	The input parameter is invalid.
DW_SUCCESS	Successful deal.

◆ dwSensorLidar_getProperties()

DW_API_PUBLIC dwStatus dwSensorLidar_getProperties	(	dwLidarProperties *const	lidarProperties,
		dwSensorHandle_t const	sensor
	)

Gets information about the Lidar sensor.

Parameters

[out]	lidarProperties	A pointer to the struct containing the properties of the Lidar.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_INVALID_HANDLE	the input handle is not a lidar handle.
DW_CALL_NOT_ALLOWED	config is not allowed to get in passive mode.
DW_SUCCESS	successful deal.

Note: Other return value will depend on the lidar type due to the reason that different type lidar will have different internal implements.

◆ dwSensorLidar_isDecodingEnabled()

DW_API_PUBLIC dwStatus dwSensorLidar_isDecodingEnabled	(	bool *const	enable,
		dwSensorHandle_t const	sensor
	)

Retrieves the state of packet decoding.

Parameters

[out]	enable	Contains the result of the query, which is true when decoding. False if RAW data.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_SUCCESS	Successful deal.
DW_INVALID_HANDLE	The input handle is not a lidar handle.

◆ dwSensorLidar_processRawData()

DW_API_PUBLIC dwStatus dwSensorLidar_processRawData	(	dwLidarDecodedPacket const **const	data,
		uint8_t const *const	rawData,
		size_t const	size,
		dwSensorHandle_t const	sensor
	)

Decodes RAW data previously read and returns a pointer to it.

This happens on the CPU thread where the function is called, incurring on additional load on that thread. The data is valid until the application calls dwSensor_returnRawData.

Parameters

[out]	data	A pointer to the memory pool owned by the sensor.
[in]	rawData	A pointer for the non-decoded Lidar packet, returned by 'dwSensor_readRawData(see reference [15])'.
[in]	size	Specifies the size in bytes of the raw data.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_INVALID_HANDLE	the input handle is not a lidar handle.
DW_CALL_NOT_ALLOWED	the decoder is not working.
DW_SUCCESS	successful deal.

Note: Other return value will depend on the lidar type due to the reason that different type lidar will have different internal implements.

◆ dwSensorLidar_readPacket()

DW_API_PUBLIC dwStatus dwSensorLidar_readPacket	(	dwLidarDecodedPacket const **const	data,
		dwTime_t const	timeoutUs,
		dwSensorHandle_t const	sensor
	)

Reads one scan packet.

The pointer returned is to the internal data pool. DW guarantees that the data remains constant until returned by the application. The data must be explicitly returned by the application.

Parameters

[out]	data	A pointer to a pointer that can read data from the sensor. The struct contains the numbers of points read, which depends on the sensor used.
[in]	timeoutUs	Specifies the timeout in microseconds. Special values: DW_TIMEOUT_INFINITE - to wait infinitly. Zero - means polling of internal queue.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_INVALID_HANDLE	the input handle is not a lidar handle.
DW_CALL_NOT_ALLOWED	the decoder is not working.
DW_INVALID_ARGUMENT	the input argument is invalid.
DW_NOT_AVAILABLE	device is disconneted or sensor is not working.
DW_TIME_OUT	timeout.
DW_SUCCESS	successful deal.

◆ dwSensorLidar_returnPacket()

DW_API_PUBLIC dwStatus dwSensorLidar_returnPacket	(	dwLidarDecodedPacket const *const	data,
		dwSensorHandle_t const	sensor
	)

Returns the data read to the internal pool.

At this point the pointer is still be valid, but data is change based on newer readings of the sensor.

Parameters

[in]	data	A pointer to the scan data previously read from the Lidar to be returned to the pool.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_INVALID_HANDLE	the input handle is not a lidar handle.
DW_CALL_NOT_ALLOWED	the decoder is not working.
DW_SUCCESS	successful deal.

Note: Other return value will depend on the lidar type due to the reason that different type lidar will have different internal implements.

◆ dwSensorLidar_sendMessage()

DW_API_PUBLIC dwStatus dwSensorLidar_sendMessage	(	uint32_t const	cmd,
		uint8_t const *const	data,
		size_t const	size,
		dwSensorHandle_t const	sensor
	)

Sends a message to Lidar sensor.

Parameters

[in]	cmd	Command identifier associated to the given message data.
[in]	data	A pointer to the message data.
[in]	size	Size in bytes of the `data`.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor(see reference [15])'.

Return values

DW_INVALID_HANDLE the input handle is not a lidar handle.

Note: Other return value will depend on the lidar type due to the reason that different type lidar will have different internal implements.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ dwLidarDecodedPacket

◆ dwLidarDecodedReturn

◆ dwLidarPointRTHI

◆ dwLidarPointXYZI

◆ dwLidarProperties

Macro Definition Documentation

◆ DW_SENSORS_LIDAR_MAX_RETURNS

◆ DW_SENSORS_LIDAR_MAX_ROWS

Typedef Documentation

◆ dwLidarDecodedSSI

Enumeration Type Documentation

◆ dwLidarAuxDataType

◆ dwLidarInvalidityFlag

◆ dwLidarReturnType

Function Documentation

◆ dwSensorLidar_disableDecoding()

◆ dwSensorLidar_enableDecoding()

◆ dwSensorLidar_getAuxElementSize()

◆ dwSensorLidar_getProperties()

◆ dwSensorLidar_isDecodingEnabled()

◆ dwSensorLidar_processRawData()

◆ dwSensorLidar_readPacket()

◆ dwSensorLidar_returnPacket()

◆ dwSensorLidar_sendMessage()