Operating systems:
nl80211
and root accessHardware:
Contact support.tps@qti.qualcomm.com to request access to the SDK, obtain the API key or get additional information.
Import the header file in your code:
#include <wpsapi.h>
Link your executable against the wpsapi
library:
wpsapi.lib
and make sure wpsapi.dll
is accessible to the executablelibwpsapi.dylib
libwpsapi.so
The WPS API can be summarized to the following calls:
WPS_load()
WPS_set_key()
or WPS_set_auth()
WPS_location()
or WPS_periodic_location()
WPS_unload()
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.
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()
.
The API works in 2 major modes: network centric and tiling.
In the network-centric model the API issues calls to a remote server to determine a location. This is the default 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()
.
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.
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.
Check the full API reference for more information on APIs that are exposed by the SDK.
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
.
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
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
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
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
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:
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.
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 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.
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.
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:
CLLocationManager
, those must be made after calling WPS_load()
Info.plist
file must be be placed in the same directory where the executable is located, with the CFBundleIdentifier
and CFBundleExecutable
fields populated.app
, e.g. YourAppName.app
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+.
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/>
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/>
Private release - a follow-up to 5.5:
Private release with native Wi-Fi/Cell/GNSS support for Qualcomm MDM9607 platform.
Private release to support offline hybrid positioning based on Wi-Fi/Cell on a custom Linux platform.
wpsapitest
WPS_set_auth
WPS_register_user
and WPS_set_registration_user
Private release to support extended offline positioning capabilities.
wpsapitest
wpsapitest
WPS_set_auth_token()
WPS_set_tunable()
WPS_load()
and WPS_unload()
callsWPS_ip_location()
.Version 4.5 was never released publicly.
WPS_tiling()
with WPS_set_tiling()
WPS_set_*
calls can now be made while WPS_periodic_location()
or WPS_location()
is in progressncell
and nsat
to WPS_Location
altitude
to WPS_Location
WPS_version()
WPS_tune_location()
WPS_ERROR_TIMEOUT
WPS_set_user_agent()
int
to WPS_Continuation
for WPS_LocationCallback
WPS_tiling()
WPS_set_tier2_area()
Official release.
WPS_periodic_location()
WPS_set_local_files_path()
WPS_set_proxy()
and WPS_set_server_url()
to voidspeed
, bearing
and nap
to WPS_Location
hpe
from WPS_IPLocation
WPS_register_user()
WPSScanner.dll
is no longer neededCopyright (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.