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.