API Reference
GNSS platform constraints
How To Use GNSS
GNSS target tool

This API provides access to the GNSS device.

GNSS or Global Navigation Satellite System is a satellite navigation system with global coverage.

This API provides function to configure the GNSS device and retrieve position information.

IPC interfaces binding

All the functions of this API are provided by the positioningService application service.

Here's a code sample binding to Positioning services:

 bindings:
 {
    clientExe.clientComponent.le_gnss -> positioningService.le_gnss
 }

GNSS Control API

Enable/Disable GNSS device

The application can enable/disable the GNSS device with the le_gnss_Enable() / le_gnss_Disable() functions. By default the GNSS device is enabled for the positioningService application service. Also see Manage GNSS.

A sample code can be seen in the following page:

Sample code for Enable/Disable GNSS device

Start/Stop GNSS device

The application shall start the GNSS device calling le_gnss_Start() function. The other starting functions that allow to start or restart the GNSS devices in particular modes (see Starting mode) are only used for test purposes and allow start performance measurement. The application shall stop the GNSS device calling le_gnss_Stop() function.

A diagram of GNSS device state machine showing how to use the different starting fonctions can be seen at Manage GNSS.

A sample code can be seen in the following page:

Sample code for Start/Stop GNSS device

Starting mode

Starting modes are used only for test purposes and allow start performance measurement.

Note: For more information about start performances, please refer to your specific platform documentation.

Start the GNSS device in the specified starting mode

The le_gnss_StartMode() function clears the GNSS data according to the starting mode and starts the GNSS device. In HOT mode, no data are cleared, the GNSS is started with its available data. It is equivalent to le_gnss_Start() function. In WARM mode, GNSS is started after the Ephemeris are cleared. In COLD mode, GNSS is started after all data are cleared except Almanac and in Factory mode GNSS is started after default data are set.

Restart the GNSS device in HOT mode

The le_gnss_ForceHotRestart() function performs a "HOT" restart of the GNSS device. The current GNSS session is stopped, then started using the available GNSS data. Please refer to API calls Requirements. Also see Manage GNSS.

Restart the GNSS device in WARM mode

The le_gnss_ForceWarmRestart() function performs a "WARM" restart of the GNSS device. The current GNSS session is stopped, then started using the available GNSS data. Please refer to API calls Requirements. Also see Manage GNSS. This API has a platform dependent feature. Please refer to GNSS WARM restart for further details.

Restart the GNSS device in COLD mode

The le_gnss_ForceColdRestart() function performs a "COLD" restart of the GNSS device. The current GNSS session is stopped, then started using the available GNSS data. Please refer to API calls Requirements. Also see Manage GNSS.

Restart the GNSS device in FACTORY mode

The le_gnss_ForceFactoryRestart() function performs a "FACTORY" restart of the GNSS device. The current GNSS session is stopped, then started using the available GNSS data. Please refer to API calls Requirements. Also see Manage GNSS.

GNSS data

The following table describes the minimum required data for those starting modes:

GNSS Data / Starting mode	HOT	WARM	COLD	FACTORY
Broadcasted Ephemeris	Used
Extended Ephemeris	Used(1)	Used(2)	Used(2)	Removed (3)
Approximate Time and Position	Used	Used
Almanac	Used	Used	Used	Used (Factory)

For example, a requested HOT start without valid broadcasted ephemeris will be treated as a WARM start.

Note: (1) Extended Ephemeris can be used if Broadcasted Ephemeris are not valid. The Extended Ephemeris could be loaded using the le_gnss_LoadExtendedEphemerisFile() function.; (2) Extended Ephemeris is used if the Extended Ephemeris file is loaded and valid.; (3) Extended Ephemeris are removed when a FACTORY start is requested. The Extended Ephemeris could be loaded again using the le_gnss_LoadExtendedEphemerisFile() function.

Setting configuration

Warning: The GNSS setting configuration depends on the platform. Please refer to Setting configuration section for full details.

Time To First Fix (TTFF)

