Vị trí Wi-Fi: phạm vi có RTT

Bạn có thể sử dụng chức năng vị trí Wi-Fi do Wi-Fi RTT (Round-Trip-Time) API cung cấp để đo khoảng cách đến các điểm truy cập Wi-Fi có hỗ trợ RTT và các thiết bị ngang hàng Wi-Fi Aware ở gần.

Nếu đo khoảng cách đến 3 điểm truy cập trở lên, bạn có thể sử dụng thuật toán đa phương để ước tính vị trí thiết bị phù hợp nhất với các phép đo đó. Kết quả thường chính xác trong phạm vi từ 1 đến 2 mét.

Với độ chính xác này, bạn có thể phát triển các dịch vụ dựa trên vị trí chi tiết, chẳng hạn như chỉ đường trong nhà, điều khiển bằng giọng nói rõ ràng (ví dụ: "Bật đèn này") và thông tin dựa trên vị trí (ví dụ: "Có ưu đãi đặc biệt nào cho sản phẩm này không?").

Thiết bị yêu cầu không cần kết nối với các điểm truy cập để đo khoảng cách bằng Wi-Fi RTT. Để duy trì quyền riêng tư, chỉ thiết bị yêu cầu mới có thể xác định khoảng cách đến điểm truy cập; các điểm truy cập không có thông tin này. Các thao tác Wi-Fi RTT không bị giới hạn đối với ứng dụng trên nền trước nhưng bị điều tiết đối với ứng dụng chạy trong nền.

Wi-Fi RTT và các chức năng Đo lường thời gian chính xác (FTM) liên quan được chỉ định theo tiêu chuẩn IEEE 802.11-2016. Wi-Fi RTT yêu cầu phép đo thời gian chính xác do FTM cung cấp vì Wi-Fi RTT tính toán khoảng cách giữa hai thiết bị bằng cách đo thời gian một gói thực hiện hành trình khứ hồi giữa các thiết bị và nhân thời gian đó với tốc độ ánh sáng.

Android 15 (cấp độ API 35) ra mắt tính năng hỗ trợ đo khoảng cách không dựa trên trình kích hoạt (NTB) IEEE 802.11az.

Sự khác biệt về cách triển khai dựa trên phiên bản Android

Wi-Fi RTT được ra mắt trong Android 9 (cấp độ API 28). Khi sử dụng giao thức này để xác định vị trí của thiết bị bằng phương pháp đa phương với các thiết bị chạy Android 9, bạn cần có quyền truy cập vào dữ liệu vị trí điểm truy cập (AP) được xác định trước trong ứng dụng. Bạn có thể quyết định cách lưu trữ và truy xuất dữ liệu này.

Trên các thiết bị chạy Android 10 (API cấp 29) trở lên, dữ liệu vị trí của AP có thể được biểu thị dưới dạng đối tượng ResponderLocation, bao gồm vĩ độ, kinh độ và độ cao. Đối với các AP RTT Wi-Fi hỗ trợ Thông tin cấu hình vị trí/Báo cáo vị trí dân sự (dữ liệu LCI/LCR), giao thức sẽ trả về một đối tượng ResponderLocation trong quá trình xác định phạm vi.

Tính năng này cho phép các ứng dụng truy vấn trực tiếp các điểm truy cập để hỏi vị trí của chúng, thay vì cần lưu trữ thông tin này trước. Vì vậy, ứng dụng của bạn có thể tìm thấy các AP và xác định vị trí của chúng ngay cả khi trước đó không biết các AP, chẳng hạn như khi người dùng bước vào một toà nhà mới.

Tính năng đo khoảng cách NTB theo chuẩn IEEE 802.11az được hỗ trợ trên các thiết bị chạy Android 15 (cấp độ API 35) trở lên. Điều này có nghĩa là nếu thiết bị hỗ trợ chế độ khởi tạo NTB IEEE 802.11az (được biểu thị bằng WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR), thì ứng dụng của bạn có thể tìm thấy cả AP có khả năng IEEE 802.11mc và IEEE 802.11az bằng một yêu cầu phạm vi duy nhất. API RangingResult đã được mở rộng để cung cấp thông tin về giá trị tối thiểu và tối đa có thể dùng cho khoảng thời gian giữa các phép đo khoảng cách, để lại khoảng thời gian chính xác trong quyền kiểm soát của ứng dụng.

Yêu cầu

