GPS Sensor API

Detailed Description

Defines A API for the GPSsensor.

Functions
DW_API_PUBLIC dwStatus	dwSensorGPS_readFrame (dwGPSFrame *const frame, dwTime_t const timeoutUs, dwSensorHandle_t const sensor)
	Reads the next available GPS data frame with a given timeout. More...
DW_API_PUBLIC dwStatus	dwSensorGPS_processRawData (uint8_t const *const data, size_t const size, dwSensorHandle_t const sensor)
	Decodes RAW data previously read. More...
DW_API_PUBLIC dwStatus	dwSensorGPS_popFrame (dwGPSFrame *const frame, dwSensorHandle_t const sensor)
	Returns any GPS frame previously processed through RAW data stream. More...

Function Documentation

dwSensorGPS_popFrame()

DW_API_PUBLIC dwStatus dwSensorGPS_popFrame	(	dwGPSFrame *const	frame,
		dwSensorHandle_t const	sensor
	)

Returns any GPS frame previously processed through RAW data stream.

This happens on the CPU thread where the function is called, incurring an additional load on that thread.

This function returns only the first single decoded GPS frame from cached GPS frames(and removes it from cache). If no frames are available in queue, DW_NOT_AVAILABLE is returned and no GPS frame is returned.

This function should only be called after sensor is started. From above descriptions, this function requires previous callings to function dwSensorGPS_readFrame or dwSensorGPS_processRawData returns success otherwise this function will return DW_NOT_AVAILABLE.

This function is a synchronous function. Customers have to wait till the polling of GPS frame queue is finished.

Parameters

[out]	frame	Pointer to an GPS frame structure to be filled with new data.
[in]	sensor	Sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns

DW_INVALID_HANDLE - if given sensor handle is invalid. Only handles returned by dwSAL_createSensor with GPS sensor protocols are allowed.
DW_INVALID_ARGUMENTS - if given arguments are invalid. Here it means input pointer 'frame' is empty
DW_NOT_AVAILABLE - if no more data is available
DW_SUCCESS - An GPS frame is dequeued from internal GPS frame queue into frame

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwSensorGPS_processRawData()

DW_API_PUBLIC dwStatus dwSensorGPS_processRawData	(	uint8_t const *const	data,
		size_t const	size,
		dwSensorHandle_t const	sensor
	)

Decodes RAW data previously read.

Any processed messages can be picked up using the dwSensorGPS_popMessage() method. This happens on the CPU thread where the function is called, incurring on additional load on that thread.

This API function will achieve functionality of this software unit:

• Decode GPS sensor packets into GPS frames and cache decoded GPS frames

This API function will push specified GPS sensor packet into its internal GPS decoders. Since internal GPS decoder will return once an GPS frame is decoded, or no GPS frames could be decoded from remaining bytes from specified GPS sensor packet, thus this API function will keep driving the decoder to return as many GPS frames as possible, until decoder could return no new GPS frames. All decoded GPS frames are cached internally and could be accessed by dwSensorGPS_readFrame() or dwSensorGPS_popFrame(). Based on sensor configuration value 'output-timestamp=', decoded GPS frames would be modified in their hostTimestamp field values accordingly.

See also

https://developer.nvidia.com/docs/drive/drive-os/6.0.8.1/public/driveworks-nvsdk/nvsdk_dw_html/sensors_usecase4.html for description of available option values for 'output-timestamp=' sensor parameter.

This function should only be called after sensor is started, and with raw GPS sensor packet(s) returned from dwSensor_readRawData. After this raw sensor packet is processed by this function, user should also call dwSensor_returnRawData to return the memory block to SAL.

This function is a synchronous function. Customers have to wait till the raw GPS sensor data is processed.

Parameters

[in]	data	Undecoded gps data.
[in]	size	Size in bytes of the raw data.
[in]	sensor	Sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns

DW_INVALID_HANDLE - if given sensor handle is invalid. Only handles returned by dwSAL_createSensor with GPS sensor protocols are allowed.
DW_INVALID_ARGUMENTS - if given arguments are invalid, Here it means input pointer 'data' is empty
DW_NOT_READY - if more data needs to be passed in (loop while it returns 'DW_NOT_READY').
DW_SUCCESS - specified raw GPS sensor packet was decoded into one or more GPS frames. Please read decoded GPS frames via dwSensorGPS_readFrame or dwSensorGPS_popFrame

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwSensorGPS_readFrame()

DW_API_PUBLIC dwStatus dwSensorGPS_readFrame	(	dwGPSFrame *const	frame,
		dwTime_t const	timeoutUs,
		dwSensorHandle_t const	sensor
	)

Reads the next available GPS data frame with a given timeout.

The method blocks until either a new valid frame is received from the sensor or the given timeout exceeds. Frames read from the sensor do not have to be returned because the messages are copied.

This API function will achieve two functionalities of this software unit:

• Read a GPS sensor packet from physical GPS sensor
• Decode this GPS sensor packet and add cache decoded GPS frames

This API function will firstly check if there are already decoded GPS frames available, if there are decoded GPS frames then this API function returns the first decoded GPS frame then return; otherwise it will read GPS sensor packet then decode it and return first decoded GPS frames, or return DW_TIME_OUT if no GPS frames could be decoded till timeout is detected.

This function is only used after the GPS sensor is initialized and started successfully.

Parameters

[out]	frame	A pointer to a GPS frame structure to be filled with new localization data.
[in]	timeoutUs	Specify the timeout in us to wait for a new message. Special values: DW_TIMEOUT_INFINITE - to wait infinitly. Zero - mean polling of internal queue. - if there are already decoded GPS frames, return first frame immediately; otherwise return DW_TIME_OUT directly.
[in]	sensor	Specify the sensor handle of the GPS sensor previously created with 'dwSAL_createSensor()'.

Returns

DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENTS - if the internal member m_decoder of GPS object is equal to nullptr.
DW_TIME_OUT - if operation has timeout.
DW_NOT_AVAILABLE - if sensor has not been started or data is not available in polling mode.
DW_END_OF_STREAM - if end of stream reached (virtual sensor only).
DW_SAL_SENSOR_ERROR - if there was an i/o or bus error.
DW_SUCCESS - if read frame successful.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

Note

This function will block until a frame is decoded or timeout is detected, if timeoutUs is specified as non-zero values.

If no valid GPS packets could be returned from physical GPS sensors(for Vehicle GPS sensors, this means either all received GPS packets have wrong packet size. or no GPS packets are received at all) till timeout, no GPS frames could be decoded.