ZEBRA MN-004074-04EN Rev A FTM Wi-Fi Location Integrator User Guide

Zebra FTM Wi-Fi Location

Integrator Guide

MN-004074-04EN Rev A

Copyright

2023/11/06

ZEBRA and the stylized Zebra head are trademarks of Zebra Technologies Corporation, registered in many jurisdictions worldwide. All other trademarks are the property of their respective owners. ©2023 Zebra Technologies Corporation and/or its affiliates. All rights reserved.

Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of those agreements.

For further information regarding legal and proprietary statements, please go to:

SOFTWARE: zebra.com/linkoslegal.
COPYRIGHTS: zebra.com/copyright.
PATENTS: ip.zebra.com.
WARRANTY: zebra.com/warranty.
END USER LICENSE AGREEMENT: zebra.com/eula.

Terms of Use

Proprietary Statement

This manual contains proprietary information of Zebra Technologies Corporation and its subsidiaries (“Zebra Technologies”). It is intended solely for the information and use of parties operating and maintaining the equipment described herein. Such proprietary information may not be used, reproduced, or disclosed to any other parties for any other purpose without the express, written permission of Zebra Technologies.

Product Improvements

Continuous improvement of products is a policy of Zebra Technologies. All specifications and designs are subject to change without notice.

Liability Disclaimer

Zebra Technologies takes steps to ensure that its published Engineering specifications and manuals are correct; however, errors do occur. Zebra Technologies reserves the right to correct any such errors and disclaims liability resulting therefrom.

Limitation of Liability

In no event shall Zebra Technologies or anyone else involved in the creation, production, or delivery of the accompanying product (including hardware and software) be liable for any damages whatsoever (including, without limitation, consequential damages including loss of business profits, business interruption, or loss of business information) arising out of the use of, the results of use of, or inability to use such product, even if Zebra Technologies has been advised of the possibility of such damages. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you.

Overview

Introduction to FTM technology

802.11mc Fine Timing Measurement (FTM), also known as Wi-Fi Round Trip Time (RTT), is a time-based measurement protocol that estimates the distance between FTM-capable Wi-Fi entities. In the context of this guide, the measured distance is between FTM-capable AP and FTM-capable Mobile Device, whereby the estimated distance is within one meters of precision. By calculating the distances between the device and multiple APs with known locations, the positions of the device can be determined.

A technique for calculating the round-trip time between an initiating and responding 802.11mc compliant unit is defined by the FTM protocol. A starting entity, such as the client (also known as STA), sends the FTM request frame to the corresponding entity, such as the AP. The responding entity, also referred to as the Responder, starts sending the FTM response frames requested by the client STA. To improve accuracy, the client STA must send FTM request frames to the collection of APs. The APs’ responses are averaged across several frames to provide an accurate reading.

Use Cases

Enterprise Applications commonly strive to support use cases of Indoor Navigation, Device Tracking, Asset Tracking, and other Location Based Services (LBS) on their Mobile Devices. For example:

• Navigation to merchandise on a shelf in the store, showing the real-time path over a map.

• Find closest associate to a specific location and dispatch that associate to quickly help a shopper
  that rings from a help station in a large store. The system needs precise location of all associates and decides who is the closest.

• Track device, which is forgotten/lost by an associate on high shelves, on fork lifts, etc.

• Record exactly where an application has an issue or service/conncectivity.

Using Wi-Fi FTM for those use cases delivers on two major standardized points:

• Sub-Meter accuracy, based on time-of-flight Round Trip Time (RTT) protocol which yields precise distance between two involved FTM-capable entities (for example, Device and AP), replacing older sensory-based only technologies such as RSSI and others.
• Leveraging on the ubiquity of Wi-Fi networks; does not require separate infrastructure.

Ecosystem of FTM-capable Devices

