tps-location-sdk-native

TPS Location SDK (Native)

Platform

Prerequisites

Operating systems:

Hardware:

Obtaining SDK

Contact support.tps@qti.qualcomm.com to request access to the SDK, obtain the API key or get additional information.

Importing SDK

Import the header file in your code:

#include <wpsapi.h>

Link your executable against the wpsapi library:

API summary

The WPS API can be summarized to the following calls:

Initialization

Invoke WPS_load() before making any other WPS API calls.

When WPS API is no longer needed, or the application is terminating, call WPS_unload() to free resources.

Registration

Prior to using any location API calls the application should set the authentication credentials. This is accomplished by calling WPS_set_key() or WPS_set_auth().

API modes

The API works in 2 major modes: network centric and tiling.

Network-centric mode

In the network-centric model the API issues calls to a remote server to determine a location. This is the default mode.

Tiling mode

In the tiling mode the SDK downloads, from the server, a small portion of the database so the device can automonously determine its location, without further need to contact the server.

This mode is generally recommended mode when fast location tracking is required or when network is not constantly available.

The tiling mode is activated by calling WPS_set_tiling().

Geofencing

The API supports geofencing that allows the application to be notifed when the user enters, or leaves, a defined zone.

This feature is activated by calling the WPS_geofence_set() API. Once defined the application runs WPS_periodic_location() to monitor the device’s location. When WPS_periodic_location() determines the device is moving inside a geofence – ie. a first location is determined to be outside, followed by a location determined to be inside the geofence – it triggers a WPS_GEOFENCE_ENTER callback. Similarly when WPS_periodic_location() determines the device is moving outside a geofence – ie. a first location is determined to be inside, followed by a location determined to be outside the geofence – it triggers a WPS_GEOGENCE_LEAVE callback.

When an application no longer desires to monitor a geofence it can call WPS_geofence_cancel() or WPS_geofence_cancel_all().

Note: geofences can be added or removed while WPS_periodic_location() is running from the WPS_periodic_location() callback. The WPS_periodic_location() callback itself will still be invoked whether the location calculated corresponds to any defined geofence.

Offline location

The API supports offline location that allows the application to determine the location of the device even offline and outside of tile coverage by collecting a token that can be replayed when the device is once again online. Offline tokens are only valid for 90 days after they are generated. Attempting to redeem a token more than 90 days old will result in an error.

API reference

Check the full API reference for more information on APIs that are exposed by the SDK.

Reference application

A reference test application named wpsapitest is provided with the SDK package on Windows and Linux platforms. You can run it out of the box on your system to test location determination capabilities of the SDK.

Start the app without arguments to see all options that are supported.

Note: make sure to run wpsapitest as root on Linux.

Note: the command line version of wpsapitest is not supported on macOS due to limitations introduced in macOS Catalina (10.15). A simplified UI version of the app is provided for macOS users in a separate disk image file: wpsapitest-5.x.x-darwin-universal.dmg.

One shot call

When executed with a single API key argument, the app will determine a location once:

./wpsapitest -k <MY_KEY>

Example output:

42.352017, -71.047445   +/-9m   2+0+0  62ms
91 Farnsworth St
Boston, MA 02210

Periodic location

Execute the following command to run periodic location updates with 1 second period indefinitely (Ctrl+C to interrupt), with tiling enabled:

./wpsapitest -k <MY_KEY> -p 1 -t <tile_dir>

Using existing tiles in offline mode:

./wpsapitest -k <MY_KEY> -p 1 -t <tile_dir> -o

Note that the tile_dir must pre-exist in the file system for tiling to work. Examples below will use /tmp/tiles as a directory to store tiles.

Example output for the above commands:

tiling directory: /tmp/tiles
42.352091, -71.047431   +/-122m 2+0+0  66ms
    0.0km/h
42.352091, -71.047431   +/-122m 2+0+0  67ms
    0.0km/h
42.352091, -71.047431   +/-122m 2+0+0  67ms
    0.0km/h
42.352091, -71.047431   +/-122m 2+0+0  67ms
    0.0km/h

CSV output format

