le_gnss_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

Macros

#define LE_GNSS_SUPL_SERVER_URL_MAX_LEN   256
 
#define LE_GNSS_SUPL_SERVER_URL_MAX_BYTES   257
 
#define LE_GNSS_SUPL_CERTIFICATE_MAX_LEN   2000
 
#define LE_GNSS_SUPL_CERTIFICATE_MAX_BYTES   2001
 
#define LE_GNSS_SV_INFO_MAX_LEN   80
 
#define LE_GNSS_NMEA_SENTENCES_MAX   32767
 
#define LE_GNSS_MIN_ELEVATION_MAX_DEGREE   90
 

Typedefs

typedef void(* le_gnss_DisconnectHandler_t) (void *)
 
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_State_t {
  LE_GNSS_STATE_UNINITIALIZED = 0, LE_GNSS_STATE_READY = 1, LE_GNSS_STATE_ACTIVE = 2, LE_GNSS_STATE_DISABLED = 3,
  LE_GNSS_STATE_MAX = 4
}
 
enum  le_gnss_FixState_t { LE_GNSS_STATE_FIX_NO_POS = 0, LE_GNSS_STATE_FIX_2D = 1, LE_GNSS_STATE_FIX_3D = 2, LE_GNSS_STATE_FIX_ESTIMATED = 3 }
 
enum  le_gnss_SbasConstellationCategory_t {
  LE_GNSS_SBAS_EGNOS = 0, LE_GNSS_SBAS_WAAS = 1, LE_GNSS_SBAS_GAGAN = 2, LE_GNSS_SBAS_MSAS = 3,
  LE_GNSS_SBAS_UNKNOWN = 4
}
 
enum  le_gnss_Constellation_t {
  LE_GNSS_SV_CONSTELLATION_UNDEFINED = 0, LE_GNSS_SV_CONSTELLATION_GPS = 1, LE_GNSS_SV_CONSTELLATION_SBAS = 2, LE_GNSS_SV_CONSTELLATION_GLONASS = 3,
  LE_GNSS_SV_CONSTELLATION_GALILEO = 4, LE_GNSS_SV_CONSTELLATION_BEIDOU = 5, LE_GNSS_SV_CONSTELLATION_QZSS = 6, LE_GNSS_SV_CONSTELLATION_MAX = 7
}
 
enum  le_gnss_AssistedMode_t { LE_GNSS_STANDALONE_MODE = 0, LE_GNSS_MS_BASED_MODE = 1, LE_GNSS_MS_ASSISTED_MODE = 2 }
 
enum  le_gnss_ConstellationBitMask_t {
  LE_GNSS_CONSTELLATION_GPS = 0x1, LE_GNSS_CONSTELLATION_GLONASS = 0x2, LE_GNSS_CONSTELLATION_BEIDOU = 0x4, LE_GNSS_CONSTELLATION_GALILEO = 0x8,
  LE_GNSS_CONSTELLATION_SBAS = 0x10, LE_GNSS_CONSTELLATION_QZSS = 0x20
}
 
enum  le_gnss_NmeaBitMask_t {
  LE_GNSS_NMEA_MASK_GPGGA = 0x1, LE_GNSS_NMEA_MASK_GPGSA = 0x2, LE_GNSS_NMEA_MASK_GPGSV = 0x4, LE_GNSS_NMEA_MASK_GPRMC = 0x8,
  LE_GNSS_NMEA_MASK_GPVTG = 0x10, LE_GNSS_NMEA_MASK_GLGSV = 0x20, LE_GNSS_NMEA_MASK_GNGNS = 0x40, LE_GNSS_NMEA_MASK_GNGSA = 0x80,
  LE_GNSS_NMEA_MASK_GAGGA = 0x100, LE_GNSS_NMEA_MASK_GAGSA = 0x200, LE_GNSS_NMEA_MASK_GAGSV = 0x400, LE_GNSS_NMEA_MASK_GARMC = 0x800,
  LE_GNSS_NMEA_MASK_GAVTG = 0x1000, LE_GNSS_NMEA_MASK_PSTIS = 0x2000, LE_GNSS_NMEA_MASK_PQXFI = 0x4000
}
 

Functions