The le_gnss_GetTtff() function provides the TTFF (first between 2-Dimensional or 3-Dimensional position fix) of the last position fix. The GNSS fix position is calculated by the GNSS engine. Its state can be retrieved by le_gnss_GetPositionState() function. The GNSS fix position states are given by le_gnss_FixState_t enum.

Note: The "estimated" fix is obtained when less than 3 Satellites Vehicle (SV) are used to establish the fix. It includes the case when no SVs are used.

Please refer to API calls Requirements. Also see Manage GNSS.

A sample code can be seen in the following page:

Sample code for restart GNSS device and get TTFF

Inject UTC time

The le_gnss_InjectUtcTime() function injects the UTC time into the location engine. Providing an accurate UTC time reduces the time to find the first fix.

Note: It is mandatory to enable the 'Extended Ephemeris' file injection into the GNSS device with le_gnss_EnableExtendedEphemerisFile() before injecting time with le_gnss_InjectUtcTime API.

Warning: Your GNSS device may require a restart to take into account the enabling of the 'Extended Ephemeris' file injection. Please refer to your platform documentation Setting configuration for further details.

Acquisition rate

The GNSS position is computed and delivered each acquisition rate. The acquisition rate defines the time interval that must elapse between two final GPS positions calculation and reports. Its default value is 1 second. The application can configure/retreive the GNSS device acquisition rate with the le_gnss_SetAcquisitionRate() / le_gnss_GetAcquisitionRate() functions.

Please refer to API calls Requirements.

Control EXT_GPS_LNA_EN signal

The le_gnss_EnableExternalLna() function enables the EXT_GPS_LNA_EN signal. The pin is set high when the GNSS state is active, and set low when the GNSS state is inactive.

The le_gnss_DisableExternalLna() function disables the EXT_GPS_LNA_EN signal. The pin remains off regardless of the GNSS state.

The le_gnss_GetExternalLna() function read the EXT_GPS_LNA_EN status.

Please refer to API calls Requirements.

A sample code can be seen in the following page:

Sample code for GNSS acquisition rate configuration

GNSS constellation selection

The le_gnss_SetConstellation() function selects the GNSS constellation(s) used in solution. If all GNSS constellations are disabled, the GNSS engine is disabled.

Warning: Your GNSS device may require a restart to take into account this change. Please refer to your platform documentation Setting configuration for further details.

Combinations of constellation for GPS, GLONASS, BDS, GALILEO and QZSS satellites are currently supported. Constellation for SBAS satellites is not supported.

Warning: Some constellation types are unsupported depending on the platform. Please refer to Constellation type section for full details.

All supported GNSS constellations are enabled by default. The le_gnss_GetConstellation() function gets the GNSS constellation(s) enabled to be used in solution.

le_gnss_SetConstellationArea sets the area for a GNSS constellation. le_gnss_GetConstellationArea gets the area for a GNSS constellation.

A sample code can be seen in the following page:

Sample code for GNSS constellation selection

The le_gnss_GetSupportedConstellations() function gets a bit mask of the constellations supported on the platform.

GNSS minimum elevation selection

The le_gnss_SetMinElevation() function sets the GNSS minimum elevation. Satellites with elevation lower than the minimum elevation will be ignored.

The le_gnss_GetMinElevation() function gets the GNSS minimum elevation.

A sample code can be seen in the following page:

Sample code for GNSS minimum elevation

NMEA sentences selection

The le_gnss_SetNmeaSentences() function selects the enabled NMEA sentences in the NMEA Flow with a bit mask. The supported values are listed in le_gnss_NmeaBitMask_t.

Note: This function may be subject to limitations depending on the platform. Please refer to the GNSS platform constraints page.

Warning: Your GNSS device may require a restart to take into account this change. Please refer to your platform documentation Setting configuration for further details.; Some NMEA sentences are unsupported depending on the platform. Please refer to Enabled NMEA sentences section for full details.

Note: All supported NMEA sentences are enabled by default.

The le_gnss_GetNmeaSentences() function gets the bit mask of the enabled NMEA sentences in the NMEA Flow.

