le_gnss_interface.h - Legato Docs

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