void le_gnss_ConnectService (void)
 
le_result_t le_gnss_TryConnectService (void)
 
void le_gnss_SetServerDisconnectHandler (le_gnss_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
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 (uint64_t *startTimePtr, uint64_t *stopTimePtr)
 
le_result_t le_gnss_InjectUtcTime (uint64_t timeUtc, uint32_t timeUnc)
 
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 handlerRef)
 
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_GetGpsTime (le_gnss_SampleRef_t positionSampleRef, uint32_t *gpsWeekPtr, uint32_t *gpsTimeOfWeekPtr)
 
le_result_t le_gnss_GetEpochTime (le_gnss_SampleRef_t positionSampleRef, uint64_t *millisecondsPtr)
 
le_result_t le_gnss_GetTimeAccuracy (le_gnss_SampleRef_t positionSampleRef, uint32_t *timeAccuracyPtr)
 
le_result_t le_gnss_GetGpsLeapSeconds (le_gnss_SampleRef_t positionSampleRef, uint8_t *leapSecondsPtr)
 
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, uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
 
le_result_t le_gnss_GetSatellitesInfo (le_gnss_SampleRef_t positionSampleRef, uint16_t *satIdPtr, size_t *satIdSizePtr, le_gnss_Constellation_t *satConstPtr, size_t *satConstSizePtr, bool *satUsedPtr, size_t *satUsedSizePtr, uint8_t *satSnrPtr, size_t *satSnrSizePtr, uint16_t *satAzimPtr, size_t *satAzimSizePtr, uint8_t *satElevPtr, size_t *satElevSizePtr)
 
le_gnss_SbasConstellationCategory_t le_gnss_GetSbasConstellationCategory (uint16_t satId)
 
le_result_t le_gnss_GetSatellitesStatus (le_gnss_SampleRef_t positionSampleRef, uint8_t *satsInViewCountPtr, uint8_t *satsTrackingCountPtr, uint8_t *satsUsedCountPtr)
 
le_result_t le_gnss_GetDop (le_gnss_SampleRef_t positionSampleRef, uint16_t *hdopPtr, uint16_t *vdopPtr, uint16_t *pdopPtr)
 
le_result_t le_gnss_GetAltitudeOnWgs84 (le_gnss_SampleRef_t positionSampleRef, int32_t *altitudeOnWgs84Ptr)
 
le_result_t le_gnss_GetMagneticDeviation (le_gnss_SampleRef_t positionSampleRef, int32_t *magneticDeviationPtr)
 
le_gnss_SampleRef_t le_gnss_GetLastSampleRef (void)
 
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 *LE_NONNULL suplServerUrl)
 
le_result_t le_gnss_InjectSuplCertificate (uint8_t suplCertificateId, uint16_t suplCertificateLen, const char *LE_NONNULL suplCertificate)
 
le_result_t le_gnss_DeleteSuplCertificate (uint8_t suplCertificateId)
 
le_result_t le_gnss_SetNmeaSentences (le_gnss_NmeaBitMask_t nmeaMask)
 
le_result_t le_gnss_GetNmeaSentences (le_gnss_NmeaBitMask_t *nmeaMaskPtrPtr)
 
le_gnss_State_t le_gnss_GetState (void)
 
le_result_t le_gnss_SetMinElevation (uint8_t minElevation)
 
le_result_t le_gnss_GetMinElevation (uint8_t *minElevationPtrPtr)
 

Detailed Description

Legato GNSS include file.

Macro Definition Documentation

#define LE_GNSS_MIN_ELEVATION_MAX_DEGREE   90

Define the maximal degree for the minimal elevation

#define LE_GNSS_NMEA_SENTENCES_MAX   32767

Define the maximal bit mask for enabled NMEA sentences

Note
This maximal value should be coherent with le_gnss_NmeaBitMask_t
#define LE_GNSS_SUPL_CERTIFICATE_MAX_BYTES   2001

Maximum SUPL certificate string size. One extra byte is added for the null character.

#define LE_GNSS_SUPL_CERTIFICATE_MAX_LEN   2000

Maximum SUPL certificate size.

#define LE_GNSS_SUPL_SERVER_URL_MAX_BYTES   257