The app supports printing location data in the CSV format, which may be useful for post-processing the output (e.g. for plotting locations on a map).

In order to enable the CSV-fromatted output, use the -V or --output-csv switch:

./wpsapitest -k <MY_KEY> -p 1 -t /tmp/tiles -V

Output:

tiling directory: /tmp/tiles
1594766000,42.352091,-71.047431,122
1594766001,42.352091,-71.047431,122
1594766002,42.352091,-71.047431,122
1594766003,42.352091,-71.047431,122
1594766004,42.352091,-71.047431,122
1594766005,42.352091,-71.047431,122
1594766006,42.352091,-71.047431,122
1594766007,42.352091,-71.047431,122

Note that unformatted status messages like tiling directory: /tmp/tiles are printed to stderr, so you can collect location-only data by redirecting stdout to a file:

./wpsapitest -k <MY_KEY> -p 1 -t /tmp/tiles -V > locations.csv

Offline location

Periodically generate and store tokens in offline mode, for 10 seconds:

./wpsapitest -k <MY_KEY> -K q1w2e3r4 -O token_dir -p 1 -i 10 -o

Output:

offline mode enabled
*** failure (6)!
saved offline token: /tmp/offline/1594750740.tok
*** failure (6)!
saved offline token: /tmp/offline/1594750742.tok
*** failure (6)!
saved offline token: /tmp/offline/1594750743.tok
*** failure (6)!
saved offline token: /tmp/offline/1594750745.tok
*** failure (6)!
saved offline token: /tmp/offline/1594750746.tok
*** failure (6)!
saved offline token: /tmp/offline/1594750747.tok
*** failure (6)!
saved offline token: /tmp/offline/1594750748.tok

Redeem previously stored tokens from a directory and resolve locations retroactively against the server:

./wpsapitest -k <MY_KEY> -K q1w2e3r4 -O token_dir

Output:

found 7 offline tokens in directory: /tmp/offline
42.352017, -71.047445   +/-9m   2+0+0  37082ms
42.352017, -71.047445   +/-9m   2+0+0  35079ms
42.352017, -71.047445   +/-9m   2+0+0  34082ms
42.352017, -71.047445   +/-9m   2+0+0  32081ms
42.352017, -71.047445   +/-9m   2+0+0  32081ms
42.352017, -71.047445   +/-9m   2+0+0  31082ms
42.352017, -71.047445   +/-9m   2+0+0  30082ms

Logging

To turn logging on, define an environment variable named WPS_LOG_CONFIGURATION that contains the path to the wpslog.properties file.

Here’s an example of a wpslog.properties file:

DEBUG,wpslog.txt

Note that the file should not contain a newline at the end.

You can also redirect logging to stdout or stderr:

DEBUG,stdout

The logging level can be one of the following:

Location settings

Starting from version 4.9.2 WPS API will respect the system-wide location permission setting (applies only to Windows 8+ and macOS 10.7 or later). If location services are disabled, WPS API will return WPS_ERROR_LOCATION_SETTING_DISABLED in WPS_location, WPS_periodic_location, WPS_certified_location and WPS_tune_location calls.

In addition, starting from version 5.0.0 WPS API may return WPS_ERROR_LOCATION_NOT_PERMITTED if the particular application is not permitted to determine Wi-Fi based location.

See more information on your platform below.

Windows

The system-wide location setting on Windows can be found in Control Panel - Location Settings. It is enabled by default.

If you receive WPS_ERROR_LOCATION_SETTING_DISABLED from WPS API in your application, that means the option Turn on the Windows Location platform or Allow apps to access your locatiaon is turned off by the user.

You might want to handle this by notifying the user that the location platform is currently disabled in the system and hence the application will not be able to determine location. You can also navigate the user to the Location Settings page directly so the user may re-enable the location setting back.

Below is a sample code snippet:

if (MessageBox(NULL,
               L"Location is disabled in system. Do you want to open Control Panel to enable it?",
               L"My Application",
               MB_YESNO | MB_ICONQUESTION) == IDYES)
{
    ShellExecute(NULL, NULL, L"control", L"-name Microsoft.LocationSettings", NULL, SW_SHOW);
}