• Phần cứng của thiết bị đưa ra yêu cầu đo khoảng cách phải triển khai tiêu chuẩn FTM 802.11-2016 hoặc tiêu chuẩn 802.11az (đo khoảng cách không dựa trên điều kiện kích hoạt).
• Thiết bị đưa ra yêu cầu đo khoảng cách phải chạy Android 9 (cấp độ API 28) trở lên. Tính năng đo khoảng cách không dựa trên trình kích hoạt IEEE 802.11az được bật trên các thiết bị chạy Android 15 (cấp độ API 35) trở lên.
• Thiết bị đưa ra yêu cầu đo khoảng cách phải bật dịch vụ vị trí và bật tính năng quét tìm Wi-Fi (trong phần Cài đặt > Vị trí).
• Nếu ứng dụng đưa ra yêu cầu đo khoảng cách nhắm đến Android 13 (API cấp 33) trở lên, thì ứng dụng đó phải có quyền NEARBY_WIFI_DEVICES. Nếu ứng dụng như vậy nhắm đến một phiên bản Android cũ hơn, thì ứng dụng đó phải có quyền ACCESS_FINE_LOCATION.
• Ứng dụng phải truy vấn phạm vi của các điểm truy cập trong khi ứng dụng hiển thị hoặc trong một dịch vụ nền trước. Ứng dụng không thể truy cập vào thông tin vị trí ở chế độ nền.
• Điểm truy cập phải triển khai tiêu chuẩn FTM IEEE 802.11-2016 hoặc tiêu chuẩn IEEE 802.11az (đo khoảng cách không dựa trên trình kích hoạt).

Thiết lập

Để thiết lập ứng dụng sử dụng Wi-Fi RTT, hãy thực hiện các bước sau.

1. Yêu cầu cấp quyền

Yêu cầu các quyền sau trong tệp kê khai của ứng dụng:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<!-- If your app targets Android 13 (API level 33)
     or higher, you must declare the NEARBY_WIFI_DEVICES permission. -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
                 <!-- If your app derives location information from Wi-Fi APIs,
                      don't include the "usesPermissionFlags" attribute. -->
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                 <!-- If any feature in your app relies on precise location
                      information, don't include the "maxSdkVersion"
                      attribute. -->
                 android:maxSdkVersion="32" />

Quyền NEARBY_WIFI_DEVICES và ACCESS_FINE_LOCATION là các quyền nguy hiểm, vì vậy, bạn cần yêu cầu các quyền này trong thời gian chạy mỗi khi người dùng muốn thực hiện thao tác quét RTT. Ứng dụng của bạn sẽ cần yêu cầu người dùng cấp quyền nếu quyền đó chưa được cấp. Để biết thêm thông tin về quyền khi bắt đầu chạy, hãy xem phần Yêu cầu quyền cho ứng dụng.

2. Kiểm tra xem thiết bị có hỗ trợ Wi-Fi RTT hay không

Để kiểm tra xem thiết bị có hỗ trợ Wi-Fi RTT hay không, hãy sử dụng API PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_RTT);

3. Kiểm tra xem có Wi-Fi RTT hay không

RTT Wi-Fi có thể tồn tại trên thiết bị, nhưng có thể không hoạt động vì người dùng đã tắt Wi-Fi. Tuỳ thuộc vào khả năng của phần cứng và chương trình cơ sở, một số thiết bị có thể không hỗ trợ Wi-Fi RTT nếu đang sử dụng SoftAP hoặc tính năng chia sẻ Internet. Để kiểm tra xem Wi-Fi RTT có hoạt động hay không, hãy gọi isAvailable().

Phạm vi cung cấp Wi-Fi RTT có thể thay đổi bất cứ lúc nào. Ứng dụng của bạn phải đăng ký một BroadcastReceiver để nhận ACTION_WIFI_RTT_STATE_CHANGED, được gửi khi có thay đổi về tình trạng rảnh/bận. Khi nhận được ý định truyền tin, ứng dụng sẽ kiểm tra trạng thái hiện tại của tính năng và điều chỉnh hành vi cho phù hợp.

Ví dụ:

val filter = IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED)
val myReceiver = object: BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (wifiRttManager.isAvailable) {
            …
        } else {
            …
        }
    }
}
context.registerReceiver(myReceiver, filter)

IntentFilter filter =
    new IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (wifiRttManager.isAvailable()) {
            …
        } else {
            …
        }
    }
};
context.registerReceiver(myReceiver, filter);

Để biết thêm thông tin, hãy xem nội dung Chương trình phát sóng.

