le_gnss_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

Macros
#define	LE_GNSS_MAX_SUPL_SERVER_URL_LEN   256
#define	LE_GNSS_MAX_SUPL_CERTIFICATE_LEN   2000
#define	LE_GNSS_MAX_SV_INFO_NUMBER   80

Typedefs
typedef struct le_gnss_Sample *	le_gnss_SampleRef_t
typedef struct le_gnss_PositionHandler *	le_gnss_PositionHandlerRef_t
typedef void(*	le_gnss_PositionHandlerFunc_t) (le_gnss_SampleRef_t positionSampleRef, void *contextPtr)

Enumerations
enum	le_gnss_FixState_t { LE_GNSS_STATE_FIX_NO_POS, LE_GNSS_STATE_FIX_2D, LE_GNSS_STATE_FIX_3D, LE_GNSS_STATE_FIX_ESTIMATED }
enum	le_gnss_AssistedMode_t { LE_GNSS_STANDALONE_MODE, LE_GNSS_MS_BASED_MODE, LE_GNSS_MS_ASSISTED_MODE }
enum	le_gnss_ConstellationBitMask_t { LE_GNSS_CONSTELLATION_GPS = 0x1, LE_GNSS_CONSTELLATION_GLONASS = 0x2 }

Functions
void	le_gnss_ConnectService (void)
void	le_gnss_DisconnectService (void)
le_result_t	le_gnss_SetConstellation (le_gnss_ConstellationBitMask_t constellationMask)
le_result_t	le_gnss_GetConstellation (le_gnss_ConstellationBitMask_t *constellationMaskPtr)
le_result_t	le_gnss_EnableExtendedEphemerisFile (void)
le_result_t	le_gnss_DisableExtendedEphemerisFile (void)
le_result_t	le_gnss_LoadExtendedEphemerisFile (int fd)
le_result_t	le_gnss_GetExtendedEphemerisValidity (le_clk_Time_t *startTimePtr, le_clk_Time_t *stopTimePtr)
le_result_t	le_gnss_Start (void)
le_result_t	le_gnss_Stop (void)
le_result_t	le_gnss_ForceHotRestart (void)
le_result_t	le_gnss_ForceWarmRestart (void)
le_result_t	le_gnss_ForceColdRestart (void)
le_result_t	le_gnss_ForceFactoryRestart (void)
le_result_t	le_gnss_GetTtff (uint32_t *ttffPtr)
le_result_t	le_gnss_Enable (void)
le_result_t	le_gnss_Disable (void)
le_result_t	le_gnss_SetAcquisitionRate (uint32_t rate)
le_result_t	le_gnss_GetAcquisitionRate (uint32_t *ratePtr)
le_gnss_PositionHandlerRef_t	le_gnss_AddPositionHandler (le_gnss_PositionHandlerFunc_t handlerPtr, void *contextPtr)
void	le_gnss_RemovePositionHandler (le_gnss_PositionHandlerRef_t addHandlerRef)
le_result_t	le_gnss_GetPositionState (le_gnss_SampleRef_t positionSampleRef, le_gnss_FixState_t *statePtr)
le_result_t	le_gnss_GetLocation (le_gnss_SampleRef_t positionSampleRef, int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr)
le_result_t	le_gnss_GetAltitude (le_gnss_SampleRef_t positionSampleRef, int32_t *altitudePtr, int32_t *vAccuracyPtr)
le_result_t	le_gnss_GetTime (le_gnss_SampleRef_t positionSampleRef, uint16_t *hoursPtr, uint16_t *minutesPtr, uint16_t *secondsPtr, uint16_t *millisecondsPtr)
le_result_t	le_gnss_GetDate (le_gnss_SampleRef_t positionSampleRef, uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
le_result_t	le_gnss_GetHorizontalSpeed (le_gnss_SampleRef_t positionSampleRef, uint32_t *hspeedPtr, uint32_t *hspeedAccuracyPtr)
le_result_t	le_gnss_GetVerticalSpeed (le_gnss_SampleRef_t positionSampleRef, int32_t *vspeedPtr, int32_t *vspeedAccuracyPtr)
le_result_t	le_gnss_GetDirection (le_gnss_SampleRef_t positionSampleRef, int32_t *directionPtr, int32_t *directionAccuracyPtr)
le_result_t	le_gnss_GetDop (le_gnss_SampleRef_t positionSampleRef, uint16_t *hdopPtr, uint16_t *vdopPtr, uint16_t *pdopPtr)
void	le_gnss_ReleaseSampleRef (le_gnss_SampleRef_t positionSampleRef)
le_result_t	le_gnss_SetSuplAssistedMode (le_gnss_AssistedMode_t assistedMode)
le_result_t	le_gnss_GetSuplAssistedMode (le_gnss_AssistedMode_t *assistedModePtr)
le_result_t	le_gnss_SetSuplServerUrl (const char *suplServerUrl)
le_result_t	le_gnss_InjectSuplCertificate (uint8_t suplCertificateId, uint16_t suplCertificateLen, const char *suplCertificate)
le_result_t	le_gnss_DeleteSuplCertificate (uint8_t suplCertificateId)

Detailed Description

Legato GNSS include file.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

Macro Definition Documentation

#define LE_GNSS_MAX_SUPL_CERTIFICATE_LEN   2000

Maximum SUPL certificate size.

#define LE_GNSS_MAX_SUPL_SERVER_URL_LEN   256

Maximum length of the SUP Server URL string.

#define LE_GNSS_MAX_SV_INFO_NUMBER   80

Define the maximum length of the Satellites Vehicle information list

Typedef Documentation

typedef void(* le_gnss_PositionHandlerFunc_t) (le_gnss_SampleRef_t positionSampleRef, void *contextPtr)

Handler for position information.

Parameters

positionSampleRef	Position's sample reference
contextPtr

typedef struct le_gnss_PositionHandler* le_gnss_PositionHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_gnss_Position'

typedef struct le_gnss_Sample* le_gnss_SampleRef_t

Reference type for dealing with GNSS position samples.

Enumeration Type Documentation

enum le_gnss_AssistedMode_t

Assisted-GNSS mode

Enumerator
LE_GNSS_STANDALONE_MODE	Standalone mode.
LE_GNSS_MS_BASED_MODE	MS-Based mode.
LE_GNSS_MS_ASSISTED_MODE	MS-Assisted mode.

enum le_gnss_ConstellationBitMask_t

GNSS constellation Bit Mask (8 bits) indicating the GNSS constellation(s) used in solution.

Enumerator
LE_GNSS_CONSTELLATION_GPS	GPS constellation used in solution.
LE_GNSS_CONSTELLATION_GLONASS	GLONASS constellation used in solution.

enum le_gnss_FixState_t

GNSS fix position states.

Enumerator
LE_GNSS_STATE_FIX_NO_POS	The GNSS fix position is not fixed.
LE_GNSS_STATE_FIX_2D	2-Dimensional position fix.
LE_GNSS_STATE_FIX_3D	3-Dimensional position fix.
LE_GNSS_STATE_FIX_ESTIMATED	Estimated (i.e. forward predicted) position fix.

Function Documentation

le_gnss_PositionHandlerRef_t le_gnss_AddPositionHandler	(	le_gnss_PositionHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

Add handler function for EVENT 'le_gnss_Position'

This event provides information on position.

• A handler reference, which is only needed for later removal of the handler.

Note

Doesn't return on failure, so there's no need to check the return value for errors.

Parameters

[in]	handlerPtr
[in]	contextPtr

void le_gnss_ConnectService

(

void

)

Connect the current client thread to the service providing this API.

This function must be called before any other functions in this API. Normally, it's automatically called for the main thread, but must be explicitly called for other threads. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_gnss_DeleteSuplCertificate

(

uint8_t

suplCertificateId

)

This function deletes the SUPL certificate.

Returns

• LE_OK on success
• LE_FAULT on failure
• LE_BUSY service is busy
• LE_TIMEOUT a time-out occurred

Parameters

[in]

suplCertificateId

Certificate ID of the SUPL certificate. Certificate ID range is 0 to 9

le_result_t le_gnss_Disable

(

void

)

This function disables the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_DUPLICATE If the GNSS device is already disabled.
• LE_NOT_PERMITTED If the GNSS device is not initialized or started.
• LE_OK The function succeeded.

le_result_t le_gnss_DisableExtendedEphemerisFile

(

void

)

This function disables the use of the 'Extended Ephemeris' file into the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_OK The function succeeded.

void le_gnss_DisconnectService

(

void

)

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_gnss_Enable

(

void

)

This function enables the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_DUPLICATE If the GNSS device is already enabled.
• LE_NOT_PERMITTED If the GNSS device is not initialized.
• LE_OK The function succeeded.

le_result_t le_gnss_EnableExtendedEphemerisFile

(

void

)

This function enables the use of the 'Extended Ephemeris' file into the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_OK The function succeeded.

le_result_t le_gnss_ForceColdRestart

(

void

)

This function performs a "COLD" restart of the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
• LE_OK The function succeeded.

le_result_t le_gnss_ForceFactoryRestart

(

void

)

This function performs a "FACTORY" restart of the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
• LE_OK The function succeeded.

le_result_t le_gnss_ForceHotRestart

(

void

)

This function performs a "HOT" restart of the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
• LE_OK The function succeeded.

le_result_t le_gnss_ForceWarmRestart

(

void

)

This function performs a "WARM" restart of the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
• LE_OK The function succeeded.

le_result_t le_gnss_GetAcquisitionRate

(

uint32_t *

ratePtr

)

This function gets the GNSS device acquisition rate.

Returns

• LE_OK on success
• LE_FAULT on failure
• LE_NOT_PERMITTED If the GNSS device is not in "ready" state.

Parameters

[out]

ratePtr

Acquisition rate in milliseconds.

le_result_t le_gnss_GetAltitude	(	le_gnss_SampleRef_t	positionSampleRef,
		int32_t *	altitudePtr,
		int32_t *	vAccuracyPtr
	)

Get the position sample's altitude.

Returns

• LE_FAULT Function failed to get the altitude.
• LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
• LE_OK Function succeeded.

Note

Altitude is in metres, above Mean Sea Level, with 3 decimal places (3047 = 3.047 metres).

For a 2D position fix, the altitude will be indicated as invalid and set to INT32_MAX

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

altitudePtr, altitudeAccuracyPtr can be set to NULL if not needed.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	altitudePtr	Altitude in metres, above Mean Sea Level [resolution 1e-3].
[out]	vAccuracyPtr	Vertical position's accuracy in metres [resolution 1e-1].

le_result_t le_gnss_GetConstellation

(

le_gnss_ConstellationBitMask_t *

constellationMaskPtr

)

Get the GNSS constellation bit mask

Returns

• LE_OK on success
• LE_FAULT on failure

Parameters

[out]

constellationMaskPtr

GNSS constellation used in solution.

le_result_t le_gnss_GetDate	(	le_gnss_SampleRef_t	positionSampleRef,
		uint16_t *	yearPtr,
		uint16_t *	monthPtr,
		uint16_t *	dayPtr
	)

Get the position sample's date.

Returns

• LE_FAULT Function failed to get the date.
• LE_OUT_OF_RANGE The retrieved date is invalid (all fields are set to 0).
• LE_OK Function succeeded.

Note

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	yearPtr	UTC Year A.D. [e.g. 2014].
[out]	monthPtr	UTC Month into the year [range 1...12].
[out]	dayPtr	UTC Days into the month [range 1...31].

le_result_t le_gnss_GetDirection	(	le_gnss_SampleRef_t	positionSampleRef,
		int32_t *	directionPtr,
		int32_t *	directionAccuracyPtr
	)

Get the position sample's direction. Direction of movement is the direction that the vehicle/person is actually moving.

Returns

• LE_FAULT Function failed to find the positionSample.
• LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
• LE_OK Function succeeded.

Note

directionPtr, directionAccuracyPtr can be set to NULL if not needed.

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	directionPtr	Direction in degrees [resolution 1e-1]. (where 0 is True North)
[out]	directionAccuracyPtr	Direction's accuracy estimate in degrees [resolution 1e-1].

le_result_t le_gnss_GetDop	(	le_gnss_SampleRef_t	positionSampleRef,
		uint16_t *	hdopPtr,
		uint16_t *	vdopPtr,
		uint16_t *	pdopPtr
	)

Get the DOP parameters (Dilution Of Precision) for the fixed position.

Returns

• LE_FAULT Function failed to find the positionSample.
• LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT16_MAX).
• LE_OK Function succeeded.

Note

The DOP values are given with 3 decimal places like: DOP value 2200 = 2.20

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	hdopPtr	Horizontal Dilution of Precision [resolution 1e-3].
[out]	vdopPtr	Vertical Dilution of Precision [resolution 1e-3].
[out]	pdopPtr	Position Dilution of Precision [resolution 1e-3].

le_result_t le_gnss_GetExtendedEphemerisValidity	(	le_clk_Time_t *	startTimePtr,
		le_clk_Time_t *	stopTimePtr
	)

This function must be called to get the validity of the last injected Extended Ephemeris.

Returns

• LE_FAULT The function failed to get the validity
• LE_OK The function succeeded.

Parameters

[out]	startTimePtr	Start time
[out]	stopTimePtr	Stop time

le_result_t le_gnss_GetHorizontalSpeed	(	le_gnss_SampleRef_t	positionSampleRef,
		uint32_t *	hspeedPtr,
		uint32_t *	hspeedAccuracyPtr
	)

Get the position sample's horizontal speed.

• LE_FAULT Function failed to find the positionSample.
• LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
• LE_OK Function succeeded.

Note

hSpeedPtr, hSpeedAccuracyPtr can be set to NULL if not needed.

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	hspeedPtr	Horizontal speed in meters/second [resolution 1e-2].
[out]	hspeedAccuracyPtr	Horizontal speed's accuracy estimate in meters/second [resolution 1e-1].

le_result_t le_gnss_GetLocation	(	le_gnss_SampleRef_t	positionSampleRef,
		int32_t *	latitudePtr,
		int32_t *	longitudePtr,
		int32_t *	hAccuracyPtr
	)

Get the location's data (Latitude, Longitude, Horizontal accuracy).

Returns

• LE_FAULT Function failed to get the location's data
• LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
• LE_OK Function succeeded.

Note

latitudePtr, longitudePtr, hAccuracyPtr, altitudePtr, vAccuracyPtr can be set to NULL if not needed.

: The latitude and longitude values are based on the WGS84 standard coordinate system.

The latitude and longitude are given in degrees with 6 decimal places like: Latitude +48858300 = 48.858300 degrees North Longitude +2294400 = 2.294400 degrees East

Altitude is in metres, above Mean Sea Level, with 3 decimal places (3047 = 3.047 metres).

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	latitudePtr	WGS84 Latitude in degrees, positive North [resolution 1e-6].
[out]	longitudePtr	WGS84 Longitude in degrees, positive East [resolution 1e-6].
[out]	hAccuracyPtr	Horizontal position's accuracy in metres [resolution 1e-2].

le_result_t le_gnss_GetPositionState	(	le_gnss_SampleRef_t	positionSampleRef,
		le_gnss_FixState_t *	statePtr
	)

This function gets the position sample's fix state

• LE_OK on success
• LE_FAULT on failure

Note

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	statePtr	Position fix state.

le_result_t le_gnss_GetSuplAssistedMode

(

le_gnss_AssistedMode_t *

assistedModePtr

)

This function gets the SUPL Assisted-GNSS mode.

Returns

• LE_OK on success
• LE_FAULT on failure

Parameters

[out]

assistedModePtr

Assisted-GNSS mode.

le_result_t le_gnss_GetTime	(	le_gnss_SampleRef_t	positionSampleRef,
		uint16_t *	hoursPtr,
		uint16_t *	minutesPtr,
		uint16_t *	secondsPtr,
		uint16_t *	millisecondsPtr
	)

Get the position sample's time.

Returns

• LE_FAULT Function failed to get the time.
• LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
• LE_OK Function succeeded.

Note

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	hoursPtr	UTC Hours into the day [range 0..23].
[out]	minutesPtr	UTC Minutes into the hour [range 0..59].
[out]	secondsPtr	UTC Seconds into the minute [range 0..59].
[out]	millisecondsPtr	UTC Milliseconds into the second [range 0..999].

le_result_t le_gnss_GetTtff

(

uint32_t *

ttffPtr

)

Get the TTFF in milliseconds

Returns

• LE_BUSY The position is not fixed and TTFF can't be measured.
• LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
• LE_OK Function succeeded.

Parameters

[out]

ttffPtr

TTFF in milliseconds

le_result_t le_gnss_GetVerticalSpeed	(	le_gnss_SampleRef_t	positionSampleRef,
		int32_t *	vspeedPtr,
		int32_t *	vspeedAccuracyPtr
	)

Get the position sample's vertical speed.

Returns

• LE_FAULT The function failed to find the positionSample.
• LE_OUT_OF_RANGE One of the retrieved parameter is not valid (set to INT32_MAX).
• LE_OK The function succeeded.

Note

vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.

For a 2D position Fix, the vertical speed will be indicated as invalid and set to INT32_MAX.

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]	positionSampleRef	Position sample's reference.
[out]	vspeedPtr	Vertical speed in meters/second [resolution 1e-2].
[out]	vspeedAccuracyPtr	Vertical speed's accuracy estimate in meters/second [resolution 1e-1].