You can check here on more ways to pop up Control Panel items programmatically.

Note: Windows 8 or higher may show a prompt to enable location services the very first time when location is requested via Location API (check the Dialogues for enabling location section here). WPS API will never cause the system to show any kind of prompts.

macOS

macOS stores location settings under System Preferences - Security & Privacy - Privacy - Location Services. In addition to the global setting (Enable Location Services) it also lists applications permitted to determine location.

On macOS versions prior to 10.15 (Catalina) WPS API will not require the application to be listed and will grant permission whenever just the global setting is enabled.

For information on the latest macOS version, see the Catalina section below.

If you receive WPS_ERROR_LOCATION_SETTING_DISABLED from WPS API, that means that the global setting is disabled by the user. You might want to handle this by notifying the user that the location services are currently disabled in the system and hence the application will not be able to determine location. You can also navigate the user to the location settings page directly so the user may re-enable the location services back.

Below is a sample Apple script:

tell application "System Preferences"
    set securityPane to pane id "com.apple.preference.security"
    tell securityPane to reveal anchor "Privacy_LocationServices"
    activate
end tell

You can save it to a file (e.g. locationsettings.scpt) and run:

osascript locationsettings.scpt

If you want to implement it in Objective C or Swift, refer to the Scripting Bridge documentation.

Location authorization in macOS Catalina

Due to changes introduced in macOS Catalina, WPS API will now require that the application has obtained an authorization to determine a high precision location, such as a location based on Wi-Fi access points. If the authorization hasn’t been granted, WPS API will return WPS_ERROR_LOCATION_NOT_PERMITTED.

The application can rely on the SDK to obtain permission automatically when needed. This will result in the SDK showing a prompt to the user when location is being determined for the first time.

For production level apps it is recommended that the app handles location authorization on its own. This allows to provide the best user experience by integrating the location permission pop-up into the app’s UI flow. Before displaying the pop-up, the app could provide explanation on why the permission is needed.

The code to request a location permission from the user would look like this:

CLLocationManager* locationManager = [[CLLocationManager alloc] init];
locationManager.delegate = delegate;
[locationManager requestAlwaysAuthorization];

Note that the calling thread must have a runloop running for the permission request to work properly.

Refer to Apple’s documentation for more information.

Command line apps in macOS Catalina

For commmand line apps in macOS Catalina or later extra steps are required to obtain the authorization to determine a Wi-Fi based location from WPS API:

Please see the quick start project as an example of a command line application utilizing the SDK to determine Wi-Fi based location on macOS 10.15+.

Hardened Runtime

If your application is using Hardened Runtime, make sure to enable access to Location in Xcode settings:

The following key will be added in your .entitlements file:

    <key>com.apple.security.personal-information.location</key>
    <true/>

App Sandbox

If you application is using the App Sandboxing feature, enable the following options in Xcode settings:

The following keys will be added in your .entitlements file:

    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
    <key>com.apple.security.personal-information.location</key>
    <true/>

Changelog

5.7

Private release - a follow-up to 5.5:

5.6

Private release with native Wi-Fi/Cell/GNSS support for Qualcomm MDM9607 platform.

5.5

Private release to support offline hybrid positioning based on Wi-Fi/Cell on a custom Linux platform.

5.4.7

5.4.6

5.4.4

5.4.2

5.4.0

5.3.0

5.2

Private release to support extended offline positioning capabilities.

5.1.1

5.1.0

5.0.0-rc1

4.9.9

4.9.8

4.9.7

4.9.6

4.9.5

4.9.4

4.9.3

4.9.2

4.9.1

4.9

4.8

4.7.6

4.7.5

4.7

4.6

4.5

Version 4.5 was never released publicly.

4.4

4.3

4.2

4.1

4.0

3.4

3.3

3.2

3.1

3.0

2.7

2.6.1

2.6

2.5

Official release.

2.4

2.3.1

2.3

License

License

Copyright (c) 2023 Qualcomm Innovation Center, Inc. All Rights Reserved.

This work is licensed under the CC BY-ND 4.0 License. See LICENSE for more details.

This site is open source. Improve this page.