Maximum length of the SUP Server URL string. One extra byte is added for the null character.

#define LE_GNSS_SUPL_SERVER_URL_MAX_LEN   256

Maximum length of the SUP Server URL string.

#define LE_GNSS_SV_INFO_MAX_LEN   80

Define the maximum length of the Satellites Vehicle information list

Typedef Documentation

typedef void(* le_gnss_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

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

Handler for position information.

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

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.

GNSS constellation type.

Enumerator
LE_GNSS_SV_CONSTELLATION_UNDEFINED 

GNSS constellation field not defined.

LE_GNSS_SV_CONSTELLATION_GPS 

Satellite Vehicle of GPS constellation. North American satellite navigation system

LE_GNSS_SV_CONSTELLATION_SBAS 

Satellite Vehicle of SBAS constellation. Satellite-based augmentation system

LE_GNSS_SV_CONSTELLATION_GLONASS 

Satellite Vehicle of Glonass constellation. Russian satellite navigation system

LE_GNSS_SV_CONSTELLATION_GALILEO 

Satellite Vehicle of Galileo constellation. European Union satellite navigation system

LE_GNSS_SV_CONSTELLATION_BEIDOU 

Satellite Vehicle of Beidou constellation. Chinese satellite navigation system

LE_GNSS_SV_CONSTELLATION_QZSS 

Satellite Vehicle of QZSS constellation. Japanese satellite navigation system

LE_GNSS_SV_CONSTELLATION_MAX 

Maximum value.

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

Enumerator
LE_GNSS_CONSTELLATION_GPS 

North American satellite navigation system.

GPS constellation used in solution.

LE_GNSS_CONSTELLATION_GLONASS 

Russian satellite navigation system.

GLONASS constellation used in solution.

LE_GNSS_CONSTELLATION_BEIDOU 

Chinese satellite navigation system.

BEIDOU constellation used in solution.

LE_GNSS_CONSTELLATION_GALILEO 

European Union satellite navigation system.

GALILEO constellation used in solution.

LE_GNSS_CONSTELLATION_SBAS 

SBAS constellation used in solution.

LE_GNSS_CONSTELLATION_QZSS 

Japanese satellite navigation system.

QZSS constellation used in solution.

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.

NMEA sentences Bit Mask indicating the NMEA sentences enabled in the NMEA flow.

Warning
The supported NMEA sentences depend on the platform. Please refer to your platform documentation for further details.
Note
The bit mask values should be coherent with LE_GNSS_NMEA_SENTENCES_MAX
Enumerator
LE_GNSS_NMEA_MASK_GPGGA 

GPGGA type enabled: GPS fix data.

LE_GNSS_NMEA_MASK_GPGSA 

GPGSA type enabled: GPS DOP and active satellites.

LE_GNSS_NMEA_MASK_GPGSV 

GPGSV type enabled: GPS satellites in view.

LE_GNSS_NMEA_MASK_GPRMC 

GPRMC type enabled: GPS recommended minimum data.

LE_GNSS_NMEA_MASK_GPVTG 

GPVTG type enabled: GPS vector track and speed over the ground.

LE_GNSS_NMEA_MASK_GLGSV 

GLGSV type enabled: GLONASS satellites in view.

LE_GNSS_NMEA_MASK_GNGNS 

GNGNS type enabled: GNSS fix data.

LE_GNSS_NMEA_MASK_GNGSA 

GNGSA type enabled: GNSS DOP and active satellites.

LE_GNSS_NMEA_MASK_GAGGA 

GAGGA type enabled: Galileo fix data.

LE_GNSS_NMEA_MASK_GAGSA 

GAGSA type enabled: Galileo DOP and active satellites.

LE_GNSS_NMEA_MASK_GAGSV 

GAGSV type enabled: Galileo satellites in view.

LE_GNSS_NMEA_MASK_GARMC 

GARMC type enabled: Galileo recommended minimum data.

LE_GNSS_NMEA_MASK_GAVTG 

GAVTG type enabled: Galileo vector track and speed over the ground.

LE_GNSS_NMEA_MASK_PSTIS 

PSTIS type enabled: GPS session start indication.

LE_GNSS_NMEA_MASK_PQXFI 

PQXFI type enabled: Proprietary Qualcomm eXtended Fix Information.

SBAS constellation category

Enumerator
LE_GNSS_SBAS_EGNOS 

Satellite Vehicle of Satellite-based augmentation system (SBAS) EGNOS constellation.

LE_GNSS_SBAS_WAAS 

Satellite Vehicle of Satellite-based augmentation system (SBAS) WAAS constellation.

LE_GNSS_SBAS_GAGAN 

Satellite Vehicle of Satellite-based augmentation system (SBAS) GAGAN constellation.

LE_GNSS_SBAS_MSAS 

Satellite Vehicle of Satellite-based augmentation system (SBAS) MSAS constellation.

LE_GNSS_SBAS_UNKNOWN 

Satellite Vehicle of Satellite-based augmentation system (SBAS) unknown constellation.

Enumeration for GNSS device state

Enumerator
LE_GNSS_STATE_UNINITIALIZED 

The GNSS device is not initialized.

LE_GNSS_STATE_READY 

The GNSS device is ready.

LE_GNSS_STATE_ACTIVE 

The GNSS device is active.

LE_GNSS_STATE_DISABLED 

The GNSS device is disabled.

LE_GNSS_STATE_MAX 

Do not use.

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. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. 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_BAD_PARAMETER on invalid parameter
  • LE_FAULT on failure
  • LE_BUSY service is busy
  • LE_TIMEOUT a time-out occurred
Parameters
[in]suplCertificateIdID 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.
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
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.
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
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.
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
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.
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
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]ratePtrAcquisition 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. Invalid Position reference provided.
  • LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
  • LE_OK Function succeeded.
