Qualcomm Enhanced SDK (QESDK) API Reference (12)

Qualcomm Enhanced SDK (QESDK) API Reference (12)

    • 6.3 Common location APIs, callbacks, enums, and structures
      • 6.3.1 Universal position function
      • 6.3.2 Native NTRIP client API
      • 6.3.3 Application Correction Data API
      • 6.3.4 Position callback
      • 6.3.5 Location enumeration
        • 6.3.5.1 Location status
        • 6.3.5.2 LocationQuality
        • 6.3.5.3 CorrectionDataType
        • 6.3.5.4 LocationCapabilities
        • 6.3.5.5 LocationFlagsBits
      • 6.3.6 Support classes and structures
    • 6.4 Code examples

6.3 Common location APIs, callbacks, enumerations and structures

6.3.1 Universal position function

requestPreciseLocationUpdates
Start a pinpoint tracking session with meter-level accuracy.

requestPreciseLocationUpdates( )

Note
When minIntervalMillis is set to 0, the callback is called whenever data is ready, which is the shortest interval supported by the engine.
Currently minIntervalMillis set to any other value internally defaults to 1 second, with pinpointing sessions running at 1 second intervals.

removePreciseLocationUpdates
Stop an ongoing precise location session.

removePreciseLocationUpdates()

registerLocationCapabilitiesCallback
Register to receive location module capabilities defined in the LocationCapabilities enumeration.
Previous

registerLocationCapabilitiesCallback( )

6.3.2 Native NTRIP Client API

These APIs configure and use native NTRIP clients to provide correction data to the precision positioning engine (eDGNSS/RTK)

Note
Only OEM applications are allowed to run these APIs. Missing OEM permissions will return EDGNSS_LOCATION_STATUS_FAILURE_UNSUPPORTED. OEM applications need to declare the com.qualcomm.qti.permission.ACCESS_PRECISE_LOCATION_API user permission in the Android manifest file to call the native NTRIP configuration API.

updateNTRIPGGAConsent
Grant permission to the native NTRIP client to share GGA NMEA with the NTRIP server. If the NTRIP server does not require GGA NMEA data, the user does not need to accept the GGA NMEE license. If the NTRIP server requires GGA NMEA data, the user should accept permission to obtain correction data. Only OEM applications are allowed to run this API.

updateNTRIPGGAConsent( )

enablePPENtripStream
Enable native NTRIP client in location module. Only one OEM application is required to configure the NTRIP native client at a time.

enablePPENtripStream( )

disablePPENtripStream
Disable native NTRIP server. Only OEM applications are allowed to run this API.

disablePPENtripStream( )

6.3.3 Application Correction Data API

These APIs are used to register an application as a source of corrected data and inject corrected data on request.

registerAsCorrectionDataSource
Registers the application as a correction data provider for the pinpointing engine. This is the API that an application must call when requesting precise location updates.

deRegisterAsCorrectionDataSource
Remove the application that is the correction data provider. Once an application as a correction data provider is removed, it can no longer request precise location updates.

injectCorrectionData
Inject correction data for use by the pinpointing engine.

6.3.4 Position callback

ILocationReportCallback
This callback receives the location field as parameter.

ILocationCapabilitiesCallback
This callback receives a feature mask as parameter.

ICorrectionStreamingControlCallback
This callback receives as a parameter a request to start or stop the transmission of correction data to the precision positioning engine. When receiving this callback, the application must choose to start or stop injection of correction data based on the parameter value.

6.3.5 Location enumeration

6.3.5.1 Location Status

Note
RTK subsystem replaces EDGNSS with RTK.

Value Description
EDGNSS_LOCATION_STATUS_SUCCESS Operation successful
EDGNSS_LOCATION_STATUS_FAILURE Unforeseen internal error.
EDGNSS_LOCATION_STATUS_FAILURE_UNSUPPORTED The operation is not supported.
EDGNSS_LOCATION_STATUS_FAILURE_INVALID_ARGS The specified parameter value is invalid.
EDGNSS_LOCATION_STATUS_FAILURE_MISSING_CBA The callback is missing.
EDGNSS_LOCATION_STATUS_FAILURE_NO_CORRECTION_DATA The application has not been registered as a correction data source (via registerAsCorrectionDataSource).
EDGNSS_LOCATION_STATUS_FAILURE_MISSING_PERMISSION The application is missing one or more mandatory permissions.
6.3.5.2 LocationQuality

Note
RTK System Used when replacing EDGNSS with RTK.

