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