Note
Altitude is in meters, above Mean Sea Level, with 3 decimal places (3047 = 3.047 meters).
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]positionSampleRefPosition sample's reference.
[out]altitudePtrAltitude in meters, above Mean Sea Level [resolution 1e-3].
[out]vAccuracyPtrVertical position's accuracy in meters [resolution 1e-1].
le_result_t le_gnss_GetAltitudeOnWgs84 ( le_gnss_SampleRef_t  positionSampleRef,
int32_t *  altitudeOnWgs84Ptr 
)

Get the position sample's altitude with respect to the WGS-84 ellipsoid

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
altitudeOnWgs84 is in meters, between WGS-84 earth ellipsoid and mean sea level with 3 decimal places (3047 = 3.047 meters).
For a 2D position fix, the altitude with respect to the WGS-84 ellipsoid 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.
Parameters
[in]positionSampleRefPosition sample's reference.
[out]altitudeOnWgs84PtrAltitude in meters, between WGS-84 earth ellipsoid and mean sea level [resolution 1e-3].
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]constellationMaskPtrGNSS 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]positionSampleRefPosition sample's reference.
[out]yearPtrUTC Year A.D. [e.g. 2014].
[out]monthPtrUTC Month into the year [range 1...12].
[out]dayPtrUTC Days into the month [range 1...31].
le_result_t le_gnss_GetDirection ( le_gnss_SampleRef_t  positionSampleRef,
uint32_t *  directionPtr,
uint32_t *  directionAccuracyPtr 
)

Get the position sample's direction. Direction of movement is the direction that the vehicle or 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 UINT32_MAX).
  • LE_OK Function succeeded.
Note
Direction is given in degrees with 1 decimal place: 1755 = 175,5 degrees. Direction ranges from 0 to 359.9 degrees, where 0 is True North.
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]positionSampleRefPosition sample's reference.
[out]directionPtrDirection in degrees [resolution 1e-1]. Range: 0 to 359.9, where 0 is True North
[out]directionAccuracyPtrDirection'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.200
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]positionSampleRefPosition sample's reference.
[out]hdopPtrHorizontal Dilution of Precision [resolution 1e-3].
[out]vdopPtrVertical Dilution of Precision [resolution 1e-3].
[out]pdopPtrPosition Dilution of Precision [resolution 1e-3].
le_result_t le_gnss_GetEpochTime ( le_gnss_SampleRef_t  positionSampleRef,
uint64_t *  millisecondsPtr 
)

Get the position sample's epoch time.