With the Zebra’s FTM-capable devices, applications can use the RTT Ranging (distance measuring) technology, accessible through the Google Wi-Fi RTT Service APIs. The Application may utilize these native APIs to manage the flows of distance-measuring, then compute positioning, and implement deployment techniques of correlating the real time positioning with Global or Local ground-references.

Applications may also choose to use the native Android Location Manager and Fused Location Services beyond the native Wi-Fi RTT Service. These additional services provide to Applications the computed Global Positioning updates by incorporating Wi-Fi RSSI and other physical sensors data computations, as well as combining location-data from exchanges with remote providers including network-addressing and cellular. However, those global-positioning techniques do not incorporate RTT distance measuring.

Zebra devices offer a unique simplification to the enablement of Locationing use-cases, in the form of Zebra’s Wi-Fi Locationing Provider solution.

This document provides integration guidance for using the Zebra Locationing Provider solution.

Zebra Wi-Fi Locationing Provider Solution

Zebra Wi-Fi Locationing Provider is a proprietary solution, based on a proprietary API service that is an extension to the Android native APIs.

An application that integrates this solution can benefit from the following:

• The service provides computed live Location Updates, as Global or Local 3-dimentional positioning data. Applications using the service do not need to compute the positioning themselves from raw RTT distance measures. The service does this for them.
• The outcome of positioning data is within 1-meter accuracy.
• Registering with the service is via an extension to the Android Location Manager, and the Location Updates of the computed position are provided to the application in a standard position format.

Additionally, the service ensures the following device performance during FTM and Location Updates activities:

• Latency-sensitive traffic, such as Voice and Video, is not interrupted.
• High Throughput Application’s Speed (Mbps) is impacted only negligibly.
• Net battery draining is negligible.

The following table depicts performance metrics of deploying FTM with using the Zebra Locationing Provider, compared to deploying FTM with using other solutions.

FTM Activities and Location Updates| Solutions using Zebra Locationing Provider| Other FTM Solutions Not Using Zebra Locationing Provider
---|---|---
During Voice and Video| User Experience of Audio and/or Video is not interrupted | Inconsistent. Sometimes interrupted leading to choppiness.
During High Throughput| Average reduction of speed: 1-5%
Rare worst-case reduction: 10%| Average reduction of speed: 10-15%
Frequent dips reductions: 20-25%
Battery Consumption| Net consumption: ~5% in 12- hours| Net consumption: ~12% in 12- hours

Supported Products and Default Configuration

The following Zebra products are natively FTM-capable within Android 10 onwards, as well as supporting the built-in Zebra Wi-Fi Locationing Provider solution.

PS20|
---|---
TC22| Requires Zebra’s MDNA License for the Zebra WiFi Locationing Provider solution
TC27| Requires Zebra’s MDNA License for the Zebra WiFi Locationing Provider solution
TC52/TC52HC|
TC52ax|
TC53|
TC57|
TC58|
TC72|
TC73|
TC77|
TC78|
MC93|
TC8300|
VC8300|
EC30|
ET40| Requires Zebra’s MDNA License for the Zebra WiFi Locationing Provider solution
ET45| Requires Zebra’s MDNA License for the Zebra WiFi Locationing Provider solution
ET60|
ET65|
ET51|
ET56|
L10|
CC600/CC6000 |
MC3300x|
MC330x|
MC3300ax|
TC52x|
TC57x|
EC50 (LAN and HC)|
EC55 (WAN) |
WT6300|

Product Default FTM Configuration

The native FTM-capability of the supporting models is not configurable. The Zebra Locationing Provider Service is configurable, enabled by default. In specific supporting models, if mentioned in the above Supported Product List, installation of Zebra’s MDNA license is required for enabling it.

NOTE: In addition to Zebra Locationing Provider support, specific solution’s parameters must be pre-configured with Device Management tools powered by Zebra MX (refer to Solution Configuration with Tools Powered by Zebra MX).

Device Setting

Table 1 Default, Supported, and Recommended Device Settings

