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.ka. IEEE 802.11mc) Wi-Fi “Fine Time Measurement” (FTM) “Round Trip Time” (RTT) protocol.

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

WifiRttScanX can be used to measure the offset in range measurements — knowledge of which makes indoor localization more accurate (e.g. when using the FTMRTT app).

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 different app based originally on the WifiRttScan open source code, see WifiRttScan app available on Google Play.)

WifiRttScanX allows:

ranging to APs that support FTM RTT, but do not advertise this in the beacon frame;
ranging to APs that do not support “two-sided FTM RTT” at all — 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 takes about 3.5 seconds — more or less — depending on how many radio modems the phone has, and how many channels it scans (see note below on possible “throttling of Wi-Fi scans”). The final update of the screen can take longer if there are many APs nearby.

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

The FTM RTT (mc) indicator is a single character that indicates the APs support for range measurements:

@ for APs that advertise their ability to respond to FTM RTT requests in the beacon frame —
such as Googe Wi-Fi, Nest Wi-Fi, Compulab WILD, Aruba 5xx, etc.;

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

* for APs that respond to FTM RTT requests but do not advertise this —
such as Linksys Velop, Eero Pro, Netgear Orbi, ASUS RT-ACRH13, Starlink Wi-Fi router etc.
(shown only if “Two-sided” in “Settings” is checked) (†);

# for APs that respond to “one-sided” FTM RTT requests
(shown only if “Two-sided” in “Settings" 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 be because of low signal strength).

There can be more APs 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-;

Long pressing “Scan Wi-Fi” toggles “Survey Mode” in which Wi-Fi scans are run repeatedly.

Entries in the 2.4 GHz band are listed first, with those in the 5 GHz band next. 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 wide (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 period” 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” and “RSSI-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 possible measurement, you may want to move the phone around a bit (by a few centimeters) because of the position dependent error.

Location: The AP latitude, longitude and altitude fields will be populated when APs provide this information.
Presently, Compulab Wi-Fi Indoor Location Device (WILD) can do this using -lci=... and -civic=... lines in the hostapd.conf file.

Recently, Aruba's Open Locate initiative has made location information available in their latest APs (Aruba 5xx and higher). 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.

“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;
“Stop” stops ranging;

The “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.

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

Settings Activity Screen

Click on the yellow star icon in the task 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 pause between ranging attempts (“Ranging period”), the time before ranging for a particular distance will be stopped (“Timer interval”), and the file name prefix for the log files.

“Two-sided RTT”, if selected (default), will try to force 802.11mc FTM RTT ranging even for APs that do not advertise this capability.
(A number of APs respond to FTM RTT request, but do not advertise this). Unchecking this switches to the new one-sided RTT (requires Android 12 or later):

Some new features in Android 12 and later:

If “Two-sided RTT” is not selected, the app will try to use “one-sided” RTT (where the turn-around time in the AP — typically about 16 to 18 μsec — is not subtracted out). This can be used even for APs that do support FTM RTT (just with somewhat lower accuracy and a much larger offset — around 2400 to 2700 m).
“RTT Burst Size” allows one to adjust the number of attempts at ranging per burst (between 2 and 31)
(This feature requires Android 12 — for earlier versions the default value of 8 is used).

FTM RTT Offset Calibration

Distances estimated using FTM RTT are linearly related to the true distance, with slope one, but are typically offset a bit.
The offset depends on the properties of the radios at the ends of the Wi-Fi links, that is, 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 one of the original Google Wi-Fi AP).
However, for some combinations of phones and APs it may be as much as 6 or 8 meter (positive or negative), in which case it is important to remove it.

Significantly, averaging many measurements taken in a fixed position is not 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 range and the overall average of the true range).

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 space or 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.

Some sample offsets for two-sided RTT for various APs may be found in FTM_RTT_two_sided_offsets.txt
(Note: these may be somewhat dated results, since firmware updates have been improving FTM RTT accuracy in some 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 by clicking “Share Log File”;
The log files in CSV format appear in:
    /Android/data/com.welwitschia.wifirttscanX/files/log i.e.
    /sdcard/Android/data/com.welwitschia.wifirttscanX/files/log i.e.
    /storage/emulated/0/Android/data/com.welwitschia.wifirttscanX/files/log
Log file names start with a file name prefix, the default prefix is rtt-log-.
What is in the CSV log files? Each 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.
The first line of each file is a comma separated list of the names (keys) of these entries (values).
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 use the Android Debug Bridge (ADB) to “pull” the files from the phone.
  (The log files are in /sdcard/Android/data/com.welwitschia.wifirttscanx/files/log)
In recent versions of WifiRttScanX, the Wi-Fi scan itself produces 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: use IEEE 802.11mc FTM RTT if checked; otherwise use one-sided RTT;
Log RTT to file: record ranging results in file;
Record Wi-Fi scans: record Wi-Fi scans in files;
Survey Mode: repeat “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;
Sort result on RSSI: sort results based on signal strength;
Sort on band & RSSI: sort results on frequency band and signal strength;
Rearrange results: put FTM RTT responders first, one-sided responders second, …
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 (debugging - will slow the process down);

(Note: There may be additional experimental menu items).

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.5 seconds on most phones and every 2.5 seconds on some more recent ones.

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 even adb install -r -t -d -g WifiRttScanX.apk).

@	for APs that advertise their ability to respond to FTM RTT requests in the beacon frame — such as Googe Wi-Fi, Nest Wi-Fi, Compulab WILD, Aruba 5xx, etc.;


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


*	for APs that respond to FTM RTT requests but do not advertise this — such as Linksys Velop, Eero Pro, Netgear Orbi, ASUS RT-ACRH13, Starlink Wi-Fi router etc. (shown only if “Two-sided” in “Settings” is checked) (†);


#	for APs that respond to “one-sided” FTM RTT requests (shown only if “Two-sided” in “Settings" 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 be because of low signal strength).