WifiRttScanX

WifiRttScanX can be used to measure the distance between a phone (UE) and a Wi-Fi access point (AP).
It uses the IEEE 8021.11-2016 (a.k.a. IEEE 802.11mc) Wi-Fi “Fine Time Measurement” (FTM) “Round Trip Time” (RTT) protocol —
and is ready for the more recent IEEE 802.11-2022 (a.k.a. IEEE 802.11az) “Next Generation Positioning” (NGP) protocol (awaiting support from access points and phones).

WifiRttScanX is useful for surveying a location to discover the properties of Wi-Fi access points — particularly the extent to which they support range measurements.

WifiRttScanX can be used to estimate the offset in range measurements — knowledge of which can make indoor localization more accurate (when, for example, using FTMRTT ).

Provenance

WifiRttScanX is an Android app for ranging to Wi-Fi access points (APs) — based on:

the original open source WifiRttScan project code available on GitHub; and
earlier versions of the indoor localization app FTMRTT.

(For a different app based on the WifiRttScan open source code, see WifiRttScan also available on Google Play.)

WifiRttScanX also allows:

ranging to APs that do support FTM RTT, but do not advertise this in the beacon frame.
ranging to APs that do not support “two-sided FTM RTT” — using “one-sided RTT” instead (since Android 12);
for convenient estimation of the unknown offset in FTM RTT results (see FTM RTT Offset Calibration);
production of range logging files in places accessible on an unrooted phone;
production of Wi-Fi scan result files.

Main Activity Screen

On the Main Activity screen click “Scan Wi-Fi” to obtain a listing of APs.
This may take 3 to 5 seconds — more or less — depending on how many radio modems the phone has (and longer on phones that also support the 6 GHz band)
(see note below on possible “throttling of Wi-Fi scans”).
The final update of the screen can take a bit longer if there are many APs nearby, since WifiRttScanX also tries ranging to all of them.

Listed are SSID, BSSID (Mac address), signal strength (in dBm), frequency (in MHz) (*), Wi-Fi standard (11n, 11ac, 11ax, or 11be), and a FTM RTT indicator.

The FTM RTT indicator is a character indicating the level of support for range measurements:

@ for APs that responded and advertised their ability to do so in the beacon frame —
such as the original Google Wi-Fi, Nest Wi-Fi, Nest Wi-Fi Pro, Compulab WILD, Aruba 500 series, Aruba 600 series, Aruba 700 series, etc.;

a for APs that advertised their ability to respond to FTM RTT requests, but then did not actually respond
(possibly because of low signal strength);

* for APs that did respond to FTM RTT requests but do not advertise this capability —
such as Linksys Velop, Netgear Orbi, ASUS RT-ACRH13, Eero Pro, Eero Max 7, etc.
(shown only if “Two-sided” is checked in the “More menu”) (†);

# for APs that respond to “one-sided” FTM RTT requests
(shown only if “Two-sided” is not checked);

blank for APs that did not respond to FTM RTT requests — most likely because they do not support the protocol —
but could also be because of low signal strength.

c A second letter is used to indicate support for 802.11az.

There can be more BSSIDs than fit on one screen, in which case, drag the view up to see the rest.

The results of individual Wi-Fi scans are recorded in files with names starting with wifi-scan- (provided “Record Wi-Fi scans” is checked in the menu);

Entries in the 2.4 GHz band are listed first, followed by those in the 5 GHz band, finally those in the 6 GHz band. Within each group entries may be sorted by RSSI.
The sorting order can be changed from the “More Menu” (⋮).

(*) Note: the frequency shown is the primary 20 MHz wide channel over which the client is communicating with the AP —
not the center frequency of the channel used for FTM RTT, which may be 80 MHz or wider (see details in article on WLAN channels).

(†) For more details about AP support for FTM RTT, see Which Wi-Fi APs support FTM RTT (IEEE 802.11mc)?

Ranging Activity Screen