The le_gnss_GetSupportedNmeaSentences() function gets a bit mask of the NMEA sentences supported on the platform.

Please refer to API calls Requirements.

A sample code can be seen in the following page:

Sample code for GNSS NMEA sentences selection

Get the supported NMEA rates

The le_gnss_GetMinNmeaRate() function gets the minimum NMEA rate supported on the platform in milliseconds.

The le_gnss_GetMaxNmeaRate() function gets the maximum NMEA rate supported on the platform in milliseconds.

API calls Requirements

The following table shows the pre-requisites when using the GNSS service API function set. ''LE_OK or error code'' means the function is authorized in the corresponding state, the request is performed and the result is returned; otherwise the returned error is indicated for each state

Function / GNSS state	UNINITIALIZED	READY	ACTIVE	DISABLED
le_gnss_Start()	LE_NOT_PERMITTED	LE_OK or error code	LE_DUPLICATE	LE_NOT_PERMITTED
le_gnss_Stop()	LE_NOT_PERMITTED	LE_DUPLICATE	LE_OK or error code	LE_NOT_PERMITTED
le_gnss_ForceHotRestart()	LE_NOT_PERMITTED	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED
le_gnss_ForceWarmRestart()	LE_NOT_PERMITTED	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED
le_gnss_ForceColdRestart()	LE_NOT_PERMITTED	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED
le_gnss_ForceFactoryRestart()	LE_NOT_PERMITTED	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED
le_gnss_Disable()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_DUPLICATE
le_gnss_Enable()	LE_NOT_PERMITTED	LE_DUPLICATE	LE_DUPLICATE	LE_OK or error code
le_gnss_SetConstellation()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_GetConstellation()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_SetConstellationArea()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_GetConstellationArea()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_GetTtff()	LE_NOT_PERMITTED	LE_OK or error code	LE_OK or error code	LE_NOT_PERMITTED
le_gnss_SetAcquisitionRate()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_GetAcquisitionRate()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_SetNmeaSentences()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_GetNmeaSentences()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_EnableExternalLna()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_DisableExternalLna()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED
le_gnss_GetExternalLna()	LE_NOT_PERMITTED	LE_OK or error code	LE_NOT_PERMITTED	LE_NOT_PERMITTED

Also see Manage GNSS.

GNSS position information

NMEA Flow

Get position information

Get leap seconds event information

NMEA Flow

The National Marine Electronics Association (NMEA) standard defines an electrical interface and data protocol for communications between marine instrumentation.

The NMEA-0183, scope of this document, defines a set of frame prefixed by $GP (concerning Global Positioning System), $GL (concerning GLONASS) and $GN (concerning combination of navigation systems). For more details about NMEA standards, please refer to http://www.nmea.org/.

That NMEA frames flow can be retrieved from the "/dev/nmea" device folder, using for example the shell command $ cat /dev/nmea | grep '$G'

Get position information

The position information is referenced to a position sample object.

An application can register a handler to be notified of the updated position each Acquisition rate, returning a position sample object.

The GNSS information commonly used such as device state, position, time and date, satellites information and accuracy can be queried using the following functions:

le_gnss_SetDataResolution() function can be called to configure the resolution of position data type per client session. Currently, three data types are supported:

Vertical position accuracy provided by le_gnss_GetAltitude().
Vertical speed accuracy provided by le_gnss_GetVerticalSpeed().
Horizontal speed accuracy provided by le_gnss_GetHorizontalSpeed(). Each data type can be set with a resolution from 0 to 3 decimal place.

For example, to get the vertical position accuracy with a resolution of 2 decimal places, le_gnss_SetDataResolution() function is called with vertical position accuracy set as data type and 2 decimal place is set as resolution, then le_gnss_GetAltitude() function is called.

Note: If le_gnss_SetDataResolution() function is not called, the position data types are received in their default accuracies.

le_gnss_ConvertDataCoordinateSystem() function can be called to convert a location data value from a coordinate system to another. Currently it is possible to convert the following data types:

