This service provides API to acquire location data and control location service configurations.

GNSS is a satellite navigation system with global coverage.

This API provides function to configure the Location service and retrieve position information.

IPC interfaces binding

The functions of this API are provided by the tafLocationSvc application service.

The following example illustrates how to bind to the Location service.

  bindings:
  {
      clientExe.clientComponent.taf_locGnss -> tafLocationSvc.taf_locGnss
  }

The location service provides multi-client safe APIs. An API call from a client thread (main or sub thread) will be treated a new session in location service. The client needs to connect the location service by API taf_locGnss_ConnectService(), setting specific settings if required (else default settings will be applied), starting the engine report by the API taf_locGnss_Start(), and adding handler by taf_locGnss_AddPositionHandler(). Then client can get the GNSS data/information and the engine reports in the same thread until the client disconnects from the location service. The previous settings and data shall not persist for next run/iteration if the client thread exits. Note that each time a client creates a new thread, it needs to connect, call, and set APIs, taf_locGnss_Start(), taf_locGnss_AddPositionHandler() for the new session to set up.

GNSS Control APIs

Enable or Disable Location service

The taf_locGnss_Enable API initializes the Location Service and prepares the TelAF location service to serve further requests after setting up internal states.

Through the taf_locGnss_Disable API, the Location Service is de-initialized and location service disallows any further requests until it is enabled again via taf_locGnss_Enable.

By default, when the service starts up, the Location Service is initialized and is ready to serve incoming requests.

  if(taf_locGnss_Enable() == LE_OK)
  {
    // Process after successfully initializing the location service.
  }

  if(taf_locGnss_Disable() == LE_OK)
  {
    // Process after successfully de-initializing the location service.
  }

Start or Stop Location service

taf_locGnss_Start and taf_locGnss_Stop can be used to control the location service.

  if(taf_locGnss_Start() == LE_OK)
  {
    // Process after successfully starting the Location session
  }

  if(taf_locGnss_Stop() == LE_OK)
  {
    // Process after successfully stopping the Location session
  }

The handler can be managed using taf_locGnss_AddPositionHandler() and taf_locGnss_RemovePositionHandler(). When a position is computed, the handler is called.

  static void PositionHandlerFunction
  (
     taf_locGnss_SampleRef_t positionSampleRef,
     void* contextPtr
  )
  {
     int32_t latitude, longitude, horizontalAccuracy;
     LE_ASSERT_OK(taf_locGnss_GetLocation(positionSampleRef, &latitude,
                                            &longitude, &horizontalAccuracy));
     taf_locGnss_ReleaseSampleRef(positionSampleRef);
  }
  static taf_locGnss_PositionHandlerRef_t positionHandlerRef = NULL;
  positionHandlerRef = taf_locGnss_AddPositionHandler(PositionHandlerFunction, NULL);
  LE_ASSERT(NULL != positionHandlerRef);
  taf_locGnss_RemovePositionHandler(positionHandlerRef);

The application has to release each position sample object received by the handler, using the taf_locGnss_ReleaseSampleRef() triggered inside the PositionHandlerFunction() function.

  taf_locGnss_ReleaseSampleRef(positionSampleRef);

Start location data session in the specified starting mode

In HOT mode, no data is cleared and the location session is started with its available data. In WARM mode, location session is started after the ephemeris is cleared. In COLD and FACTORY mode, location session is started after all data is cleared except almanac.

Restart location session

The taf_locGnss_ForceHotRestart() function performs a "HOT" restart of the location session. The current GNSS session is restarted.

  if(taf_locGnss_ForceHotRestart() == LE_OK)
  {
    // Process after successfully restarting the location session.
  }

Restart location session in WARM mode

The taf_locGnss_ForceWarmRestart() function performs a "WARM" restart of the location session.

  if(taf_locGnss_ForceWarmRestart() == LE_OK)
  {
    // Process after successfully restarting location session in "WARM" mode.
  }

Restart the Location service in COLD mode

The taf_locGnss_ForceColdRestart() function performs a "COLD" restart of the Location session. The current GNSS session is stopped and then started with GNSS data is cleared.

  if(taf_locGnss_ForceColdRestart() == LE_OK)
  {
    // Process after successfully deleting the aiding data and restarting the location session.
  }

Obtain Time To First Fix (TTFF)

The taf_locGnss_GetTtff() function provides the TTFF

  uint32_t ttff = 0;
  if(taf_locGnss_GetTtff(&ttff) == LE_OK)
  {
    // Process after successfully getting the time of computing the first GNSS fix
  }

The GNSS fix position is calculated by the GNSS engine. Its state can be retrieved with the taf_locGnss_GetPositionState() function. The GNSS fix position states are given by the taf_locGnss_FixState_t enum. The API is triggered inside the PositionHandlerFunction() function to get fix state from the position sample reference.

  taf_locGnss_FixState_t fixState;
  if(taf_locGnss_GetPositionState(positionSampleRef,&fixState)== LE_OK)
  {
    // Process after successfully getting the position state.
  }

