le_gnss_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_gnss GNSS
12  *
13  * @ref le_gnss_interface.h "API Reference" <br>
14  * @ref platformConstraintsGnss <br>
15  * @ref howToGNSS "How To Use GNSS" <br>
16  * @ref toolsTarget_gnss "GNSS target tool" <br>
17  *
18  * <HR>
19  *
20  * This API provides access to the GNSS device.
21  *
22  * GNSS or Global Navigation Satellite System is a satellite navigation system with global coverage.
23  *
24  * This API provides function to configure the GNSS device and retrieve position information.
25  *
26  * @section le_gnss_binding IPC interfaces binding
27  *
28  * All the functions of this API are provided by the @b positioningService application service.
29  *
30  * Here's a code sample binding to Positioning services:
31  * @verbatim
32  bindings:
33  {
34  clientExe.clientComponent.le_gnss -> positioningService.le_gnss
35  }
36  @endverbatim
37  *
38  * @section le_gnss_ControlApi GNSS Control API
39  *
40  * @subsection le_gnss_EnableDisable Enable/Disable GNSS device
41  *
42  * The application can enable/disable the GNSS device with the le_gnss_Enable()
43  * / le_gnss_Disable() functions.
44  * By default the GNSS device is enabled for the positioningService application service.
45  * Also see @ref howToGNSS.
46  *
47  * A sample code can be seen in the following page:
48  * - @subpage c_gnssSampleCodeEnableDisable
49  *
50  * @subsection le_gnss_StartStop Start/Stop GNSS device
51  *
52  * The application can start/stop the GNSS device with the le_gnss_Start() / le_gnss_Stop()
53  * functions.
54  * The default "HOT" start condition is applied and all assistance data are used.
55  * Also see @ref howToGNSS.
56  *
57  * A sample code can be seen in the following page:
58  * - @subpage c_gnssSampleCodeStartStop
59  *
60  * @subsubsection le_gnss_StartingMode Starting mode
61  *
62  * Starting modes are used only for test purposes and allow start performance measurement.
63  * @note For more information about start performances, please refer to your specific
64  * platform documentation.
65  *
66  * @subsubsection le_gnss_Data GNSS data
67  * The following table describes the <b>minimum</b> required data for those starting modes:
68  *
69  * | GNSS Data / Starting mode | HOT | WARM | COLD | FACTORY |
70  *| -----------------------| -----| ------| ----- | ------- |
71  *| Broadcasted Ephemeris | Used | | | |
72  *| Extended Ephemeris | Used(1) | Used(2) | Used(2) | Removed (3) |
73  *| Approximate Time and Position | Used | Used | | |
74  *| Almanac | Used | Used | Used | Used (Factory) |
75  *
76  * For example, a requested HOT start without valid broadcasted ephemeris will be treated
77  * as a WARM start.
78  *
79  * @note (1) Extended Ephemeris can be used if Broadcasted Ephemeris are not valid.
80  * The Extended Ephemeris could be loaded using the le_gnss_LoadExtendedEphemerisFile()
81  * function.
82  * @note (2) Extended Ephemeris is used if the Extended Ephemeris file is loaded and valid.
83  * @note (3) Extended Ephemeris are removed when a FACTORY start is requested.
84  * The Extended Ephemeris could be loaded again using the le_gnss_LoadExtendedEphemerisFile()
85  * function.
86  *
87  * @subsubsection le_gnss_TTFF Time To First Fix (TTFF)
88  * The le_gnss_GetTtff() function provides the TTFF (first between 2-Dimensional or 3-Dimensional
89  * position fix) of the last position fix.
90  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
91  *
92  * A sample code can be seen in the following page:
93  * - @subpage c_gnssSampleCodeReStart
94  *
95  * @subsubsection le_gnss_ForceHotRestart Force HOT restart
96  * The le_gnss_ForceHotRestart() function performs a "HOT" restart of the GNSS device. The current
97  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
98  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
99  *
100  * @subsubsection le_gnss_ForceWarmRestart Force WARM restart
101  * The le_gnss_ForceWarmRestart() function performs a "WARM" restart of the GNSS device. The current
102  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
103  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
104  *
105  * @subsubsection le_gnss_ForceColdRestart Force COLD restart
106  * The le_gnss_ForceColdRestart() function performs a "COLD" restart of the GNSS device. The current
107  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
108  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
109  *
110  * @subsubsection le_gnss_ForceFactoryRestart Force FACTORY restart
111  * The le_gnss_ForceFactoryRestart() function performs a "FACTORY" restart of the GNSS device.
112  * The current GNSS session is stopped, then started using the available @ref le_gnss_Data.
113  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
114  *
115  * @subsection le_gnss_AcquisitionRate Acquisition rate
116  * The GNSS position is computed and delivered each acquisition rate. Default value is 1 second.
117  * The application can configure/retrieve the GNSS device acquisition rate with the
118  * le_gnss_SetAcquisitionRate() / le_gnss_GetAcquisitionRate() functions.
119  *
120  * Please refer to @ref le_gnss_APIcallsRequirements.
121  *
122  * A sample code can be seen in the following page:
123  * - @subpage c_gnssSampleCodeAcquisitionRate
124  *
125  * @subsection le_gnss_SetGetConstellation GNSS constellation selection
126  *
127  * The le_gnss_SetConstellation() function selects the GNSS constellation(s) used in solution.
128  * If all GNSS constellations are disabled, the GNSS engine is disabled.
129  *
130  * @warning Your platform may require a reboot to take into account this change.
131  * Please refer to your platform documentation for further details.
132  *
133  * The following configurations are currently supported:
134  * - GPS
135  * - GPS + GLONASS
136  *
137  * All supported GNSS constellations are enabled by default.
138  * The le_gnss_GetConstellation() function gets the GNSS constellation(s) enabled to be used
139  * in solution.
140  *
141  * A sample code can be seen in the following page:
142  * - @subpage c_gnssSampleCodeConstellation
143  *
144  * @subsection le_gnss_NmeaSentences NMEA sentences selection
145  *
146  * The le_gnss_SetNmeaSentences() function selects the enabled NMEA sentences in the
147  * @ref le_gnss_NMEA with a bit mask. The supported values are listed in @ref le_gnss_NmeaBitMask_t.
148  *
149  * @warning Your GNSS device may require a restart to take into account this change.
150  * Please refer to your platform documentation for further details.
151  *
152  * @note All supported NMEA sentences are enabled by default.
153  *
154  * The le_gnss_GetNmeaSentences() function gets the bit mask of the enabled NMEA sentences in the
155  * @ref le_gnss_NMEA.
156  *
157  * Please refer to @ref le_gnss_APIcallsRequirements.
158  *
159  * A sample code can be seen in the following page:
160  * - @subpage c_gnssSampleCodeNmeaSentences
161  *
162  * @subsection le_gnss_APIcallsRequirements API calls Requirements
163  * The following table shows the pre-requisites when using the GNSS service API function set.
164  * ''LE_OK or error code'' means the function is authorized in the corresponding state, the request
165  * is performed and the result is returned; otherwise the returned error is indicated for each state
166  *.
167  * | Function / GNSS state | UNINITIALIZED | READY | ACTIVE | DISABLED |
168  *| ----------------------------- | --------------------------- | -----------------------------| --------------------------- | --------------------------- |
169  *| le_gnss_Start() | LE_NOT_PERMITTED | LE_OK or error code | LE_DUPLICATE | LE_NOT_PERMITTED |
170  *| le_gnss_Stop() | LE_NOT_PERMITTED | LE_DUPLICATE | LE_OK or error code | LE_NOT_PERMITTED |
171  *| le_gnss_ForceHotRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
172  *| le_gnss_ForceWarmRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
173  *| le_gnss_ForceColdRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
174  *| le_gnss_ForceFactoryRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
175  *| le_gnss_Disable() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_DUPLICATE |
176  *| le_gnss_Enable() | LE_NOT_PERMITTED | LE_DUPLICATE | LE_DUPLICATE | LE_OK or error code |
177  *| le_gnss_SetConstellation() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
178  *| le_gnss_GetConstellation() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
179  *| le_gnss_GetTtff() | LE_NOT_PERMITTED | LE_OK or error code | LE_OK or error code | LE_NOT_PERMITTED |
180  *| le_gnss_SetAcquisitionRate() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
181  *| le_gnss_GetAcquisitionRate() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
182  *| le_gnss_SetNmeaSentences() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
183  *| le_gnss_GetNmeaSentences() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
184  *
185  * Also see @ref howToGNSS.
186  *
187  * @section le_gnss_Information GNSS position information
188  * @ref le_gnss_NMEA
189  *
190  * @ref le_gnss_GetInfo
191  *
192  * @subsection le_gnss_NMEA NMEA Flow
193  * The National Marine Electronics Association (NMEA) standard defines an electrical interface
194  * and data protocol for communications between marine instrumentation.
195  *
196  * The NMEA-0183, scope of this document, defines a set of frame prefixed by
197  * $GP (concerning Global Positioning System),
198  * $GL (concerning GLONASS)
199  * and $GN (concerning combination of navigation systems).
200  * For more details about NMEA standards, please refer to http://www.nmea.org/.
201  *
202  * That NMEA frames flow can be retrieved from the "/dev/nmea" device folder, using for example
203  * the shell command $<EM> cat /dev/nmea | grep '$G'</EM>
204  *
205  * @subsection le_gnss_GetInfo Get position information
206  * The position information is referenced to a position sample object.
207  *
208  * An application can register a handler to be notified of the
209  * updated position each @ref le_gnss_AcquisitionRate, returning a position sample object.
210  *
211  * The GNSS information commonly used such as
212  * position, time and date, satellites information and accuracy
213  * can be queried using the following functions:
214  * - le_gnss_GetPositionState()
215  * - le_gnss_GetLocation()
216  * - le_gnss_GetAltitude()
217  * - le_gnss_GetDate()
218  * - le_gnss_GetTime()
219  * - le_gnss_GetGpsTime()
220  * - le_gnss_GetTimeAccuracy()
221  * - le_gnss_GetHorizontalSpeed()
222  * - le_gnss_GetVerticalSpeed()
223  * - le_gnss_GetDirection()
224  * - le_gnss_GetSatellitesInfo()
225  * - le_gnss_GetSatellitesStatus()
226  * - le_gnss_GetDop()
227  * - le_gnss_GetAltitudeOnWgs84()
228  * - le_gnss_GetMagneticDeviation()
229 
230  * The handler can be managed using le_gnss_AddPositionHandler()
231  * and le_gnss_RemovePositionHandler().
232  * When a position is computed, the handler is called.
233  *
234  * The application has to release each position sample object received by the handler,
235  * using the le_gnss_ReleaseSampleRef().
236  *
237  * A sample code can be seen in the following page:
238  * - @subpage c_gnssSampleCodePosition
239  *
240  * @section le_gnss_Assisted_GNSS Assisted GNSS
241  *
242  * @ref le_gnss_Assisted_GNSS_EE
243  * @ref le_gnss_Assisted_GNSS_UP
244  *
245  * @subsection le_gnss_Assisted_GNSS_EE Server based Extended Ephemeris
246  *
247  * @todo Add detailed documentation.
248  *
249  * With le_gnss_LoadExtendedEphemerisFile() , you can load an 'Extended Ephemeris' file into
250  * the GNSS device from the filesystem.
251  * You have to download the file before loading it.
252  * @warning Ensure to check that the downloaded file is supported for your specific platform.
253  *
254  * With le_gnss_GetExtendedEphemerisValidity(), you will to get the validity of the last injected
255  * Extended Ephemeris.
256  *
257  * You can enable/disable the use of the 'Extended Ephemeris' file into the GNSS device with
258  * le_gnss_EnableExtendedEphemerisFile() / le_gnss_DisableExtendedEphemerisFile() functions.
259  * @warning Ensure to check configuration capabilities for your specific platform.
260  * A reboot must be required if your platform doesn't allow run-time configuration.
261  *
262  * A sample code can be seen in the following page:
263  * - @subpage c_gnssSampleCodeXtra
264  *
265  * @subsection le_gnss_Assisted_GNSS_UP 3GPP User Plane (OMA SUPL)
266  *
267  * That 3GPP User Plane A-GNSS (Assisted GNSS) protocol is defined by two different standardization
268  * bodies, 3GPP and Open Mobile Alliance (OMA). For more information, please refer to the standard.
269  *
270  * Both MS-Assisted and MS-Based position determination methods are supported in the User Plane.
271  *
272  * In MS-Assisted mode, the MS (Mobile Station) measures the signals from the GNSS satellites
273  *, then returns the retrieved GNSS data to the SUPL (Secure User Plan Location) server, where the
274  * position calculation is performed.
275  *
276  * In MS-Based mode, the MS gets the assistance data from the SUPL (Secure User Plan Location)
277  * server. The MS measures the signals from the GNSS satellites and makes the position calculation.
278  *
279  * The data transport over User Plan is done using the TCP/IP protocol.
280  *
281  * The Assisted-GNSS mode can be configured thru the le_gnss_SetSuplAssistedMode() function.
282  *
283  * The supported modes are the following:
284  * - Standalone mode: That 3GPP User Plane A-GNSS feature is deactivated.
285  * - MS-Based mode
286  * - MS-Assisted mode
287  *
288  * Moreover, the le_gnss_GetSuplAssistedMode() function reads the configured Assisted-GNSS mode.
289  *
290  * The SUPL server is configured using the le_gnss_SetSuplServerUrl() function. That function sets
291  * the SUPL server URL and optionally the port number.
292  *
293  * The SUPL certificate to be used in A-GNSS sessions is injected through the
294  * le_gnss_InjectSuplCertificate() function and deleted through the le_gnss_DeleteSuplCertificate()
295  * function.
296  *
297  *
298  * <HR>
299  *
300  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
301  */
302 /**
303  * @page c_gnssSampleCode Sample code for GNSS device
304  *
305  * @include "apps/test/positioning/gnssTest/gnssTest/gnssTest.c"
306  */
307 /**
308  * @page c_gnssSampleCodeEnableDisable Sample code for Enable/Disable GNSS device
309  *
310  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssEnable
311  */
312 /**
313  * @page c_gnssSampleCodeStartStop Sample code for Start/Stop GNSS device
314  *
315  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
316  */
317 /**
318  * @page c_gnssSampleCodeReStart Sample code for restart GNSS device and get TTFF
319  *
320  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssReStart
321  */
322 /**
323  * @page c_gnssSampleCodeAcquisitionRate Sample code for GNSS acquisition rate configuration
324  *
325  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
326  */
327 /**
328  * @page c_gnssSampleCodeConstellation Sample code for GNSS constellation selection
329  *
330  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
331  */
332 /**
333  * @page c_gnssSampleCodeNmeaSentences Sample code for GNSS NMEA sentences selection
334  *
335  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
336  */
337 /**
338  * @page c_gnssSampleCodePosition Sample code for GNSS position information
339  *
340  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssPosition
341  */
342 /**
343  * @page c_gnssSampleCodeXtra Sample code for GNSS Server based Extended Ephemeris
344  *
345  * @include "apps/test/positioning/gnssXtraTest/gnssXtraTest/xtraTest.c"
346  */
347 /**
348  * @file le_gnss_interface.h
349  *
350  * Legato @ref c_gnss include file.
351  *
352  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
353  */
354 
355 #ifndef LE_GNSS_INTERFACE_H_INCLUDE_GUARD
356 #define LE_GNSS_INTERFACE_H_INCLUDE_GUARD
357 
358 
359 #include "legato.h"
360 
361 //--------------------------------------------------------------------------------------------------
362 /**
363  *
364  * Connect the current client thread to the service providing this API. Block until the service is
365  * available.
366  *
367  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
368  * called before any other functions in this API. Normally, ConnectService is automatically called
369  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
370  *
371  * This function is created automatically.
372  */
373 //--------------------------------------------------------------------------------------------------
375 (
376  void
377 );
378 
379 //--------------------------------------------------------------------------------------------------
380 /**
381  *
382  * Try to connect the current client thread to the service providing this API. Return with an error
383  * if the service is not available.
384  *
385  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
386  * called before any other functions in this API. Normally, ConnectService is automatically called
387  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
388  *
389  * This function is created automatically.
390  *
391  * @return
392  * - LE_OK if the client connected successfully to the service.
393  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
394  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
395  * - LE_COMM_ERROR if the Service Directory cannot be reached.
396  */
397 //--------------------------------------------------------------------------------------------------
399 (
400  void
401 );
402 
403 //--------------------------------------------------------------------------------------------------
404 /**
405  *
406  * Disconnect the current client thread from the service providing this API.
407  *
408  * Normally, this function doesn't need to be called. After this function is called, there's no
409  * longer a connection to the service, and the functions in this API can't be used. For details, see
410  * @ref apiFilesC_client.
411  *
412  * This function is created automatically.
413  */
414 //--------------------------------------------------------------------------------------------------
416 (
417  void
418 );
419 
420 
421 //--------------------------------------------------------------------------------------------------
422 /**
423  * Reference type for dealing with GNSS position samples.
424  */
425 //--------------------------------------------------------------------------------------------------
426 typedef struct le_gnss_Sample* le_gnss_SampleRef_t;
427 
428 
429 //--------------------------------------------------------------------------------------------------
430 /**
431  * Maximum length of the SUP Server URL string.
432  */
433 //--------------------------------------------------------------------------------------------------
434 #define LE_GNSS_SUPL_SERVER_URL_MAX_LEN 256
435 
436 
437 //--------------------------------------------------------------------------------------------------
438 /**
439  * Maximum length of the SUP Server URL string.
440  * One extra byte is added for the null character.
441  */
442 //--------------------------------------------------------------------------------------------------
443 #define LE_GNSS_SUPL_SERVER_URL_MAX_BYTES 257
444 
445 
446 //--------------------------------------------------------------------------------------------------
447 /**
448  * Maximum SUPL certificate size.
449  */
450 //--------------------------------------------------------------------------------------------------
451 #define LE_GNSS_SUPL_CERTIFICATE_MAX_LEN 2000
452 
453 
454 //--------------------------------------------------------------------------------------------------
455 /**
456  * Maximum SUPL certificate string size.
457  * One extra byte is added for the null character.
458  */
459 //--------------------------------------------------------------------------------------------------
460 #define LE_GNSS_SUPL_CERTIFICATE_MAX_BYTES 2001
461 
462 
463 //--------------------------------------------------------------------------------------------------
464 /**
465  * Define the maximum length of the Satellites Vehicle information list
466  */
467 //--------------------------------------------------------------------------------------------------
468 #define LE_GNSS_SV_INFO_MAX_LEN 80
469 
470 
471 //--------------------------------------------------------------------------------------------------
472 /**
473  * Define the maximal bit mask for enabled NMEA sentences
474  *
475  * @note This maximal value should be coherent with @ref le_gnss_NmeaBitMask_t
476  */
477 //--------------------------------------------------------------------------------------------------
478 #define LE_GNSS_NMEA_SENTENCES_MAX 32767
479 
480 
481 //--------------------------------------------------------------------------------------------------
482 /**
483  * GNSS fix position states.
484  */
485 //--------------------------------------------------------------------------------------------------
486 typedef enum
487 {
489  ///< The GNSS fix position is not fixed.
490 
492  ///< 2-Dimensional position fix.
493 
495  ///< 3-Dimensional position fix.
496 
498  ///< Estimated (i.e. forward predicted) position fix.
499 }
501 
502 
503 //--------------------------------------------------------------------------------------------------
504 /**
505  * GNSS constellation type.
506  */
507 //--------------------------------------------------------------------------------------------------
508 typedef enum
509 {
511  ///< GNSS constellation field not defined.
512 
514  ///< Satellite Vehicle of GPS constellation.
515  ///< North American satellite navigation system
516 
518  ///< Satellite Vehicle of SBAS constellation.
519  ///< Satellite-based augmentation system
520 
522  ///< Satellite Vehicle of Glonass constellation.
523  ///< Russian satellite navigation system
524 
526  ///< Satellite Vehicle of Galileo constellation.
527  ///< European Union satellite navigation system
528 
530  ///< Satellite Vehicle of Beidou constellation.
531  ///< Chinese satellite navigation system
532 
534  ///< Maximum value.
535 }
537 
538 
539 //--------------------------------------------------------------------------------------------------
540 /**
541  * Assisted-GNSS mode
542  */
543 //--------------------------------------------------------------------------------------------------
544 typedef enum
545 {
547  ///< Standalone mode
548 
550  ///< MS-Based mode.
551 
553  ///< MS-Assisted mode.
554 }
556 
557 
558 //--------------------------------------------------------------------------------------------------
559 /**
560  * GNSS constellation Bit Mask (8 bits) indicating the GNSS constellation(s)
561  * used in solution.
562  *
563  */
564 //--------------------------------------------------------------------------------------------------
565 typedef enum
566 {
568  ///< GPS constellation used in solution.
569  ///< North American satellite navigation system
570 
572  ///< GLONASS constellation used in solution.
573  ///< Russian satellite navigation system
574 
576  ///< BEIDOU constellation used in solution.
577  ///< Chinese satellite navigation system
578 
580  ///< GALILEO constellation used in solution.
581  ///< European Union satellite navigation system
582 }
584 
585 
586 //--------------------------------------------------------------------------------------------------
587 /**
588  * NMEA sentences Bit Mask indicating the NMEA sentences enabled in the NMEA flow.
589  *
590  * @warning The supported NMEA sentences depend on the platform. Please refer to your platform
591  * documentation for further details.
592  *
593  * @note The bit mask values should be coherent with @ref LE_GNSS_NMEA_SENTENCES_MAX
594  */
595 //--------------------------------------------------------------------------------------------------
596 typedef enum
597 {
599  ///< GPGGA type enabled: GPS fix data.
600 
602  ///< GPGSA type enabled: GPS DOP and active satellites.
603 
605  ///< GPGSV type enabled: GPS satellites in view.
606 
608  ///< GPRMC type enabled: GPS recommended minimum data.
609 
611  ///< GPVTG type enabled: GPS vector track and speed over the ground.
612 
614  ///< GLGSV type enabled: GLONASS satellites in view.
615 
617  ///< GNGNS type enabled: GNSS fix data.
618 
620  ///< GNGSA type enabled: GNSS DOP and active satellites.
621 
623  ///< GAGGA type enabled: Galileo fix data.
624 
626  ///< GAGSA type enabled: Galileo DOP and active satellites.
627 
629  ///< GAGSV type enabled: Galileo satellites in view.
630 
632  ///< GARMC type enabled: Galileo recommended minimum data.
633 
635  ///< GAVTG type enabled: Galileo vector track and speed over the ground.
636 
638  ///< PSTIS type enabled: GPS session start indication.
639 
641  ///< PQXFI type enabled: Proprietary Qualcomm eXtended Fix Information.
642 }
644 
645 
646 //--------------------------------------------------------------------------------------------------
647 /**
648  * Reference type used by Add/Remove functions for EVENT 'le_gnss_Position'
649  */
650 //--------------------------------------------------------------------------------------------------
651 typedef struct le_gnss_PositionHandler* le_gnss_PositionHandlerRef_t;
652 
653 
654 //--------------------------------------------------------------------------------------------------
655 /**
656  * Handler for position information.
657  *
658  *
659  * @param positionSampleRef
660  * Position's sample reference
661  * @param contextPtr
662  */
663 //--------------------------------------------------------------------------------------------------
664 typedef void (*le_gnss_PositionHandlerFunc_t)
665 (
666  le_gnss_SampleRef_t positionSampleRef,
667  void* contextPtr
668 );
669 
670 //--------------------------------------------------------------------------------------------------
671 /**
672  * Set the GNSS constellation bit mask
673  *
674  * @return
675  * - LE_FAULT The function failed.
676  * - LE_UNSUPPORTED If the request is not supported.
677  * - LE_NOT_PERMITTED If the GNSS device is not initialized, disabled or active.
678  * - LE_OK The function succeeded.
679  */
680 //--------------------------------------------------------------------------------------------------
682 (
683  le_gnss_ConstellationBitMask_t constellationMask
684  ///< [IN] GNSS constellation used in solution.
685 );
686 
687 //--------------------------------------------------------------------------------------------------
688 /**
689  * Get the GNSS constellation bit mask
690  *
691  * @return
692  * - LE_OK on success
693  * - LE_FAULT on failure
694  */
695 //--------------------------------------------------------------------------------------------------
697 (
698  le_gnss_ConstellationBitMask_t* constellationMaskPtr
699  ///< [OUT] GNSS constellation used in solution.
700 );
701 
702 //--------------------------------------------------------------------------------------------------
703 /**
704  * This function enables the use of the 'Extended Ephemeris' file into the GNSS device.
705  *
706  * @return
707  * - LE_FAULT The function failed.
708  * - LE_OK The function succeeded.
709  *
710  */
711 //--------------------------------------------------------------------------------------------------
713 (
714  void
715 );
716 
717 //--------------------------------------------------------------------------------------------------
718 /**
719  * This function disables the use of the 'Extended Ephemeris' file into the GNSS device.
720  *
721  * @return
722  * - LE_FAULT The function failed.
723  * - LE_OK The function succeeded.
724  *
725  */
726 //--------------------------------------------------------------------------------------------------
728 (
729  void
730 );
731 
732 //--------------------------------------------------------------------------------------------------
733 /**
734  * This function must be called to load an 'Extended Ephemeris' file into the GNSS device.
735  *
736  * @return
737  * - LE_FAULT The function failed to inject the 'Extended Ephemeris' file.
738  * - LE_TIMEOUT A time-out occurred.
739  * - LE_FORMAT_ERROR 'Extended Ephemeris' file format error.
740  * - LE_OK The function succeeded.
741  *
742  */
743 //--------------------------------------------------------------------------------------------------
745 (
746  int fd
747  ///< [IN] Extended ephemeris file descriptor
748 );
749 
750 //--------------------------------------------------------------------------------------------------
751 /**
752  * This function must be called to get the validity of the last injected Extended Ephemeris.
753  *
754  * @return
755  * - LE_FAULT The function failed to get the validity
756  * - LE_OK The function succeeded.
757  *
758  */
759 //--------------------------------------------------------------------------------------------------
761 (
762  uint64_t* startTimePtr,
763  ///< [OUT] Start time in seconds (since Jan. 1, 1970)
764 
765  uint64_t* stopTimePtr
766  ///< [OUT] Stop time in seconds (since Jan. 1, 1970)
767 );
768 
769 //--------------------------------------------------------------------------------------------------
770 /**
771  * This function starts the GNSS device.
772  *
773  * @return
774  * - LE_FAULT The function failed.
775  * - LE_DUPLICATE If the GNSS device is already started.
776  * - LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
777  * - LE_OK The function succeeded.
778  *
779  */
780 //--------------------------------------------------------------------------------------------------
782 (
783  void
784 );
785 
786 //--------------------------------------------------------------------------------------------------
787 /**
788  * This function stops the GNSS device.
789  *
790  * @return
791  * - LE_FAULT The function failed.
792  * - LE_DUPLICATE If the GNSS device is already stopped.
793  * - LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
794  * - LE_OK The function succeeded.
795  *
796  */
797 //--------------------------------------------------------------------------------------------------
799 (
800  void
801 );
802 
803 //--------------------------------------------------------------------------------------------------
804 /**
805  * This function performs a "HOT" restart of the GNSS device.
806  *
807  * @return
808  * - LE_FAULT The function failed.
809  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
810  * - LE_OK The function succeeded.
811  *
812  */
813 //--------------------------------------------------------------------------------------------------
815 (
816  void
817 );
818 
819 //--------------------------------------------------------------------------------------------------
820 /**
821  * This function performs a "WARM" restart of the GNSS device.
822  *
823  * @return
824  * - LE_FAULT The function failed.
825  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
826  * - LE_OK The function succeeded.
827  *
828  */
829 //--------------------------------------------------------------------------------------------------
831 (
832  void
833 );
834 
835 //--------------------------------------------------------------------------------------------------
836 /**
837  * This function performs a "COLD" restart of the GNSS device.
838  *
839  * @return
840  * - LE_FAULT The function failed.
841  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
842  * - LE_OK The function succeeded.
843  *
844  */
845 //--------------------------------------------------------------------------------------------------
847 (
848  void
849 );
850 
851 //--------------------------------------------------------------------------------------------------
852 /**
853  * This function performs a "FACTORY" restart of the GNSS device.
854  *
855  * @return
856  * - LE_FAULT The function failed.
857  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
858  * - LE_OK The function succeeded.
859  *
860  */
861 //--------------------------------------------------------------------------------------------------
863 (
864  void
865 );
866 
867 //--------------------------------------------------------------------------------------------------
868 /**
869  * Get the TTFF in milliseconds
870  *
871  * @return
872  * - LE_BUSY The position is not fixed and TTFF can't be measured.
873  * - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
874  * - LE_OK Function succeeded.
875  *
876  */
877 //--------------------------------------------------------------------------------------------------
879 (
880  uint32_t* ttffPtr
881  ///< [OUT] TTFF in milliseconds
882 );
883 
884 //--------------------------------------------------------------------------------------------------
885 /**
886  * This function enables the GNSS device.
887  *
888  * @return
889  * - LE_FAULT The function failed.
890  * - LE_DUPLICATE If the GNSS device is already enabled.
891  * - LE_NOT_PERMITTED If the GNSS device is not initialized.
892  * - LE_OK The function succeeded.
893  *
894  */
895 //--------------------------------------------------------------------------------------------------
897 (
898  void
899 );
900 
901 //--------------------------------------------------------------------------------------------------
902 /**
903  * This function disables the GNSS device.
904  *
905  * @return
906  * - LE_FAULT The function failed.
907  * - LE_DUPLICATE If the GNSS device is already disabled.
908  * - LE_NOT_PERMITTED If the GNSS device is not initialized or started.
909  * - LE_OK The function succeeded.
910  *
911  */
912 //--------------------------------------------------------------------------------------------------
914 (
915  void
916 );
917 
918 //--------------------------------------------------------------------------------------------------
919 /**
920  * This function sets the GNSS device acquisition rate.
921  *
922  * @return
923  * - LE_OK on success
924  * - LE_FAULT on failure
925  * - LE_UNSUPPORTED request not supported
926  * - LE_TIMEOUT a time-out occurred
927  * - LE_NOT_PERMITTED If the GNSS device is not in "ready" state.
928  *
929  * @warning This function may be subject to limitations depending on the platform. Please refer to
930  * the @ref platformConstraintsGnss page.
931  */
932 //--------------------------------------------------------------------------------------------------
934 (
935  uint32_t rate
936  ///< [IN] Acquisition rate in milliseconds.
937 );
938 
939 //--------------------------------------------------------------------------------------------------
940 /**
941  * This function gets the GNSS device acquisition rate.
942  *
943  * @return
944  * - LE_OK on success
945  * - LE_FAULT on failure
946  * - LE_NOT_PERMITTED If the GNSS device is not in "ready" state.
947  */
948 //--------------------------------------------------------------------------------------------------
950 (
951  uint32_t* ratePtr
952  ///< [OUT] Acquisition rate in milliseconds.
953 );
954 
955 //--------------------------------------------------------------------------------------------------
956 /**
957  * Add handler function for EVENT 'le_gnss_Position'
958  *
959  * This event provides information on position.
960  *
961  * - A handler reference, which is only needed for later removal of the handler.
962  *
963  * @note Doesn't return on failure, so there's no need to check the return value for errors.
964  */
965 //--------------------------------------------------------------------------------------------------
967 (
969  ///< [IN]
970 
971  void* contextPtr
972  ///< [IN]
973 );
974 
975 //--------------------------------------------------------------------------------------------------
976 /**
977  * Remove handler function for EVENT 'le_gnss_Position'
978  */
979 //--------------------------------------------------------------------------------------------------
981 (
982  le_gnss_PositionHandlerRef_t addHandlerRef
983  ///< [IN]
984 );
985 
986 //--------------------------------------------------------------------------------------------------
987 /**
988  * This function gets the position sample's fix state
989  *
990  * - LE_OK on success
991  * - LE_FAULT on failure
992  *
993  * @note If the caller is passing an invalid Position sample reference into this function,
994  * it is a fatal error, the function will not return.
995  */
996 //--------------------------------------------------------------------------------------------------
998 (
999  le_gnss_SampleRef_t positionSampleRef,
1000  ///< [IN] Position sample's reference.
1001 
1002  le_gnss_FixState_t* statePtr
1003  ///< [OUT] Position fix state.
1004 );
1005 
1006 //--------------------------------------------------------------------------------------------------
1007 /**
1008  * Get the location's data (Latitude, Longitude, Horizontal accuracy).
1009  *
1010  * @return
1011  * - LE_FAULT Function failed to get the location's data
1012  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
1013  * - LE_OK Function succeeded.
1014  *
1015  * @note latitudePtr, longitudePtr, hAccuracyPtr, altitudePtr, vAccuracyPtr can be set to NULL
1016  * if not needed.
1017  *
1018  * @note: The latitude and longitude values are based on the WGS84 standard coordinate system.
1019  *
1020  * @note The latitude and longitude are given in degrees with 6 decimal places like:
1021  * Latitude +48858300 = 48.858300 degrees North
1022  * Longitude +2294400 = 2.294400 degrees East
1023  *
1024  * @note If the caller is passing an invalid Position sample reference into this function,
1025  * it is a fatal error, the function will not return.
1026  */
1027 //--------------------------------------------------------------------------------------------------
1029 (
1030  le_gnss_SampleRef_t positionSampleRef,
1031  ///< [IN] Position sample's reference.
1032 
1033  int32_t* latitudePtr,
1034  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
1035 
1036  int32_t* longitudePtr,
1037  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
1038 
1039  int32_t* hAccuracyPtr
1040  ///< [OUT] Horizontal position's accuracy in meters [resolution 1e-2].
1041 );
1042 
1043 //--------------------------------------------------------------------------------------------------
1044 /**
1045  * Get the position sample's altitude.
1046  *
1047  * @return
1048  * - LE_FAULT Function failed to get the altitude.
1049  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
1050  * - LE_OK Function succeeded.
1051  *
1052  * @note Altitude is in meters, above Mean Sea Level, with 3 decimal places (3047 = 3.047 meters).
1053  *
1054  * @note For a 2D position fix, the altitude will be indicated as invalid and set to INT32_MAX
1055  *
1056  * @note If the caller is passing an invalid Position reference into this function,
1057  * it is a fatal error, the function will not return.
1058  *
1059  * @note altitudePtr, altitudeAccuracyPtr can be set to NULL if not needed.
1060  */
1061 //--------------------------------------------------------------------------------------------------
1063 (
1064  le_gnss_SampleRef_t positionSampleRef,
1065  ///< [IN] Position sample's reference.
1066 
1067  int32_t* altitudePtr,
1068  ///< [OUT] Altitude in meters, above Mean Sea Level [resolution 1e-3].
1069 
1070  int32_t* vAccuracyPtr
1071  ///< [OUT] Vertical position's accuracy in meters [resolution 1e-1].
1072 );
1073 
1074 //--------------------------------------------------------------------------------------------------
1075 /**
1076  * Get the position sample's time.
1077  *
1078  * @return
1079  * - LE_FAULT Function failed to get the time.
1080  * - LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
1081  * - LE_OK Function succeeded.
1082  *
1083  * @note If the caller is passing an invalid Position sample reference into this function,
1084  * it is a fatal error, the function will not return.
1085  */
1086 //--------------------------------------------------------------------------------------------------
1088 (
1089  le_gnss_SampleRef_t positionSampleRef,
1090  ///< [IN] Position sample's reference.
1091 
1092  uint16_t* hoursPtr,
1093  ///< [OUT] UTC Hours into the day [range 0..23].
1094 
1095  uint16_t* minutesPtr,
1096  ///< [OUT] UTC Minutes into the hour [range 0..59].
1097 
1098  uint16_t* secondsPtr,
1099  ///< [OUT] UTC Seconds into the minute [range 0..59].
1100 
1101  uint16_t* millisecondsPtr
1102  ///< [OUT] UTC Milliseconds into the second [range 0..999].
1103 );
1104 
1105 //--------------------------------------------------------------------------------------------------
1106 /**
1107  * Get the position sample's GPS time.
1108  *
1109  * @return
1110  * - LE_FAULT Function failed to get the time.
1111  * - LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
1112  * - LE_OK Function succeeded.
1113  *
1114  * @note If the caller is passing an invalid Position sample reference into this function,
1115  * it is a fatal error, the function will not return.
1116  */
1117 //--------------------------------------------------------------------------------------------------
1119 (
1120  le_gnss_SampleRef_t positionSampleRef,
1121  ///< [IN] Position sample's reference.
1122 
1123  uint32_t* gpsWeekPtr,
1124  ///< [OUT] GPS week number from midnight, Jan. 6, 1980.
1125 
1126  uint32_t* gpsTimeOfWeekPtr
1127  ///< [OUT] Amount of time in milliseconds into the GPS week.
1128 );
1129 
1130 //--------------------------------------------------------------------------------------------------
1131 /**
1132  * Get the position sample's time accurary.
1133  *
1134  * @return
1135  * - LE_FAULT Function failed to get the time.
1136  * - LE_OUT_OF_RANGE The retrieved time accuracy is invalid (set to UINT16_MAX).
1137  * - LE_OK Function succeeded.
1138  *
1139  * @note If the caller is passing an invalid Position sample reference into this function,
1140  * it is a fatal error, the function will not return.
1141  */
1142 //--------------------------------------------------------------------------------------------------
1144 (
1145  le_gnss_SampleRef_t positionSampleRef,
1146  ///< [IN] Position sample's reference.
1147 
1148  uint32_t* timeAccuracyPtr
1149  ///< [OUT] Estimated time accuracy in milliseconds
1150 );
1151 
1152 //--------------------------------------------------------------------------------------------------
1153 /**
1154  * Get the position sample's date.
1155  *
1156  * @return
1157  * - LE_FAULT Function failed to get the date.
1158  * - LE_OUT_OF_RANGE The retrieved date is invalid (all fields are set to 0).
1159  * - LE_OK Function succeeded.
1160  *
1161  * @note If the caller is passing an invalid Position sample reference into this function,
1162  * it is a fatal error, the function will not return.
1163  */
1164 //--------------------------------------------------------------------------------------------------
1166 (
1167  le_gnss_SampleRef_t positionSampleRef,
1168  ///< [IN] Position sample's reference.
1169 
1170  uint16_t* yearPtr,
1171  ///< [OUT] UTC Year A.D. [e.g. 2014].
1172 
1173  uint16_t* monthPtr,
1174  ///< [OUT] UTC Month into the year [range 1...12].
1175 
1176  uint16_t* dayPtr
1177  ///< [OUT] UTC Days into the month [range 1...31].
1178 );
1179 
1180 //--------------------------------------------------------------------------------------------------
1181 /**
1182  * Get the position sample's horizontal speed.
1183  *
1184  * - LE_FAULT Function failed to find the positionSample.
1185  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
1186  * - LE_OK Function succeeded.
1187  *
1188  * @note hSpeedPtr, hSpeedAccuracyPtr can be set to NULL if not needed.
1189  *
1190  * @note If the caller is passing an invalid Position sample reference into this function,
1191  * it is a fatal error, the function will not return.
1192  */
1193 //--------------------------------------------------------------------------------------------------
1195 (
1196  le_gnss_SampleRef_t positionSampleRef,
1197  ///< [IN] Position sample's reference.
1198 
1199  uint32_t* hspeedPtr,
1200  ///< [OUT] Horizontal speed in meters/second [resolution 1e-2].
1201 
1202  uint32_t* hspeedAccuracyPtr
1203  ///< [OUT] Horizontal speed's accuracy estimate
1204  ///< in meters/second [resolution 1e-1].
1205 );
1206 
1207 //--------------------------------------------------------------------------------------------------
1208 /**
1209  * Get the position sample's vertical speed.
1210  *
1211  * @return
1212  * - LE_FAULT The function failed to find the positionSample.
1213  * - LE_OUT_OF_RANGE One of the retrieved parameter is not valid (set to INT32_MAX).
1214  * - LE_OK The function succeeded.
1215  *
1216  * @note vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.
1217  *
1218  * @note For a 2D position Fix, the vertical speed will be indicated as invalid
1219  * and set to 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 
1230  int32_t* vspeedPtr,
1231  ///< [OUT] Vertical speed in meters/second [resolution 1e-2],
1232  ///< positive up.
1233 
1234  int32_t* vspeedAccuracyPtr
1235  ///< [OUT] Vertical speed's accuracy estimate
1236  ///< in meters/second [resolution 1e-1].
1237 );
1238 
1239 //--------------------------------------------------------------------------------------------------
1240 /**
1241  * Get the position sample's direction. Direction of movement is the direction that the vehicle or
1242  * person is actually moving.
1243  *
1244  * @return
1245  * - LE_FAULT Function failed to find the positionSample.
1246  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
1247  * - LE_OK Function succeeded.
1248  *
1249  * @note Direction is given in degrees with 1 decimal place: 1755 = 175,5 degrees.
1250  * Direction ranges from 0 to 359.9 degrees, where 0 is True North.
1251  *
1252  * @note directionPtr, directionAccuracyPtr can be set to NULL if not needed.
1253  *
1254  * @note If the caller is passing an invalid Position sample reference into this function,
1255  * it is a fatal error, the function will not return.
1256  */
1257 //--------------------------------------------------------------------------------------------------
1259 (
1260  le_gnss_SampleRef_t positionSampleRef,
1261  ///< [IN] Position sample's reference.
1262 
1263  uint32_t* directionPtr,
1264  ///< [OUT] Direction in degrees [resolution 1e-1].
1265  ///< Range: 0 to 359.9, where 0 is True North
1266 
1267  uint32_t* directionAccuracyPtr
1268  ///< [OUT] Direction's accuracy estimate
1269  ///< in degrees [resolution 1e-1].
1270 );
1271 
1272 //--------------------------------------------------------------------------------------------------
1273 /**
1274  * Get the Satellites Vehicle information.
1275  *
1276  * @return
1277  * - LE_FAULT Function failed to find the positionSample.
1278  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid.
1279  * - LE_OK Function succeeded.
1280  *
1281  * @note satId[] can be set to 0 if that information list index is not configured, so
1282  * all satellite parameters (satConst[], satSnr[],satAzim[], satElev[]) are fixed to 0.
1283  *
1284  * @note For LE_OUT_OF_RANGE returned code, invalid value depends on field type:
1285  * UINT16_MAX for satId, LE_GNSS_SV_CONSTELLATION_UNDEFINED for satConst, false for satUsed,
1286  * UINT8_MAX for satSnr, UINT16_MAX for satAzim, UINT8_MAX for satElev.
1287  *
1288  * @note If the caller is passing an invalid Position sample reference into this function,
1289  * it is a fatal error, the function will not return.
1290  */
1291 //--------------------------------------------------------------------------------------------------
1293 (
1294  le_gnss_SampleRef_t positionSampleRef,
1295  ///< [IN] Position sample's reference.
1296 
1297  uint16_t* satIdPtr,
1298  ///< [OUT] Satellites in View ID number, referring
1299  ///< to NMEA standard.
1300 
1301  size_t* satIdNumElementsPtr,
1302  ///< [INOUT]
1303 
1304  le_gnss_Constellation_t* satConstPtr,
1305  ///< [OUT] GNSS constellation type.
1306 
1307  size_t* satConstNumElementsPtr,
1308  ///< [INOUT]
1309 
1310  bool* satUsedPtr,
1311  ///< [OUT] TRUE if satellite in View Used
1312  ///< for Navigation.
1313 
1314  size_t* satUsedNumElementsPtr,
1315  ///< [INOUT]
1316 
1317  uint8_t* satSnrPtr,
1318  ///< [OUT] Satellites in View Signal To
1319  ///< Noise Ratio [dBHz].
1320 
1321  size_t* satSnrNumElementsPtr,
1322  ///< [INOUT]
1323 
1324  uint16_t* satAzimPtr,
1325  ///< [OUT] Satellites in View Azimuth [degrees].
1326  ///< Range: 0 to 360
1327  ///< If Azimuth angle is currently unknown,
1328  ///< the value is set to UINT16_MAX.
1329 
1330  size_t* satAzimNumElementsPtr,
1331  ///< [INOUT]
1332 
1333  uint8_t* satElevPtr,
1334  ///< [OUT] Satellites in View Elevation [degrees].
1335  ///< Range: 0 to 90
1336  ///< If Elevation angle is currently unknown,
1337  ///< the value is set to UINT8_MAX.
1338 
1339  size_t* satElevNumElementsPtr
1340  ///< [INOUT]
1341 );
1342 
1343 //--------------------------------------------------------------------------------------------------
1344 /**
1345  * Get the Satellites Vehicle status.
1346  *
1347  * @return
1348  * - LE_FAULT Function failed to find the positionSample.
1349  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid.
1350  * - LE_OK Function succeeded.
1351  *
1352  * @note If the caller is passing an invalid Position sample reference into this function,
1353  * it is a fatal error, the function will not return.
1354  */
1355 //--------------------------------------------------------------------------------------------------
1357 (
1358  le_gnss_SampleRef_t positionSampleRef,
1359  ///< [IN] Position sample's reference.
1360 
1361  uint8_t* satsInViewCountPtr,
1362  ///< [OUT] Number of satellites expected to be in view.
1363 
1364  uint8_t* satsTrackingCountPtr,
1365  ///< [OUT] Number of satellites in view, when tracking.
1366 
1367  uint8_t* satsUsedCountPtr
1368  ///< [OUT] Number of satellites in view used for Navigation.
1369 );
1370 
1371 //--------------------------------------------------------------------------------------------------
1372 /**
1373  * Get the DOP parameters (Dilution Of Precision) for the fixed position.
1374  *
1375  * @return
1376  * - LE_FAULT Function failed to find the positionSample.
1377  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT16_MAX).
1378  * - LE_OK Function succeeded.
1379  *
1380  * @note The DOP values are given with 3 decimal places like: DOP value 2200 = 2.20
1381  *
1382  * @note If the caller is passing an invalid Position sample reference into this function,
1383  * it is a fatal error, the function will not return.
1384  */
1385 //--------------------------------------------------------------------------------------------------
1387 (
1388  le_gnss_SampleRef_t positionSampleRef,
1389  ///< [IN] Position sample's reference.
1390 
1391  uint16_t* hdopPtr,
1392  ///< [OUT] Horizontal Dilution of Precision [resolution 1e-3].
1393 
1394  uint16_t* vdopPtr,
1395  ///< [OUT] Vertical Dilution of Precision [resolution 1e-3].
1396 
1397  uint16_t* pdopPtr
1398  ///< [OUT] Position Dilution of Precision [resolution 1e-3].
1399 );
1400 
1401 //--------------------------------------------------------------------------------------------------
1402 /**
1403  * Get the position sample's altitude with respect to the WGS-84 ellipsoid
1404  *
1405  * @return
1406  * - LE_FAULT Function failed to get the altitude.
1407  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
1408  * - LE_OK Function succeeded.
1409  *
1410  * @note altitudeOnWgs84 is in meters, between WGS-84 earth ellipsoid and mean sea level
1411  * with 3 decimal places (3047 = 3.047 meters).
1412  *
1413  * @note For a 2D position fix, the altitude with respect to the WGS-84 ellipsoid will be indicated
1414  * as invalid and set to INT32_MAX.
1415  *
1416  * @note If the caller is passing an invalid Position reference into this function,
1417  * it is a fatal error, the function will not return.
1418  */
1419 //--------------------------------------------------------------------------------------------------
1421 (
1422  le_gnss_SampleRef_t positionSampleRef,
1423  ///< [IN] Position sample's reference.
1424 
1425  int32_t* altitudeOnWgs84Ptr
1426  ///< [OUT] Altitude in meters, between WGS-84 earth ellipsoid
1427  ///< and mean sea level [resolution 1e-3].
1428 );
1429 
1430 //--------------------------------------------------------------------------------------------------
1431 /**
1432  * Get the position sample's magnetic deviation. It is the difference between the bearing to
1433  * true north and the bearing shown on a magnetic compass. The deviation is positive when the
1434  * magnetic north is east of true north.
1435  *
1436  * @return
1437  * - LE_FAULT Function failed to find the positionSample.
1438  * - LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
1439  * - LE_OK Function succeeded.
1440  *
1441  * @note magneticDeviation is in degrees, with 1 decimal places (47 = 4.7 degree).
1442  *
1443  * @note If the caller is passing an invalid Position sample reference into this function,
1444  * it is a fatal error, the function will not return.
1445  */
1446 //--------------------------------------------------------------------------------------------------
1448 (
1449  le_gnss_SampleRef_t positionSampleRef,
1450  ///< [IN] Position sample's reference.
1451 
1452  int32_t* magneticDeviationPtr
1453  ///< [OUT] MagneticDeviation in degrees [resolution 1e-1].
1454 );
1455 
1456 //--------------------------------------------------------------------------------------------------
1457 /**
1458  * This function gets the last updated position sample object reference.
1459  *
1460  * @return A reference to last Position's sample.
1461  *
1462  * @note
1463  * On failure, the process exits, so you don't have to worry about checking the returned
1464  * reference for validity.
1465  */
1466 //--------------------------------------------------------------------------------------------------
1468 (
1469  void
1470 );
1471 
1472 //--------------------------------------------------------------------------------------------------
1473 /**
1474  * This function must be called to release the position sample.
1475  *
1476  * @note If the caller is passing an invalid Position sample reference into this function,
1477  * it is a fatal error, the function will not return.
1478  */
1479 //--------------------------------------------------------------------------------------------------
1481 (
1482  le_gnss_SampleRef_t positionSampleRef
1483  ///< [IN] Position sample's reference.
1484 );
1485 
1486 //--------------------------------------------------------------------------------------------------
1487 /**
1488  * This function sets the SUPL Assisted-GNSS mode.
1489  *
1490  * @return
1491  * - LE_OK on success
1492  * - LE_FAULT on failure
1493  * - LE_UNSUPPORTED request not supported
1494  * - LE_TIMEOUT a time-out occurred
1495  */
1496 //--------------------------------------------------------------------------------------------------
1498 (
1499  le_gnss_AssistedMode_t assistedMode
1500  ///< [IN] Assisted-GNSS mode.
1501 );
1502 
1503 //--------------------------------------------------------------------------------------------------
1504 /**
1505  * This function gets the SUPL Assisted-GNSS mode.
1506  *
1507  * @return
1508  * - LE_OK on success
1509  * - LE_FAULT on failure
1510  */
1511 //--------------------------------------------------------------------------------------------------
1513 (
1514  le_gnss_AssistedMode_t* assistedModePtr
1515  ///< [OUT] Assisted-GNSS mode.
1516 );
1517 
1518 //--------------------------------------------------------------------------------------------------
1519 /**
1520  * This function sets the SUPL server URL.
1521  * That server URL is a NULL-terminated string with a maximum string length (including NULL
1522  * terminator) equal to 256. Optionally the port number is specified after a colon.
1523  *
1524  * @return
1525  * - LE_OK on success
1526  * - LE_FAULT on failure
1527  * - LE_BUSY service is busy
1528  * - LE_TIMEOUT a time-out occurred
1529  */
1530 //--------------------------------------------------------------------------------------------------
1532 (
1533  const char* suplServerUrl
1534  ///< [IN] SUPL server URL.
1535 );
1536 
1537 //--------------------------------------------------------------------------------------------------
1538 /**
1539  * This function injects the SUPL certificate to be used in A-GNSS sessions. Certificates must
1540  * be encoded in DER. Other certificate encryptions (e.g., PEM, CER and CRT)
1541  * aren't supported.
1542  *
1543  * @return
1544  * - LE_OK on success
1545  * - LE_FAULT on failure
1546  * - LE_BUSY service is busy
1547  * - LE_TIMEOUT a time-out occurred
1548  */
1549 //--------------------------------------------------------------------------------------------------
1551 (
1552  uint8_t suplCertificateId,
1553  ///< [IN] ID of the SUPL certificate.
1554  ///< Certificate ID range is 0 to 9
1555 
1556  uint16_t suplCertificateLen,
1557  ///< [IN] SUPL certificate size in Bytes.
1558 
1559  const char* suplCertificate
1560  ///< [IN] SUPL certificate contents.
1561 );
1562 
1563 //--------------------------------------------------------------------------------------------------
1564 /**
1565  * This function deletes the SUPL certificate.
1566  *
1567  * @return
1568  * - LE_OK on success
1569  * - LE_FAULT on failure
1570  * - LE_BUSY service is busy
1571  * - LE_TIMEOUT a time-out occurred
1572  */
1573 //--------------------------------------------------------------------------------------------------
1575 (
1576  uint8_t suplCertificateId
1577  ///< [IN] ID of the SUPL certificate.
1578  ///< Certificate ID range is 0 to 9
1579 );
1580 
1581 //--------------------------------------------------------------------------------------------------
1582 /**
1583  * This function sets the enabled NMEA sentences using a bit mask.
1584  *
1585  * @return
1586  * - LE_OK Success
1587  * - LE_BAD_PARAMETER Bit mask exceeds the maximal value
1588  * - LE_FAULT Failure
1589  * - LE_BUSY Service is busy
1590  * - LE_TIMEOUT Timeout occurred
1591  * - LE_NOT_PERMITTED GNSS device is not in "ready" state
1592  *
1593  * @warning This function may be subject to limitations depending on the platform. Please refer to
1594  * the @ref platformConstraintsGnss page.
1595  */
1596 //--------------------------------------------------------------------------------------------------
1598 (
1599  le_gnss_NmeaBitMask_t nmeaMask
1600  ///< [IN] Bit mask for enabled NMEA sentences.
1601 );
1602 
1603 //--------------------------------------------------------------------------------------------------
1604 /**
1605  * This function gets the bit mask for the enabled NMEA sentences.
1606  *
1607  * @return
1608  * - LE_OK Success
1609  * - LE_FAULT Failure
1610  * - LE_BUSY Service is busy
1611  * - LE_TIMEOUT Timeout occurred
1612  * - LE_NOT_PERMITTED GNSS device is not in "ready" state
1613  *
1614  * @note If the caller is passing an null pointer to this function, it is a fatal error
1615  * and the function will not return.
1616  */
1617 //--------------------------------------------------------------------------------------------------
1619 (
1620  le_gnss_NmeaBitMask_t* nmeaMaskPtrPtr
1621  ///< [OUT] Bit mask for enabled NMEA sentences.
1622 );
1623 
1624 
1625 #endif // LE_GNSS_INTERFACE_H_INCLUDE_GUARD
1626 
le_gnss_AssistedMode_t
Definition: le_gnss_interface.h:544
le_result_t le_gnss_InjectSuplCertificate(uint8_t suplCertificateId, uint16_t suplCertificateLen, const char *suplCertificate)
le_result_t le_gnss_GetDirection(le_gnss_SampleRef_t positionSampleRef, uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
le_result_t le_gnss_GetAltitude(le_gnss_SampleRef_t positionSampleRef, int32_t *altitudePtr, int32_t *vAccuracyPtr)
le_result_t le_gnss_SetSuplServerUrl(const char *suplServerUrl)
void(* le_gnss_PositionHandlerFunc_t)(le_gnss_SampleRef_t positionSampleRef, void *contextPtr)
Definition: le_gnss_interface.h:665
Definition: le_gnss_interface.h:525
le_result_t le_gnss_GetExtendedEphemerisValidity(uint64_t *startTimePtr, uint64_t *stopTimePtr)
GNGSA type enabled: GNSS DOP and active satellites.
Definition: le_gnss_interface.h:619
le_result_t
Definition: le_basics.h:35
void le_gnss_RemovePositionHandler(le_gnss_PositionHandlerRef_t addHandlerRef)
le_result_t le_gnss_Start(void)
Standalone mode.
Definition: le_gnss_interface.h:546
le_gnss_PositionHandlerRef_t le_gnss_AddPositionHandler(le_gnss_PositionHandlerFunc_t handlerPtr, void *contextPtr)
Definition: le_gnss_interface.h:571
le_result_t le_gnss_ForceFactoryRestart(void)
struct le_gnss_Sample * le_gnss_SampleRef_t
Definition: le_gnss_interface.h:426
le_result_t le_gnss_LoadExtendedEphemerisFile(int fd)
PSTIS type enabled: GPS session start indication.
Definition: le_gnss_interface.h:637
le_result_t le_gnss_GetAcquisitionRate(uint32_t *ratePtr)
void le_gnss_DisconnectService(void)
Definition: le_gnss_interface.h:513
Definition: le_gnss_interface.h:529
Definition: le_gnss_interface.h:575
GNGNS type enabled: GNSS fix data.
Definition: le_gnss_interface.h:616
GAGGA type enabled: Galileo fix data.
Definition: le_gnss_interface.h:622
le_result_t le_gnss_ForceColdRestart(void)
GAGSA type enabled: Galileo DOP and active satellites.
Definition: le_gnss_interface.h:625
Estimated (i.e. forward predicted) position fix.
Definition: le_gnss_interface.h:497
le_result_t le_gnss_ForceWarmRestart(void)
GPGSV type enabled: GPS satellites in view.
Definition: le_gnss_interface.h:604
Definition: le_gnss_interface.h:521
le_result_t le_gnss_GetTtff(uint32_t *ttffPtr)
le_result_t le_gnss_GetConstellation(le_gnss_ConstellationBitMask_t *constellationMaskPtr)
Maximum value.
Definition: le_gnss_interface.h:533
le_result_t le_gnss_EnableExtendedEphemerisFile(void)
3-Dimensional position fix.
Definition: le_gnss_interface.h:494
le_result_t le_gnss_GetAltitudeOnWgs84(le_gnss_SampleRef_t positionSampleRef, int32_t *altitudeOnWgs84Ptr)
le_result_t le_gnss_GetTime(le_gnss_SampleRef_t positionSampleRef, uint16_t *hoursPtr, uint16_t *minutesPtr, uint16_t *secondsPtr, uint16_t *millisecondsPtr)
le_result_t le_gnss_GetSuplAssistedMode(le_gnss_AssistedMode_t *assistedModePtr)
le_result_t le_gnss_GetLocation(le_gnss_SampleRef_t positionSampleRef, int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr)
le_result_t le_gnss_DisableExtendedEphemerisFile(void)
GAVTG type enabled: Galileo vector track and speed over the ground.
Definition: le_gnss_interface.h:634
le_result_t le_gnss_TryConnectService(void)
le_result_t le_gnss_SetAcquisitionRate(uint32_t rate)
le_gnss_NmeaBitMask_t
Definition: le_gnss_interface.h:596
le_result_t le_gnss_DeleteSuplCertificate(uint8_t suplCertificateId)
Definition: le_gnss_interface.h:567
le_gnss_FixState_t
Definition: le_gnss_interface.h:486
2-Dimensional position fix.
Definition: le_gnss_interface.h:491
le_result_t le_gnss_GetMagneticDeviation(le_gnss_SampleRef_t positionSampleRef, int32_t *magneticDeviationPtr)
void le_gnss_ReleaseSampleRef(le_gnss_SampleRef_t positionSampleRef)
Definition: le_gnss_interface.h:517
le_result_t le_gnss_GetNmeaSentences(le_gnss_NmeaBitMask_t *nmeaMaskPtrPtr)
le_result_t le_gnss_GetVerticalSpeed(le_gnss_SampleRef_t positionSampleRef, int32_t *vspeedPtr, int32_t *vspeedAccuracyPtr)
MS-Assisted mode.
Definition: le_gnss_interface.h:552
le_result_t le_gnss_SetSuplAssistedMode(le_gnss_AssistedMode_t assistedMode)
le_result_t le_gnss_GetDate(le_gnss_SampleRef_t positionSampleRef, uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
le_gnss_ConstellationBitMask_t
Definition: le_gnss_interface.h:565
GPVTG type enabled: GPS vector track and speed over the ground.
Definition: le_gnss_interface.h:610
le_result_t le_gnss_GetSatellitesInfo(le_gnss_SampleRef_t positionSampleRef, uint16_t *satIdPtr, size_t *satIdNumElementsPtr, le_gnss_Constellation_t *satConstPtr, size_t *satConstNumElementsPtr, bool *satUsedPtr, size_t *satUsedNumElementsPtr, uint8_t *satSnrPtr, size_t *satSnrNumElementsPtr, uint16_t *satAzimPtr, size_t *satAzimNumElementsPtr, uint8_t *satElevPtr, size_t *satElevNumElementsPtr)
void le_gnss_ConnectService(void)
GPRMC type enabled: GPS recommended minimum data.
Definition: le_gnss_interface.h:607
le_result_t le_gnss_GetSatellitesStatus(le_gnss_SampleRef_t positionSampleRef, uint8_t *satsInViewCountPtr, uint8_t *satsTrackingCountPtr, uint8_t *satsUsedCountPtr)
PQXFI type enabled: Proprietary Qualcomm eXtended Fix Information.
Definition: le_gnss_interface.h:640
Definition: le_gnss_interface.h:579
le_result_t le_gnss_Stop(void)
le_result_t le_gnss_SetNmeaSentences(le_gnss_NmeaBitMask_t nmeaMask)
le_result_t le_gnss_GetPositionState(le_gnss_SampleRef_t positionSampleRef, le_gnss_FixState_t *statePtr)
le_result_t le_gnss_Disable(void)
GPGGA type enabled: GPS fix data.
Definition: le_gnss_interface.h:598
le_result_t le_gnss_GetHorizontalSpeed(le_gnss_SampleRef_t positionSampleRef, uint32_t *hspeedPtr, uint32_t *hspeedAccuracyPtr)
le_gnss_SampleRef_t le_gnss_GetLastSampleRef(void)
le_result_t le_gnss_SetConstellation(le_gnss_ConstellationBitMask_t constellationMask)
GNSS constellation field not defined.
Definition: le_gnss_interface.h:510
le_result_t le_gnss_ForceHotRestart(void)
MS-Based mode.
Definition: le_gnss_interface.h:549
le_result_t le_gnss_Enable(void)
le_result_t le_gnss_GetGpsTime(le_gnss_SampleRef_t positionSampleRef, uint32_t *gpsWeekPtr, uint32_t *gpsTimeOfWeekPtr)
GPGSA type enabled: GPS DOP and active satellites.
Definition: le_gnss_interface.h:601
The GNSS fix position is not fixed.
Definition: le_gnss_interface.h:488
GLGSV type enabled: GLONASS satellites in view.
Definition: le_gnss_interface.h:613
GAGSV type enabled: Galileo satellites in view.
Definition: le_gnss_interface.h:628
le_result_t le_gnss_GetTimeAccuracy(le_gnss_SampleRef_t positionSampleRef, uint32_t *timeAccuracyPtr)
struct le_gnss_PositionHandler * le_gnss_PositionHandlerRef_t
Definition: le_gnss_interface.h:651
GARMC type enabled: Galileo recommended minimum data.
Definition: le_gnss_interface.h:631
le_gnss_Constellation_t
Definition: le_gnss_interface.h:508
le_result_t le_gnss_GetDop(le_gnss_SampleRef_t positionSampleRef, uint16_t *hdopPtr, uint16_t *vdopPtr, uint16_t *pdopPtr)