Feature| Default Configuration| Supported Configuration| Recommended for FTM Location
---|---|---|---
11K| Enabled| • Enable
• Disable| As default
Location| Enabled| • Enable
• Disable| As default
Wi-Fi Scanning| Enabled| • Enable
• Disable| As default
11ac| Enabled| • Enable
• Disable| As default

Integration of the Zebra Locationing Provider Solution

This section describes how to enable the solution. The integrator of the solution must complete the procedures outlined below.

• Verfiy that the WLAN infrastructure vendor (APs) support FTM and it is enabled.

Set up and enable the device to match characteristics of the WLAN FTM-capable infrastructure.

Certain location infrastructures may not support the suggested settings such as 11k, LCI, and LCR. To enable to the solution, the device must be provisioned with a predefined configuration based on the supported infrastructure. For more information, go to Solution Configuration with Tools Powered by Zebra MX.

• Use the Zebra Locationing Provider APIs inside the target Android location application.

This document contains a sample code snippet to help integrators create their own location application. For more information, go to Sample Code for the Zebra Locationing Provider Service.

Sample Code Sequence for the Zebra Locationing Provider Service

Android Location Manager API List

• Public void requestLocationUpdates (String provider, long minTime, float minDistance, LocationListener listener)
  Provider: The name of the provider with which to register. This value must never be null. minTime: Minimum time interval between location updates, minDistance: Minimum distance between location updates, in meters.
  Listener: A LocationListener whose LocationListener#onLocationChanged method will be called for each location update This value must never be null.

• Get Current Location in A11 and higher:
  • public void getCurrentLocation(String provider,CancellationSignal cancellationSignaol, Executor executor, Consumerconsumer): Returns a single location update from the very recent past.
  Provider: The name of the provider with which to register. This value must never be null.
  CancellationSignal: Used to cancel the operation, no callback should be expected after the cancellation.
  Executor: the callback will take place on this executor.
  Consumer: the callback invoked with either a Location or null.

• Get Current Location in A10:
  • public void requestSingleUpdate(String provider, LocationListener listener, Looper looper):
  Provider: Name of the location provider
  Listener: The listener to receive location updates
  Looper: The looper handling listener callbacks, or null to use the looper of the calling thread

Application Code Snippet

• To Initialize and Get Location Manager Object: The application gets the location manager object using an Android existing API:

LocationManager manager = (LocationManager)
getSystemService(LOCATION_SERVICE)

Obtain the LocationManager object in order to use the API’s listed below.

• To Request Location Updates:
  To request location updates using the Zebra Locationing service as a provider:

manager.requestLocationUpdates(“rtt”, 5000, 1, listener);

By default, Android provides two providers: GPS and network providers. Zebra provides a specific FTM provider called “rtt” provider, which can be accessed through the APIs of the Location Manager services. Android provides an API to query the list of supported providers. Application developers can use the API to retrieve the list of providers supported by the product. [getAllProviders]

Here, the listener is Android’s existing listener called LocationListener to get the location updates.

LocationListener listener = new LocationListener( )
{
@Override
public void onLocationChanged(Location location)
{location.getLongitude();location.getLatitude( ); }
}

• To Remove Location Updates:
  To stop the location updates using blow API

manager.removeUpdates(listener);

• To Get the Last Known Location:
  To get the last known location, one should use the Android API below:

Location loc = manager.getLastKnownLocation(“rtt”)

• To Get Current Location:

1. manager.requestSingleUpdate(“rtt”, listener,Looper);//use this API for A10 and below
2. manager.getCurrentLocation(“rtt”,new CancellationSignal( ), new CustomExecutor(),newConsumer( )
{
@Override
public void accept (Location location) {
if (location != null) {
location.getLongitude();
location.getLatitude();
}
}
}); // use this AI for Android A11 and above

Solution Configuration with Tools powered by Zebra MX