Selecting one of the APs on the Main Activity Screen takes you to the Ranging Activity screen
(From there, you can use the left arrow to return to the Main Activity screen).
Ranging is carried out with respect to the selected AP.

Two parameters control this ranging process:

“Ranging delay” is the pause between ranging attempts - in msec;
“Stats window size” is the size of the sliding window over which averages are calculated.

These parameters can be changed by clicking on the corresponding values
(New values of the parameter will be saved and restored when the app is opened again).

The “Range-mean”, “RangeSD-mean”, “RSSI-mean”, “Time-mean” are block averages of the raw data.
Click “Reset Ranging” to clear out the history and restart the averaging process.

Suggestion: To obtain the best result, you may want to move the phone around a bit (by a few centimeters) in order to try and "average out" the position dependent error.

Location: The AP latitude, longitude and altitude fields will be populated if the AP provides this information (in the LCI field of the FTM RTT response):

Compulab Wi-Fi Indoor Location Device (WILD) can do this using -lci=... and -civic=... lines in the hostapd.conf file.
On Aruba access points running ArubaInstant. the AP latitude, longitude and altitude fields can be set up from the command line interface (CLI) (using
lci-location <latitude> <longitude> <altitude> <uncertainty-radius> <altitude-uncertainty> <number-of-floors> ).
On Aruba access points running ArubaOS, the Open Locate initiative can make location information available (Aruba 500 or later).
See Self-locating Wireless Access Points.

Logging Activity Screen

Click on “Logging” to go to the Logging Activity screen. (From there, you can use the left arrow to return to the Ranging Activity screen).
The idea here is to take a number of measurements at each of a set of regularly spaced distances from the AP in order to get a good estimate of the offset.

“New Session” opens a file — in comma-separated-value (CSV) format — for output, and resets the “True Range” to its starting value.
The name of the file contains the date and time when it was opened, and is shown below the text line containing “Log file is saved locally”;
“Start” begins the ranging and logging process. It will run until either “Stop” is pressed — or the timer runs out (and the buzzer goes off);
“Stop” stops ranging;

The value of “True Range” is advanced whenever the ranging and logging process is stopped.

At each stage, one of the three buttons is highlighted (in blue) to suggest what might be the best next action (although other buttons are not disabled).

The “Overall Offset” field shows the difference between the average estimated range and the average true range.
This is an estimate of the offset or bias of ranging measurements made by this combination of cell phone and AP.
It can be used later to correct FTM RTT measurements

(NOTE: FTMRTT requires an offset that is to be subtracted from the measured distance which is what WifiRttScanX produces).

WifiRttScanX also shows the offset and slope of a straight line fit. The expected value of the slope is, of course, one.

WifiRttSxanX discards a small fraction of the highest and the lowest ranging results in order to suppress the effect of inevitable outliers.

The resulting log file can be shared, after closing the file, by using the “Share Log File” button. For additional details see measuring the offset.

Settings Activity Screen

Click on the yellow star icon in the action bar to go to the Settings Activity screen. This provides control of some of the parameters.
(The parameter values are saved and will be restored when the app is used again.)

Here you can select the starting value (default 0.5 m) and increment (default 0.5 m) for the true range, the RTT burst size, the time before ranging for a particular distance will be stopped (“Timer interval”), and the file name prefix for the log files.

“RTT Burst Size” provides for adjusting the number of attempts at ranging per burst (typically between 2 and 31)
(This feature requires Android 12 — for earlier versions the default value of 8 is used).

FTM RTT Offset Calibration

Distances measured using FTM RTT are linearly related to the true distance, with slope one, but may be offset a bit
(particularly if the AP has not yet been certified for location capabilities by the Wi-Fi Alliance).

The offset depends somewhat on the properties of the radios at the ends of the Wi-Fi links, that is, the ones in the UE (phone) and the AP (access point).
Knowing the offset can improve the accuracy of indoor localization performed by the FTMRTT app.