Latitude
Longitude
Altitude

System coordinates source and destination are currently:

Coordinate system WGS84
Coordinate system PZ90

Note: Only conversion from WGS84 coordinate system to PZ90 coordinate system is currently supported.; The altitude in coordinate system WGS84 is obtained by le_gnss_GetAltitudeOnWgs84() function.

A sample code using le_gnss_ConvertDataCoordinate() function can be seen in the following page:

Sample code for GNSS position information

le_gnss_GetDilutionOfPrecision() gets the DOP parameters (Dilution Of Precision) with a resolution of 3 decimal places by default. This resolution can be modified by calling the le_gnss_SetDopResolution() function first.

As le_gnss_SetDopResolution() sets the resolution per client session, le_gnss_SetDopResolution() and le_gnss_GetDilutionOfPrecision() functions should be called in the same thread or client session.

A sample code can be seen in the following page:

Sample code for GNSS position information

The handler can be managed using le_gnss_AddPositionHandler() and le_gnss_RemovePositionHandler(). When a position is computed, the handler is called.

The application has to release each position sample object received by the handler, using the le_gnss_ReleaseSampleRef().

A sample code can be seen in the following page:

Sample code for GNSS position information

Get leap seconds event information

The leap seconds event information is retrieved by calling le_gnss_GetLeapSeconds() API. The result includes current GPS time, current leap seconds, next leap second event time, and next leap seconds.

Insertion of each UTC leap second is usually decided about six months in advance by the International Earth Rotation and Reference Systems Service (IERS).

Assisted GNSS

Server based Extended Ephemeris 3GPP User Plane (OMA SUPL)

Server based Extended Ephemeris

With le_gnss_LoadExtendedEphemerisFile() , you can load an 'Extended Ephemeris' file into the GNSS device from the filesystem. You have to download the file before loading it.

Warning: Ensure to check that the downloaded file is supported for your specific platform.

With le_gnss_GetExtendedEphemerisValidity(), you will to get the validity of the last injected Extended Ephemeris.

You can enable/disable the use of the 'Extended Ephemeris' file into the GNSS device with le_gnss_EnableExtendedEphemerisFile() / le_gnss_DisableExtendedEphemerisFile() functions.

Warning: Ensure to check configuration capabilities for your specific platform. A reboot must be required if your platform doesn't allow run-time configuration.

A sample code can be seen in the following page:

Sample code for GNSS Server based Extended Ephemeris

3GPP User Plane (OMA SUPL)

That 3GPP User Plane A-GNSS (Assisted GNSS) protocol is defined by two different standardization bodies, 3GPP and Open Mobile Alliance (OMA). For more information, please refer to the standard.

Both MS-Assisted and MS-Based position determination methods are supported in the User Plane.

In MS-Assisted mode, the MS (Mobile Station) measures the signals from the GNSS satellites , then returns the retrieved GNSS data to the SUPL (Secure User Plan Location) server, where the position calculation is performed.

In MS-Based mode, the MS gets the assistance data from the SUPL (Secure User Plan Location) server. The MS measures the signals from the GNSS satellites and makes the position calculation.

The data transport over User Plan is done using the TCP/IP protocol.

The Assisted-GNSS mode can be configured thru the le_gnss_SetSuplAssistedMode() function.

The supported modes are the following:

Standalone mode: That 3GPP User Plane A-GNSS feature is deactivated.
MS-Based mode
MS-Assisted mode

Moreover, the le_gnss_GetSuplAssistedMode() function reads the configured Assisted-GNSS mode.

The SUPL server is configured using the le_gnss_SetSuplServerUrl() function. That function sets the SUPL server URL and optionally the port number.

The SUPL certificate to be used in A-GNSS sessions is injected through the le_gnss_InjectSuplCertificate() function and deleted through the le_gnss_DeleteSuplCertificate() function. The SUPL certificate lenght given as parameter to le_gnss_InjectSuplCertificate() must be less than LE_GNSS_SUPL_CERTIFICATE_MAX_LEN.