le_gnss_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_gnss GNSS
14  *
15  * @ref le_gnss_interface.h "API Reference" <br>
16  * @ref platformConstraintsGnss <br>
17  * @ref howToGNSS "How To Use GNSS" <br>
18  * @ref toolsTarget_gnss "GNSS target tool" <br>
19  *
20  * <HR>
21  *
22  * This API provides access to the GNSS device.
23  *
24  * GNSS or Global Navigation Satellite System is a satellite navigation system with global coverage.
25  *
26  * This API provides function to configure the GNSS device and retrieve position information.
27  *
28  * @section le_gnss_binding IPC interfaces binding
29  *
30  * All the functions of this API are provided by the @b positioningService application service.
31  *
32  * Here's a code sample binding to Positioning services:
33  * @verbatim
34  bindings:
35  {
36  clientExe.clientComponent.le_gnss -> positioningService.le_gnss
37  }
38  @endverbatim
39  *
40  * @section le_gnss_ControlApi GNSS Control API
41  *
42  * @subsection le_gnss_EnableDisable Enable/Disable GNSS device
43  *
44  * The application can enable/disable the GNSS device with the le_gnss_Enable()
45  * / le_gnss_Disable() functions.
46  * By default the GNSS device is enabled for the positioningService application service.
47  * Also see @ref howToGNSS.
48  *
49  * A sample code can be seen in the following page:
50  * - @subpage c_gnssSampleCodeEnableDisable
51  *
52  * @subsection le_gnss_StartStop Start/Stop GNSS device
53  *
54  * The application shall start the GNSS device calling le_gnss_Start() function.
55  * The other starting functions that allow to start or restart the GNSS devices in particular modes
56  * (see @ref le_gnss_StartingMode) are only used for test purposes and allow start performance
57  * measurement.
58  * The application shall stop the GNSS device calling le_gnss_Stop() function.
59  *
60  * A diagram of GNSS device state machine showing how to use the different starting fonctions can be
61  * seen at @ref howToGNSS.
62  *
63  * A sample code can be seen in the following page:
64  * - @subpage c_gnssSampleCodeStartStop
65  *
66  * @subsubsection le_gnss_StartingMode Starting mode
67  *
68  * Starting modes are used only for test purposes and allow start performance measurement.
69  * @note For more information about start performances, please refer to your specific
70  * platform documentation.
71  *
72  * @subsubsection le_gnss_startMode Start the GNSS device in the specified starting mode
73  * The le_gnss_StartMode() function clears the @ref le_gnss_Data according to the starting mode and
74  * starts the GNSS device.
75  * In HOT mode, no data are cleared, the GNSS is started with its available data. It is equivalent
76  * to @ref le_gnss_Start() function. In WARM mode, GNSS is started after the Ephemeris are cleared.
77  * In COLD mode, GNSS is started after all data are cleared except Almanac and in Factory mode GNSS
78  * is started after default data are set.
79  *
80  * @subsubsection le_gnss_ForceHotRestart Restart the GNSS device in HOT mode
81  * The le_gnss_ForceHotRestart() function performs a "HOT" restart of the GNSS device. The current
82  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
83  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
84  *
85  * @subsubsection le_gnss_ForceWarmRestart Restart the GNSS device in WARM mode
86  * The le_gnss_ForceWarmRestart() function performs a "WARM" restart of the GNSS device. The current
87  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
88  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
89  * @Note This API has a platform dependent feature. Please refer to
90  * @ref platformConstraintsGnss_WarmRestart for further details.
91  *
92  * @subsubsection le_gnss_ForceColdRestart Restart the GNSS device in COLD mode
93  * The le_gnss_ForceColdRestart() function performs a "COLD" restart of the GNSS device. The current
94  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
95  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
96  *
97  * @subsubsection le_gnss_ForceFactoryRestart Restart the GNSS device in FACTORY mode
98  * The le_gnss_ForceFactoryRestart() function performs a "FACTORY" restart of the GNSS device.
99  * The current GNSS session is stopped, then started using the available @ref le_gnss_Data.
100  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
101  *
102  * @subsubsection le_gnss_Data GNSS data
103  * The following table describes the <b>minimum</b> required data for those starting modes:
104  *
105  * | GNSS Data / Starting mode | HOT | WARM | COLD | FACTORY |
106  *| -----------------------| -----| ------| ----- | ------- |
107  *| Broadcasted Ephemeris | Used | | | |
108  *| Extended Ephemeris | Used(1) | Used(2) | Used(2) | Removed (3) |
109  *| Approximate Time and Position | Used | Used | | |
110  *| Almanac | Used | Used | Used | Used (Factory) |
111  *
112  * For example, a requested HOT start without valid broadcasted ephemeris will be treated
113  * as a WARM start.
114  *
115  * @note (1) Extended Ephemeris can be used if Broadcasted Ephemeris are not valid.
116  * The Extended Ephemeris could be loaded using the le_gnss_LoadExtendedEphemerisFile()
117  * function.
118  * @note (2) Extended Ephemeris is used if the Extended Ephemeris file is loaded and valid.
119  * @note (3) Extended Ephemeris are removed when a FACTORY start is requested.
120  * The Extended Ephemeris could be loaded again using the le_gnss_LoadExtendedEphemerisFile()
121  * function.
122  *
123  * @subsubsection SettingConfiguration Setting configuration
124  *
125  * @warning The GNSS setting configuration depends on the platform. Please refer to
126  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
127  *
128  * @subsubsection le_gnss_TTFF Time To First Fix (TTFF)
129  * The le_gnss_GetTtff() function provides the TTFF (first between 2-Dimensional or 3-Dimensional
130  * position fix) of the last position fix.
131  * The GNSS fix position is calculated by the GNSS engine. Its state can be retrieved by
132  * le_gnss_GetPositionState() function. The GNSS fix position states are given by le_gnss_FixState_t
133  * enum.
134  * @note The "estimated" fix is obtained when less than 3 Satellites Vehicle (SV) are used to
135  * establish the fix. It includes the case when no SVs are used.
136  *
137  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
138  *
139  * A sample code can be seen in the following page:
140  * - @subpage c_gnssSampleCodeReStart
141  *
142  * @subsubsection le_gnss_InjectUtcTime Inject UTC time
143  * The le_gnss_InjectUtcTime() function injects the UTC time into the location engine. Providing an
144  * accurate UTC time reduces the time to find the first fix.
145  * @note It is mandatory to enable the 'Extended Ephemeris' file injection into the GNSS device with
146  * le_gnss_EnableExtendedEphemerisFile() before injecting time with le_gnss_InjectUtcTime API.
147  * @warning Your GNSS device may require a restart to take into account the enabling of the
148  * 'Extended Ephemeris' file injection.
149  * Please refer to your platform documentation @ref platformConstraintsGnss_SettingConfiguration for
150  * further details.
151  *
152  * @subsection le_gnss_AcquisitionRate Acquisition rate
153  * The GNSS position is computed and delivered each acquisition rate. The acquisition rate defines
154  * the time interval that must elapse between two final GPS positions calculation and reports.
155  * Its default value is 1 second.
156  * The application can configure/retreive the GNSS device acquisition rate with the
157  * le_gnss_SetAcquisitionRate() / le_gnss_GetAcquisitionRate() functions.
158  *
159  * Please refer to @ref le_gnss_APIcallsRequirements.
160  *
161  * @subsection le_gnss_EnableDisableExternalLna Control EXT_GPS_LNA_EN signal
162  * The le_gnss_EnableExternalLna() function enables the EXT_GPS_LNA_EN signal. The pin is set high
163  * when the GNSS state is active, and set low when the GNSS state is inactive.
164  *
165  * The le_gnss_DisableExternalLna() function disables the EXT_GPS_LNA_EN signal. The pin remains off
166  * regardless of the GNSS state.
167  *
168  * Please refer to @ref le_gnss_APIcallsRequirements.
169  *
170  * A sample code can be seen in the following page:
171  * - @subpage c_gnssSampleCodeAcquisitionRate
172  *
173  * @subsection le_gnss_SetGetConstellation GNSS constellation selection
174  *
175  * The le_gnss_SetConstellation() function selects the GNSS constellation(s) used in solution.
176  * If all GNSS constellations are disabled, the GNSS engine is disabled.
177  *
178  * @warning Your GNSS device may require a restart to take into account this change.
179  * Please refer to your platform documentation @ref platformConstraintsGnss_SettingConfiguration for
180  * further details.
181  *
182  * Combinations of constellation for GPS, GLONASS, BDS, GALILEO and QZSS satellites are currently
183  * supported. Constellation for SBAS satellites is not supported.
184  *
185  * @warning Some constellation types are unsupported depending on the platform. Please refer to
186  * @ref platformConstraintsGnss_ConstellationType section for full details.
187  *
188  * All supported GNSS constellations are enabled by default.
189  * The le_gnss_GetConstellation() function gets the GNSS constellation(s) enabled to be used
190  * in solution.
191  *
192  * le_gnss_SetConstellationArea sets the area for a GNSS constellation. le_gnss_GetConstellationArea
193  * gets the area for a GNSS constellation.
194  *
195  * A sample code can be seen in the following page:
196  * - @subpage c_gnssSampleCodeConstellation
197  *
198  * The le_gnss_GetSupportedConstellations() function gets a bit mask of the constellations
199  * supported on the platform.
200  *
201  * @subsection le_gnss_SetGetMinElevation GNSS minimum elevation selection
202  *
203  * The le_gnss_SetMinElevation() function sets the GNSS minimum elevation.
204  * Satellites with elevation lower than the minimum elevation will be ignored.
205  *
206  * The le_gnss_GetMinElevation() function gets the GNSS minimum elevation.
207  *
208  * A sample code can be seen in the following page:
209  * - @subpage c_gnssSampleCodeMinElevation
210  *
211  * @subsection le_gnss_NmeaSentences NMEA sentences selection
212  *
213  * The le_gnss_SetNmeaSentences() function selects the enabled NMEA sentences in the
214  * @ref le_gnss_NMEA with a bit mask. The supported values are listed in @ref le_gnss_NmeaBitMask_t.
215  *
216  * @note This function may be subject to limitations depending on the platform. Please refer to the
217  * @ref platformConstraintsGnss page.
218  *
219  * @warning Your GNSS device may require a restart to take into account this change.
220  * Please refer to your platform documentation @ref platformConstraintsGnss_SettingConfiguration for
221  * further details.
222  *
223  * @warning Some NMEA sentences are unsupported depending on the platform. Please refer to
224  * @ref platformConstraintsGnss_nmeaMask section for full details.
225  *
226  * @note All supported NMEA sentences are enabled by default.
227  *
228  * The le_gnss_GetNmeaSentences() function gets the bit mask of the enabled NMEA sentences in the
229  * @ref le_gnss_NMEA.
230  *
231  * The le_gnss_GetSupportedNmeaSentences() function gets a bit mask of the NMEA sentences supported
232  * on the platform.
233  *
234  * Please refer to @ref le_gnss_APIcallsRequirements.
235  *
236  * A sample code can be seen in the following page:
237  * - @subpage c_gnssSampleCodeNmeaSentences
238  *
239  * @subsection le_gnss_GetMinMaxNmeaRate Get the supported NMEA rates
240  * The le_gnss_GetMinNmeaRate() function gets the minimum NMEA rate supported on the platform
241  * in milliseconds.
242  *
243  * The le_gnss_GetMaxNmeaRate() function gets the maximum NMEA rate supported on the platform
244  * in milliseconds.
245  *
246  * @subsection le_gnss_APIcallsRequirements API calls Requirements
247  * The following table shows the pre-requisites when using the GNSS service API function set.
248  * ''LE_OK or error code'' means the function is authorized in the corresponding state, the request
249  * is performed and the result is returned; otherwise the returned error is indicated for each state
250  *.
251  * | Function / GNSS state | UNINITIALIZED | READY | ACTIVE | DISABLED |
252  *| ----------------------------- | --------------------------- | -----------------------------| --------------------------- | --------------------------- |
253  *| le_gnss_Start() | LE_NOT_PERMITTED | LE_OK or error code | LE_DUPLICATE | LE_NOT_PERMITTED |
254  *| le_gnss_Stop() | LE_NOT_PERMITTED | LE_DUPLICATE | LE_OK or error code | LE_NOT_PERMITTED |
255  *| le_gnss_ForceHotRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
256  *| le_gnss_ForceWarmRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
257  *| le_gnss_ForceColdRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
258  *| le_gnss_ForceFactoryRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
259  *| le_gnss_Disable() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_DUPLICATE |
260  *| le_gnss_Enable() | LE_NOT_PERMITTED | LE_DUPLICATE | LE_DUPLICATE | LE_OK or error code |
261  *| le_gnss_SetConstellation() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
262  *| le_gnss_GetConstellation() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
263  *| le_gnss_SetConstellationArea() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
264  *| le_gnss_GetConstellationArea() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
265  *| le_gnss_GetTtff() | LE_NOT_PERMITTED | LE_OK or error code | LE_OK or error code | LE_NOT_PERMITTED |
266  *| le_gnss_SetAcquisitionRate() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
267  *| le_gnss_GetAcquisitionRate() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
268  *| le_gnss_SetNmeaSentences() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
269  *| le_gnss_GetNmeaSentences() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
270  *| le_gnss_EnableExternalLna() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
271  *| le_gnss_DisableExternalLna() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
272  *
273  * Also see @ref howToGNSS.
274  *
275  * @section le_gnss_Information GNSS position information
276  * @ref le_gnss_NMEA
277  *
278  * @ref le_gnss_GetInfo
279  *
280  * @ref le_gnss_GetLeapSeconds
281  *
282  * @subsection le_gnss_NMEA NMEA Flow
283  * The National Marine Electronics Association (NMEA) standard defines an electrical interface
284  * and data protocol for communications between marine instrumentation.
285  *
286  * The NMEA-0183, scope of this document, defines a set of frame prefixed by
287  * $GP (concerning Global Positioning System),
288  * $GL (concerning GLONASS)
289  * and $GN (concerning combination of navigation systems).
290  * For more details about NMEA standards, please refer to http://www.nmea.org/.
291  *
292  * That NMEA frames flow can be retrieved from the "/dev/nmea" device folder, using for example
293  * the shell command $<EM> cat /dev/nmea | grep '$G'</EM>
294  *
295  * @subsection le_gnss_GetInfo Get position information
296  * The position information is referenced to a position sample object.
297  *
298  * An application can register a handler to be notified of the
299  * updated position each @ref le_gnss_AcquisitionRate, returning a position sample object.
300  *
301  * The GNSS information commonly used such as
302  * device state, position, time and date, satellites information and accuracy
303  * can be queried using the following functions:
304  * - le_gnss_GetState()
305  * - le_gnss_GetPositionState()
306  * - le_gnss_GetLocation()
307  * - le_gnss_GetAltitude()
308  * - le_gnss_GetDate()
309  * - le_gnss_GetTime()
310  * - le_gnss_GetGpsTime()
311  * - le_gnss_GetGpsLeapSeconds()
312  * - le_gnss_GetEpochTime()
313  * - le_gnss_GetTimeAccuracy()
314  * - le_gnss_GetHorizontalSpeed()
315  * - le_gnss_GetVerticalSpeed()
316  * - le_gnss_GetDirection()
317  * - le_gnss_GetSatellitesInfo()
318  * - le_gnss_GetSbasConstellationCategory()
319  * - le_gnss_GetSatellitesStatus()
320  * - le_gnss_GetDop()
321  * - le_gnss_GetDilutionOfPrecision()
322  * - le_gnss_GetAltitudeOnWgs84()
323  * - le_gnss_GetMagneticDeviation()
324  *
325  * le_gnss_SetDataResolution() function can be called to configure the resolution of position data
326  * type per client session. Currently, three data types are supported:
327  * - Vertical position accuracy provided by le_gnss_GetAltitude().
328  * - Vertical speed accuracy provided by le_gnss_GetVerticalSpeed().
329  * - Horizontal speed accuracy provided by le_gnss_GetHorizontalSpeed().
330  * Each data type can be set with a resolution from 0 to 3 decimal place.
331  *
332  * For example, to get the vertical position accuracy with a resolution of 2 decimal places,
333  * le_gnss_SetDataResolution() function is called with vertical position accuracy set as data type
334  * and 2 decimal place is set as resolution, then le_gnss_GetAltitude() function is called.
335  *
336  * @note If le_gnss_SetDataResolution() function is not called, the position data types are received
337  * in their default accuracies.
338  *
339  * le_gnss_ConvertDataCoordinateSystem() function can be called to convert a location data value
340  * from a coordinate system to another. Currently it is possible to convert the following data
341  * types:
342  * - Latitude
343  * - Longitude
344  * - Altitude
345  *
346  * System coordinates source and destination are currently:
347  * - Coordinate system WGS84
348  * - Coordinate system PZ90
349  *
350  * @note Only conversion from WGS84 coordinate system to PZ90 coordinate system is currently
351  * supported.
352  * @note The altitude in coordinate system WGS84 is obtained by le_gnss_GetAltitudeOnWgs84()
353  * function.
354  *
355  * A sample code using le_gnss_ConvertDataCoordinate() function can be seen in the following page:
356  * - @subpage c_gnssSampleCodePosition
357  *
358  * le_gnss_GetDilutionOfPrecision() gets the DOP parameters (Dilution Of Precision) with a
359  * resolution of 3 decimal places by default. This resolution can be modified by calling the
360  * @c le_gnss_SetDopResolution() function first.
361  *
362  * As @c le_gnss_SetDopResolution() sets the resolution per client session,
363  * @c le_gnss_SetDopResolution() and @c le_gnss_GetDilutionOfPrecision() functions should be called
364  * in the same thread or client session.
365  *
366  * A sample code can be seen in the following page:
367  * - @subpage c_gnssSampleCodePosition
368  *
369  * The handler can be managed using le_gnss_AddPositionHandler()
370  * and le_gnss_RemovePositionHandler().
371  * When a position is computed, the handler is called.
372  *
373  * The application has to release each position sample object received by the handler,
374  * using the le_gnss_ReleaseSampleRef().
375  *
376  * A sample code can be seen in the following page:
377  * - @subpage c_gnssSampleCodePosition
378  *
379  * @subsection le_gnss_GetLeapSeconds Get leap seconds event information
380  * The leap seconds event information is retrieved by calling le_gnss_GetLeapSeconds() API.
381  * The result includes current GPS time, current leap seconds, next leap second event time,
382  * and next leap seconds.
383  *
384  * Insertion of each UTC leap second is usually decided about six months in advance by the
385  * International Earth Rotation and Reference Systems Service (IERS).
386  *
387  * @section le_gnss_Assisted_GNSS Assisted GNSS
388  *
389  * @ref le_gnss_Assisted_GNSS_EE
390  * @ref le_gnss_Assisted_GNSS_UP
391  *
392  * @subsection le_gnss_Assisted_GNSS_EE Server based Extended Ephemeris
393  *
394  * @todo Add detailed documentation.
395  *
396  * With le_gnss_LoadExtendedEphemerisFile() , you can load an 'Extended Ephemeris' file into
397  * the GNSS device from the filesystem.
398  * You have to download the file before loading it.
399  * @warning Ensure to check that the downloaded file is supported for your specific platform.
400  *
401  * With le_gnss_GetExtendedEphemerisValidity(), you will to get the validity of the last injected
402  * Extended Ephemeris.
403  *
404  * You can enable/disable the use of the 'Extended Ephemeris' file into the GNSS device with
405  * le_gnss_EnableExtendedEphemerisFile() / le_gnss_DisableExtendedEphemerisFile() functions.
406  * @warning Ensure to check configuration capabilities for your specific platform.
407  * A reboot must be required if your platform doesn't allow run-time configuration.
408  *
409  * A sample code can be seen in the following page:
410  * - @subpage c_gnssSampleCodeXtra
411  *
412  * @subsection le_gnss_Assisted_GNSS_UP 3GPP User Plane (OMA SUPL)
413  *
414  * That 3GPP User Plane A-GNSS (Assisted GNSS) protocol is defined by two different standardization
415  * bodies, 3GPP and Open Mobile Alliance (OMA). For more information, please refer to the standard.
416  *
417  * Both MS-Assisted and MS-Based position determination methods are supported in the User Plane.
418  *
419  * In MS-Assisted mode, the MS (Mobile Station) measures the signals from the GNSS satellites
420  *, then returns the retrieved GNSS data to the SUPL (Secure User Plan Location) server, where the
421  * position calculation is performed.
422  *
423  * In MS-Based mode, the MS gets the assistance data from the SUPL (Secure User Plan Location)
424  * server. The MS measures the signals from the GNSS satellites and makes the position calculation.
425  *
426  * The data transport over User Plan is done using the TCP/IP protocol.
427  *
428  * The Assisted-GNSS mode can be configured thru the le_gnss_SetSuplAssistedMode() function.
429  *
430  * The supported modes are the following:
431  * - Standalone mode: That 3GPP User Plane A-GNSS feature is deactivated.
432  * - MS-Based mode
433  * - MS-Assisted mode
434  *
435  * Moreover, the le_gnss_GetSuplAssistedMode() function reads the configured Assisted-GNSS mode.
436  *
437  * The SUPL server is configured using the le_gnss_SetSuplServerUrl() function. That function sets
438  * the SUPL server URL and optionally the port number.
439  *
440  * The SUPL certificate to be used in A-GNSS sessions is injected through the
441  * le_gnss_InjectSuplCertificate() function and deleted through the le_gnss_DeleteSuplCertificate()
442  * function.
443  * The SUPL certificate lenght given as parameter to le_gnss_InjectSuplCertificate() must be less
444  * than LE_GNSS_SUPL_CERTIFICATE_MAX_LEN.
445  *
446  * <HR>
447  *
448  * Copyright (C) Sierra Wireless Inc.
449  */
450 /**
451  * @page c_gnssSampleCode Sample code for GNSS device
452  *
453  * @include "apps/test/positioning/gnssTest/gnssTest/gnssTest.c"
454  */
455 /**
456  * @page c_gnssSampleCodeEnableDisable Sample code for Enable/Disable GNSS device
457  *
458  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssEnable
459  */
460 /**
461  * @page c_gnssSampleCodeStartStop Sample code for Start/Stop GNSS device
462  *
463  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
464  */
465 /**
466  * @page c_gnssSampleCodeReStart Sample code for restart GNSS device and get TTFF
467  *
468  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssReStart
469  */
470 /**
471  * @page c_gnssSampleCodeAcquisitionRate Sample code for GNSS acquisition rate configuration
472  *
473  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
474  */
475 /**
476  * @page c_gnssSampleCodeConstellation Sample code for GNSS constellation selection
477  *
478  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
479  */
480 /**
481  * @page c_gnssSampleCodeMinElevation Sample code for GNSS minimum elevation
482  *
483  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
484  */
485 /**
486  * @page c_gnssSampleCodeNmeaSentences Sample code for GNSS NMEA sentences selection
487  *
488  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
489  */
490 /**
491  * @page c_gnssSampleCodePosition Sample code for GNSS position information
492  *
493  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssPosition
494  */
495 /**
496  * @page c_gnssSampleCodeXtra Sample code for GNSS Server based Extended Ephemeris
497  *
498  * @include "apps/test/positioning/gnssXtraTest/gnssXtraTest/xtraTest.c"
499  */
500 /**
501  * @file le_gnss_interface.h
502  *
503  * Legato @ref c_gnss include file.
504  *
505  * Copyright (C) Sierra Wireless Inc.
506  */
507 
508 #ifndef LE_GNSS_INTERFACE_H_INCLUDE_GUARD
509 #define LE_GNSS_INTERFACE_H_INCLUDE_GUARD
510 
511 
512 #include "legato.h"
513 
514 // Internal includes for this interface
515 #include "le_gnss_common.h"
516 //--------------------------------------------------------------------------------------------------
517 /**
518  * Type for handler called when a server disconnects.
519  */
520 //--------------------------------------------------------------------------------------------------
521 typedef void (*le_gnss_DisconnectHandler_t)(void *);
522 
523 //--------------------------------------------------------------------------------------------------
524 /**
525  *
526  * Connect the current client thread to the service providing this API. Block until the service is
527  * available.
528  *
529  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
530  * called before any other functions in this API. Normally, ConnectService is automatically called
531  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
532  *
533  * This function is created automatically.
534  */
535 //--------------------------------------------------------------------------------------------------
537 (
538  void
539 );
540 
541 //--------------------------------------------------------------------------------------------------
542 /**
543  *
544  * Try to connect the current client thread to the service providing this API. Return with an error
545  * if the service is not available.
546  *
547  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
548  * called before any other functions in this API. Normally, ConnectService is automatically called
549  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
550  *
551  * This function is created automatically.
552  *
553  * @return
554  * - LE_OK if the client connected successfully to the service.
555  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
556  * bound.
557  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
558  * - LE_COMM_ERROR if the Service Directory cannot be reached.
559  */
560 //--------------------------------------------------------------------------------------------------
562 (
563  void
564 );
565 
566 //--------------------------------------------------------------------------------------------------
567 /**
568  * Set handler called when server disconnection is detected.
569  *
570  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
571  * to continue without exiting, it should call longjmp() from inside the handler.
572  */
573 //--------------------------------------------------------------------------------------------------
575 (
576  le_gnss_DisconnectHandler_t disconnectHandler,
577  void *contextPtr
578 );
579 
580 //--------------------------------------------------------------------------------------------------
581 /**
582  *
583  * Disconnect the current client thread from the service providing this API.
584  *
585  * Normally, this function doesn't need to be called. After this function is called, there's no
586  * longer a connection to the service, and the functions in this API can't be used. For details, see
587  * @ref apiFilesC_client.
588  *
589  * This function is created automatically.
590  */
591 //--------------------------------------------------------------------------------------------------
593 (
594  void
595 );
596 
597 
598 //--------------------------------------------------------------------------------------------------
599 /**
600  * Reference type for dealing with GNSS position samples.
601  */
602 //--------------------------------------------------------------------------------------------------
603 
604 
605 //--------------------------------------------------------------------------------------------------
606 /**
607  * Enumeration for GNSS device state
608  */
609 //--------------------------------------------------------------------------------------------------
610 
611 
612 //--------------------------------------------------------------------------------------------------
613 /**
614  * GNSS fix position states.
615  */
616 //--------------------------------------------------------------------------------------------------
617 
618 
619 //--------------------------------------------------------------------------------------------------
620 /**
621  * Resolutions values.
622  */
623 //--------------------------------------------------------------------------------------------------
624 
625 
626 //--------------------------------------------------------------------------------------------------
627 /**
628  ** Data types.
629  */
630 //--------------------------------------------------------------------------------------------------
631 
632 
633 //--------------------------------------------------------------------------------------------------
634 /**
635  * SBAS constellation category
636  */
637 //--------------------------------------------------------------------------------------------------
638 
639 
640 //--------------------------------------------------------------------------------------------------
641 /**
642  * GNSS constellation type.
643  */
644 //--------------------------------------------------------------------------------------------------
645 
646 
647 //--------------------------------------------------------------------------------------------------
648 /**
649  * Assisted-GNSS mode
650  */
651 //--------------------------------------------------------------------------------------------------
652 
653 
654 //--------------------------------------------------------------------------------------------------
655 /**
656  * Dilution of precision type
657  */
658 //--------------------------------------------------------------------------------------------------
659 
660 
661 //--------------------------------------------------------------------------------------------------
662 /**
663  * GNSS constellation area type
664  */
665 //--------------------------------------------------------------------------------------------------
666 
667 
668 //--------------------------------------------------------------------------------------------------
669 /**
670  * GNSS constellation Bit Mask (8 bits) indicating the GNSS constellation(s)
671  * used in solution.
672  *
673  */
674 //--------------------------------------------------------------------------------------------------
675 
676 
677 //--------------------------------------------------------------------------------------------------
678 /**
679  * NMEA sentences Bit Mask indicating the NMEA sentences enabled in the NMEA flow.
680  *
681  * @warning The supported NMEA sentences depend on the platform. Please refer to your platform
682  * documentation for further details.
683  *
684  * @note The bit mask values should be coherent with @ref LE_GNSS_NMEA_SENTENCES_MAX
685  */
686 //--------------------------------------------------------------------------------------------------
687 
688 
689 //--------------------------------------------------------------------------------------------------
690 /**
691  * Coordinate system
692  */
693 //--------------------------------------------------------------------------------------------------
694 
695 
696 //--------------------------------------------------------------------------------------------------
697 /**
698  ** Location data types
699  */
700 //--------------------------------------------------------------------------------------------------
701 
702 
703 //--------------------------------------------------------------------------------------------------
704 /**
705  * Type of GNSS start.
706  */
707 //--------------------------------------------------------------------------------------------------
708 
709 
710 //--------------------------------------------------------------------------------------------------
711 /**
712  * Handler for position information.
713  *
714  */
715 //--------------------------------------------------------------------------------------------------
716 
717 
718 //--------------------------------------------------------------------------------------------------
719 /**
720  * Reference type used by Add/Remove functions for EVENT 'le_gnss_Position'
721  */
722 //--------------------------------------------------------------------------------------------------
723 
724 
725 //--------------------------------------------------------------------------------------------------
726 /**
727  * Set the GNSS constellation bit mask
728  *
729  * @return
730  * - LE_FAULT The function failed.
731  * - LE_UNSUPPORTED If the request is not supported.
732  * - LE_NOT_PERMITTED If the GNSS device is not initialized, disabled or active.
733  * - LE_OK The function succeeded.
734  *
735  * @warning Some constellation types are unsupported depending on the platform. Please refer to
736  * @ref platformConstraintsGnss_ConstellationType section for full details.
737  *
738  * @warning The settings are platform dependent. Please refer to
739  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
740  */
741 //--------------------------------------------------------------------------------------------------
743 (
744  le_gnss_ConstellationBitMask_t constellationMask
745  ///< [IN] GNSS constellation used in solution.
746 );
747 
748 //--------------------------------------------------------------------------------------------------
749 /**
750  * Get the GNSS constellation bit mask
751  *
752  * @return
753  * - LE_OK on success
754  * - LE_FAULT on failure
755  *
756  * @note If the caller is passing a null pointer into this function, it is a fatal error, the
757  * function will not return.
758  */
759 //--------------------------------------------------------------------------------------------------
761 (
762  le_gnss_ConstellationBitMask_t* constellationMaskPtr
763  ///< [OUT] GNSS constellation used in solution.
764 );
765 
766 //--------------------------------------------------------------------------------------------------
767 /**
768  * Set the area for the GNSS constellation
769  *
770  * @return
771  * - LE_OK The function succeeded.
772  * - LE_FAULT The function failed.
773  * - LE_UNSUPPORTED If the request is not supported.
774  * - LE_NOT_PERMITTED If the GNSS device is not initialized, disabled or active.
775  * - LE_BAD_PARAMETER Invalid constellation area.
776  *
777  * @warning The settings are platform dependent. Please refer to
778  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
779  */
780 //--------------------------------------------------------------------------------------------------
782 (
783  le_gnss_Constellation_t satConstellation,
784  ///< [IN] GNSS constellation type.
785  le_gnss_ConstellationArea_t constellationArea
786  ///< [IN] GNSS constellation area.
787 );
788 
789 //--------------------------------------------------------------------------------------------------
790 /**
791  * Get the area for the GNSS constellation
792  *
793  * @return
794  * - LE_OK On success
795  * - LE_FAULT On failure
796  * - LE_UNSUPPORTED Request not supported
797  * - LE_NOT_PERMITTED If the GNSS device is not initialized, disabled or active.
798  *
799  * @note If the caller is passing a null pointer into this function, it is a fatal error, the
800  * function will not return.
801  */
802 //--------------------------------------------------------------------------------------------------
804 (
805  le_gnss_Constellation_t satConstellation,
806  ///< [IN] GNSS constellation type.
807  le_gnss_ConstellationArea_t* constellationAreaPtr
808  ///< [OUT] GNSS constellation area.
809 );
810 
811 //--------------------------------------------------------------------------------------------------
812 /**
813  * This function enables the use of the 'Extended Ephemeris' file into the GNSS device.
814  *
815  * @return
816  * - LE_FAULT The function failed.
817  * - LE_OK The function succeeded.
818  *
819  * @warning The settings are platform dependent. Please refer to
820  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
821  */
822 //--------------------------------------------------------------------------------------------------
824 (
825  void
826 );
827 
828 //--------------------------------------------------------------------------------------------------
829 /**
830  * This function disables the use of the 'Extended Ephemeris' file into the GNSS device.
831  *
832  * @return
833  * - LE_FAULT The function failed.
834  * - LE_OK The function succeeded.
835  *
836  * @warning The settings are platform dependent. Please refer to
837  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
838  */
839 //--------------------------------------------------------------------------------------------------
841 (
842  void
843 );
844 
845 //--------------------------------------------------------------------------------------------------
846 /**
847  * This function must be called to load an 'Extended Ephemeris' file into the GNSS device.
848  *
849  * @return
850  * - LE_FAULT The function failed to inject the 'Extended Ephemeris' file.
851  * - LE_TIMEOUT A time-out occurred.
852  * - LE_FORMAT_ERROR 'Extended Ephemeris' file format error.
853  * - LE_OK The function succeeded.
854  *
855  */
856 //--------------------------------------------------------------------------------------------------
858 (
859  int fd
860  ///< [IN] Extended ephemeris file descriptor
861 );
862 
863 //--------------------------------------------------------------------------------------------------
864 /**
865  * This function must be called to get the validity of the last injected Extended Ephemeris.
866  *
867  * @return
868  * - LE_FAULT The function failed to get the validity
869  * - LE_OK The function succeeded.
870  *
871  * @note If the caller is passing an invalid Position sample reference or null pointers into this
872  * function, it is a fatal error, the function will not return.
873  */
874 //--------------------------------------------------------------------------------------------------
876 (
877  uint64_t* startTimePtr,
878  ///< [OUT] Start time in seconds (since Jan. 1, 1970)
879  uint64_t* stopTimePtr
880  ///< [OUT] Stop time in seconds (since Jan. 1, 1970)
881 );
882 
883 //--------------------------------------------------------------------------------------------------
884 /**
885  * This function must be called to inject the UTC time into the GNSS device.
886  *
887  * @return
888  * - LE_OK The function succeeded.
889  * - LE_FAULT The function failed to inject the UTC time.
890  * - LE_TIMEOUT A time-out occurred.
891  *
892  * @note It is mandatory to enable the 'Extended Ephemeris' file injection into the GNSS device with
893  * le_gnss_EnableExtendedEphemerisFile() before injecting time with this API.
894  */
895 //--------------------------------------------------------------------------------------------------
897 (
898  uint64_t timeUtc,
899  ///< [IN] [IN] UTC time since Jan. 1, 1970 in milliseconds
900  uint32_t timeUnc
901  ///< [IN] [IN] Time uncertainty in milliseconds
902 );
903 
904 //--------------------------------------------------------------------------------------------------
905 /**
906  * This function starts the GNSS device.
907  *
908  * @return
909  * - LE_FAULT The function failed.
910  * - LE_DUPLICATE If the GNSS device is already started.
911  * - LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
912  * - LE_OK The function succeeded.
913  *
914  */
915 //--------------------------------------------------------------------------------------------------
917 (
918  void
919 );
920 
921 //--------------------------------------------------------------------------------------------------
922 /**
923  * This function starts the GNSS device in the specified start mode.
924  *
925  * @return
926  * - LE_OK The function succeeded.
927  * - LE_BAD_PARAMETER Invalid start mode
928  * - LE_FAULT The function failed.
929  * - LE_DUPLICATE If the GNSS device is already started.
930  * - LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
931  *
932  * @warning This function may be subject to limitations depending on the platform. Please refer to
933  * the @ref platformConstraintsGnss page.
934  */
935 //--------------------------------------------------------------------------------------------------
937 (
938  le_gnss_StartMode_t mode
939  ///< [IN] [IN] Start mode
940 );
941 
942 //--------------------------------------------------------------------------------------------------
943 /**
944  * This function stops the GNSS device.
945  *
946  * @return
947  * - LE_FAULT The function failed.
948  * - LE_DUPLICATE If the GNSS device is already stopped.
949  * - LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
950  * - LE_OK The function succeeded.
951  *
952  */
953 //--------------------------------------------------------------------------------------------------
955 (
956  void
957 );
958 
959 //--------------------------------------------------------------------------------------------------
960 /**
961  * This function performs a "HOT" restart of the GNSS device.
962  *
963  * @return
964  * - LE_FAULT The function failed.
965  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
966  * - LE_OK The function succeeded.
967  *
968  * @Note This API can be used to restart the GNSS device. It is equivalent calling le_gnss_Stop()
969  * and le_gnss_Start().
970  */
971 //--------------------------------------------------------------------------------------------------
973 (
974  void
975 );
976 
977 //--------------------------------------------------------------------------------------------------
978 /**
979  * This function performs a "WARM" restart of the GNSS device.
980  *
981  * @return
982  * - LE_FAULT The function failed.
983  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
984  * - LE_OK The function succeeded.
985  *
986  * @Note This API has a platform dependent feature. Please refer to
987  * @ref platformConstraintsGnss_WarmRestart for further details.
988  */
989 //--------------------------------------------------------------------------------------------------
991 (
992  void
993 );
994 
995 //--------------------------------------------------------------------------------------------------
996 /**
997  * This function performs a "COLD" restart of the GNSS device.
998  *
999  * @return
1000  * - LE_FAULT The function failed.
1001  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
1002  * - LE_OK The function succeeded.
1003  *
1004  */
1005 //--------------------------------------------------------------------------------------------------
1007 (
1008  void
1009 );
1010 
1011 //--------------------------------------------------------------------------------------------------
1012 /**
1013  * This function performs a "FACTORY" restart of the GNSS device.
1014  *
1015  * @return
1016  * - LE_FAULT The function failed.
1017  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
1018  * - LE_OK The function succeeded.
1019  *
1020  */
1021 //--------------------------------------------------------------------------------------------------
1023 (
1024  void
1025 );
1026 
1027 //--------------------------------------------------------------------------------------------------
1028 /**
1029  * Get the TTFF in milliseconds
1030  *
1031  * @return
1032  * - LE_BUSY The position is not fixed and TTFF can't be measured.
1033  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
1034  * - LE_OK Function succeeded.
1035  * - LE_FAULT If there are some other errors.
1036  *
1037  * @note If the caller is passing a null pointer into this function, it is a fatal error, the
1038  * function will not return.
1039  */
1040 //--------------------------------------------------------------------------------------------------
1042 (
1043  uint32_t* ttffPtr
1044  ///< [OUT] TTFF in milliseconds
1045 );
1046 
1047 //--------------------------------------------------------------------------------------------------
1048 /**
1049  * This function enables the GNSS device.
1050  *
1051  * @return
1052  * - LE_FAULT The function failed.
1053  * - LE_DUPLICATE If the GNSS device is already enabled.
1054  * - LE_NOT_PERMITTED If the GNSS device is not initialized.
1055  * - LE_OK The function succeeded.
1056  *
1057  * @warning The settings are platform dependent. Please refer to
1058  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
1059  */
1060 //--------------------------------------------------------------------------------------------------
1062 (
1063  void
1064 );
1065 
1066 //--------------------------------------------------------------------------------------------------
1067 /**
1068  * This function disables the GNSS device.
1069  *
1070  * @return
1071  * - LE_FAULT The function failed.
1072  * - LE_DUPLICATE If the GNSS device is already disabled.
1073  * - LE_NOT_PERMITTED If the GNSS device is not initialized or started.
1074  * - LE_OK The function succeeded.
1075  *
1076  * @warning The settings are platform dependent. Please refer to
1077  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
1078  */
1079 //--------------------------------------------------------------------------------------------------
1081 (
1082  void
1083 );
1084 
1085 //--------------------------------------------------------------------------------------------------
1086 /**
1087  * This function sets the GNSS device acquisition rate.
1088  *
1089  * @return
1090  * - LE_OK on success
1091  * - LE_FAULT on failure
1092  * - LE_UNSUPPORTED request not supported
1093  * - LE_TIMEOUT a time-out occurred
1094  * - LE_NOT_PERMITTED If the GNSS device is not in "ready" state.
1095  * - LE_OUT_OF_RANGE if acquisition rate value is equal to zero
1096  *
1097  * @warning This function may be subject to limitations depending on the platform. Please refer to
1098  * the @ref platformConstraintsGnss page.
1099  *
1100  * @warning The settings are platform dependent. Please refer to
1101  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
1102  */
1103 //--------------------------------------------------------------------------------------------------
1105 (
1106  uint32_t rate
1107  ///< [IN] Acquisition rate in milliseconds.
1108 );
1109 
1110 //--------------------------------------------------------------------------------------------------
1111 /**
1112  * This function gets the GNSS device acquisition rate.
1113  *
1114  * @return
1115  * - LE_OK on success
1116  * - LE_FAULT on failure
1117  * - LE_NOT_PERMITTED If the GNSS device is not in "ready" state.
1118  *
1119  * @note If the caller is passing a null pointer into this function, it is a fatal error, the
1120  * function will not return.
1121  */
1122 //--------------------------------------------------------------------------------------------------
1124 (
1125  uint32_t* ratePtr
1126  ///< [OUT] Acquisition rate in milliseconds.
1127 );
1128 
1129 //--------------------------------------------------------------------------------------------------
1130 /**
1131  * Add handler function for EVENT 'le_gnss_Position'
1132  *
1133  * This event provides information on position.
1134  *
1135  * - A handler reference, which is only needed for later removal of the handler.
1136  *
1137  * @note Doesn't return on failure, so there's no need to check the return value for errors.
1138  */
1139 //--------------------------------------------------------------------------------------------------
1140 le_gnss_PositionHandlerRef_t le_gnss_AddPositionHandler
1141 (
1142  le_gnss_PositionHandlerFunc_t handlerPtr,
1143  ///< [IN]
1144  void* contextPtr
1145  ///< [IN]
1146 );
1147 
1148 //--------------------------------------------------------------------------------------------------
1149 /**
1150  * Remove handler function for EVENT 'le_gnss_Position'
1151  */
1152 //--------------------------------------------------------------------------------------------------
1154 (
1155  le_gnss_PositionHandlerRef_t handlerRef
1156  ///< [IN]
1157 );
1158 
1159 //--------------------------------------------------------------------------------------------------
1160 /**
1161  * This function gets the position sample's fix state
1162  *
1163  * - LE_OK on success
1164  * - LE_FAULT on failure
1165  *
1166  * @note If the caller is passing an invalid Position sample reference or a null pointer into this
1167  * function, it is a fatal error, the function will not return.
1168  */
1169 //--------------------------------------------------------------------------------------------------
1171 (
1172  le_gnss_SampleRef_t positionSampleRef,
1173  ///< [IN] Position sample's reference.
1174  le_gnss_FixState_t* statePtr
1175  ///< [OUT] Position fix state.
1176 );
1177 
1178 //--------------------------------------------------------------------------------------------------
1179 /**
1180  * Get the location's data (Latitude, Longitude, Horizontal accuracy).
1181  *
1182  * @return
1183  * - LE_FAULT Function failed to get the location's data
1184  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is invalid (set to INT32_MAX).
1185  * - LE_OK Function succeeded.
1186  *
1187  * @note latitudePtr, longitudePtr and hAccuracyPtr can be set to NULL if not needed.
1188  *
1189  * @note The latitude and longitude values are based on the WGS84 standard coordinate system.
1190  *
1191  * @note The latitude and longitude values are given in degrees with 6 decimal places like:
1192  * Latitude +48858300 = 48.858300 degrees North
1193  * Longitude +2294400 = 2.294400 degrees East
1194  * (The latitude and longitude values are given in degrees, minutes, seconds in NMEA frame)
1195  *
1196  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1197  * valid. Please compare them with INT32_MAX.
1198  *
1199  * @note If the caller is passing an invalid Position sample reference into this function,
1200  * it is a fatal error, the function will not return.
1201  */
1202 //--------------------------------------------------------------------------------------------------
1204 (
1205  le_gnss_SampleRef_t positionSampleRef,
1206  ///< [IN] Position sample's reference.
1207  int32_t* latitudePtr,
1208  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
1209  int32_t* longitudePtr,
1210  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
1211  int32_t* hAccuracyPtr
1212  ///< [OUT] Horizontal position's accuracy in meters [resolution 1e-2].
1213 );
1214 
1215 //--------------------------------------------------------------------------------------------------
1216 /**
1217  * Get the position sample's altitude.
1218  *
1219  * @return
1220  * - LE_FAULT Function failed to get the altitude. Invalid Position reference provided.
1221  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is invalid (set to INT32_MAX).
1222  * - LE_OK Function succeeded.
1223  *
1224  * @note Altitude is in meters, above Mean Sea Level, with 3 decimal places (3047 = 3.047 meters).
1225  *
1226  * @note For a 2D position fix, the altitude will be indicated as invalid and set to INT32_MAX
1227  *
1228  * @note Vertical position accuracy is default set to meters with 1 decimal place (3047 = 3.0
1229  * meters). To change its accuracy, call the @c le_gnss_SetDataResolution() function. Vertical
1230  * position accuracy is set as data type and accuracy from 0 to 3 decimal place is set as
1231  * resolution.
1232  *
1233  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1234  * valid. Please compare them with INT32_MAX.
1235  *
1236  * @note If the caller is passing an invalid Position reference into this function,
1237  * it is a fatal error, the function will not return.
1238  *
1239  * @note altitudePtr, altitudeAccuracyPtr can be set to NULL if not needed.
1240  */
1241 //--------------------------------------------------------------------------------------------------
1243 (
1244  le_gnss_SampleRef_t positionSampleRef,
1245  ///< [IN] Position sample's reference.
1246  int32_t* altitudePtr,
1247  ///< [OUT] Altitude in meters, above Mean Sea Level [resolution 1e-3].
1248  int32_t* vAccuracyPtr
1249  ///< [OUT] Vertical position's accuracy in meters.
1250 );
1251 
1252 //--------------------------------------------------------------------------------------------------
1253 /**
1254  * Get the position sample's time.
1255  *
1256  * @return
1257  * - LE_FAULT Function failed to get the time.
1258  * - LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
1259  * - LE_OK Function succeeded.
1260  *
1261  * @note If the caller is passing an invalid Position sample reference or null pointers into this
1262  * function, it is a fatal error, the function will not return.
1263  *
1264  */
1265 //--------------------------------------------------------------------------------------------------
1267 (
1268  le_gnss_SampleRef_t positionSampleRef,
1269  ///< [IN] Position sample's reference.
1270  uint16_t* hoursPtr,
1271  ///< [OUT] UTC Hours into the day [range 0..23].
1272  uint16_t* minutesPtr,
1273  ///< [OUT] UTC Minutes into the hour [range 0..59].
1274  uint16_t* secondsPtr,
1275  ///< [OUT] UTC Seconds into the minute [range 0..59].
1276  uint16_t* millisecondsPtr
1277  ///< [OUT] UTC Milliseconds into the second [range 0..999].
1278 );
1279 
1280 //--------------------------------------------------------------------------------------------------
1281 /**
1282  * Get the position sample's GPS time.
1283  *
1284  * @return
1285  * - LE_FAULT Function failed to get the time.
1286  * - LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
1287  * - LE_OK Function succeeded.
1288  *
1289  * @note If the caller is passing an invalid Position sample reference or null pointers into this
1290  * function, it is a fatal error, the function will not return.
1291  */
1292 //--------------------------------------------------------------------------------------------------
1294 (
1295  le_gnss_SampleRef_t positionSampleRef,
1296  ///< [IN] Position sample's reference.
1297  uint32_t* gpsWeekPtr,
1298  ///< [OUT] GPS week number from midnight, Jan. 6, 1980.
1299  uint32_t* gpsTimeOfWeekPtr
1300  ///< [OUT] Amount of time in milliseconds into the GPS week.
1301 );
1302 
1303 //--------------------------------------------------------------------------------------------------
1304 /**
1305  * Get the position sample's epoch time.
1306  *
1307  * @return
1308  * - LE_FAULT Function failed to acquire the epoch time.
1309  * - LE_OK Function succeeded.
1310  * - LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
1311  *
1312  * @note The epoch time is the number of seconds elapsed since January 1, 1970
1313  * (midnight UTC/GMT), not counting leaps seconds.
1314  *
1315  * @note If the caller is passing an invalid position sample reference or a null pointer into this
1316  * function, it is a fatal error, the function will not return.
1317  */
1318 //--------------------------------------------------------------------------------------------------
1320 (
1321  le_gnss_SampleRef_t positionSampleRef,
1322  ///< [IN] Position sample's reference.
1323  uint64_t* millisecondsPtr
1324  ///< [OUT] Milliseconds since Jan. 1, 1970.
1325 );
1326 
1327 //--------------------------------------------------------------------------------------------------
1328 /**
1329  * Get the position sample's time accurary.
1330  *
1331  * @return
1332  * - LE_FAULT Function failed to get the time.
1333  * - LE_OUT_OF_RANGE The retrieved time accuracy is invalid (set to UINT16_MAX).
1334  * - LE_OK Function succeeded.
1335  *
1336  * @note If the caller is passing an invalid position sample reference or a null pointer into this
1337  * function, it is a fatal error, the function will not return.
1338  */
1339 //--------------------------------------------------------------------------------------------------
1341 (
1342  le_gnss_SampleRef_t positionSampleRef,
1343  ///< [IN] Position sample's reference.
1344  uint32_t* timeAccuracyPtr
1345  ///< [OUT] Estimated time accuracy in nanoseconds
1346 );
1347 
1348 //--------------------------------------------------------------------------------------------------
1349 /**
1350  * Get the position sample's UTC leap seconds in advance
1351  *
1352  * @return
1353  * - LE_FAULT Function failed to get the leap seconds.
1354  * - LE_OUT_OF_RANGE The retrieved time accuracy is invalid (set to UINT8_MAX).
1355  * - LE_OK Function succeeded.
1356  *
1357  * @note The leap seconds in advance is the accumulated time in seconds since the start of GPS Epoch
1358  * time (Jan 6, 1980). This value has to be added to the UTC time (since Jan. 1, 1970)
1359  *
1360  * @note Insertion of each UTC leap second is usually decided about six months in advance by the
1361  * International Earth Rotation and Reference Systems Service (IERS).
1362  *
1363  * @note If the caller is passing an invalid position sample reference or a null pointer into this
1364  * function, it is a fatal error, the function will not return.
1365  *
1366  * @deprecated This function is deprecated, le_gnss_GetLeapSeconds should be used instead.
1367  */
1368 //--------------------------------------------------------------------------------------------------
1370 (
1371  le_gnss_SampleRef_t positionSampleRef,
1372  ///< [IN] Position sample's reference.
1373  uint8_t* leapSecondsPtr
1374  ///< [OUT] UTC leap seconds in advance in seconds
1375 );
1376 
1377 //--------------------------------------------------------------------------------------------------
1378 /**
1379  * Get leap seconds information.
1380  *
1381  * @return
1382  * - LE_OK Function succeeded.
1383  * - LE_FAULT Function failed to get the data.
1384  * - LE_TIMEOUT Timeout occured.
1385  * - LE_UNSUPPORTED Not supported on this platform.
1386  *
1387  * @note Insertion of each UTC leap second is usually decided about six months in advance by the
1388  * International Earth Rotation and Reference Systems Service (IERS).
1389  *
1390  * @note If the caller is passing a null pointer into this function, it is considered a fatal
1391  * error and the function will not return.
1392  *
1393  * @note If the return value of a parameter is INT32_MAX/UINT64_MAX, the parameter is not valid.
1394  */
1395 //--------------------------------------------------------------------------------------------------
1397 (
1398  uint64_t* gpsTimePtr,
1399  ///< [OUT] The number of milliseconds of GPS time since midnight,
1400  ///< Jan. 6, 1980.
1401  int32_t* currentLeapSecondsPtr,
1402  ///< [OUT] Current UTC leap seconds value in milliseconds.
1403  uint64_t* changeEventTimePtr,
1404  ///< [OUT] The number of milliseconds since midnight, Jan. 6, 1980
1405  ///< to the next leap seconds change event.
1406  int32_t* nextLeapSecondsPtr
1407  ///< [OUT] UTC leap seconds value to be applied at the change
1408  ///< event time in milliseconds.
1409 );
1410 
1411 //--------------------------------------------------------------------------------------------------
1412 /**
1413  * Get the position sample's date.
1414  *
1415  * @return
1416  * - LE_FAULT Function failed to get the date.
1417  * - LE_OUT_OF_RANGE The retrieved date is invalid (all fields are set to 0).
1418  * - LE_OK Function succeeded.
1419  *
1420  * @note If the caller is passing an invalid Position sample reference or null pointers into this
1421  * function, it is a fatal error, the function will not return.
1422  */
1423 //--------------------------------------------------------------------------------------------------
1425 (
1426  le_gnss_SampleRef_t positionSampleRef,
1427  ///< [IN] Position sample's reference.
1428  uint16_t* yearPtr,
1429  ///< [OUT] UTC Year A.D. [e.g. 2014].
1430  uint16_t* monthPtr,
1431  ///< [OUT] UTC Month into the year [range 1...12].
1432  uint16_t* dayPtr
1433  ///< [OUT] UTC Days into the month [range 1...31].
1434 );
1435 
1436 //--------------------------------------------------------------------------------------------------
1437 /**
1438  * Get the position sample's horizontal speed.
1439  *
1440  * - LE_FAULT Function failed to find the positionSample.
1441  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is invalid (set to UINT32_MAX).
1442  * - LE_OK Function succeeded.
1443  *
1444  * @note hSpeedPtr, hSpeedAccuracyPtr can be set to NULL if not needed.
1445  *
1446  * @note Horizontal speed is in meters/second with 2 decimal places (3047 = 30.47 meters/second).
1447  *
1448  * @note Horizontal speed accuracy estimate is default set to meters/second with 1 decimal place
1449  * (304 = 30.4 meters/second). To change its accuracy, call the @c le_gnss_SetDataResolution()
1450  * function. Horizontal speed accuracy estimate is set as data type and accuracy from 0 to 3
1451  * decimal place is set as resolution.
1452  *
1453  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1454  * valid. Please compare them with UINT32_MAX.
1455  *
1456  * @note If the caller is passing an invalid Position sample reference into this function,
1457  * it is a fatal error, the function will not return.
1458  *
1459  * @warning The Horizontal speed accuracy is platform dependent. Please refer to
1460  * @ref platformConstraintsGnss_speedAccuracies section for full details.
1461  */
1462 //--------------------------------------------------------------------------------------------------
1464 (
1465  le_gnss_SampleRef_t positionSampleRef,
1466  ///< [IN] Position sample's reference.
1467  uint32_t* hspeedPtr,
1468  ///< [OUT] Horizontal speed in meters/second [resolution 1e-2].
1469  uint32_t* hspeedAccuracyPtr
1470  ///< [OUT] Horizontal speed's accuracy estimate in meters/second.
1471 );
1472 
1473 //--------------------------------------------------------------------------------------------------
1474 /**
1475  * Get the position sample's vertical speed.
1476  *
1477  * @return
1478  * - LE_FAULT The function failed to find the positionSample.
1479  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is not valid (set to INT32_MAX).
1480  * - LE_OK The function succeeded.
1481  *
1482  * @note vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.
1483  *
1484  * @note For a 2D position Fix, the vertical speed will be indicated as invalid
1485  * and set to INT32_MAX.
1486  *
1487  * @note Vertical speed accuracy estimate is default set to meters/second with 1 decimal place
1488  * (304 = 30.4 meters/second). To change its accuracy, call the @c le_gnss_SetDataResolution()
1489  * function. Vertical speed accuracy estimate is set as data type and accuracy from 0 to 3
1490  * decimal place is set as resolution.
1491  *
1492  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1493  * valid. Please compare them with INT32_MAX.
1494  *
1495  * @note If the caller is passing an invalid Position sample reference into this function,
1496  * it is a fatal error, the function will not return.
1497  *
1498  * @warning The Vertical speed accuracy is platform dependent. Please refer to
1499  * @ref platformConstraintsGnss_speedAccuracies section for full details.
1500  */
1501 //--------------------------------------------------------------------------------------------------
1503 (
1504  le_gnss_SampleRef_t positionSampleRef,
1505  ///< [IN] Position sample's reference.
1506  int32_t* vspeedPtr,
1507  ///< [OUT] Vertical speed in meters/second [resolution 1e-2],
1508  ///< positive up.
1509  int32_t* vspeedAccuracyPtr
1510  ///< [OUT] Vertical speed's accuracy estimate in meters/second.
1511 );
1512 
1513 //--------------------------------------------------------------------------------------------------
1514 /**
1515  * Get the position sample's direction. Direction of movement is the direction that the vehicle or
1516  * person is actually moving.
1517  *
1518  * @return
1519  * - LE_FAULT Function failed to find the positionSample.
1520  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is invalid (set to UINT32_MAX).
1521  * - LE_OK Function succeeded.
1522  *
1523  * @note Direction and direction accuracy are given in degrees with 1 decimal place: 1755 = 175.5
1524  * degrees.
1525  * Direction ranges from 0 to 359.9 degrees, where 0 is True North.
1526  *
1527  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1528  * valid. Please compare them with UINT32_MAX.
1529  *
1530  * @note directionPtr, directionAccuracyPtr can be set to NULL if not needed.
1531  *
1532  * @note If the caller is passing an invalid Position sample reference into this function,
1533  * it is a fatal error, the function will not return.
1534  */
1535 //--------------------------------------------------------------------------------------------------
1537 (
1538  le_gnss_SampleRef_t positionSampleRef,
1539  ///< [IN] Position sample's reference.
1540  uint32_t* directionPtr,
1541  ///< [OUT] Direction in degrees [resolution 1e-1].
1542  ///< Range: 0 to 359.9, where 0 is True North
1543  uint32_t* directionAccuracyPtr
1544  ///< [OUT] Direction's accuracy estimate
1545  ///< in degrees [resolution 1e-1].
1546 );
1547 
1548 //--------------------------------------------------------------------------------------------------
1549 /**
1550  * Get the Satellites Vehicle information.
1551  *
1552  * @return
1553  * - LE_FAULT Function failed to find the positionSample.
1554  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is invalid.
1555  * - LE_OK Function succeeded.
1556  *
1557  * @note satId[] can be set to 0 if that information list index is not configured, so
1558  * all satellite parameters (satConst[], satSnr[],satAzim[], satElev[]) are fixed to 0.
1559  *
1560  * @note For LE_OUT_OF_RANGE returned code, invalid value depends on field type:
1561  * UINT16_MAX for satId, LE_GNSS_SV_CONSTELLATION_UNDEFINED for satConst, false for satUsed,
1562  * UINT8_MAX for satSnr, UINT16_MAX for satAzim, UINT8_MAX for satElev.
1563  *
1564  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1565  * valid.
1566  *
1567  * @note If the caller is passing an invalid Position sample reference into this function,
1568  * it is a fatal error, the function will not return.
1569  */
1570 //--------------------------------------------------------------------------------------------------
1572 (
1573  le_gnss_SampleRef_t positionSampleRef,
1574  ///< [IN] Position sample's reference.
1575  uint16_t* satIdPtr,
1576  ///< [OUT] Satellites in View ID number, referring
1577  ///< to NMEA standard.
1578  size_t* satIdSizePtr,
1579  ///< [INOUT]
1580  le_gnss_Constellation_t* satConstPtr,
1581  ///< [OUT] GNSS constellation type.
1582  size_t* satConstSizePtr,
1583  ///< [INOUT]
1584  bool* satUsedPtr,
1585  ///< [OUT] TRUE if satellite in View Used
1586  ///< for Navigation.
1587  size_t* satUsedSizePtr,
1588  ///< [INOUT]
1589  uint8_t* satSnrPtr,
1590  ///< [OUT] Satellites in View Signal To
1591  ///< Noise Ratio (C/No) [dBHz].
1592  size_t* satSnrSizePtr,
1593  ///< [INOUT]
1594  uint16_t* satAzimPtr,
1595  ///< [OUT] Satellites in View Azimuth [degrees].
1596  ///< Range: 0 to 360
1597  ///< If Azimuth angle is currently unknown,
1598  ///< the value is set to UINT16_MAX.
1599  size_t* satAzimSizePtr,
1600  ///< [INOUT]
1601  uint8_t* satElevPtr,
1602  ///< [OUT] Satellites in View Elevation [degrees].
1603  ///< Range: 0 to 90
1604  ///< If Elevation angle is currently unknown,
1605  ///< the value is set to UINT8_MAX.
1606  size_t* satElevSizePtr
1607  ///< [INOUT]
1608 );
1609 
1610 //--------------------------------------------------------------------------------------------------
1611 /**
1612  * Get the SBAS constellation category given the SBAS satellite number ID.
1613  *
1614  */
1615 //--------------------------------------------------------------------------------------------------
1616 le_gnss_SbasConstellationCategory_t le_gnss_GetSbasConstellationCategory
1617 (
1618  uint16_t satId
1619  ///< [IN] SBAS satellite number ID, referring to NMEA standard.
1620 );
1621 
1622 //--------------------------------------------------------------------------------------------------
1623 /**
1624  * Get the Satellites Vehicle status.
1625  *
1626  * @return
1627  * - LE_FAULT Function failed to find the positionSample.
1628  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is invalid (set to UINT8_MAX).
1629  * - LE_OK Function succeeded.
1630  *
1631  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1632  * valid. Please compare them with UINT8_MAX.
1633  *
1634  * @note If the caller is passing an invalid Position sample reference into this function,
1635  * it is a fatal error, the function will not return.
1636  */
1637 //--------------------------------------------------------------------------------------------------
1639 (
1640  le_gnss_SampleRef_t positionSampleRef,
1641  ///< [IN] Position sample's reference.
1642  uint8_t* satsInViewCountPtr,
1643  ///< [OUT] Number of satellites expected to be in view.
1644  uint8_t* satsTrackingCountPtr,
1645  ///< [OUT] Number of satellites in view, when tracking.
1646  uint8_t* satsUsedCountPtr
1647  ///< [OUT] Number of satellites in view used for Navigation.
1648 );
1649 
1650 //--------------------------------------------------------------------------------------------------
1651 /**
1652  * Get the DOP parameters (Dilution Of Precision) for the fixed position
1653  *
1654  * @return
1655  * - LE_FAULT Function failed to find the positionSample.
1656  * - LE_OUT_OF_RANGE At least one of the retrieved parameters is invalid (set to UINT16_MAX).
1657  * - LE_OK Function succeeded.
1658  *
1659  * @deprecated This function is deprecated, le_gnss_GetDilutionOfPrecision() should be used for
1660  * new code.
1661  *
1662  * @note The DOP values are given with 3 decimal places like: DOP value 2200 = 2.200
1663  *
1664  * @note In case the function returns LE_OUT_OF_RANGE, some of the retrieved parameters may be
1665  * valid. Please compare them with UINT16_MAX.
1666  *
1667  * @note If the caller is passing an invalid Position sample reference into this function,
1668  * it is a fatal error, the function will not return.
1669  */
1670 //--------------------------------------------------------------------------------------------------
1672 (
1673  le_gnss_SampleRef_t positionSampleRef,
1674  ///< [IN] Position sample's reference.
1675  uint16_t* hdopPtr,
1676  ///< [OUT] Horizontal Dilution of Precision [resolution 1e-3].
1677  uint16_t* vdopPtr,
1678  ///< [OUT] Vertical Dilution of Precision [resolution 1e-3].
1679  uint16_t* pdopPtr
1680  ///< [OUT] Position Dilution of Precision [resolution 1e-3].
1681 );
1682 
1683 //--------------------------------------------------------------------------------------------------
1684 /**
1685  * Get the DOP parameter (Dilution Of Precision) for the fixed position.
1686  *
1687  * @return
1688  * - LE_FAULT Function failed to find the DOP value.
1689  * - LE_OUT_OF_RANGE The retrieved parameter is invalid (set to UINT16_MAX).
1690  * - LE_OK Function succeeded.
1691  *
1692  * @note This function replaces the deprecated function le_gnss_GetDop().
1693  *
1694  * @note The DOP value is given with 3 decimal places by default like: DOP value 2200 = 2.200
1695  * The resolution can be modified by calling the @c le_gnss_SetDopResolution() function.
1696  *
1697  * @note If the caller is passing an invalid Position sample reference into this function,
1698  * it is a fatal error, the function will not return.
1699  */
1700 //--------------------------------------------------------------------------------------------------
1702 (
1703  le_gnss_SampleRef_t positionSampleRef,
1704  ///< [IN] Position sample's reference.
1705  le_gnss_DopType_t dopType,
1706  ///< [IN] Dilution of Precision type.
1707  uint16_t* dopPtr
1708  ///< [OUT] Dilution of Precision corresponding to the dopType
1709 );
1710 
1711 //--------------------------------------------------------------------------------------------------
1712 /**
1713  * Get the position sample's altitude with respect to the WGS-84 ellipsoid
1714  *
1715  * @return
1716  * - LE_FAULT Function failed to get the altitude.
1717  * - LE_OUT_OF_RANGE The altitudeOnWgs84 is invalid (set to INT32_MAX).
1718  * - LE_OK Function succeeded.
1719  *
1720  * @note altitudeOnWgs84 is in meters, with respect to the WGS-84 ellipsoid with 3 decimal
1721  * places (3047 = 3.047 meters).
1722  *
1723  * @note For a 2D position fix, the altitude with respect to the WGS-84 ellipsoid will be indicated
1724  * as invalid and set to INT32_MAX.
1725  *
1726  * @note If the caller is passing an invalid Position reference or a null pointer into this
1727  * function, it is a fatal error, the function will not return.
1728  */
1729 //--------------------------------------------------------------------------------------------------
1731 (
1732  le_gnss_SampleRef_t positionSampleRef,
1733  ///< [IN] Position sample's reference.
1734  int32_t* altitudeOnWgs84Ptr
1735  ///< [OUT] Altitude in meters, between WGS-84 earth ellipsoid
1736  ///< and mean sea level [resolution 1e-3].
1737 );
1738 
1739 //--------------------------------------------------------------------------------------------------
1740 /**
1741  * Get the position sample's magnetic deviation. It is the difference between the bearing to
1742  * true north and the bearing shown on a magnetic compass. The deviation is positive when the
1743  * magnetic north is east of true north.
1744  *
1745  * @return
1746  * - LE_FAULT Function failed to find the positionSample.
1747  * - LE_OUT_OF_RANGE The magneticDeviation is invalid (set to INT32_MAX).
1748  * - LE_OK Function succeeded.
1749  *
1750  * @note magneticDeviation is in degrees, with 1 decimal places (47 = 4.7 degree).
1751  *
1752  * @note If the caller is passing an invalid Position sample reference into this function,
1753  * it is a fatal error, the function will not return.
1754  */
1755 //--------------------------------------------------------------------------------------------------
1757 (
1758  le_gnss_SampleRef_t positionSampleRef,
1759  ///< [IN] Position sample's reference.
1760  int32_t* magneticDeviationPtr
1761  ///< [OUT] MagneticDeviation in degrees [resolution 1e-1].
1762 );
1763 
1764 //--------------------------------------------------------------------------------------------------
1765 /**
1766  * This function gets the last updated position sample object reference.
1767  *
1768  * @return A reference to last Position's sample.
1769  *
1770  * @note
1771  * On failure, the process exits, so you don't have to worry about checking the returned
1772  * reference for validity.
1773  */
1774 //--------------------------------------------------------------------------------------------------
1775 le_gnss_SampleRef_t le_gnss_GetLastSampleRef
1776 (
1777  void
1778 );
1779 
1780 //--------------------------------------------------------------------------------------------------
1781 /**
1782  * This function must be called to release the position sample.
1783  *
1784  * @note If the caller is passing an invalid Position sample reference into this function,
1785  * it is a fatal error, the function will not return.
1786  */
1787 //--------------------------------------------------------------------------------------------------
1789 (
1790  le_gnss_SampleRef_t positionSampleRef
1791  ///< [IN] Position sample's reference.
1792 );
1793 
1794 //--------------------------------------------------------------------------------------------------
1795 /**
1796  * This function sets the SUPL Assisted-GNSS mode.
1797  *
1798  * @return
1799  * - LE_OK on success
1800  * - LE_FAULT on failure
1801  * - LE_UNSUPPORTED request not supported
1802  * - LE_TIMEOUT a time-out occurred
1803  *
1804  * @warning The settings are platform dependent. Please refer to
1805  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
1806  */
1807 //--------------------------------------------------------------------------------------------------
1809 (
1810  le_gnss_AssistedMode_t assistedMode
1811  ///< [IN] Assisted-GNSS mode.
1812 );
1813 
1814 //--------------------------------------------------------------------------------------------------
1815 /**
1816  * This function gets the SUPL Assisted-GNSS mode.
1817  *
1818  * @return
1819  * - LE_OK on success
1820  * - LE_FAULT on failure
1821  *
1822  * @note If the caller is passing a null pointer into this function, it is a fatal error, the
1823  * function will not return.
1824  */
1825 //--------------------------------------------------------------------------------------------------
1827 (
1828  le_gnss_AssistedMode_t* assistedModePtr
1829  ///< [OUT] Assisted-GNSS mode.
1830 );
1831 
1832 //--------------------------------------------------------------------------------------------------
1833 /**
1834  * This function sets the SUPL server URL.
1835  * That server URL is a NULL-terminated string with a maximum string length (including NULL
1836  * terminator) equal to 256. Optionally the port number is specified after a colon.
1837  *
1838  * @return
1839  * - LE_OK on success
1840  * - LE_FAULT on failure
1841  * - LE_BUSY service is busy
1842  * - LE_TIMEOUT a time-out occurred
1843  *
1844  * @note If the SUPL server URL size is bigger than the maximum string length (including NULL
1845  * terminator) size, it is a fatal error, the function will not return.
1846  *
1847  * @warning The settings are platform dependent. Please refer to
1848  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
1849  */
1850 //--------------------------------------------------------------------------------------------------
1852 (
1853  const char* LE_NONNULL suplServerUrl
1854  ///< [IN] SUPL server URL.
1855 );
1856 
1857 //--------------------------------------------------------------------------------------------------
1858 /**
1859  * This function injects the SUPL certificate to be used in A-GNSS sessions. Certificates must
1860  * be encoded in DER. Other certificate encryptions (e.g., PEM, CER and CRT)
1861  * aren't supported.
1862  *
1863  * @return
1864  * - LE_OK on success
1865  * - LE_BAD_PARAMETER on invalid parameter
1866  * - LE_FAULT on failure
1867  * - LE_BUSY service is busy
1868  * - LE_TIMEOUT a time-out occurred
1869  *
1870  * @note If the SUPL certificate size is bigger than the Maximum SUPL certificate size,
1871  * it is a fatal error, the function will not return.
1872  */
1873 //--------------------------------------------------------------------------------------------------
1875 (
1876  uint8_t suplCertificateId,
1877  ///< [IN] ID of the SUPL certificate.
1878  ///< Certificate ID range is 0 to 9
1879  uint16_t suplCertificateLen,
1880  ///< [IN] SUPL certificate size in Bytes.
1881  const char* LE_NONNULL suplCertificate
1882  ///< [IN] SUPL certificate contents.
1883 );
1884 
1885 //--------------------------------------------------------------------------------------------------
1886 /**
1887  * This function deletes the SUPL certificate.
1888  *
1889  * @return
1890  * - LE_OK on success
1891  * - LE_BAD_PARAMETER on invalid parameter
1892  * - LE_FAULT on failure
1893  * - LE_BUSY service is busy
1894  * - LE_TIMEOUT a time-out occurred
1895  */
1896 //--------------------------------------------------------------------------------------------------
1898 (
1899  uint8_t suplCertificateId
1900  ///< [IN] ID of the SUPL certificate.
1901  ///< Certificate ID range is 0 to 9
1902 );
1903 
1904 //--------------------------------------------------------------------------------------------------
1905 /**
1906  * This function sets the enabled NMEA sentences using a bit mask.
1907  *
1908  * @return
1909  * - LE_OK Success
1910  * - LE_BAD_PARAMETER Bit mask exceeds the maximal value
1911  * - LE_FAULT Failure
1912  * - LE_BUSY Service is busy
1913  * - LE_TIMEOUT Timeout occurred
1914  * - LE_NOT_PERMITTED GNSS device is not in "ready" state
1915  *
1916  * @warning This function may be subject to limitations depending on the platform. Please refer to
1917  * the @ref platformConstraintsGnss page.
1918  *
1919  * @note Some NMEA sentences are unsupported depending on the platform. Please refer to
1920  * @ref platformConstraintsGnss_nmeaMask section for full details. Setting an unsuported NMEA
1921  * sentence won't report an error.
1922  *
1923  * @warning The settings are platform dependent. Please refer to
1924  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
1925  *
1926  * @deprecated LE_GNSS_NMEA_MASK_PQXFI is deprecated. LE_GNSS_NMEA_MASK_PTYPE should be used
1927  * instead. Setting LE_GNSS_NMEA_MASK_PTYPE will also set LE_GNSS_NMEA_MASK_PQXFI.
1928  */
1929 //--------------------------------------------------------------------------------------------------
1931 (
1932  le_gnss_NmeaBitMask_t nmeaMask
1933  ///< [IN] Bit mask for enabled NMEA sentences.
1934 );
1935 
1936 //--------------------------------------------------------------------------------------------------
1937 /**
1938  * This function gets the bit mask for the enabled NMEA sentences.
1939  *
1940  * @return
1941  * - LE_OK Success
1942  * - LE_FAULT Failure
1943  * - LE_BUSY Service is busy
1944  * - LE_TIMEOUT Timeout occurred
1945  * - LE_NOT_PERMITTED GNSS device is not in "ready" state
1946  *
1947  * @note If the caller is passing a null pointer to this function, it is a fatal error, the
1948  * function will not return.
1949  *
1950  * @note Some NMEA sentences are unsupported depending on the platform. Please refer to
1951  * @ref platformConstraintsGnss_nmeaMask section for full details. The bit mask for an unset
1952  * or unsupported NMEA sentence is zero.
1953  */
1954 //--------------------------------------------------------------------------------------------------
1956 (
1957  le_gnss_NmeaBitMask_t* nmeaMaskPtrPtr
1958  ///< [OUT] Bit mask for enabled NMEA sentences.
1959 );
1960 
1961 //--------------------------------------------------------------------------------------------------
1962 /**
1963  * This function returns the status of the GNSS device.
1964  *
1965  */
1966 //--------------------------------------------------------------------------------------------------
1967 le_gnss_State_t le_gnss_GetState
1968 (
1969  void
1970 );
1971 
1972 //--------------------------------------------------------------------------------------------------
1973 /**
1974  * This function sets the GNSS minimum elevation.
1975  *
1976  * @return
1977  * - LE_OK on success
1978  * - LE_FAULT on failure
1979  * - LE_OUT_OF_RANGE if the minimum elevation is above range
1980  * - LE_UNSUPPORTED request not supported
1981  *
1982  * @warning The settings are platform dependent. Please refer to
1983  * @ref platformConstraintsGnss_SettingConfiguration section for full details.
1984  */
1985 //--------------------------------------------------------------------------------------------------
1987 (
1988  uint8_t minElevation
1989  ///< [IN] Minimum elevation in degrees [range 0..90].
1990 );
1991 
1992 //--------------------------------------------------------------------------------------------------
1993 /**
1994  * This function gets the GNSS minimum elevation.
1995  *
1996  * @return
1997  * - LE_OK on success
1998  * - LE_FAULT on failure
1999  * - LE_UNSUPPORTED request not supported
2000  *
2001  * @note If the caller is passing n null pointer to this function, it is a fatal error, the
2002  * function will not return.
2003  */
2004 //--------------------------------------------------------------------------------------------------
2006 (
2007  uint8_t* minElevationPtrPtr
2008  ///< [OUT] Minimum elevation in degrees [range 0..90].
2009 );
2010 
2011 //--------------------------------------------------------------------------------------------------
2012 /**
2013  * Set the resolution for the DOP parameters
2014  *
2015  * @return LE_OK Function succeeded.
2016  * @return LE_BAD_PARAMETER Invalid parameter provided.
2017  * @return LE_FAULT Function failed.
2018  *
2019  * @note The function sets the same resolution to all DOP values returned by
2020  * le_gnss_GetDilutionOfPrecision() API. The resolution setting takes effect immediately.
2021  *
2022  * @note The resolution setting is done per client session.
2023  */
2024 //--------------------------------------------------------------------------------------------------
2026 (
2027  le_gnss_Resolution_t resolution
2028  ///< [IN] Resolution.
2029 );
2030 
2031 //--------------------------------------------------------------------------------------------------
2032 /**
2033  * Set the resolution for the specific type of data
2034  *
2035  * @return LE_OK Function succeeded.
2036  * @return LE_BAD_PARAMETER Invalid parameter provided.
2037  * @return LE_FAULT Function failed.
2038  *
2039  * @note The resolution setting takes effect immediately and is not persistent to reset.
2040  *
2041  * @note The resolution setting is done per client session.
2042  */
2043 //--------------------------------------------------------------------------------------------------
2045 (
2046  le_gnss_DataType_t dataType,
2047  ///< [IN] Data type.
2048  le_gnss_Resolution_t resolution
2049  ///< [IN] Resolution.
2050 );
2051 
2052 //--------------------------------------------------------------------------------------------------
2053 /**
2054  * This function converts a location data parameter from/to multi-coordinate system
2055  *
2056  * @return
2057  * - LE_OK on success
2058  * - LE_FAULT on failure
2059  * - LE_BAD_PARAMETER Invalid parameter provided.
2060  * - LE_UNSUPPORTED request not supported
2061  *
2062  * @note The resolution of location data parameter remains unchanged after the conversion.
2063  */
2064 //--------------------------------------------------------------------------------------------------
2066 (
2067  le_gnss_CoordinateSystem_t coordinateSrc,
2068  ///< [IN] Coordinate system to convert from.
2069  le_gnss_CoordinateSystem_t coordinateDst,
2070  ///< [IN] Coordinate system to convert to.
2071  le_gnss_LocationDataType_t locationDataType,
2072  ///< [IN] Type of location data to convert.
2073  int64_t locationDataSrc,
2074  ///< [IN] Data to convert.
2075  int64_t* locationDataDstPtr
2076  ///< [OUT] Converted Data.
2077 );
2078 
2079 //--------------------------------------------------------------------------------------------------
2080 /**
2081  * Enables the EXT_GPS_LNA_EN signal
2082  *
2083  * @return LE_OK Function succeeded.
2084  * @return LE_NOT_PERMITTED GNSS is not in the ready state
2085  * @return LE_UNSUPPORTED Function not supported on this platform
2086  *
2087  * @note The EXT_GPS_LNA_EN signal will be set high when the GNSS state is active
2088  */
2089 //--------------------------------------------------------------------------------------------------
2091 (
2092  void
2093 );
2094 
2095 //--------------------------------------------------------------------------------------------------
2096 /**
2097  * Disables the EXT_GPS_LNA_EN signal
2098  *
2099  * @return LE_OK Function succeeded.
2100  * @return LE_NOT_PERMITTED GNSS is not in the ready state
2101  * @return LE_UNSUPPORTED Function not supported on this platform
2102  *
2103  */
2104 //--------------------------------------------------------------------------------------------------
2106 (
2107  void
2108 );
2109 
2110 //--------------------------------------------------------------------------------------------------
2111 /**
2112  * Returns a bitmask containing all NMEA sentences supported on this platform
2113  *
2114  * @return LE_OK Function succeeded.
2115  * @return LE_UNSUPPORTED Function not supported on this platform.
2116  */
2117 //--------------------------------------------------------------------------------------------------
2119 (
2120  le_gnss_NmeaBitMask_t* NmeaMaskPtr
2121  ///< [OUT] Supported NMEA sentences
2122 );
2123 
2124 //--------------------------------------------------------------------------------------------------
2125 /**
2126  * Returns a bitmask containing all satellite constellations supported on this platform
2127  *
2128  * @return LE_OK Function succeeded.
2129  * @return LE_UNSUPPORTED Function not supported on this platform.
2130  */
2131 //--------------------------------------------------------------------------------------------------
2133 (
2134  le_gnss_ConstellationBitMask_t* constellationMaskPtr
2135  ///< [OUT] Supported GNSS constellations
2136 );
2137 
2138 //--------------------------------------------------------------------------------------------------
2139 /**
2140  * Get the minimum NMEA rate supported on this platform
2141  *
2142  * @return LE_OK Function succeeded.
2143  * @return LE_UNSUPPORTED Function not supported on this platform
2144  */
2145 //--------------------------------------------------------------------------------------------------
2147 (
2148  uint32_t* minNmeaRatePtr
2149  ///< [OUT] Minimum NMEA rate in milliseconds.
2150 );
2151 
2152 //--------------------------------------------------------------------------------------------------
2153 /**
2154  * Get the maximum NMEA rate supported on this platform
2155  *
2156  * @return LE_OK Function succeeded.
2157  * @return LE_UNSUPPORTED Function not supported on this platform
2158  */
2159 //--------------------------------------------------------------------------------------------------
2161 (
2162  uint32_t* maxNmeaRatePtr
2163  ///< [OUT] Maximum NMEA rate in milliseconds.
2164 );
2165 
2166 #endif // LE_GNSS_INTERFACE_H_INCLUDE_GUARD
le_result_t le_gnss_GetDirection(le_gnss_SampleRef_t positionSampleRef, uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
le_result_t le_gnss_GetAltitude(le_gnss_SampleRef_t positionSampleRef, int32_t *altitudePtr, int32_t *vAccuracyPtr)
le_gnss_SbasConstellationCategory_t le_gnss_GetSbasConstellationCategory(uint16_t satId)
le_result_t le_gnss_InjectSuplCertificate(uint8_t suplCertificateId, uint16_t suplCertificateLen, const char *LE_NONNULL suplCertificate)
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_result_t le_gnss_StartMode(le_gnss_StartMode_t mode)
le_result_t le_gnss_GetExtendedEphemerisValidity(uint64_t *startTimePtr, uint64_t *stopTimePtr)
le_result_t
Definition: le_basics.h:35
le_result_t le_gnss_Start(void)
le_gnss_PositionHandlerRef_t le_gnss_AddPositionHandler(le_gnss_PositionHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_gnss_GetEpochTime(le_gnss_SampleRef_t positionSampleRef, uint64_t *millisecondsPtr)
le_result_t le_gnss_ForceFactoryRestart(void)
le_result_t le_gnss_GetLeapSeconds(uint64_t *gpsTimePtr, int32_t *currentLeapSecondsPtr, uint64_t *changeEventTimePtr, int32_t *nextLeapSecondsPtr)
le_result_t le_gnss_LoadExtendedEphemerisFile(int fd)
le_result_t le_gnss_GetAcquisitionRate(uint32_t *ratePtr)
void le_gnss_DisconnectService(void)
le_result_t le_gnss_ForceColdRestart(void)
le_result_t le_gnss_ForceWarmRestart(void)
le_result_t le_gnss_InjectUtcTime(uint64_t timeUtc, uint32_t timeUnc)
le_result_t le_gnss_SetDataResolution(le_gnss_DataType_t dataType, le_gnss_Resolution_t resolution)
le_result_t le_gnss_SetConstellationArea(le_gnss_Constellation_t satConstellation, le_gnss_ConstellationArea_t constellationArea)
le_result_t le_gnss_GetTtff(uint32_t *ttffPtr)
le_result_t le_gnss_GetConstellation(le_gnss_ConstellationBitMask_t *constellationMaskPtr)
void le_gnss_RemovePositionHandler(le_gnss_PositionHandlerRef_t handlerRef)
le_result_t le_gnss_SetSuplServerUrl(const char *LE_NONNULL suplServerUrl)
le_result_t le_gnss_EnableExtendedEphemerisFile(void)
le_result_t le_gnss_GetAltitudeOnWgs84(le_gnss_SampleRef_t positionSampleRef, int32_t *altitudeOnWgs84Ptr)
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_GetSuplAssistedMode(le_gnss_AssistedMode_t *assistedModePtr)
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_DisableExtendedEphemerisFile(void)
le_result_t le_gnss_TryConnectService(void)
le_result_t le_gnss_SetAcquisitionRate(uint32_t rate)
le_result_t le_gnss_SetMinElevation(uint8_t minElevation)
le_result_t le_gnss_GetDilutionOfPrecision(le_gnss_SampleRef_t positionSampleRef, le_gnss_DopType_t dopType, uint16_t *dopPtr)
le_result_t le_gnss_DeleteSuplCertificate(uint8_t suplCertificateId)
le_result_t le_gnss_ConvertDataCoordinateSystem(le_gnss_CoordinateSystem_t coordinateSrc, le_gnss_CoordinateSystem_t coordinateDst, le_gnss_LocationDataType_t locationDataType, int64_t locationDataSrc, int64_t *locationDataDstPtr)
le_result_t le_gnss_GetMagneticDeviation(le_gnss_SampleRef_t positionSampleRef, int32_t *magneticDeviationPtr)
void le_gnss_ReleaseSampleRef(le_gnss_SampleRef_t positionSampleRef)
le_result_t le_gnss_GetMaxNmeaRate(uint32_t *maxNmeaRatePtr)
le_result_t le_gnss_GetNmeaSentences(le_gnss_NmeaBitMask_t *nmeaMaskPtrPtr)
le_result_t le_gnss_GetVerticalSpeed(le_gnss_SampleRef_t positionSampleRef, int32_t *vspeedPtr, int32_t *vspeedAccuracyPtr)
le_result_t le_gnss_DisableExternalLna(void)
le_result_t le_gnss_SetSuplAssistedMode(le_gnss_AssistedMode_t assistedMode)
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_SetDopResolution(le_gnss_Resolution_t resolution)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
void le_gnss_ConnectService(void)
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_Stop(void)
le_result_t le_gnss_GetSupportedConstellations(le_gnss_ConstellationBitMask_t *constellationMaskPtr)
le_gnss_State_t le_gnss_GetState(void)
le_result_t le_gnss_SetNmeaSentences(le_gnss_NmeaBitMask_t nmeaMask)
le_result_t le_gnss_GetPositionState(le_gnss_SampleRef_t positionSampleRef, le_gnss_FixState_t *statePtr)
le_result_t le_gnss_GetMinElevation(uint8_t *minElevationPtrPtr)
le_result_t le_gnss_Disable(void)
le_result_t le_gnss_GetHorizontalSpeed(le_gnss_SampleRef_t positionSampleRef, uint32_t *hspeedPtr, uint32_t *hspeedAccuracyPtr)
le_gnss_SampleRef_t le_gnss_GetLastSampleRef(void)
le_result_t le_gnss_SetConstellation(le_gnss_ConstellationBitMask_t constellationMask)
le_result_t le_gnss_EnableExternalLna(void)
le_result_t le_gnss_ForceHotRestart(void)
le_result_t le_gnss_GetMinNmeaRate(uint32_t *minNmeaRatePtr)
LE_FULL_API void le_gnss_SetServerDisconnectHandler(le_gnss_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_gnss_Enable(void)
void(* le_gnss_DisconnectHandler_t)(void *)
Definition: le_gnss_interface.h:521
le_result_t le_gnss_GetGpsTime(le_gnss_SampleRef_t positionSampleRef, uint32_t *gpsWeekPtr, uint32_t *gpsTimeOfWeekPtr)
le_result_t le_gnss_GetConstellationArea(le_gnss_Constellation_t satConstellation, le_gnss_ConstellationArea_t *constellationAreaPtr)
le_result_t le_gnss_GetGpsLeapSeconds(le_gnss_SampleRef_t positionSampleRef, uint8_t *leapSecondsPtr)
le_result_t le_gnss_GetSupportedNmeaSentences(le_gnss_NmeaBitMask_t *NmeaMaskPtr)
le_result_t le_gnss_GetTimeAccuracy(le_gnss_SampleRef_t positionSampleRef, uint32_t *timeAccuracyPtr)
le_result_t le_gnss_GetDop(le_gnss_SampleRef_t positionSampleRef, uint16_t *hdopPtr, uint16_t *vdopPtr, uint16_t *pdopPtr)