Set/Get location acquisition rate

The acquisition rate defines the time interval that must elapse between two location reports. The default aquisition rate is 1 sec. The application can configure or retreive the Location service acquisition rate with the taf_locGnss_SetAcquisitionRate() or taf_locGnss_GetAcquisitionRate() functions.

  if(taf_locGnss_SetAcquisitionRate(3000)== LE_OK)
  {
    // Process after successfully setting the acquisition rate to 3 seconds.
  }

  uint32_t acqRate = 0;
  if(taf_locGnss_GetAcquisitionRate(&acqRate)== LE_OK)
  {
    // Process after successfully getting the acquisition rate
  }

Control GNSS constellation blacklisting

The taf_locGnss_SetConstellation() function blacklists some constellations or subset of SVs from the constellation from being used by the GNSS standard position engine (SPE).

  taf_locGnss_ConstellationBitMask_t constellationMask;
  constellationMask = TAF_LOCGNSS_CONSTELLATION_GPS;
  if(taf_locGnss_SetConstellation(constellationMask)== LE_FAULT)
  {
    // GPS constellation and SVs cannot be blacklisted.
  }

  constellationMask = TAF_LOCGNSS_CONSTELLATION_SBAS | taf_locGnss_CONSTELLATION_BEIDOU;
  if(taf_locGnss_SetConstellation(constellationMask)== LE_OK)
  {
    // Process after successfully blacklisting SBAS and BEIDOU.
  }

Warning: Some constellation types are unsupported depending on the platform.

The taf_locGnss_GetConstellation() function gets the blacklisted GNSS constellation(s).

  taf_locGnss_ConstellationBitMask_t constellationMask;
  if(taf_locGnss_GetConstellation(&constellationMask)== LE_OK)
  {
    // Process after successfully getting the blacklisted constellation type.
  }

The taf_locGnss_GetSupportedConstellations() function gets a bitmask of the constellations supported on the platform.

  taf_locGnss_ConstellationBitMask_t supportedConstellations;
  if(taf_locGnss_GetSupportedConstellations(&supportedConstellations)== LE_OK)
  {
    // Process after successfully getting the list of supported constellations.
  }

GNSS minimum elevation selection

The taf_locGnss_SetMinElevation() function sets the GNSS minimum elevation. Satellites with elevation lower than the minimum elevation will will not be used in computation of position.

  uint8_t  minElevation;
  minElevation = 40;
  if(taf_locGnss_SetMinElevation(minElevation)== LE_OK)
  {
    // Process after successfully setting the minimum elevation.
  }

The taf_locGnss_GetMinElevation() function gets the GNSS minimum elevation.

  uint8_t  minElevation;
  if(taf_locGnss_GetMinElevation(&minElevation)== LE_OK)
  {
    // Process after successfully getting the minimum elevation.
  }

APIs to control NMEA sentences

A handler function should be registered for NMEA sentences notifications. taf_locGnss_AddNmeaHandler() allows users to register a NMEA handler.

The handler function is invoked whenever new NMEA sentences are available.

The handler must follow the below prototype:

  static void NmeaHandlerFunction
  (
      uint64_t timestamp,
      char nmeaInfo[TAF_LOCGNSS_NMEA_STRING_MAX],
      void* contextPtr
  )
  {
     // Process the NMEA sentence type received in the handler function.
  }

Note: If many applications register handlers for NMEA notifications, they will all receive it.

An application may unregister a NMEA handler by calling taf_locGnss_RemoveNmeaHandler().

The National Marine Electronics Association (NMEA) standard defines an electrical interface and data protocol for communications between marine instrumentation. $GP (Global Positioning System), $GL (GLONASS) and $GN (combination of navigation systems). The taf_locGnss_SetNmeaSentences() function selects the enabled NMEA sentences with a bitmask. The supported values are listed in taf_locGnss_NmeaBitMask_t.

  taf_locGnss_NmeaBitMask_t nmeaMask;
  nmeaMask = TAF_LOCGNSS_NMEA_MASK_GPGGA;
  if(taf_locGnss_SetNmeaSentences(nmeaMask)== LE_OK)
  {
    // Process after successfully setting a NMEA sentence type.
  }

Note: This function may be subject to limitations depending on the platform.

Warning: Some NMEA sentences are unsupported depending on the platform.

Note: All supported NMEA sentences are enabled by default.

The taf_locGnss_GetNmeaSentences() function gets the bitmask of the enabled NMEA sentences.

  taf_locGnss_NmeaBitMask_t nmeaMask;
  if(taf_locGnss_GetNmeaSentences(&nmeaMask)== LE_OK)
  {
    // Process after successfully getting a NMEA sentence type.
  }

The taf_locGnss_GetSupportedNmeaSentences() function gets a bitmask of the NMEA sentences supported on the platform.

  taf_locGnss_NmeaBitMask_t supportedNmeaSentences;
  if(taf_locGnss_GetSupportedNmeaSentences(&supportedNmeaSentences)== LE_OK)
  {
    // Process after successfully getting a list of supported NMEA sentence types.
  }