Enumeration value Description
EDGNSS_LOCATION_QUALITY_STANDALONE Position calculated using only satellite signals.
EDGNSS_LOCATION_QUALITY_DGNSS Location calculated using satellite signals and eDGNSS technology.
EDGNSS_LOCATION_QUALITY_FLOAT Position calculated using satellite signals and RTK technology; floating point.
Note Not applicable to EDGNSS subsystem
EDGNSS_LOCATION_QUALITY_FIXED not applicable.
6.3.5.3 CorrectionDataType
Enumeration value
CORRECTION_DATA_TYPE_EDGNSS
CORRECTION_DATA_TYPE_RTK
6.3.5.4 LocationCapabilities
Enumeration value Integer value
PP_LOCATION_CAPABILITIES_EDGNSS_BIT 1
PP_LOCATION_CAPABILITIES_RTK_BIT 2
6.3.5.5 LocationFlagsBits
Enumeration value Integer value
PP_LOCATION_HAS_LAT_LONG_BIT 1
PP_LOCATION_HAS_ALTITUDE_BIT 2
PP_LOCATION_HAS_SPEED_BIT 4
PP_LOCATION_HAS_BEARING_BIT 8
PP_LOCATION_HAS_ACCURACY_BIT 16
PP_LOCATION_HAS_VERTICAL_ACCURACY_BIT 32
PP_LOCATION_HAS_SPEED_ACCURACY_BIT 64
PP_LOCATION_HAS_BEARING_ACCURACY_BIT 128
PP_LOCATION_HAS_ELAPSED_REAL_TIME_BIT 256
PP_LOCATION_HAS_ELAPSED_REAL_TIME_UNC_BIT 512

6.3.6 Support classes and structures

Location Report

Location class (Java) / pp_rtk_Location structure (native)

Note
The precision field indicates + /- the corresponding value.

6.4 Code Example

Java
Need to import

import com.qualcomm.qti.qesdkIntf.IQesdk;
import com.qualcomm.qti.qesdk.QesdkStatusException;
import com.qualcomm.qti.qesdk.Location.PP_eDGNSSUDT;
import com.qualcomm.qti.qesdk.Location.PP_RTKUDT;
import com.qualcomm.qti.qesdk.Location.IPP_RTKCBs;
import com.qualcomm.qti.qesdk.Location.IPP_eDGNSSCBs;
import com.qualcomm.qti.qesdk.Location.PP_RTKEnums;
import com.qualcomm.qti.qesdk.Location.PP_RTKManager;
import com.qualcomm.qti.qesdk.Location.PP_eDGNSSEnums;
import com.qualcomm.qti.qesdk.Location.PP_eDGNSSManager;

Declare required objects

private IQesdk mQesdkManager;
private PP_eDGNSSManager mPpeEdgnssManager;
private PP_RTKManager mPpeRtkManager;

Create a QESDK manager instance and initialize it

mQesdkManager = IQesdk.createInstance(this);
int statusId = qesdkManager.init(eventCallbackHandler);

Create an eDGNSS or RTK manager instance as needed

mPpeEdgnssManager = new PP_eDGNSSManager(mQesdkManager);
mPpeRtkManager = new PP_RTKManager(mQesdkManager);

Set callback

IQesdkEventCallBack eventCallbackHandler = new IQesdkEventCallBack() {<!-- -->
      @Override
      public void onEvent(int opcode, int[] subsys) {<!-- -->
      // Handle QESDK event
      }
      };
      
      // For Checking eDGNSS/ RTK precise positioning Capabilities
      private IPP_eDGNSSCBs.ILocationCapabilitiesCallback locationCapabilitiesCallback = new IPP_eDGNSSCBs.ILocationCapabilitiesCallback() {<!-- -->
      @Override
      public void onValues(long l) {<!-- -->
      // Check precise positioning Capabilities
      }
      };
      
      
      // For controlling correction data streaming to Precise Positioning engine
      private IPP_eDGNSSCBs.ICorrectionStreamingControlCallback streamingControlCallback = new IPP_eDGNSSCBs.ICorrectionStreamingControlCallback() {<!-- -->
      @Override
      public void onValues(PP_eDGNSSEnums.CorrectionStreamingState correctionStreamingState) {<!-- -->
      // Start or Stop correction data streaming as requested
      }
      };
      
      // For handling location reports
      private IPP_eDGNSSCBs.ILocationReportCallback eDgnssLocationReportCallback = new IPP_eDGNSSCBs.ILocationReportCallback() {<!-- -->
      @Override
      public void onValues(PP_eDGNSSUDT.Location location) {<!-- -->
      // Handle eDGNSS location report callback
      }
      };
      
      private IPP_RTKCBs.ILocationReportCallback rtkLocationReportCallback = new IPP_RTKCBs.ILocationReportCallback() {<!-- -->
      @Override
      public void onValues(PP_RTKUDT.Location location) {<!-- -->
      // Handle RTK location report callback
      }
      };

