Introduction

The positioning component is used for representing and manipulating position-related data, plus it provides IMU drivers and interface code for working with NovAtel and VectorNav INS/IMU solutions. Position-related data uses the WGS-84 reference ellipsoid.

Collaboration diagram for PTK Positioning Component:

Sub Modules
	PTK Position

Data Structures
struct	PTK_INS_Velocity
	Velocity. More...

struct	PTK_INS_Attitude
	Attitude. More...

struct	PTK_INS_InsPva
	Ins Position, Velocity, and Attitude information. More...

struct	PTK_INS_MsgInscov
	Covariance record definition. More...

union	PTK_INS_RecordData
	Data type indicator. More...

struct	PTK_INS_Record
	INS record. More...

Functions
void	PTK_INS_initializeBuffers ()
	Initialize internal storage structures. This must be called once during startup to configure the INS software subsystem for use. More...

void	PTK_INS_resetBuffers ()
	Reset the internal storage structures. This can be called anytime after the initial initialization. More...

PTK_INS_RetCode	PTK_INS_getCurrentRecord (PTK_INS_RecordType type, PTK_INS_Record *dst)
	Copy the most recently written record of the specified type into the record struct. More...

PTK_INS_RetCode	PTK_INS_getRecordBefore (PTK_INS_RecordType type, uint64_t timestamp, PTK_INS_Record *dst)
	Copy the first record before the given timestamp into the given struct. More...

PTK_INS_RetCode	PTK_INS_getRecordAfter (PTK_INS_RecordType type, uint64_t timestamp, PTK_INS_Record *dst)
	Copy the first record after or equal to the given timestamp into the given struct. More...

PTK_INS_RetCode	PTK_INS_getRecordLinearInterp (PTK_INS_RecordType type, uint64_t timestamp, PTK_INS_Record *dst)
	Interpolate between the two records surrounding the given time stamp and store the computed INS information in the given struct. More...

PTK_INS_RetCode	PTK_INS_getIMUtoENU (const PTK_INS_Record imu, PTK_RigidTransform M_enu_imu)
	Compute the transformation between the IMU-based coordinate system (sometimes called ego coordinates) and the ENU frame defined at the specified position. The resulting transformation is only a rotation. More...

PTK_INS_RetCode	PTK_INS_getReferenceFrame (PTK_RigidTransform_d M_ecef_ref, PTK_Position ref)
	Get the current reference frame (coordinate system) w.r.t ECEF. The first call to this function sets the reference frame to the current INS position oriented as ENU. Subsequent calls simply return this reference frame. More...

void	PTK_INS_clearReferenceFrame ()
	Clears the pointer to the frame previously marked as reference. More...

PTK_INS_Record *	PTK_INS_getNextRecord (PTK_INS_RecordType type)
	This gets a writeable pointer to the next data record in our buffer. More...

void	PTK_INS_publishRecord (PTK_INS_RecordType type)
	This "publishes" the current data record to the database, advancing the write pointer and allowing read access to the record it was just on. More...

PTK_INS_RetCode	PTK_INS_Novatel_checkArchitecture ()
	Perform architecture and alignment checks that we assume are true for the rest of the IMU parsing library and return a status code indicating whether those checks were passed. This should be called at startup during development to detect any problems caused by compiler or achitecture that may affect correct behavior. More...

void	PTK_INS_Novatel_parseINSPVA (uint8_t pRawMessage, uint64_t timestamp, PTK_INS_Record insRec)
	Read data out of a INSPVA message, which contains all of our position and velocity information. This assumes that the packet given is an INSPVA packet, otherwise the behavior is undefined. More...

PTK_INS_RetCode	PTK_INS_Novatel_processMessage (uint8_t *pRawMessage, uint64_t timestamp)
	Process the given message and write it to the internal storage structure where it will be accessible to the generic INS interface API. More...

Enumerations
enum	PTK_INS_RecordType { PTK_INS_RECORD_TYPE_INSPVA = 0, PTK_INS_RECORD_TYPE_INSCOV, PTK_INS_RECORD_TYPE_MAX }
	INS record type enumeration. More...

enum	PTK_INS_RetCode { PTK_INS_RETURN_CODE_OK = 0, PTK_INS_RETURN_CODE_RECORD_PARTIALLY_AVAIL, PTK_INS_RETURN_CODE_RECORD_UNAVAIL, PTK_INS_RETURN_CODE_ILLEGAL_ARGIN, PTK_INS_RETURN_CODE_INVALID_RECORD_TYPE, PTK_INS_RETURN_CODE_UNEXPECTED_BEHAVIOR }
	Error code enumeration. More...

enum	PTK_INS_SolStatus { PTK_INS_SOL_STATUS_GOOD = 0, PTK_INS_SOL_STATUS_NOT_GOOD, PTK_INS_SOL_STATUS_UNAVAILABLE }
	INS reported status code enumeration. More...