The accuracy of distance estimates can be improved if the offset is measured and subtracted from the value returned by RTT.
In some favorable cases the offset is smaller than a meter, and can be ignored (e.g. Google Pixel 5 phone with respect to the original Google Wi-Fi AP).
However, for some combinations of phones and APs it may be 5 meter or more (positive or negative), in which case it is important to remove it.

Significantly, averaging many measurements taken in a fixed position is not very helpful because of the position dependent error.

What does work well is to make measurements at several different, but known distances, and average the offsets —
(or, equivalently, take the difference between the overall average of the estimated ranges and the overall average of the true ranges).

The following is a sequence of steps for offset calibration using WifiRttScanX:

Open WifiRttScanX and click “Scan Wi-Fi";
Select the AP of interest — based on its SSID and BSSID (Mac address);
In the resulting “Ranging Activity” screen, click “Logging”;
Click “New Session"
Move the phone to the indicated true distance from the AP and click “Start"
Wait for the selection highlight to return from the “Stop” button to the “Start” button
go back to (e)

After a dozen or two true distance positions (or when you run out of patience), stop and make a note of the “Overall Offset” value.

Close the file and share it, if desired, by clicking “Share Log File”. Use the back arrow to return to the Ranging Activity.

As mentioned above, WifiRttSxanX discards a small fraction of the highest and the lowest ranging results in order to suppress the effect of inevitable outliers (and it takes this into account when estimating the RMS error).

Some sample offsets for two-sided RTT for various APs may be found in FTM_RTT_two_sided_offsets.txt
(Note: these are somewhat outdated results, since firmware updates have been improving FTM RTT accuracy in APs).
Some sample offsets for one-sided RTT for various APs may be found in FTM_RTT_one_sided_offsets.txt

Where Are The Log Files?

First, you can always “Share” the most recent ranging log file by clicking “Share Log File”;
The files can be found on the device if this opportunity was missed:
The log files in CSV format appear in (depending on the Android version and access method):
    /Android/data/com.welwitschia.wifirttscanX/files/logfiles
    /sdcard/Android/data/com.welwitschia.wifirttscanX/files/logfiles
    /storage/emulated/0/Android/data/com.welwitschia.wifirttscanX/files/logfiles
Log file names start with a file name prefix (the starting default prefix is rtt-log-).
What is in the CSV log files? The first line of each file is a comma-separated list of the names (keys) of the entries (values).
Each data line lists:
date, time, true range, estimated range, st dev of estimate, number of successful measurements,
number of attempted measurements, signal strength (dBm), frequency (MHz), bandwidth (MHz), BSSID and SSID.
How can one access the log files?
1. The most recent log file can be shared (e.g. via email or Google Drive) by selecting “Share Log File”;
2. Another convenient way is to hook up your laptop to the phone via USB and connect to the file system on it.
  
  For this to work, certain permissions and default settings may be needed:
  On the phone, in “Settings > System > Advanced” select “Developer Options”.
  Then, under “Debugging", enable “USB debugging”.
  Further, under “Networking", click “Default USB configuration” and select “File transfer / Android Auto"
  (Exact details depend on which version of Android is installed on the phone);
3. Finally, one can instead use the Android Debug Bridge (ADB) to “pull” the files from the phone.
  (As mentioned above, the log files are in /storage/emulated/0/Android/data/com.welwitschia.wifirttscanX/files/logfiles)
In addition, Wi-Fi scans can produce files with prefix wifi-scan- in the scans subdirectory

The More Menu (⋮)

Additional control of the operation of WifiRttScanX is available from the "More Menu" (⋮):