This section describes the solution configuration options when using any Device Management tool that is powered by Zebra Mobility Extensions (MX). Such configuration methods might be, for example, a centralized Enterprise Mobility Management system already powered by MX, or a staging tool such as Zebra’s StageNow, or an ondevice application which may have privileged access to the MX framework.

The tool used for the solution configuration option must have an MX version of 10.2 or above.

For more MX generic information, go to techdocs.zebra.com.

For FTM configuration options, please go to techdocs.zebra.com/ms/wifi and search for FTM.

During solution’s trial staging and testing, it is convenient to use the Zebra’s StageNow tool and deploy configuration with a scanned barcode or other StageNow methods.

StageNow version 5.0 is required. It includes the required MX 10.2. download.
For more information on StageNow, go to techdocs.zebra.com/stagenow.

Configuration Options

Zebra Locationing Provider service must run continuously in the background.
FTM Enable: Specify whether to enable or disable Zebra Locationing Provider service.

• Enable: Enables the Zebra Location Provider service.
• Disable: Disables the Zebra Location Provider service. For example, the application can only access Google’s native RTT features for raw distance measuring.

Enable state is is required for the further solutions parameters.

The Default is Enabled in factory image of Enterprise device models. The Default is Disabled in Professional device models which do not include the Zebra’s mDNA license. In those devices, if the mDNA license is pre-installed (or once it is installed), the FTMEnable param is automatically set to Enable.

FTMDeployment Mode:Choose the desired deployment mode.

• Standard (FTM-enabled): Use this option when devices are deployed in WLAN infrastructure APs that
  support FTM/802.11mc.

• Enhanced-Infra (FTM-enabled): Use this option when devices are deployed in WLAN infrastructure in which the APs of the primary network (providing normal connectivity) are not FTM-capable, and a separate set of APs that are FTM-capable are specifically added to the system for the purpose of FTM and those APs do not provide connectivity.

Standard (FTM-enabled) is the default configuration when FTMEnable is set to Enable.

FTM AP Source:The Zebra Locationing Provider needs the knowledge of the AP (FTM-capable) position coordinates to identify the device’s Global or relative Local location in the three-dimensional space. The AP’s positions can be conveyed to the device dynamically via AP’s Beacons Information Element (IE) using WGS format (GPS) given that the WLAN APs system is configured and provisioned with LCI and LCR data, or in manual-specific format (meters/feet) reflecting the relative Local Grid coordinates, hard-coded XML file.

Supported Modes are Location via XML & Location via AP LCI configuration.

• Location XML: Use this option if the AP is unable to send its GPS position coordinates as part of LCI IE. The administrator must manually insert all AP coordinates into an XML file. (AP position is determined using a ground reference point.) See example ZML file in Sample XML File Format section.

By selecting this option, the FTM Deployment File option is enabled, allowing the user to input the XML path for the floor.

NOTE: The XML file (floormap.xml) for the floor plan must be relocated to the device’s SD card path using FileMgr CSP. See Deploying XML with FileMgr CSP.

• The location from API (LCR/LCI): Choose this option if the APs are configured and provisioned with their GPS coordinates and can broadcast LCI data as part of the 802.11mc frames.

Location XML is the default configuration when FTMEnable is set to Enable.

FTMDeployment_File:This option is only accessible if the FTM AP Source setup includes Location XML. The same path must be supplied once the FTM deployment file has been copied to the SDcard path on the device through FileMgr CSP . For further information, see Deploying XML using FileMgr CSP.

Deploying XML Using FileMgr CSP

The File Manager (FileMgr) allows an application to manage files on the device. In this case, the use forFTM is to cop

1. File Action: Select Transfer/Copy file.

2. Target Path and File Name: Enter the full path of the file to be located on the device.
   Example: /sdcard/FloorMap.xml

3. Source Path and File Name: Enter the details of the file to push the device.
   Example: C:UsersUsernameDownloadsFloorMap.xml

4. Click Continue to finish the process and generate a barcode.

5. Click Complete Profile.