le_result_t le_gnss_InjectSuplCertificate	(	uint8_t	suplCertificateId,
		uint16_t	suplCertificateLen,
		const char *	suplCertificate
	)

This function injects the SUPL certificate to be used in A-GNSS sessions.

Returns

• LE_OK on success
• LE_FAULT on failure
• LE_BUSY service is busy
• LE_TIMEOUT a time-out occurred

Parameters

[in]	suplCertificateId	Certificate ID of the SUPL certificate. Certificate ID range is 0 to 9
[in]	suplCertificateLen	SUPL certificate size in Bytes.
[in]	suplCertificate	SUPL certificate contents.

le_result_t le_gnss_LoadExtendedEphemerisFile

(

int

fd

)

This function must be called to load an 'Extended Ephemeris' file into the GNSS device.

Returns

• LE_FAULT The function failed to inject the 'Extended Ephemeris' file.
• LE_TIMEOUT A time-out occurred.
• LE_FORMAT_ERROR 'Extended Ephemeris' file format error.
• LE_OK The function succeeded.

Parameters

[in]

fd

Extended ephemeris file descriptor

void le_gnss_ReleaseSampleRef

(

le_gnss_SampleRef_t

positionSampleRef

)

This function must be called to release the position sample.

Note

If the caller is passing an invalid Position sample reference into this function, it is a fatal error, the function will not return.

