GPS Sensor

Detailed Description

Defines the GPS sensor.

Data Structures
struct	dwGPSFrameNew
	This structure contains one frame of data from an GPS/GNSS sensor. More...

Functions
DW_API_PUBLIC dwStatus	dwSensorGPS_popFrame (dwGPSFrame *const frame, dwSensorHandle_t const sensor)
	Returns any GPS frame previously processed through RAW data stream. More...
DW_API_PUBLIC dwStatus	dwSensorGPS_popFrameNew (dwGPSFrameNew *const frame, dwSensorHandle_t const sensor)
	Returns any GPS frame New previously processed through RAW data stream. 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_processRawDataNew (uint8_t const *const data, size_t const size, dwSensorHandle_t const sensor)
	Decodes RAW data previously read. More...
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_readFrameNew (dwGPSFrameNew *const frame, dwTime_t const timeoutUs, dwSensorHandle_t const sensor)
	Reads the next GPS packet with a given timeout. More...

---

Data Structure Documentation

dwGPSFrameNew

struct dwGPSFrameNew

Data Fields
float64_t	altitude	Note ID VS-91040 description Altitude over WGS-84 ellipsoid. min nan max nan freq 4 unit m
float64_t	climb	Note ID VS-91070 description Vertical speed. min nan max nan freq 4 unit m/s
float64_t	course	Note ID VS-91050 description Course relative to true north. min nan max nan freq 4 unit deg
dwGPSFixStatus	fixStatus	Note ID VS-91150 description 2D or 3D fix. TODO: Backend not yet implemented min nan max nan freq 4 unit unitless *** valid values**: { DW_GPS_FIX_STATUS_NO_FIX, DW_GPS_FIX_STATUS_2D_FIX, DW_GPS_FIX_STATUS_3D_FIX }
float64_t	hacc	Note ID VS-91110 description Horizontal Accuracy of Solution. min nan max nan freq 4 unit m
float64_t	hdop	Note ID VS-91080 description Horizontal Dilution of Precision. min nan max nan freq 4 unit unitless
float64_t	latitude	Note ID VS-91020 description Latitude in WGS-84. min nan max nan freq 4 unit deg
float64_t	longitude	Note ID VS-91030 description Longitude in WGS-84. min nan max nan freq 4 unit deg
dwGPSMode	mode	Note ID VS-91175 description GPS mode. TODO: Backend not yet implemented min nan max nan freq 4 unit unitless *** valid values**: { DW_GPS_MODE_UNKNOWN, DW_GPS_MODE_INVALID_GPS, DW_GPS_MODE_DEAD_RECKONING, DW_GPS_MODE_STAND_ALONE, DW_GPS_MODE_PRECISE_POINT, DW_GPS_MODE_CODE_DIFFERENTIAL, DW_GPS_MODE_RTK_FLOAT, DW_GPS_MODE_RTK_FIXED, DW_GPS_MODE_PPP_CONVERGING, DW_GPS_MODE_PPP_CONVERGED }
float64_t	pdop	Note ID VS-91100 description Position Dilution of Precision. min nan max nan freq 4 unit unitless
uint8_t	reserved[508]	Reserved space.
uint8_t	satelliteCount	Note ID VS-91140 description Number of satellites in view. TODO: Backend not yet implemented min nan max nan freq 4 unit unitless
float64_t	speed	Note ID VS-91060 description Horizontal speed. min nan max nan freq 4 unit m/s
dwTime_t	timestamp_us	Note ID VS-91010 description Timestamp of the message when first received. min nan max nan freq 4 unit us
dwGPSTimestampQuality	timestampQuality	Note ID VS-91170 description GNSS Timestamp Quality. TODO: Backend not yet implemented min nan max nan freq 4 unit unitless *** valid values**: { DW_GPS_TIMESTAMP_QUALITY_NOT_INIT, DW_GPS_TIMESTAMP_QUALITY_OK, DW_GPS_TIMESTAMP_QUALITY_SYNC_LOST, }
dwTime_t	utcTime	Note ID VS-91130 description UTC time. min nan max nan freq 4 unit us
float64_t	vacc	Note ID VS-91120 description Vertical Accuracy of Solution. min nan max nan freq 4 unit m
dwGPSSignalValidityInfo	validityInfo	Signal validity information.
float64_t	vdop	Note ID VS-91090 description Vertical Dilution of Precision. min nan max nan freq 4 unit unitless

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_popFrameNew()

DW_API_PUBLIC dwStatus dwSensorGPS_popFrameNew	(	dwGPSFrameNew *const	frame,
		dwSensorHandle_t const	sensor
	)

Returns any GPS frame New previously processed through RAW data stream.

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

Parameters

[out]	frame	Pointer to an GPS frame New 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.
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 - if the procedure is done successfully.

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

http://www.open-lab.net/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_processRawDataNew()

DW_API_PUBLIC dwStatus dwSensorGPS_processRawDataNew	(	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_popMessageNew() method. This happens on the CPU thread where the function is called, incurring on additional load on that thread.

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,
DW_INVALID_ARGUMENTS - if the member m_decoder of GPS object is not initialized correctly or equal to nullptr,
DW_NOT_READY - if more data needs to be passed in (loop while it returns 'DW_NOT_READY').
DW_SUCCESS - if the procedure is done successfully.

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.

dwSensorGPS_readFrameNew()

DW_API_PUBLIC dwStatus dwSensorGPS_readFrameNew	(	dwGPSFrameNew *const	frame,
		dwTime_t const	timeoutUs,
		dwSensorHandle_t const	sensor
	)

Reads the next GPS packet with a given timeout.

The method blocks until either a new valid frame is received from the sensor or the given timeout exceeds.

Parameters

[out]	frame	A pointer to a GPS frame New 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 - means polling of internal queue.
[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 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 - the procedure is done successfully.

API Group

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