Returns
  • LE_FAULT Function failed to acquire the epoch time.
  • LE_OK Function succeeded.
  • LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
Note
The epoch time is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leaps seconds.
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]positionSampleRefPosition sample's reference.
[out]millisecondsPtrMilliseconds since Jan. 1, 1970.
le_result_t le_gnss_GetExtendedEphemerisValidity ( uint64_t *  startTimePtr,
uint64_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]startTimePtrStart time in seconds (since Jan. 1, 1970)
[out]stopTimePtrStop time in seconds (since Jan. 1, 1970)
le_result_t le_gnss_GetGpsLeapSeconds ( le_gnss_SampleRef_t  positionSampleRef,
uint8_t *  leapSecondsPtr 
)

Get the position sample's UTC leap seconds in advance

Returns
  • LE_FAULT Function failed to get the leap seconds.
  • LE_OUT_OF_RANGE The retrieved time accuracy is invalid (set to UINT8_MAX).
  • LE_OK Function succeeded.
Note
The leap seconds in advance is the accumulated time in seconds since the start of GPS Epoch time (Jan 6, 1980). This value has to be added to the UTC time (since Jan. 1, 1970)
Insertion of each UTC leap second is usually decided about six months in advance by the International Earth Rotation and Reference Systems Service (IERS).
If the caller is passing an invalid position sample reference or a null pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]positionSampleRefPosition sample's reference.
[out]leapSecondsPtrUTC leap seconds in advance in seconds
le_result_t le_gnss_GetGpsTime ( le_gnss_SampleRef_t  positionSampleRef,
uint32_t *  gpsWeekPtr,
uint32_t *  gpsTimeOfWeekPtr 
)

Get the position sample's GPS 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]positionSampleRefPosition sample's reference.
[out]gpsWeekPtrGPS week number from midnight, Jan. 6, 1980.
[out]gpsTimeOfWeekPtrAmount of time in milliseconds into the GPS week.
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]positionSampleRefPosition sample's reference.
[out]hspeedPtrHorizontal speed in meters/second [resolution 1e-2].
[out]hspeedAccuracyPtrHorizontal speed's accuracy estimate in meters/second [resolution 1e-1].
le_gnss_SampleRef_t le_gnss_GetLastSampleRef ( void  )

This function gets the last updated position sample object reference.

Returns
A reference to last Position's sample.
Note
On failure, the process exits, so you don't have to worry about checking the returned reference for validity.
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
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]positionSampleRefPosition sample's reference.
[out]latitudePtrWGS84 Latitude in degrees, positive North [resolution 1e-6].
[out]longitudePtrWGS84 Longitude in degrees, positive East [resolution 1e-6].
[out]hAccuracyPtrHorizontal position's accuracy in meters [resolution 1e-2].
le_result_t le_gnss_GetMagneticDeviation ( le_gnss_SampleRef_t  positionSampleRef,
int32_t *  magneticDeviationPtr 
)

Get the position sample's magnetic deviation. It is the difference between the bearing to true north and the bearing shown on a magnetic compass. The deviation is positive when the magnetic north is east of true north.

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
magneticDeviation is in degrees, with 1 decimal places (47 = 4.7 degree).
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]positionSampleRefPosition sample's reference.
[out]magneticDeviationPtrMagneticDeviation in degrees [resolution 1e-1].
le_result_t le_gnss_GetMinElevation ( uint8_t *  minElevationPtrPtr)

This function gets the GNSS minimum elevation.

Returns
  • LE_OK on success
  • LE_FAULT on failure
  • LE_UNSUPPORTED request not supported
Note
If the caller is passing an null pointer to this function, it is a fatal error and the function will not return.
Parameters
[out]minElevationPtrPtrMinimum elevation in degrees [range 0..90].
le_result_t le_gnss_GetNmeaSentences ( le_gnss_NmeaBitMask_t nmeaMaskPtrPtr)

This function gets the bit mask for the enabled NMEA sentences.

Returns
  • LE_OK Success
  • LE_FAULT Failure
  • LE_BUSY Service is busy
  • LE_TIMEOUT Timeout occurred
  • LE_NOT_PERMITTED GNSS device is not in "ready" state