6. Select the desired barcode type and click Test to view the barcode in a PDF.

Sample XML File Format

<?xml version=’1.0′ encoding=’UTF-8′ standalone=’yes’?>

NOTE: This sample XML maps many sites and their associated floors in a single XML file. If more than one XML file is kept, the user must push the corresponding XML file to the SDcard and restart the staging procedure.

Configure Various FTM Deployments

Configure FTM for Standard Mode of Deployment (XML Method)

Prerequisites

• The product supports FTM feature.
• The infrastructure AP has built-in 11mc feature and the feature is enabled.
• It is preferred that 11k and 11ac are enabled in the infrastructure. See Common Recommendations for Infrastructure to Support FTM.
• XML file with the BSSID of 11mc APs and the corresponding x, y, and z coordinates in relation to the floor plan.

Configuration

To configure FTM for Standard Mode of Deployment (XML method):

1. Select FTM Enable to enable the solution.

2. Select Standard (FTM Enabled) from FTM Deployment Mode option. Ensure that 11k and 11ac are enabled on the device and in the infrastructure.

3. Select the coordinate source AP. Select the Location XML option.

4. After selecting Location XML, push the XML file. The XML file (for e.g. floormap.xml) should have all 11mc APs BSSID and their x, y, z coordinates hard coded in the file. (See Sample XML File Format.) The administrator must deploy the XML file to the sdcard path on the device using FileMgr CSP. (See Deploying XML Using FileMgr CSP.)

5. Specify the path of the XML file in the FTM Deployment file (sdcard path of the device).
   Deploy the above configuration using StageNow. The device is ready for indoor navigation.

6. View the Application code snippet and modify the location application by using the Android Location Manager API to get location updates.

Configure FTM for Standard Mode of Deployment (LCI/LCR Method)

Prerequisites

• The product supports FTM feature.
• The infrastructure AP has built-in 11mc feature and the feature is enabled.
• It is preferred that 11k and 11ac are enabled in the infrastructure. See Common Recommendations for Infrastructure to Support FTM.
• The infrastructure AP should have LCI and LCR configurable and send them FTM action frames.

Configuration

To configure FTM for Standard Mode of Deployment (LCI/LCR method):

1. Select FTM Enable to enable the solution.

2. Select Standard (FTM Enabled) from FTM Deployment Mode option. Ensure that 11k and 11ac are enabled on the device and in the infrastructure.

3. Select Location from AP option.
   Deploy the above configuration using StageNow. The device is ready.

4. View the Application code snippet and modify the location application by using the Android Location Manager API to get location updates.

Configure FTM for Enhanced Infra Mode of Deployment

Enhanced Infra Mode means that the AP network that the device is connecting to might not have a built-in 11mc capability, and the deployment is enhancing the infrastructure with separate set of AP network supporting 11mc, to which the device is not connecting.

In this case, if the Enhanced Infra satisfies the same above mentioned prerequisites respective to XML or LCI/ LCR methods, then the same above mentioned configuration steps of respective XML or LCI/ LCR methods enable the Device’s FTM locationing inter-operated with that Enhanced Infrastructure.

Notes on Location Updates in Mobility and Idle Scenarios

Android Power Management and Zebra’s additional device optimizations influence the outcome of the location updates.

The following points need to be considered:

• The location updates operate based on fresh Wi-Fi RTT-
  Scanning and per the configured interval, in the following scenarios:
  • When the device is moving.
  • When the device is not moving and the Battery Optimizations settings of the App/Service using the Location API is set to Don’t Optimize.
  • When the WLAN Infrastructure has 802.11k enabled and the device has its 802.11k enabled (default).
  • This capability of fresh scans under this configuration, even without satisfying the above two conditions, is specific to Zebra’s enhancements.

• The location updates operate based on cached Wi-Fi RTTScanning (older scans) and per the configured interval, when the device is not moving and nothing is preventing Android from optimizing the battery. This condition is sometimes referred as Doze mode.