Tạo yêu cầu đo khoảng cách

Yêu cầu đo khoảng cách (RangingRequest) được tạo bằng cách chỉ định danh sách các AP hoặc thiết bị ngang hàng Wi-Fi Aware mà bạn yêu cầu đo khoảng cách. Bạn có thể chỉ định nhiều điểm truy cập hoặc thiết bị ngang hàng Wi-Fi Aware trong một yêu cầu đo khoảng cách; khoảng cách đến tất cả thiết bị sẽ được đo và trả về.

Ví dụ: một yêu cầu có thể sử dụng phương thức addAccessPoint() để chỉ định một điểm truy cập cần đo khoảng cách:

val req: RangingRequest = RangingRequest.Builder().run {
    addAccessPoint(ap1ScanResult)
    addAccessPoint(ap2ScanResult)
    build()
}

RangingRequest.Builder builder = new RangingRequest.Builder();
builder.addAccessPoint(ap1ScanResult);
builder.addAccessPoint(ap2ScanResult);

RangingRequest req = builder.build();

Điểm truy cập được xác định bằng đối tượng ScanResult, có thể lấy được bằng cách gọi WifiManager.getScanResults(). Bạn có thể sử dụng addAccessPoints(List<ScanResult>) để thêm nhiều điểm truy cập cùng lúc.

Đối tượng ScanResult có thể chứa cả AP hỗ trợ IEEE 802.11mc (is80211mcResponder()) và AP hỗ trợ đo khoảng cách không dựa trên trình kích hoạt IEEE 802.11az (is80211azNtbResponder()). Các thiết bị hỗ trợ đo khoảng cách IEEE 802.11az NTB sẽ thực hiện đo khoảng cách 802.11mc hoặc 802.11az tuỳ thuộc vào chức năng của AP, mặc định là 802.11az khi AP hỗ trợ cả hai. Các thiết bị không hỗ trợ IEEE 802.11az sẽ thực hiện tất cả phép đo khoảng cách bằng giao thức IEEE 802.11mc.

Tương tự, yêu cầu đo khoảng cách có thể thêm một thiết bị ngang hàng Wi-Fi Aware bằng địa chỉ MAC hoặc PeerHandle của thiết bị đó, tương ứng bằng các phương thức addWifiAwarePeer(MacAddress peer) và addWifiAwarePeer(PeerHandle peer). Để biết thêm thông tin về cách khám phá các thiết bị ngang hàng Wi-Fi Aware, hãy xem tài liệu về Wi-Fi Aware.

Yêu cầu đo khoảng cách

Ứng dụng đưa ra yêu cầu đo khoảng cách bằng phương thức WifiRttManager.startRanging() và cung cấp những thông tin sau: RangingRequest để chỉ định thao tác, Executor để chỉ định ngữ cảnh gọi lại và RangingResultCallback để nhận kết quả.

Ví dụ:

val mgr = context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE) as WifiRttManager
val request: RangingRequest = myRequest
mgr.startRanging(request, executor, object : RangingResultCallback() {

    override fun onRangingResults(results: List<RangingResult>) { … }

    override fun onRangingFailure(code: Int) { … }
})

WifiRttManager mgr =
      (WifiRttManager) Context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE);

RangingRequest request ...;
mgr.startRanging(request, executor, new RangingResultCallback() {

  @Override
  public void onRangingFailure(int code) { … }

  @Override
  public void onRangingResults(List<RangingResult> results) { … }
});

Thao tác đo khoảng cách được thực hiện không đồng bộ và kết quả đo khoảng cách được trả về trong một trong các lệnh gọi lại của RangingResultCallback:

• Nếu toàn bộ hoạt động đo khoảng cách không thành công, lệnh gọi lại onRangingFailure sẽ được kích hoạt bằng mã trạng thái được mô tả trong RangingResultCallback. Lỗi như vậy có thể xảy ra nếu dịch vụ không thể thực hiện thao tác đo khoảng cách tại thời điểm đó, chẳng hạn như do Wi-Fi bị tắt, do ứng dụng đã yêu cầu quá nhiều thao tác đo khoảng cách và bị điều tiết hoặc do vấn đề về quyền.
• Khi thao tác đo khoảng cách hoàn tất, lệnh gọi lại onRangingResults sẽ được kích hoạt bằng danh sách kết quả khớp với danh sách yêu cầu (mỗi yêu cầu có một kết quả). Thứ tự của kết quả không nhất thiết phải khớp với thứ tự của yêu cầu. Xin lưu ý rằng thao tác đo khoảng cách có thể hoàn tất nhưng mỗi kết quả vẫn có thể cho thấy lỗi của phép đo cụ thể đó.