Note
If the caller is passing an null pointer to this function, it is a fatal error and the function will not return.
Parameters
[out]nmeaMaskPtrPtrBit mask for enabled NMEA sentences.
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]positionSampleRefPosition sample's reference.
[out]statePtrPosition fix state.
le_result_t le_gnss_GetSatellitesInfo ( le_gnss_SampleRef_t  positionSampleRef,
uint16_t *  satIdPtr,
size_t *  satIdSizePtr,
le_gnss_Constellation_t satConstPtr,
size_t *  satConstSizePtr,
bool *  satUsedPtr,
size_t *  satUsedSizePtr,
uint8_t *  satSnrPtr,
size_t *  satSnrSizePtr,
uint16_t *  satAzimPtr,
size_t *  satAzimSizePtr,
uint8_t *  satElevPtr,
size_t *  satElevSizePtr 
)

Get the Satellites Vehicle information.

Returns
  • LE_FAULT Function failed to find the positionSample.
  • LE_OUT_OF_RANGE One of the retrieved parameter is invalid.
  • LE_OK Function succeeded.
Note
satId[] can be set to 0 if that information list index is not configured, so all satellite parameters (satConst[], satSnr[],satAzim[], satElev[]) are fixed to 0.
For LE_OUT_OF_RANGE returned code, invalid value depends on field type: UINT16_MAX for satId, LE_GNSS_SV_CONSTELLATION_UNDEFINED for satConst, false for satUsed, UINT8_MAX for satSnr, UINT16_MAX for satAzim, UINT8_MAX for satElev.
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]positionSampleRefPosition sample's reference.
[out]satIdPtrSatellites in View ID number, referring to NMEA standard.
[in,out]satIdSizePtr
[out]satConstPtrGNSS constellation type.
[in,out]satConstSizePtr
[out]satUsedPtrTRUE if satellite in View Used for Navigation.
[in,out]satUsedSizePtr
[out]satSnrPtrSatellites in View Signal To Noise Ratio [dBHz].
[in,out]satSnrSizePtr
[out]satAzimPtrSatellites in View Azimuth [degrees]. Range: 0 to 360 If Azimuth angle is currently unknown, the value is set to UINT16_MAX.
[in,out]satAzimSizePtr
[out]satElevPtrSatellites in View Elevation [degrees]. Range: 0 to 90 If Elevation angle is currently unknown, the value is set to UINT8_MAX.
[in,out]satElevSizePtr
le_result_t le_gnss_GetSatellitesStatus ( le_gnss_SampleRef_t  positionSampleRef,
uint8_t *  satsInViewCountPtr,
uint8_t *  satsTrackingCountPtr,
uint8_t *  satsUsedCountPtr 
)

Get the Satellites Vehicle status.

Returns
  • LE_FAULT Function failed to find the positionSample.
  • LE_OUT_OF_RANGE One of the retrieved parameter is invalid.
  • 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]positionSampleRefPosition sample's reference.
[out]satsInViewCountPtrNumber of satellites expected to be in view.
[out]satsTrackingCountPtrNumber of satellites in view, when tracking.
[out]satsUsedCountPtrNumber of satellites in view used for Navigation.
le_gnss_SbasConstellationCategory_t le_gnss_GetSbasConstellationCategory ( uint16_t  satId)

Get the SBAS constellation category

Parameters
[in]satIdSatellites in View ID number, referring to NMEA standard.
le_gnss_State_t le_gnss_GetState ( void  )

This function returns the status of the GNSS device.

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]assistedModePtrAssisted-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]positionSampleRefPosition sample's reference.
[out]hoursPtrUTC Hours into the day [range 0..23].
[out]minutesPtrUTC Minutes into the hour [range 0..59].
[out]secondsPtrUTC Seconds into the minute [range 0..59].
[out]millisecondsPtrUTC Milliseconds into the second [range 0..999].
le_result_t le_gnss_GetTimeAccuracy ( le_gnss_SampleRef_t  positionSampleRef,
uint32_t *  timeAccuracyPtr 
)

Get the position sample's time accurary.

Returns
  • LE_FAULT Function failed to get the time.
  • LE_OUT_OF_RANGE The retrieved time accuracy is invalid (set to UINT16_MAX).
  • 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]positionSampleRefPosition sample's reference.