• When the device is entering a state of Preferred Network Offload (PNO) and is not moving; for example, when the display screen times out when device is sitting on the table, then the location updates are provided for approximately one hour based on the fresh Wi-Fi RTT-Scanning and per the configured interval. Afterwards, Android forces periodical and sensory-triggering based logics of going in and out of Doze mode for purpose of saving battery life. In the sub periods of the Doze mode, the location updates operate based on cached Wi-Fi RTT-Scanning (older scans), as explained above.

• It is advised to upgrade the device to the latest LifeGuard Update, where optimization for High Ceiling is applicable, and XML characteristics are introduced to support DeviceHeight and ApHeight, and coordinates are provided with additional Z-axis.

Example of Real Time Indoor Navigation Solution

The figure below depicts an example of real-time indoor navigation using the Zebra Location Provider Service.

Legend for the figure.

• Green dots are the 11mc-capable APs.
• Green Arrows is the user’s physical walking path.
• Red dots are the real-time location updates data that the Zebra Location Provider Service provides to the application along the path.
• Circles around the red dots are used to highlight a few examples of deviations:
  • “A” is location data which deviates between 0 to 0.2 meters from the physical location.
  • “B” is location data which deviates between 0.3 to 0.5 meters from the physical location.
  • “C” is location data which deviates between 0.8 to 1 meters from the physical location.

As shown in Figure 1, most of the red dots deviate from the physical path similarly to “A” and “B”.

Common Recommendations for Infrastructure to Support FTM

Default, Supported, and Recommended AP settings

This section describes general WLAN AP guidelines and limitations for FTM responder support.

These guidelines are typically the default parameters of the infrastructure configuration. However, they should to be examined to make sure that it is actually the case, and/or consider the respective compromises of FTM performance.

Bandwidth

It is recommended to use ≥80 MHz, while 11ac remains enabled. This is because location results are best at higher bandwidth due to better measuremen

Channels

During testing, it is better to use a nonDFS 80 MHz channel. The actual deployment may use all available 80 MHz channels, including DFS.

802.11k

802.11K can be enabled to make it easy for clients to discover neighbors of the currently associated AP, as well as their FTM Responder capability. This can be used by clients in their roaming and FTM ranging decisions.

AP Density for Ranging

Line of Sight (LoS) range measurements have greater accuracy and lower error spread. The current recommendation

AP Deployment

A grid-like deployment wherever possible, since range measurements from collinear APs with some error can affect the position estimation greater than measurements from APs uniformly spread.

MCS Rates

Leave MCS0 available to be used for 11mc ranging frames.

Aruba Recommendations for Infrastructure to Support FTM

This section describes Aruba WLAN AP guidelines and limitations for FTM responder support.

Enabling FTM Profile

Enabling in Aruba Instant AP (IAP) System

The figure below shows the command sequence to enable the IAP’s FTM responder and location advertisement capabilities. The sequence includes:

• ftm-responder-enable
• advertise-location
• end
• commit apply
• show network

NOTE: To disable LCI advertisement , the command “no advertise-location” shall be used. To disable FTM responder, the command “no ftm-responder-enable” shall be used.

Provisioning of LCI Coordinates in the Aruba IAP

Use the following commands, shown as examples, to configure GPS Location Coordinates of AP.

NOTE: This section provides commands to configure the LCI parameters (Latitude, Longitude & Altitude).

IAP5xx_LCI# lci-location 45.47951819 -73.62921609 1 37 1
IAP5xx_LCI# lci-uncertainty 20.016 20 0.03
IAP5xx_LCI# floor-info-mgmt 0 15 10 0
IAP5xx_LCI# commit apply

Optional Provisioning of Z Subelement Field in the Aruba IAP

Use the following commands, shown as examples, to configure Z subelement of AP.
floor-info-mgmt is used to configure Z elements.
floor-info-mgmt