Parameters

[in]

positionSampleRef

Position sample's reference.

void le_gnss_RemovePositionHandler

(

le_gnss_PositionHandlerRef_t

addHandlerRef

)

Remove handler function for EVENT 'le_gnss_Position'

Parameters

[in]

addHandlerRef

le_result_t le_gnss_SetAcquisitionRate

(

uint32_t

rate

)

This function sets the GNSS device acquisition rate.

Returns

• LE_OK on success
• LE_FAULT on failure
• LE_UNSUPPORTED request not supported
• LE_TIMEOUT a time-out occurred
• LE_NOT_PERMITTED If the GNSS device is not in "ready" state.

Parameters

[in]

rate

Acquisition rate in milliseconds.

le_result_t le_gnss_SetConstellation

(

le_gnss_ConstellationBitMask_t

constellationMask

)

Set the GNSS constellation bit mask

Returns

• LE_FAULT The function failed.
• LE_UNSUPPORTED If the request is not supported.
• LE_NOT_PERMITTED If the GNSS device is not initialized, disabled or active.
• LE_OK The function succeeded.

Parameters

[in]

constellationMask

GNSS constellation used in solution.

le_result_t le_gnss_SetSuplAssistedMode

(

le_gnss_AssistedMode_t

assistedMode

)

This function sets the SUPL Assisted-GNSS mode.

Returns

• LE_OK on success
• LE_FAULT on failure
• LE_UNSUPPORTED request not supported
• LE_TIMEOUT a time-out occurred

Parameters

[in]

assistedMode

Assisted-GNSS mode.

le_result_t le_gnss_SetSuplServerUrl

(

const char *

suplServerUrl

)

This function sets the SUPL server URL. That server URL is a NULL-terminated string with a maximum string length (including NULL terminator) equal to 256. Optionally the port number is specified after a colon.

Returns

• LE_OK on success
• LE_FAULT on failure
• LE_BUSY service is busy
• LE_TIMEOUT a time-out occurred

Parameters

[in]

suplServerUrl

SUPL server URL.

le_result_t le_gnss_Start

(

void

)

This function starts the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_DUPLICATE If the GNSS device is already started.
• LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
• LE_OK The function succeeded.

le_result_t le_gnss_Stop

(

void

)

This function stops the GNSS device.

Returns

• LE_FAULT The function failed.
• LE_DUPLICATE If the GNSS device is already stopped.
• LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
• LE_OK The function succeeded.