[out]timeAccuracyPtrEstimated time accuracy in milliseconds
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]ttffPtrTTFF 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]positionSampleRefPosition sample's reference.
[out]vspeedPtrVertical speed in meters/second [resolution 1e-2], positive up.
[out]vspeedAccuracyPtrVertical speed's accuracy estimate in meters/second [resolution 1e-1].
le_result_t le_gnss_InjectSuplCertificate ( uint8_t  suplCertificateId,
uint16_t  suplCertificateLen,
const char *LE_NONNULL  suplCertificate 
)

This function injects the SUPL certificate to be used in A-GNSS sessions. Certificates must be encoded in DER. Other certificate encryptions (e.g., PEM, CER and CRT) aren't supported.

Returns
  • LE_OK on success
  • LE_BAD_PARAMETER on invalid parameter
  • LE_FAULT on failure
  • LE_BUSY service is busy
  • LE_TIMEOUT a time-out occurred
Note
If the SUPL certificate size is bigger than the Maximum SUPL certificate size, it is a fatal error, the function will not return.
Parameters
[in]suplCertificateIdID of the SUPL certificate. Certificate ID range is 0 to 9
[in]suplCertificateLenSUPL certificate size in Bytes.
[in]suplCertificateSUPL certificate contents.
le_result_t le_gnss_InjectUtcTime ( uint64_t  timeUtc,
uint32_t  timeUnc 
)

This function must be called to inject the UTC time into the GNSS device.

Returns
  • LE_OK The function succeeded.
  • LE_FAULT The function failed to inject the UTC time.
  • LE_TIMEOUT A time-out occurred.
Parameters
[in]timeUtc[IN] UTC time since Jan. 1, 1970 in milliseconds
[in]timeUnc[IN] Time uncertainty in milliseconds
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]fdExtended 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]positionSampleRefPosition sample's reference.
void le_gnss_RemovePositionHandler ( le_gnss_PositionHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_gnss_Position'

Parameters
[in]handlerRef
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.
  • LE_OUT_OF_RANGE if acquisition rate value is equal to zero
Warning
This function may be subject to limitations depending on the platform. Please refer to the GNSS platform constraints page.
The settings are platform dependent. Please refer to Setting configuration section for full details.
Parameters
[in]rateAcquisition 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.
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
Parameters
[in]constellationMaskGNSS constellation used in solution.
le_result_t le_gnss_SetMinElevation ( uint8_t  minElevation)

This function sets the GNSS minimum elevation.

Returns
  • LE_OK on success
  • LE_FAULT on failure
  • LE_OUT_OF_RANGE if the minimum elevation is above range
  • LE_UNSUPPORTED request not supported
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
Parameters
[in]minElevationMinimum elevation in degrees [range 0..90].
le_result_t le_gnss_SetNmeaSentences ( le_gnss_NmeaBitMask_t  nmeaMask)

This function sets the enabled NMEA sentences using a bit mask.

Returns
  • LE_OK Success
  • LE_BAD_PARAMETER Bit mask exceeds the maximal value
  • LE_FAULT Failure
  • LE_BUSY Service is busy
  • LE_TIMEOUT Timeout occurred
  • LE_NOT_PERMITTED GNSS device is not in "ready" state
Warning
This function may be subject to limitations depending on the platform. Please refer to the GNSS platform constraints page.
The settings are platform dependent. Please refer to Setting configuration section for full details.
Parameters
[in]nmeaMaskBit mask for enabled NMEA sentences.
void le_gnss_SetServerDisconnectHandler ( le_gnss_DisconnectHandler_t  disconnectHandler,
void *  contextPtr 
)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

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
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
Parameters
[in]assistedModeAssisted-GNSS mode.
le_result_t le_gnss_SetSuplServerUrl ( const char *LE_NONNULL  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
Note
If the SUPL server URL size is bigger than the maximum string length (including NULL terminator) size, it is a fatal error, the function will not return.
Warning
The settings are platform dependent. Please refer to Setting configuration section for full details.
Parameters
[in]suplServerUrlSUPL 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.
le_result_t le_gnss_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.