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.

Start/Stop GNSS device

The application can start/stop the GNSS device with the le_gnss_Start() / le_gnss_Stop() functions. The default "HOT" start condition is applied and all assistance data are used. Also see Manage GNSS.

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.

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.

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. Please refer to API calls Requirements. Also see Manage GNSS.

Force HOT restart

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.

Force WARM restart

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.

Force COLD restart

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.

Force FACTORY restart

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.

Acquisition rate

The GNSS position is computed and delivered each acquisition rate. 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.

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 platform may require a reboot to take into account this change. Please refer to your platform documentation for further details.

The following configurations are currently supported:

GPS
GPS + GLONASS

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

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_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

Also see Manage GNSS.

GNSS position information

NMEA Flow

Get position 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 position, time and date and accuracy can be queried using the following functions:

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

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.

Example:

#define EXT_EPH_PATH     "/tmp/ext_eph.bin"
le_clk_Time_t start,stop;
char startTime[100] = {0};
char StopTime[100] = {0};
int32_t fd;
// Download file into EXT_EPH_PATH using for example the "wget" system command
DownloadExtendedEphemerisFile(EXT_EPH_PATH);
if ((fd=open(EXT_EPH_PATH, O_RDONLY)) == -1)
{
    LE_ERROR("Open file %s failure: errno.%d (%s)",  EXT_EPH_PATH, errno, strerror(errno));
}
else
{
    LE_INFO("Open file %s with fd.%d",  EXT_EPH_PATH, fd);
}
if ( le_gnss_LoadExtendedEphemerisFile(EXT_EPH_PATH) != LE_OK )
{
   LE_WARN("Could not load '%s'",EXT_EPH_PATH);
}
if ( le_gnss_GetExtendedEphemerisValidity(&start,&stop) != LE_OK )
{
   LE_WARN("Could get the validity");
}
if ( le_clk_ConvertToUTCString(start,
                               LE_CLK_STRING_FORMAT_DATE_TIME,
                               startTime,
                               sizeof(startTime),
                               NULL) != LE_OK )
{
    LE_INFO("Could not convert start time");
}
if ( le_clk_ConvertToUTCString(stop,
                               LE_CLK_STRING_FORMAT_DATE_TIME,
                               StopTime,
                               sizeof(StopTime),
                               NULL) != LE_OK )
{
    LE_INFO("Could not convert stop time");
}
LE_INFO("Validity Start time  %s",startTime);
LE_INFO("Validity Stop time %s",StopTime);
close (fd);

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.

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