Localization using FTMRTT

FTMRTT is an Android app (available from Google Play Store) for localization using a mobile phone and Wi-Fi access points.

You provide the positions of three or more Wi-Fi access points (APs) and it will dynamically indicate — by way of a red blob on a floorplan — where it thinks you are.

Note that only the locations of the Wi-Fi APs are needed (no “learning”, “training” or “fingerprinting”).

                 

Above screenshots: (a) Small house (8 m x 12 m); (b) Large house (3 APs); (c) Big box store (82 m x 108 m) (20 APs); (d) Large condo complex (illustrating outdoor use).

The FTMRTT app can be used whether the Wi-Fi APs advertize support for the FTM RTT protocol in their Wi-Fi beacon frames or not. Further, the FTMRTT app can be used even with uncooperative APs (those not supporting the protocol) using one-sided RTT measurements (although with somewhat reduced accuracy).

For more details about the IEEE 802.11-2016 (a.k.a. IEEE 802.11mc or FTM RTT or WiFi RTT) Wi-Fi protocol for “Fine Time Measurement” (FTM) “Round Trip Time” (RTT) see “Indoor positioning using time of flight with respect to WiFi access points". Check out sample videos of FTMRTT in action and read papers reporting on research done with FTMRTT.

Many Wi-Fi access points and phones provide support for FTM RTT range finding — e.g. Google Wi-Fi APs and Google Pixel phones. See AP FTM RTT support for a list of APs that support two-sided FTM-RTT. See phone FTM RTT support for a list of phones, as well as retail, warehousing and distribution center devices that support two-sided FTM-RTT.

Recently "enterprise level" access points have started to support FTM RTT as well (when enabled in the system). See e.g. HPE / Aruba "Self-Locating Wireless Access Points" and CISCO / Meraki "Set Up Access Point Auto Location".

Setting up FTMRTT - inputs

FTMRTT reads three files (two of which are optional):

  1. Responders (required — default "responders.json"): Locations of the Wi-Fi access points (APs). This file uses a simple JSON format (example below). The APs are identified by their “basic service set identifier” — BSSID (BSSIDs of APs can be determined using “Settings > Network & Internet” or some apps, such as WifiRttScan or WiFiRttScanX, see below). The coordinates can be provided in any convenient Cartesian coordinate system (in meters) (Optionally, geographical coordinates can be used.) If needed, the responders file can be used to provide additional information about access points.

    Sample responders.json file:

       { "APS" : [
       { "BSSID" : "a8:bd:27:28:5d:d0",  "cartesian" : [11.2, 3.6, 2.5] },
       { "BSSID" : "a8:bd:27:29:c9:10",  "cartesian" : [16.1, 14.1, 2.5] },
       { "BSSID" : "20:a6:cd:23:2d:50",  "cartesian" : [5.5, 2.7, 2.5] }
      ]
   }
    An elaborate example (for many more APs) may be found at responders.json .
    (Note: The sample file makes use of some convenient extensions, such as C-style comments, supported by the Android JSON parser).

    By the way, it is possible for APs to provide location information themselves, but few do so. 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. See Self-locating Wireless Access Points. So, at some point, it won't be necessary to provide this information in the responders file.

  2. Bounding box (optional — default "boundingbox.json"): Bounding box of a rectangular area of interest (in meters) to be shown on screen. This file uses a simple JSON format (example below). For convenience, the rectangle may be aligned with the sides of a building. If there is no bounding box file, a bounding box will be created using the coordinates of the APs. If needed, the bounding box file can also be used to specify other parameters.

    Sample boundingbox.json file:

    { "bbox" : [-4.7, -2.7, 18.6, 15.1 ],
  "floorheight" : [ 0, 2.6 ]
 }
    A more detailed example may be found at boundingbox.json .
    (By the way, the lower left corner of the bounding box need not be at [ 0, 0 ] and coordinates need not be positive).

  3. Floorplans (optional — default "floorplans.png"): Floorplan in image format. This should be a bitmap image (PNG recommended) used as a background by the app. It's lower left and upper right corners should correspond to the lower left and upper right limits specified in the bounding box. If there is no floorplan image file, a white background will be shown.