Two-sided RTT: if checked, use IEEE 802.11mc FTM RTT (otherwise use “one-sided” RTT);
When IEEE 802.11az is supported, a second menu item will appear;
Survey Mode: repeat the “Scan Wi-Fi” process once started;
Ignore 2.4 GHz: do not use BSSIDs in the 2.4 GHz band;
Ignore 5 GHz: do not use BSSIDs in the 5 GHz band;
Ignore DFS: do not use BSSIDs in the DFS part of the 5 GHz band;
Ignore 6 GHz: do not use BSSIDs in the 6 GHz band;
Sort results on BSSID: sort results on Mac address;
Sort on band & RSSI: sort results on frequency band and signal strength;
Log RTT to file: record ranging results in file;
Record Wi-Fi scans: record Wi-Fi scans in files;
Debug log to file: record extra debugging information in log files;
Single AP ranging: range to one BSSID at a time rather than groups of up to 10 APs at a time (will slow things down a lot);

Note: There may be additional experimental menu items that limit the bandwidth or the preamble used in the RangingRequest.

Wi-Fi Scan Throttling:

Android 9 introduced a limitation on how often Wi-Fi scans can occur — no more than 4 scans in 2 minutes when in foreground mode.

Since Android 10 it has become easy to override this: just disable “Wi-Fi scan throttling” from the “Developer Options” menu
(assuming you have enabled Developer Options).

This way it is possible to scan about every 3 to 5 seconds on most phones (longer on phones supporting the 6 GHz band as well).

Key code events:

For research purposes, it can be useful to automate repeated measurements using some positioning equipment.
For this purpose some on-screen activities can be simulated using “key code events” which can be driven from a connected laptop.

On the Logging Activity Screen, the buttons can be activated using “key codes”.
These can, for example, be provided using the Android Debug Bridge (ADB):

adb shell input keyevent <keycode>

<keycode> is 37 ('I') for “New Session”
<keycode> is 47 ('S') for “Start”
<keycode> is 46 ('R') for “Stop”
<keycode> is 31 ('C') for “Close Log File”
<keycode> is 32 ('D') for “Delete All Log Files”
<keycode> is 33 ('E') for “Exit”

This can be useful for “remote control” of the process and integration of ranging with scripts controlling robotic motion equipment.

Installing WifiRttScanX

WifiTRttScanX is available from the Google Play Store.

When you first open the installed app you will get a Permission Activity Screen since Wi-Fi RTT Ranging requires “Fine Location” permission.

You may also need to turn on “Location” in “Settings”.

If you already have one version of the app installed, then it may happen that a new version cannot be installed on top of it
(perhaps because of a change in name or file “signature”). In that case, simply uninstall the old version first.

Alternatively: “Side Loading”

You can also get the latest beta version APK file WifiRttScanX.apk from a browser on your phone. Open it.
You will most likely get a security alert and will be taken to Settings to “allow installation from this source” (i.e. from your browser).

Details: if you are downloading in some browser, like FireFox or Chrome, you have to give it permission to install. From
Settings > Apps > Special app access > Install unknown apps.
Then click on the browser you use, and, finally, slide the Allow from this source slider.

Alternatively, if you have AndroidStudio (or just its command-line tools) you can use the Android Debug Bridge (ADB) with your phone connected via USB cable:
adb install WifiRttScanX.apk
You may need to use the -t and -r command line flags:
adb install -t -r WifiRttScanX.apk
(or perhaps even adb install -r -t -d -g WifiRttScanX.apk).

@	for APs that responded and advertised their ability to do so in the beacon frame — such as the original Google Wi-Fi, Nest Wi-Fi, Nest Wi-Fi Pro, Compulab WILD, Aruba 500 series, Aruba 600 series, Aruba 700 series, etc.;


a	for APs that advertised their ability to respond to FTM RTT requests, but then did not actually respond (possibly because of low signal strength);


*	for APs that did respond to FTM RTT requests but do not advertise this capability — such as Linksys Velop, Netgear Orbi, ASUS RT-ACRH13, Eero Pro, Eero Max 7, etc. (shown only if “Two-sided” is checked in the “More menu”) (†);


#	for APs that respond to “one-sided” FTM RTT requests (shown only if “Two-sided” is not checked);


blank	for APs that did not respond to FTM RTT requests — most likely because they do not support the protocol — but could also be because of low signal strength.


c	A second letter is used to indicate support for 802.11az.