Get position information

The position information is referenced to a position sample object.

An application can register a handler to be notified of the updated position at a rate configured using Set/Get location acquisition rate, returning a position sample object.

The GNSS information commonly used, such as state, position, time and date, satellite information and accuracy can be queried using the following functions.

taf_locGnss_GetState()

  if(taf_locGnss_GetState()== TAF_LOCGNSS_STATE_READY)
  {
    // Process after successfully getting the status.
  }

taf_locGnss_GetPositionState() – Triggered inside PositionHandlerFunction() function to get fix state from the position sample reference.

  taf_locGnss_FixState_t state;
  if(taf_locGnss_GetPositionState(positionSampleRef,&state)
  {
    // Process after successfully getting fix state.
  }

taf_locGnss_GetLocation() – Triggered inside PositionHandlerFunction() function to get longitude, latitude, and horizontal accuracy from the position sample reference.

  int32_t     latitude;
  int32_t     longitude;
  int32_t     hAccuracy;
  if(taf_locGnss_GetLocation(positionSampleRef,&latitude,&longitude,&hAccuracy) == LE_OK)
  {
    // Process after successfully getting the location information.
  }

taf_locGnss_GetAltitude() – Triggered inside PositionHandlerFunction() function to get altitude and vertical accuracy from the position sample reference.

  int32_t     altitude;
  int32_t     vAccuracy;
  if(taf_locGnss_GetAltitude(positionSampleRef,&altitude,&vAccuracy) == LE_OK)
  {
    // Process after successfully getting the altitude.
  }

taf_locGnss_GetDate() – Triggered inside PositionHandlerFunction() function to get date information from the position sample reference.

  uint16_t year;
  uint16_t month;
  uint16_t day;
  if(taf_locGnss_GetDate(positionSampleRef,&year,&month, &day) == LE_OK)
  {
    // Process after successfully getting the date information.
  }

taf_locGnss_GetTime() – Triggered inside PositionHandlerFunction() function to get time information from the position sample reference.

  uint16_t hours;
  uint16_t minutes;
  uint16_t seconds;
  uint16_t milliseconds;
  if(taf_locGnss_GetTime(positionSampleRef,&hours,&minutes, &seconds, &milliseconds) == LE_OK)
  {
    // Process after successfully getting the time information.
  }

taf_locGnss_GetGpsTime() – Triggered inside PositionHandlerFunction() function to get GPS time from the position sample reference.

  uint32_t gpsWeek;
  uint32_t gpsTimeOfWeek;
  if(taf_locGnss_GetGpsTime(positionSampleRef,&gpsWeek,&gpsTimeOfWeek) == LE_OK)
  {
    // Process after successfully getting the GPS time information.
  }

taf_locGnss_GetGpsLeapSeconds() – Triggered inside PositionHandlerFunction() function to get GPS leap seconds from the position sample reference.

  uint8_t leapSeconds = 0;
  if(taf_locGnss_GetGpsLeapSeconds(positionSampleRef,&leapSeconds) == LE_OK)
  {
    // Process after successfully getting the GPS leap second information
  }

taf_locGnss_GetEpochTime() – Triggered inside PositionHandlerFunction() function to get epoch time from the position sample reference.

  uint64_t epochTime;
  if(taf_locGnss_GetEpochTime(positionSampleRef,&epochTime) == LE_OK)
  {
    // Process after successfully getting the Epoch time.
  }

taf_locGnss_GetTimeAccuracy() – Triggered inside PositionHandlerFunction() function to get time accuracy from the position sample reference.

  uint32_t TimeAccuracy=0;
  if(taf_locGnss_GetTimeAccuracy(positionSampleRef,&TimeAccuracy) == LE_OK)
  {
    // Process after successfully getting the time accuracy.
  }

taf_locGnss_GetHorizontalSpeed() – Triggered inside PositionHandlerFunction() function to get horizontal speed and its accuracy from the position sample reference.

  uint32_t hSpeed;
  uint32_t hSpeedAccuracy;
  if(taf_locGnss_GetHorizontalSpeed(positionSampleRef,&hSpeed,&hSpeedAccuracy) == LE_OK)
  {
    // Process after successfully getting the horizontal speed
  }

taf_locGnss_GetVerticalSpeed() – Triggered inside PositionHandlerFunction() function to get vertical speed and its accuracy from the position sample reference.

  int32_t vSpeed = 0;
  int32_t vSpeedAccuracy = 0;
  if(taf_locGnss_GetVerticalSpeed(positionSampleRef,&vSpeed,&vSpeedAccuracy) == LE_OK)
  {
    // Process after successfully getting the vertical speed.
  }

taf_locGnss_GetDirection() – Triggered inside PositionHandlerFunction() function to get direction and its accuracy from the position sample reference.

  uint32_t direction = 0;
  uint32_t directionAccuracy = 0;
  if(taf_locGnss_GetDirection(positionSampleRef,&direction,&directionAccuracy) == LE_OK)
  {
    // Process after successfully getting the direction information.
  }

taf_locGnss_GetSatellitesInfo() – Triggered inside PositionHandlerFunction() function to get satellites information from the position sample reference.

  uint16_t satIdPtr[TAF_LOCGNSS_SV_INFO_MAX_LEN];
  size_t satIdNumElements = NUM_ARRAY_MEMBERS(satIdPtr);
  taf_locGnss_Constellation_t satConstPtr[TAF_LOCGNSS_SV_INFO_MAX_LEN];
  size_t satConstNumElements = NUM_ARRAY_MEMBERS(satConstPtr);
  bool satUsedPtr[TAF_LOCGNSS_SV_INFO_MAX_LEN];
  size_t satUsedNumElements = NUM_ARRAY_MEMBERS(satUsedPtr);
  uint8_t satSnrPtr[TAF_LOCGNSS_SV_INFO_MAX_LEN];
  size_t satSnrNumElements = NUM_ARRAY_MEMBERS(satSnrPtr);
  uint16_t satAzimPtr[TAF_LOCGNSS_SV_INFO_MAX_LEN];
  size_t satAzimNumElements = NUM_ARRAY_MEMBERS(satAzimPtr);
  uint8_t satElevPtr[TAF_LOCGNSS_SV_INFO_MAX_LEN];
  size_t satElevNumElements = NUM_ARRAY_MEMBERS(satElevPtr);
  if(taf_locGnss_GetSatellitesInfo(positionSampleRef,satIdPtr,&satIdNumElements
                                                 ,satConstPtr,&satConstNumElements
                                                 ,satUsedPtr,&satUsedNumElements
                                                 ,satSnrPtr,&satSnrNumElements
                                                 ,satAzimPtr,&satAzimNumElements
                                                 ,satElevPtr,&satElevNumElements) == LE_OK)
  {
    // Process after successfully getting the satellite information.
  }

taf_locGnss_GetSatellitesStatus() – Triggered inside PositionHandlerFunction() function to get satellites status from the position sample reference.

  uint8_t satsInViewCount;
  uint8_t satsTrackingCount;
  uint8_t satsUsedCount;
  if(taf_locGnss_GetSatellitesStatus(positionSampleRef,&satsInViewCount,&satsTrackingCount,&satsUsedCount) == LE_OK)
  {
    // Process after successfully getting the satellite status information.
  }

taf_locGnss_ConfigureEngineState() – Triggered to set the engine state for the given engine type.

  if(taf_locGnss_ConfigureEngineState(TAF_LOCGNSS_ENGINE_TYPE_SPE,TAF_LOCGNSS_ENGINE_STATE_SUSPENDED) == LE_OK)
  {
    // Process after successfully configuring Engine state for the given Engine type
  }

taf_locGnss_ConfigureRobustLocation() – Triggered to enable or disable robust location while device is on E911.

  int enable = (1<<(TAF_LOCGNSS_SB_CONSTELLATION_GPS-1));
  int enabled911 =1;
  if(taf_locGnss_ConfigureRobustLocation(enable,enabled911) == LE_OK)
  {
    // Process after successfully configuring configuring robust location.
  }

taf_locGnss_RobustLocationInformation() – Get robust location status and version.

  uint8_t enable;
  uint8_t enabled911;
  uint8_t majorVersion;
  uint8_t minorVersion;
  if(taf_locGnss_RobustLocationInformation(&enable,&enabled911, &majorVersion,&minorVersion) == LE_OK)
  {
    // Process after successfully getting Robust location information for Enable/Disable, 911 enable or disable, major and minor version numbers
  }

taf_locGnss_DefaultSecondaryBandConstellations() – Triggered to set the default secondary band constellations.

  if(taf_locGnss_DefaultSecondaryBandConstellations() == LE_OK)
  {
    // Process after successfully setting default secondary Band constellations
  }

taf_locGnss_RequestSecondaryBandConstellations() – Triggered to get the secondary band constellations set.

  int32_t constellationSb=0;
  if(taf_locGnss_RequestSecondaryBandConstellations(&constellationSb)==LE_OK)
  {
    // Process after successfully getting secondary band constellations set
  }

taf_locGnss_ConfigureSecondaryBandConstellations() – Triggered to set the secondary band constellation using a bitmask.

  uint32_t constellationSb = 1;
  if(taf_locGnss_ConfigureSecondaryBandConstellations(constellationSb)==LE_OK)
  {
    // Process after successfully configuring secondary Band constellations
  }

taf_locGnss_GetDilutionOfPrecision() – Triggered inside PositionHandlerFunction() function to get DOP from the position sample reference.

  uint16_t dop;
  taf_locGnss_DopType_t dopType = TAF_LOCGNSS_PDOP;
  if(taf_locGnss_GetDilutionOfPrecision(positionSampleRef,dopType,&dop) == LE_OK)
  {
    // Process after successfully getting the dilute of precision for dilute of precision type.
  }

taf_locGnss_GetMagneticDeviation() – Triggered inside the PositionHandlerFunction() function to get magnetic deviation from the position sample reference.

  int32_t magneticDeviation;
  if(taf_locGnss_GetMagneticDeviation(positionSampleRef,&magneticDeviation) == LE_OK)
  {
    // Process after successfully getting the magnetic deviation.
  }

taf_locGnss_GetEllipticalUncertainty() – Triggered inside the PositionHandlerFunction() function to get semi major and semi minor from positionSampleRef.

  uint32_t SemiMajor;
  uint32_t SemiMinor;
  if(taf_locGnss_GetEllipticalUncertainty(positionSampleRef,&SemiMajor, &SemiMinor) == LE_OK)
  {
    // Process after successfully getting the elliptical uncertainty values.
  }

taf_locGnss_SetDRConfig() – Triggered to configure the dead reckoning parameters. By default all DRE parameters mask get enabled.

  taf_locGnss_DrParams_t *drParamsPtr;
  static le_mem_PoolRef_t DrFramePool = NULL;
  DrFramePool = le_mem_CreatePool("DrframePool", sizeof(taf_locGnss_DrParams_t));
  drParamsPtr = (taf_locGnss_DrParams_t*) le_mem_ForceAlloc(DrFramePool);
  drParamsPtr->rollOffset = 1.2;
  drParamsPtr->yawOffset = 2.3;
  drParamsPtr->pitchOffset = 3.4;
  drParamsPtr->offsetUnc = 180.0;
  drParamsPtr->speedFactor = 1.0;
  drParamsPtr->speedFactorUnc = 0.0;
  drParamsPtr->gyroFactor = 1.0;
  drParamsPtr->gyroFactorUnc = 0.0;
  if(taf_locGnss_SetDRConfig(drParamsPtr) == LE_OK)
  {
    // Process after successfully configuring the dead reckoning parameters with the default mask enabled.
  }
  le_mem_Release(drParamsPtr);

taf_locGnss_SetLeverArmConfig() – Triggered to configure the lever arm parameters.

  taf_locGnss_LeverArmParams_t *leverArmParamsPtr;
  static le_mem_PoolRef_t LevArmFramePool = NULL;
  LevArmFramePool = le_mem_CreatePool("LevArmFramePool", sizeof(taf_locGnss_LeverArmParams_t));
  leverArmParamsPtr = (taf_locGnss_LeverArmParams_t*) le_mem_ForceAlloc(LevArmFramePool);
  leverArmParamsPtr->forwardOffsetMeters = 5.5;
  leverArmParamsPtr->sidewaysOffsetMeters = 1.2;
  leverArmParamsPtr->upOffsetMeters = 1.0;
  leverArmParamsPtr->levArmType = TAF_LOCGNSS_LEVER_ARM_TYPE_GNSS_TO_VRP;
  if(taf_locGnss_SetLeverArmConfig(leverArmParamsPtr) == LE_OK)
  {
    // Process after successfully configuring the lever arm parameters.
  }
  le_mem_Release(leverArmParamsPtr);

taf_locGnss_SetEngineType() – Triggered to set an engine type.

  taf_locGnss_EngineReportsType_t EngineType;
  EngineType = TAF_LOCGNSS_ENGINE_REPORT_TYPE_FUSED;
  if(taf_locGnss_SetEngineType(EngineType) == LE_OK)
  {
    // Process after successfully setting an engine type.
  }

taf_locGnss_GetConformityIndex() – Triggered inside the PositionHandlerFunction() function to get conformity index from the position sample reference.

  double indexPtr;
  if(taf_locGnss_GetConformityIndex(positionSampleRef,&indexPtr) == LE_OK)
  {
    // Process after successfully getting the conformity index.
  }

taf_locGnss_GetCalibrationData() – Triggered inside the PositionHandlerFunction() function to get calibration data from the position sample reference.

  uint32 calibPtr;
  uint8_t percentPtr;
  if(taf_locGnss_GetCalibrationData(positionSampleRef,&calibPtr,&percentPtr) == LE_OK)
  {
    // Process after successfully getting the calibration status and confidence percentage.
  }

taf_locGnss_GetBodyFrameData() – Triggered inside the PositionHandlerFunction() function to get body frame data from the positionSampleRef.

  taf_locGnss_KinematicsData_t *bodyFrameData;
  le_mem_PoolRef_t bodyFramePool = NULL;
  bodyFramePool = le_mem_CreatePool("bodyFramePool", sizeof(taf_locGnss_KinematicsData_t));
  bodyFrameData = (taf_locGnss_KinematicsData_t*) le_mem_ForceAlloc(bodyFramePool);
  if(taf_locGnss_GetBodyFrameData(positionSampleRef,bodyFrameData) == LE_OK)
  {
    // Process after successfully getting the body frame parameters.
  }

taf_locGnss_GetVRPBasedLLA() – Triggered inside the PositionHandlerFunction() function to get VRP based LLA from the position sample reference.

  double vrpLatitude;
  double vrpLongitude;
  double vrpAltitude;
  if(taf_locGnss_GetVRPBasedLLA(positionSampleRef, &vrpLatitude,&vrpLongitude,&vrpAltitude) == LE_OK)
  {
    // Process after successfully getting VRP based latitude, longitude, and altitude information.
  }

taf_locGnss_GetVRPBasedVelocity() – Triggered inside the PositionHandlerFunction() function to get VRP based velocity from the position sample reference.

  double eastVel;
  double northVel;
  double upVel;
  if(taf_locGnss_GetVRPBasedVelocity(positionSampleRef, &eastVel,&northVel,&upVel) == LE_OK)
  {
    // Process after successfully getting VRP based east, north, and up velocity information.
  }

taf_locGnss_GetSvUsedInPosition() – Triggered inside the PositionHandlerFunction() function to get SV used in position from the position sample reference.

  taf_locGnss_SvUsedInPosition_t *svData;
  le_mem_PoolRef_t svFramePool = NULL;
  svFramePool = le_mem_CreatePool("svFramePool", sizeof(taf_locGnss_SvUsedInPosition_t));
  svData = (taf_locGnss_SvUsedInPosition_t*) le_mem_ForceAlloc(svFramePool);
  if(taf_locGnss_GetSvUsedInPosition(positionSampleRef, svData) == LE_OK)
  {
    // Process after successfully getting set of SVs that are used to calculate position.
  }

taf_locGnss_GetSbasCorrection() – Triggered inside the PositionHandlerFunction() function to get SBAS correction from the position sample reference.

  uint32_t sbasMask;
  if(taf_locGnss_GetSbasCorrection(positionSampleRef, &sbasMask) == LE_OK)
  {
    // Process after successfully getting the mask used to indicate SBAS corrections.
  }

taf_locGnss_GetPositionTechnology() – Triggered inside the PositionHandlerFunction() function to get position technology from the position sample reference.

  uint32_t techMask;
  if(taf_locGnss_GetPositionTechnology(positionSampleRef,&techMask) == LE_OK)
  {
    // Process after successfully getting position tech mask
  }

taf_locGnss_GetLocationInfoValidity() – Triggered inside the PositionHandlerFunction() function to get location information validity from the position sample reference.

  uint32_t validityMask;
  uint64_t validityExMask;
  if(taf_locGnss_GetLocationInfoValidity(positionSampleRef, &validityMask,&validityExMask) == LE_OK)
  {
    // Process after successfully getting the validity information
  }

taf_locGnss_GetLocationOutputEngParams() – Triggered inside the PositionHandlerFunction() function to get engine output parameters from the position sample reference.

  uint16_t engMask;
  uint16_t locationEngType;
  if(taf_locGnss_GetLocationOutputEngParams(positionSampleRef, &engMask,&locationEngType) == LE_OK)
  {
    // Process after successfully getting the location engine mask and engine type parameters.
  }

taf_locGnss_GetReliabilityInformation() – Triggered inside the PositionHandlerFunction() function to get reliablity information from the position sample reference.

  uint16_t horireliability;
  uint16_t vertreliability;
  if(taf_locGnss_GetReliabilityInformation(positionSampleRef, &horireliability,&vertreliability) == LE_OK)
  {
    // Process after successfully getting the horizontal and vertical reliability information.
  }

taf_locGnss_GetStdDeviationAzimuthInfo() – Triggered inside the PositionHandlerFunction() function to get standard deviation and azimuth information from the position sample reference.

  double azimuth;
  double eastDev;
  double northDev;
  if(taf_locGnss_GetStdDeviationAzimuthInfo(positionSampleRef, &azimuth,&eastDev,&northDev) == LE_OK)
  {
    // Process after successfully getting the azimuth, east, and north deviation information.
  }

taf_locGnss_GetRealTimeInformation() – Triggered inside the PositionHandlerFunction() function to get real time information from the position sample reference.

  uint64_t realTime;
  uint64_t realTimeUnc;
  if(taf_locGnss_GetRealTimeInformation(positionSampleRef, &realTime,&realTimeUnc) == LE_OK)
  {
    // Process after successfully getting elapsed real time and its uncertainity.
  }

taf_locGnss_GetMeasurementUsageInfo() – Triggered inside the PositionHandlerFunction() function to get GNSS measurement usage information from the position sample reference.

  taf_locGnss_GnssMeasurementInfo_t measInfo[TAF_LOCGNSS_MEASUREMENT_INFO_MAX];
  size_t gnssMeasLen = TAF_LOCGNSS_MEASUREMENT_INFO_MAX;
  if(taf_locGnss_GetMeasurementUsageInfo(positionSampleRef, measInfo, &gnssMeasLen) == LE_OK)
  {
    // Process after successfully getting GNSS measurement information.
  }

taf_locGnss_GetReportStatus() – Triggered inside the PositionHandlerFunction() function to get status of report in terms of how optimally the report was calculated by the engine from the position sample reference.
```
  int32_t reportStatus = -1;
  if(taf_locGnss_GetReportStatus(positionSampleRef, &reportStatus) == LE_OK)
  {
    // Process after successfully getting the report status.
  }
```
taf_locGnss_GetAltitudeMeanSeaLevel() – Triggered inside the PositionHandlerFunction() function to get altitude with respect to mean sea level in meters from the position sample reference.
```
  double altMSeaLevel;
  if(taf_locGnss_GetAltitudeMeanSeaLevel(positionSampleRef, &altMSeaLevel) == LE_OK)
  {
    // Process after successfully getting the mean sea level.
  }
```

taf_locGnss_GetSVIds() – Triggered inside the PositionHandlerFunction() function to get GNSS Satellite Vehicles used in position data from the position sample reference.

  uint16_t svIds[TAF_LOCGNSS_MEASUREMENT_INFO_MAX];
  size_t svIdsLen = TAF_LOCGNSS_MEASUREMENT_INFO_MAX;
  if(taf_locGnss_GetSVIds(positionSampleRef, svIds, &svIdsLen) == LE_OK)
  {
    // Process after successfully getting the GNSS Satellite Vehicles used in position data.
  }

taf_locGnss_GetDilutionOfPrecision() – Gets the Dilution of Precision (DOP) paramters with a resolution of 3 decimal places by default. This resolution can be modified by calling the taf_locGnss_SetDopResolution() function first.

taf_locGnss_SetDopResolution() – Sets the resolution per client session.

  static taf_locGnss_Resolution_t DopRes = TAF_LOCGNSS_RES_ONE_DECIMAL;
  if(taf_locGnss_SetDopResolution(DopRes) == LE_OK)
  {
    // Process after successfully setting the dilute of precision resolution
  }

taf_locGnss_SetDopResolution() and taf_locGnss_GetDilutionOfPrecision() functions should be called in the same thread or client session.

taf_locGnss_SetMinGpsWeek() – Sets the minimum GPS week used by the modem GNSS standard position engine (SPE). This API shall not be called when GNSS state is ACTIVE. Behavior is not defined if client issues a second request of SetMinGpsWeek without waiting for the previous SetMinGpsWeek to finish. Additionally minimum GPS week number shall NEVER be in the future of the current GPS Week.
```
  uint16        minGpsWeek = 1;
  if(taf_locGnss_SetMinGpsWeek(minGpsWeek) == LE_OK)
  {
    // Process after succesfully setting the minimum GPS week.
  }
```

taf_locGnss_GetMinGpsWeek() – Gets the minimum GPS week used by the modem GNSS standard position engine (SPE).

  uint16        minGpsWeek;
  if(taf_locGnss_GetMinGpsWeek(&minGpsWeek) == LE_OK)
  {
    // Process after succesfully getting the minimum GPS week.
  }

A handler function should be registered for location capability notification. taf_locGnss_AddCapabilityChangeHandler() allows users to register a location capability handler.

When the capability of the GNSS stack changes, the handler is invoked to notify the client about the update.

The handler must follow the below prototype:

  static void CapabilityHandlerFunction
  (
      taf_locGnss_LocCapabilityType_t locCapability,
      void* contextPtr
  )
  {
      // Process the location capability received in the handler function.
  }

Note: If many applications register handlers for capability notifications, they will all receive it.

An application may unregister a capability handler by calling taf_locGnss_RemoveCapabilityChangeHandler().

taf_locGnss_GetCapabilities() – Gets the GNSS capability information.

  uint64  locCapability;
  if(taf_locGnss_GetCapabilities(&locCapability) == LE_OK)
  {
    // Process after succesfully getting the GNSS capability information.
  }

taf_locGnss_SetNmeaConfiguration() – Sets the configuration for NMEA sentences that will be received by the clients via NmeaHandler.

Without prior invocation to this API, all NMEA sentences supported in the system will get generated and delivered to all the clients that register to receive NMEA sentences. The configuration is common across all clients and updating it will affect all clients.

  taf_locGnss_NmeaBitMask_t nmeaMask = TAF_LOCGNSS_NMEA_MASK_GPGGA | TAF_LOCGNSS_NMEA_MASK_GPGNS;
  taf_locGnss_GeodeticDatumType_t datumType = TAF_LOCGNSS_GEODETIC_TYPE_WGS_84;
  taf_locGnss_LocEngineType engineType = TAF_LOCGNSS_LOC_REQ_ENGINE_FUSED_BIT
  if(taf_locGnss_SetNmeaConfiguration(nmeaMask, datumType, engineType) == LE_OK)
  {
    // Process after succesfully getting the the NMEA sentences.
  }

Note: This API call is not incremental and the new NMEA configuration will completely overwrite the previous call to this API.

taf_locGnss_GetXtraStatus() – Gets whether the XTRA feature is enabled or not, XTRA data status, and the valid time in hours.

  taf_locGnss_XtraStatusParams_t *XtraParamsPtr;
  le_result_t result = LE_FAULT;
  le_mem_PoolRef_t XtraFramePool = NULL;
  XtraFramePool = le_mem_CreatePool("XtraFramePool", sizeof(taf_locGnss_XtraStatusParams_t));
  XtraParamsPtr = (taf_locGnss_XtraStatusParams_t*) le_mem_ForceAlloc(XtraFramePool);
  if(XtraParamsPtr != NULL)
  {
      if(taf_locGnss_GetXtraStatus(XtraParamsPtr) == LE_OK)
      {
        // Process after successfully getting the XTRA data parameters.
      }
  }
  le_mem_Release(XtraParamsPtr);

taf_locGnss_GetGnssData() – Gets GNSS data for data mask, jammer indication, and Automatic Gain Control (AGC) information.

  size_t maxSigTypes = TAF_LOCGNSS_NUMBER_OF_SIGNAL_TYPES_MAX;
  taf_locGnss_GnssData_t gnssDataPtr[TAF_LOCGNSS_NUMBER_OF_SIGNAL_TYPES_MAX];
  if(taf_locGnss_GetGnssData(positionSampleRef, gnssDataPtr, &maxSigTypes))
  {
    // Process after successfully getting data mask, jammer, and AGC information.
  }

taf_locGnss_SetDRConfigValidity() – Sets the dead reckoning parameters validity mask.

  taf_locGnss_DRConfigValidityType_t drParamsMask;
  taf_locGnss_DrParams_t *drParamsPtr;
  drParamsMask |= TAF_LOCGNSS_BODY_TO_SENSOR_MOUNT_PARAMS_VALID;
  drParamsMask |= TAF_LOCGNSS_VEHICLE_SPEED_SCALE_FACTOR_VALID;
  drParamsMask |= TAF_LOCGNSS_VEHICLE_SPEED_SCALE_FACTOR_UNC_VALID;
  drParamsMask |= TAF_LOCGNSS_GYRO_SCALE_FACTOR_VALID;
  drParamsMask |= TAF_LOCGNSS_GYRO_SCALE_FACTOR_UNC_VALID;
  static le_mem_PoolRef_t DrFramePool = NULL;
  DrFramePool = le_mem_CreatePool("DrframePool", sizeof(taf_locGnss_DrParams_t));
  drParamsPtr = (taf_locGnss_DrParams_t*) le_mem_ForceAlloc(DrFramePool);
  drParamsPtr->rollOffset = 1.2;
  drParamsPtr->yawOffset = 2.3;
  drParamsPtr->pitchOffset = 3.4;
  drParamsPtr->offsetUnc = 180.0;
  drParamsPtr->speedFactor = 1.0;
  drParamsPtr->speedFactorUnc = 0.0;
  drParamsPtr->gyroFactor = 1.0;
  drParamsPtr->gyroFactorUnc = 0.0;
  if(taf_locGnss_SetDRConfigValidity(drParamsMask) == LE_OK)
  {
    // Process after successfully setting the dead reckoning parameters validity mask.
  }
  if(taf_locGnss_SetDRConfig(drParamsPtr) == LE_OK)
  {
    // Process after successfully configuring the dead reckoning parameters with the mask enabled.
  }
  le_mem_Release(drParamsPtr);

taf_locGnss_GetGptpTime() – Gets Gptp time and its uncertainty

  uint64_t gPtpTime;
  uint64_t gPtpTimeUnc;
  if(taf_locGnss_GetGptpTime(positionSampleRef,&gPtpTime,&gPtpTimeUnc))
  {
    // Process after successfully getting Gptp time information.
  }

Get leap seconds event information

The leap seconds event information is retrieved by calling taf_locGnss_GetLeapSeconds() API. The result includes the current GPS time, current leap seconds, next leap second event time, and next leap seconds. Insertion of each UTC leap second is usually decided about six months in advance by the International Earth Rotation and Reference Systems Service (IERS).

Typical application call flow

The Location application locates in NAD device and access the tafLocationSvc on the corresponding NAD device.

#0 – Start GNSS session with the service.

#1 – Add the position handler to be able to receive any GNSS fixes received from the location service.

#2 – Get location information including longitude, latitude and horizontal accuracy.

#3 – Get the altitude information and its accuracy.

#4 – Get the vehicle direction information and its accuracy.

#5 – Get the horizontal speed information and its accuracy.

#6 – Get the vertical speed information and its accuracy.

#7 – Get the position state, ex. 2D, 3D and Estimated Fix.

#8 – When there's no need to receive any GNSS fixes from the application, the registered handler reference can be removed.

#9 – Stop the GNSS session with the service. This will stop receiving fixes at the location service.