Diễn giải kết quả đo khoảng cách

Mỗi kết quả do lệnh gọi lại onRangingResults trả về được chỉ định bằng một đối tượng RangingResult. Trên mỗi yêu cầu, hãy làm như sau.

1. Xác định yêu cầu

Xác định yêu cầu dựa trên thông tin được cung cấp khi tạo RangingRequest: thường là địa chỉ MAC được cung cấp trong ScanResult xác định điểm truy cập. Bạn có thể lấy địa chỉ MAC từ kết quả đo khoảng cách bằng phương thức getMacAddress().

Danh sách kết quả đo khoảng cách có thể theo thứ tự khác với các thiết bị ngang hàng (điểm truy cập) được chỉ định trong yêu cầu đo khoảng cách, vì vậy, bạn nên sử dụng địa chỉ MAC để xác định thiết bị ngang hàng, chứ không phải thứ tự của kết quả.

2. Xác định xem mỗi lần đo có thành công hay không

Để xác định xem một phép đo có thành công hay không, hãy sử dụng phương thức getStatus(). Bất kỳ giá trị nào khác STATUS_SUCCESS đều cho biết lỗi. Lỗi có nghĩa là tất cả các trường khác của kết quả này (ngoại trừ thông tin nhận dạng yêu cầu ở trên) đều không hợp lệ và phương thức get* tương ứng sẽ không thành công kèm theo một ngoại lệ IllegalStateException.

3. Nhận kết quả cho mỗi lần đo lường thành công

Đối với mỗi phép đo thành công (RangingResult), bạn có thể truy xuất các giá trị kết quả bằng các phương thức get tương ứng:

• Khoảng cách (tính bằng mm) và độ lệch chuẩn của phép đo:

  getDistanceMm()

  getDistanceStdDevMm()

• RSSI của các gói được dùng để đo lường:

  getRssi()

• Thời gian (tính bằng mili giây) mà phép đo được thực hiện (cho biết thời gian kể từ khi khởi động):

  getRangingTimestampMillis()

• Số lần đo lường đã thử và số lần đo lường thành công (và các phép đo khoảng cách dựa trên đó):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• Thời gian tối thiểu và tối đa mà thiết bị khách phải chờ giữa các phép đo 11az NTB:

  getMinTimeBetweenNtbMeasurementsMicros() và getMaxTimeBetweenNtbMeasurementsMicros() trả về thời gian tối thiểu và tối đa. Nếu phép đo khoảng cách tiếp theo được yêu cầu trước khi hết thời gian tối thiểu, thì API sẽ trả về kết quả đo khoảng cách được lưu vào bộ nhớ đệm. Nếu phép đo lường phạm vi tiếp theo được yêu cầu sau khi hết thời gian tối đa, thì API sẽ chấm dứt phiên đo lường phạm vi không kích hoạt và thương lượng một phiên đo lường phạm vi mới với trạm phản hồi. Bạn nên tránh yêu cầu một phiên đo khoảng cách mới vì việc này sẽ làm tăng thời gian đo khoảng cách. Để tận dụng tối đa hiệu quả đo khoảng cách không dựa trên trình kích hoạt của 802.11az, hãy kích hoạt yêu cầu đo khoảng cách tiếp theo trong khoảng thời gian đo tối thiểu và tối đa được chỉ định trong phép đo RangingResult trước đó.

• Số lần lặp lại Trường huấn luyện dài (LTF) mà các trạm phản hồi và trạm khởi tạo sử dụng trong phần mở đầu cho kết quả IEEE 802.11az NTB:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Số lượng luồng thời gian không gian (STS) truyền và nhận mà trạm khởi tạo đã sử dụng cho kết quả IEEE 802.11az NTB:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

Thiết bị Android hỗ trợ WiFi-RTT

Các bảng sau đây liệt kê một số điện thoại, điểm truy cập và thiết bị bán lẻ, kho bãi và trung tâm phân phối hỗ trợ WiFi-RTT. Đây chưa phải là danh sách đầy đủ. Bạn nên liên hệ với chúng tôi để liệt kê các sản phẩm hỗ trợ RTT tại đây.

Điểm truy cập

Điện thoại

Thiết bị cho trung tâm bán lẻ, kho bãi và phân phối