Enumeration Type Documentation

◆ PTK_INS_RecordType

enum PTK_INS_RecordType

INS record type enumeration.

Enumerator
PTK_INS_RECORD_TYPE_INSPVA	INS-computed position, velocity, and attitude information.
PTK_INS_RECORD_TYPE_INSCOV	covariance information for position, velocity, and attitude records.
PTK_INS_RECORD_TYPE_MAX	Tag to detect maximum allowed enumeration.

◆ PTK_INS_RetCode

enum PTK_INS_RetCode

Error code enumeration.

Enumerator
PTK_INS_RETURN_CODE_OK	The requested record was retrieved without issue.
PTK_INS_RETURN_CODE_RECORD_PARTIALLY_AVAIL	The requested record was not completely available but a similar record was provided instead.
PTK_INS_RETURN_CODE_RECORD_UNAVAIL	The requested record was not available and nothing was retrieved.
PTK_INS_RETURN_CODE_ILLEGAL_ARGIN	Invalid arguments were provided as part of the request for an IMU record.
PTK_INS_RETURN_CODE_INVALID_RECORD_TYPE	Invalid record type requested.
PTK_INS_RETURN_CODE_UNEXPECTED_BEHAVIOR	An undefined failure happened. This should not be observed but may indicate hardware or other problems.

◆ PTK_INS_SolStatus

enum PTK_INS_SolStatus

INS reported status code enumeration.

Enumerator
PTK_INS_SOL_STATUS_GOOD	INS solution was computed accurately, according to the sensor.
PTK_INS_SOL_STATUS_NOT_GOOD	INS solution may be inaccurate, according to sensor, for any reason.
PTK_INS_SOL_STATUS_UNAVAILABLE	INS solution is incorrect or may simply be dummy data reported by the driver, according to the sensor.

Function Documentation

◆ PTK_INS_initializeBuffers()

void PTK_INS_initializeBuffers ( )

Initialize internal storage structures. This must be called once during startup to configure the INS software subsystem for use.

This is independent from the driver initialization or the general PTK initialization.

◆ PTK_INS_resetBuffers()

void PTK_INS_resetBuffers ( )

Reset the internal storage structures. This can be called anytime after the initial initialization.

This resets the internal read/write pointers.

◆ PTK_INS_getCurrentRecord()

PTK_INS_RetCode PTK_INS_getCurrentRecord	(	PTK_INS_RecordType	type,
		PTK_INS_Record *	dst
	)

Copy the most recently written record of the specified type into the record struct.

Parameters

[in]	type	The type of record to retrieve.
[out]	dst	The record is copied to this struct.

Returns

PTK_INS_RETURN_CODE_OK, if record found
PTK_INS_RETURN_CODE_RECORD_UNAVAIL, no data has been written yet

◆ PTK_INS_getRecordBefore()

PTK_INS_RetCode PTK_INS_getRecordBefore	(	PTK_INS_RecordType	type,
		uint64_t	timestamp,
		PTK_INS_Record *	dst
	)

Copy the first record before the given timestamp into the given struct.

Parameters

[in]	type	The type of record to retrieve.
[in]	timestamp	The timestamp to look for.
[out]	dst	The record is copied to this struct.

Returns

PTK_INS_RETURN_CODE_OK, if record found
PTK_INS_RETURN_CODE_RECORD_UNAVAIL, otherwise

◆ PTK_INS_getRecordAfter()

PTK_INS_RetCode PTK_INS_getRecordAfter	(	PTK_INS_RecordType	type,
		uint64_t	timestamp,
		PTK_INS_Record *	dst
	)

Copy the first record after or equal to the given timestamp into the given struct.

Parameters

[in]	type	The type of record to retrieve.
[in]	timestamp	The timestamp to look for.
[out]	dst	The record is copied to this struct.

Returns

PTK_INS_RETURN_CODE_OK, if record found
PTK_INS_RETURN_CODE_RECORD_UNAVAIL, otherwise

◆ PTK_INS_getRecordLinearInterp()

PTK_INS_RetCode PTK_INS_getRecordLinearInterp	(	PTK_INS_RecordType	type,
		uint64_t	timestamp,
		PTK_INS_Record *	dst
	)

Interpolate between the two records surrounding the given time stamp and store the computed INS information in the given struct.

If only one of the two records surrounding the given timestamp is available, it will be copied exactly and PTK_INS_RETURN_CODE_RECORD_PARTIALLY_AVAIL will be returned.

If both the records are available PTK_INS_RETURN_CODE_OK will be returned.

If no records are avilable then PTK_INS_RETURN_CODE_RECORD_UNAVAIL will be returned.

Parameters

[in]	type	The type of record to retrieve.
[in]	timestamp	The timestamp to look for
[out]	dst	The record is copied to this struct.

Returns

PTK_INS_RETURN_CODE_OK
PTK_INS_RETURN_CODE_RECORD_PARTIALLY_AVAIL
PTK_INS_RETURN_CODE_RECORD_UNAVAIL

