WifiRttScanX


WifiRttScanX is an Android app for ranging to Wi-Fi access points (APs) modeled on:
  1. the original open source WifiRttScan project available on GitHub; and
  2. the more elaborate WifiRttScan app available on Google Play.
WifiRttScanX differs from these in that it:
  1. allows ranging to APs that support FTM RTT (802.11mc), but do not advertise this support;
  2. writes logging files in a place accessible on an unrooted phone;
  3. allows for “one-sided” RTT ranging in Android 12, even to APs that do not support FTM RTT (802.11mc);
  4. provides for estimation of offset / bias in FTM RTT results (see FTM RTT OffSet Calibration)


Main Activity Screen

On the Main Activity screen click “Scan Wi-Fi” to obtain a listing of APs. This takes a few seconds — longer if there are many APs nearby.

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

The FTM RTT indicator is a single character:

There can be more APs than fit on one screen, in which case, drag the view 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 sorted by RSSI (Note: sorting order depends on menu settings).

(*) 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).


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:

  1. “Ranging period” is the pause between ranging attempts - in msec;
  2. “Stats window size” is the size of the block over which averages are calculated.
These parameters can be changed by clicking on the corresponding values
(New parameter values are saved and will be restored when the app is opened again).

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


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.
  1. “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 data and time when it was opened, and is shown below the text line containing “Log file is saved locally”;

  2. “Start” begins the ranging and logging process. It will run until either “Stop” is pressed — or the timer runs out;

  3. “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 / bias 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):

Some experimental features for Android 12:


Log Files

  1. Where are the log files? The log files in CSV format appear in:
        /Android/data/com.example.wifirttscanX/files/log i.e.
        /sdcard/Android/data/com.example.wifirttscanx/files/log i.e.
        /storage/emulated/0/Android/data/com.example.wifirttscanx/files/log
    The log file names start with a file name prefix, the default prefix is rtt-log-.
    (Records of the results of Wi-Fi scans have file names starting with wifi-scan-).

  2. What is in the 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 the file is a comma separated list of the names of these entries.

  3. 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.example.wifirttscanx/files/log)

  4. In recent versions of WifiRttScanX, the Wi-Fi scan itself produces files with prefix wifi-scan- in the scans subdirectory

Key code events:

On the Logging Acitivity 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>

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

FTM RTT Offset Calibration

Distances estimated using FTM RTT are linearly related to the true distance, 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).

The accuracy of distance estimates can be improved if the offset is measured and subtracted from the estimate.
In some favorable cases the offset may be smaller than a meter, and can perhaps be ignored (e.g. Google Pixel 5 phone and 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.

Importantly, averaging many measurements taken in a fixed position is not particularly 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:

  1. Open WifiRttScanX and click “Scan Wi-Fi";
  2. Select the AP of interest — based on its SSID and Mac address (BSSID);
  3. In the resulting Ranging Activity screen, click “Logging”;
  4. Click “New Session"
  5. Move the phone to the indicated true distance from the AP and click “Start"
  6. Wait for the highlight to return from the “Stop” button to the “Start” button
  7. 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, as described above. Use the back arrow to return to the Ranging Activity.

Some sample results may be found in FTM_RTT_AP_ratings.txt


Installing WifiRttScanX (“Side Loading”)

Download the APK file
WifiRttScanX.apk from a browser on your phone. Then 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).

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

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.