Output (on screen)

The on-screen output shows a red “heat map” of the probabilities of the user being in various positions (see samples above). The reddest spot is the most likely position, while the centroid of the red blob is the expected value of the position. If a floorplan is provided, this will be shown as background. The locations of the access points are shown as well — color coded: an AP providing ranging information is green, an AP being interrogated but currently not providing ranging information is magenta. Optionally some additional information (RTT distance, st dev, signal level, last few digits of the BSSID) can be shown next to the graphic indicating an AP (see first two sample screenshots above).

Optionally, for each AP, the annulus of currently most likely positions for the user equipment (UE) can be overlaid (see menu features below):

File locations (input)

The files can be specified interactively using a “file picker”. Alternatively, the input file(s) can reside in a fixed location, and be read automatically when starting. The “File Picker” check box in the “more menu” (⋮) controls whether the file picker is used or not. (

Files (output)

The FTMRTT app folder on the phone may have subfolders. One subfolder, called “log”, contains log files (plain text format) that optionally can be written by the app continuously recording its state (basically a record of what is normally sent to “logcat”). Log file recording can be toggled on and off using the blue double up arrow in the action bar.

Another subfolder called “crash” is where, should the app crash, a dump is written in plain text format. Both “log” and “crash” files can be useful for tracking down bugs. These files can be accesses via USB link, as above, or via ADB. For example:
    adb pull /sdcard/Android/data/com.welwitschia.ftmrtt/files/log

Trouble Shooting

Sadly, it is easy to produce a JSON file that can not be understood by the built-in parser (e.g. an extra comma and the end of a JSON array). FTMRTT catches and fixes a few of the more obvious problems automatically. Some other errors result in on-screen messages (“toasts”). More subtle problems, that may or may not affect the overall operation, are noted in the “log” files described above.

Prior Information

The Bayesian grid update method can exploit some prior information provided about the area of interest. The floor plan may show walls (which are considered impenetrable by the Bayesian update rule). Walls should be black (or an optional color specified in the bounding box file).

One-sided RTT

The best results are obtained when the access points and the phone support the IEEE 802.11-2016 protocol (i.e. two-sided FTM RTT). Google Wi-Fi APs and various Google Pixel phones do. See AP FTM RTT support for a list of APs that support two-sided FTM-RTT. See phone FTM RTT support for a list of phones, and retail, warehousing and distribution center devices that support two-sided FTM-RTT. By the way, quite a few APs support the protocol, but do not advertize this in their Wi-Fi beacon frames.

In addition it is possible to work with uncooperative APs in one-sided RTT mode. In this case the responder definition should include a "offset-one-sided" field which specifies the amount (always negative) to add to the returned one-sided RTT value. For example:
    "offset-one-sided" : -2573,
These offsets depend on the type of AP and can be determined using the WifiRttScanX app (see below).

Using WifiRttScanX

WifiRttScanX is an Android app that makes it easy to survey an area and determine BSSIDs, frequency, bandwidth, signal strength etc. It also provides a convenient way to “calibrate” a new type of AP, (i.e. determining its offset / bias). This is particularly useful for one-sided RTT.

Controlling FTMRTT

FTMRTT Action Bar

FTMRTT “More Menu” (⋮)

    

Note: Parts of the menu are still evolving so may look different from what is shown here.

Note: FTMRTT has uses other than indoor localization, so several of the menu settings will not be used here (and some combinations will not make sense).

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.)
This does not affect FTM RTT ranging, but FTMRTT needs to perform Wi-Fi scans to determine which APs are nearby — and what frequency and bandwidth they are operating on (at least initially).

Fortunatey, since Android 10, overriding this has become easy: just disable “Wi-Fi scan throttling” from the “Developer Options” menu
(assuming you have enabled Developer Options).

Questions? Check out the FAQ

Installing FTMRTT

FTMRTT is available on the Google app 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”):

The latest beta version of the APK is also available on this web site. Download the APK file FTMRTT.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 FTMRTT.apk
You may need to use the -t and -r command line flags:
    adb install -t -r FTMRTT.apk (or even adb install -r -t -d -g FTMRTT.apk).