◆ PTK_INS_getIMUtoENU()

PTK_INS_RetCode PTK_INS_getIMUtoENU	(	const PTK_INS_Record *	imu,
		PTK_RigidTransform *	M_enu_imu
	)

Compute the transformation between the IMU-based coordinate system (sometimes called ego coordinates) and the ENU frame defined at the specified position. The resulting transformation is only a rotation.

Parameters

[in]	imu	INS record defining the ENU coordinate system. The type of the record must be PTK_INS_RECORD_TYPE_INSPVA.
[out]	M_enu_imu	The IMU to ENU coordinate transformation is written here.

Returns

PTK_INS_RETURN_CODE_OK
PTK_INS_RETURN_CODE_INVALID_RECORD_TYPE

◆ PTK_INS_getReferenceFrame()

PTK_INS_RetCode PTK_INS_getReferenceFrame	(	PTK_RigidTransform_d *	M_ecef_ref,
		PTK_Position *	ref
	)

Get the current reference frame (coordinate system) w.r.t ECEF. The first call to this function sets the reference frame to the current INS position oriented as ENU. Subsequent calls simply return this reference frame.

The reference frame can be cleared using PTK_INS_clearReferenceFrame()

Parameters

[out]	M_ecef_ref	Reference frame.
[out]	ref	Position information from the reference record.

Returns

PTK_INS_RETURN_CODE_OK if reference frame is available
PTK_INS_RETURN_CODE_RECORD_UNAVAIL, otherwise

◆ PTK_INS_clearReferenceFrame()

void PTK_INS_clearReferenceFrame ( )

Clears the pointer to the frame previously marked as reference.

◆ PTK_INS_getNextRecord()

PTK_INS_Record* PTK_INS_getNextRecord ( PTK_INS_RecordType type )

This gets a writeable pointer to the next data record in our buffer.

Parameters

[in] type

Returns

Pointer to data structure to write to, if successful.
NULL, otherwise

◆ PTK_INS_publishRecord()

void PTK_INS_publishRecord ( PTK_INS_RecordType type )

This "publishes" the current data record to the database, advancing the write pointer and allowing read access to the record it was just on.

Parameters

[in] type

◆ PTK_INS_Novatel_checkArchitecture()

PTK_INS_RetCode PTK_INS_Novatel_checkArchitecture ( )

Perform architecture and alignment checks that we assume are true for the rest of the IMU parsing library and return a status code indicating whether those checks were passed. This should be called at startup during development to detect any problems caused by compiler or achitecture that may affect correct behavior.

Returns

PTK_INS_RETURN_CODE_OK, if the check is successful
PTK_INS_RETURN_CODE_UNEXPECTED_BEHAVIOR, otherwise

◆ PTK_INS_Novatel_parseINSPVA()

void PTK_INS_Novatel_parseINSPVA	(	uint8_t *	pRawMessage,
		uint64_t	timestamp,
		PTK_INS_Record *	insRec
	)

Read data out of a INSPVA message, which contains all of our position and velocity information. This assumes that the packet given is an INSPVA packet, otherwise the behavior is undefined.

Parameters

[in]	pRawMessage	Pointer to message data received from the INS.
[in]	timestamp	Timestamp to tag the data with internally.
[out]	insRec	Decoded INSPVA record.

◆ PTK_INS_Novatel_processMessage()

PTK_INS_RetCode PTK_INS_Novatel_processMessage	(	uint8_t *	pRawMessage,
		uint64_t	timestamp
	)

Process the given message and write it to the internal storage structure where it will be accessible to the generic INS interface API.

Parameters

[in]	pRawMessage	Pointer to message data received from the INS.
[in]	timestamp	Timestamp to tag the data with internally.

Returns

PTK_INS_RETURN_CODE_OK, if successful
PTK_INS_RETURN_CODE_ILLEGAL_ARGIN, otherwise

Introduction

Sub Modules

Data Structures

Functions

Enumerations

Enumeration Type Documentation

◆ PTK_INS_RecordType

◆ PTK_INS_RetCode

◆ PTK_INS_SolStatus

Function Documentation

◆ PTK_INS_initializeBuffers()

◆ PTK_INS_resetBuffers()

◆ PTK_INS_getCurrentRecord()

◆ PTK_INS_getRecordBefore()

◆ PTK_INS_getRecordAfter()

◆ PTK_INS_getRecordLinearInterp()

◆ PTK_INS_getIMUtoENU()

◆ PTK_INS_getReferenceFrame()

◆ PTK_INS_clearReferenceFrame()

◆ PTK_INS_getNextRecord()

◆ PTK_INS_publishRecord()

◆ PTK_INS_Novatel_checkArchitecture()

◆ PTK_INS_Novatel_parseINSPVA()

◆ PTK_INS_Novatel_processMessage()