Get location function

registerLocationCapabilitiesCallback(locationCapabilitiesCallback)

Updated NTRIP GGA licensing for native NTRIP clients (OEM applications only)

mPpeEdgnssManager.updateNTRIPGGAConsent(ntripGgaConsent);

Configure native NTRIP client if needed (OEM applications only)

// enable Native NTRIP client
mPpeEdgnssManager.enablePPENtripStream(
      hostNameOrIp, mountPoint,
      username, password, port,
      requiresNmeaLocation, useSSL,
      enableRTKEngine);
      
// Disable Native NTRIP client
mPpeEdgnssManager.disablePPENtripStream();

Register as a correction data provider

mPpeEdgnssManager.registerAsCorrectionDataSource(
correctionDataType, streamingControlCallback);

Unregister as a calibration data provider

mPpeEdgnssManager.deRegisterAsCorrectionDataSource();

Send precise location update request

mPpeEdgnssManager.requestPreciseLocationUpdates(
            minIntervalMillis, eDgnssLocationReportCallback);

or

mPpeRtkManager.requestPreciseLocationUpdates(
      minIntervalMillis, rtkLocationReportCallback);

Remove precise location update request

mPpeEdgnssManager.removePreciseLocationUpdates(eDgnssLocationReportCallback)

or

mPpeRtkManager.removePreciseLocationUpdates(rtkLocationReportCallback)

When a StreamingControlCallback is received to start correction data injection, the correction data is downloaded from the application NTRIP client and then injected.

mPpeEdgnssManager.injectCorrectionData(correctionData);

Receive precise location reports in a registered ILocationReportCallback.

Native
What to include

#include "qesdk_ndk.h"
#include "qesdk_Location_PP_eDGNSS.h"
#include "qesdk_Location_PP_RTK.h"

initialization

qesdk_handle_t qesdk_handle = qesdk_init(nativeLicense, len, event_callback_handler);
PP_RTKManager *rtkManager = new PP_RTKManager();
PP_eDGNSSManager *edgnssManager = new PP_eDGNSSManager();
int ret = rtkManager->init(nativeLicense, len, event_callback_handler);
ret = edgnssManager->init(nativeLicense, len, event_callback_handler);

Set callback

void event_callback_handler(uint32_t opcode, uint32_t subsys[]) {<!-- -->
      // Callback to handle QESDK events
      }
      
      
void location_capabilities_callback(uint64_t capabilitiesMask){<!-- -->
      // Check precise positioning Capabilities
      }
      
void edgnss_CorrectionStreamingControlCallback(pp_edgnss_CorrectionStreamingState streamingState){<!-- -->
      // Start or Stop correction data streaming as requested
      }
      
void edgnss_LocationReportCallback(pp_edgnss_Location location){<!-- -->
      // Handle eDGNSS location report callback
      }
      
void rtk_LocationReportCallback(pp_rtk_Location location){<!-- -->
      // Handle RTK location report callback
      }

Get location function

ret = edgnssManager->registerLocationCapabilitiesCallback(location_capabilities_callback);

Updated NTRIP GGA licensing for native NTRIP clients (OEM applications only)

ret = edgnssManager->updateNTRIPGGAConsent(ntrip_gga_consent);

Configure native NTRIP client if needed (OEM applications only)

// enable Native NTRIP client
ret = edgnssManager->enablePPENtripStream(hostNameIP, mountPoint, userName, pass, server_port, require_nmealocation, use_ssl, enable_rtkengine);
// Disable Native NTRIP client
ret = edgnssManager->disablePPENtripStream();

Register as a correction data provider

ret = edgnssManager->registerAsCorrectionDataSource((pp_edgnss_CorrectionDataType)correction_data_type, edgnss_CorrectionStreamingControlCallback);

Unregister as a calibration data provider

ret = edgnssManager->deRegisterAsCorrectionDataSource();

Send precise location update request

ret = edgnssManager->requestPreciseLocationUpdates(min_interval_ms, edgnss_LocationReportCallback);

or

ret = rtkManager->requestPreciseLocationUpdates(min_interval_ms, rtk_LocationReportCallback);

Remove precise location update request

ret = edgnssManager->removePreciseLocationUpdates(edgnss_LocationReportCallback);

or

ret = rtkManager->removePreciseLocationUpdates(rtk_LocationReportCallback);

When a StreamingControlCallback is received to start correction data injection, the correction data is downloaded from the application NTRIP client and then injected.

ret = edgnssManager->injectCorrectionData(corr_data);

Receive precise location reports in a registered ILocationReportCallback.