GNSS
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:
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.
A sample code can be seen in the following page:
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.
Setting configuration
- Warning
- The GNSS setting configuration depends on the platform. Please refer to Setting configuration section for full details.
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.
A sample code can be seen in the following page:
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.
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. This API has a platform dependent feature. Please refer to GNSS WARM restart for further details.
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. 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.
A sample code can be seen in the following page:
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.
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:
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:
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 plateform. 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.
Please refer to API calls Requirements.
A sample code can be seen in the following page:
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 |
Also see Manage GNSS.
GNSS 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 device state, position, time and date, satellites information and accuracy can be queried using the following functions:
- le_gnss_GetState()
- le_gnss_GetPositionState()
- le_gnss_GetLocation()
- le_gnss_GetAltitude()
- le_gnss_GetDate()
- le_gnss_GetTime()
- le_gnss_GetGpsTime()
- le_gnss_GetGpsLeapSeconds()
- le_gnss_GetEpochTime()
- le_gnss_GetTimeAccuracy()
- le_gnss_GetHorizontalSpeed()
- le_gnss_GetVerticalSpeed()
- le_gnss_GetDirection()
- le_gnss_GetSatellitesInfo()
- le_gnss_GetSbasConstellationCategory()
- le_gnss_GetSatellitesStatus()
- le_gnss_GetDop()
- le_gnss_GetDilutionOfPrecision()
- le_gnss_GetAltitudeOnWgs84()
- le_gnss_GetMagneticDeviation()
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:
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:
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.
Copyright (C) Sierra Wireless Inc.