מיקום Wi-Fi: טווח עם RTT

אפשר להשתמש בפונקציות של מיקום Wi-Fi שמספק Wi-Fi RTT (Round-Trip-Time) API כדי למדוד את המרחק מנקודות גישה בקרבת מקום עם תמיכה ב-RTT וממכשירים אחרים עם תמיכה ב-Wi-Fi Aware.

אם מודדים את המרחק לשלוש נקודות גישה או יותר, אפשר להשתמש באלגוריתם של טריאנגולציה כדי להעריך את המיקום של המכשיר שמתאים בצורה הטובה ביותר למדידות האלה. בדרך כלל התוצאה מדויקת בטווח של 1-2 מטר.

בעזרת הדיוק הזה אפשר לפתח שירותים מבוססי-מיקום ברמת פירוט גבוהה, כמו ניווט בתוך מבנים, שליטה קולית ללא צורך בהבהרה (לדוגמה, "הפעלת הנורה הזו") ומידע מבוסס-מיקום (לדוגמה, "האם יש מבצעים מיוחדים על המוצר הזה?").

המכשיר המבקש לא צריך להתחבר לנקודות הגישה כדי למדוד את המרחק באמצעות Wi-Fi RTT. כדי לשמור על הפרטיות, רק המכשיר ששלח את הבקשה יכול לקבוע את המרחק לנקודת הגישה. המידע הזה לא קיים בנקודות הגישה. אין הגבלה על פעולות RTT ב-Wi-Fi באפליקציות בחזית, אבל הן מוגבלות באפליקציות ברקע.

זמן ה-RTT ב-Wi-Fi והיכולות הקשורות של מדידה מדויקת בזמן (FTM) מצוינים בתקן IEEE 802.11-2016. כדי לחשב את המרחק בין שני מכשירים ב-Wi-Fi RTT, צריך למדוד את הזמן המדויק של חבילה שמבצעת נסיעה הלוך ושוב בין המכשירים, ולהכפיל את הזמן הזה במהירות האור. לשם כך, נדרש מדידת הזמן המדויקת שמספקת FTM.

ב-Android 15 (רמת API 35) נוספה תמיכה במדידה לטווח (ranging) מסוג IEEE 802.11az ללא טריגר (NTB).

הבדלים בהטמעה בהתאם לגרסת Android

התחלנו להשתמש ב-RTT ב-Wi-Fi ב-Android 9 (רמת API 28). כשמשתמשים בפרוטוקול הזה כדי לקבוע את מיקום המכשיר באמצעות ריבוי עיבודים עם מכשירים עם Android 9, צריכה להיות לכם גישה לנתוני מיקומי נקודות גישה (AP) שנקבעו מראש באפליקציה. אתם אלה שמחליטים איך לאחסן ולאחזר את הנתונים האלה.

במכשירים עם Android מגרסה 10 ואילך (רמת API 29 ואילך), נתוני המיקום של נקודת הגישה יכולים להיות מיוצגים כאובייקטים מסוג ResponderLocation, שכוללים קו רוחב, קו אורך וגובה. לנקודות גישה RTT ב-Wi-Fi שתומכות במידע על הגדרות המיקום/בדוח ה-Location Civic (נתוני LCI/LCR), הפרוטוקול יחזיר אובייקט ResponderLocation במהלך תהליך הטווח.

התכונה הזו מאפשרת לאפליקציות לשלוח שאילתות לנקודות הגישה כדי לבקש מהן את המיקום שלהן ישירות, במקום לאחסן את המידע הזה מראש. כך האפליקציה יכולה למצוא נקודות גישה ולקבוע את המיקומים שלהן גם אם הן לא היו ידועות קודם, למשל כשמשתמש נכנס לבניין חדש.

תמיכה ב-IEEE 802.11az NTB למדידת מרחק זמינה במכשירים עם Android מגרסה 15 (רמת API 35) ואילך. כלומר, אם המכשיר תומך במצב היזם של NTB בתקן IEEE 802.11az (הסימן הוא WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR), האפליקציה יכולה למצוא נקודות AP שתומכות בתקנים IEEE 802.11mc ו-IEEE 802.11az באמצעות בקשת טווח אחת. הרחבנו את ממשק ה-API של RangingResult כדי לספק מידע על הערך המינימלי והמקסימלי שאפשר להשתמש בו עבור המרווח בין מדידות הטווח, כך שהמרווח המדויק יהיה בשליטת האפליקציה.

הדרישות

• החומרה של המכשיר שמבצע את בקשת הטווח חייבת להטמיע את תקן FTM 802.11-2016 או את תקן 802.11az (טווח שמבוסס על טריגרים שלא מבוססים על טריגר).
• במכשיר שממנו נשלחה בקשת הטווח צריכה לפעול מערכת Android בגרסה 9 (רמת API 28) ואילך. מדידת המרחק ללא טריגר של IEEE 802.11az מופעלת במכשירים עם Android מגרסה 15 (רמת API 35) ואילך.
• במכשיר שמגיש את בקשת המדידה צריכים להיות מופעלים שירותי המיקום וחיפוש רשתות Wi-Fi (בקטע הגדרות > מיקום).
• אם האפליקציה ששולחת את בקשת הטווח מטרגטת ל-Android 13 (רמת API 33) ואילך, היא צריכה את ההרשאה NEARBY_WIFI_DEVICES. אם אפליקציה כזו מטרגטת גרסה קודמת של Android, היא צריכה לקבל את ההרשאה ACCESS_FINE_LOCATION.
• האפליקציה צריכה לשלוח שאילתה על טווח נקודות הגישה בזמן שהיא גלויה או בשירות שפועל בחזית. לאפליקציה אין אפשרות לגשת למידע על המיקום ברקע.
• נקודת הגישה חייבת להטמיע את תקן IEEE 802.11-2016 FTM או את תקן IEEE 802.11az (טווח שמבוסס על טריגרים שאינם מבוססים).

הגדרה

כדי להגדיר את האפליקציה לשימוש ב-Wi-Fi RTT, מבצעים את השלבים הבאים.

1. בקשת הרשאות

מבקשים את ההרשאות הבאות במניפסט של האפליקציה:

<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" />

ההרשאות NEARBY_WIFI_DEVICES ו-ACCESS_FINE_LOCATION הן הרשאות מסוכנות, ולכן צריך לבקש אותן בזמן הריצה בכל פעם שהמשתמש רוצה לבצע סריקת RTT. אם ההרשאה עדיין לא ניתנה, האפליקציה תצטרך לבקש את הרשאת המשתמש. מידע נוסף על הרשאות בסביבת זמן הריצה זמין במאמר בקשה להרשאות לאפליקציה.

2. בדיקה אם המכשיר תומך ב-Wi-Fi RTT

כדי לבדוק אם המכשיר תומך ב-RTT ב-Wi-Fi, משתמשים ב-API של PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. איך בודקים אם התכונה Wi-Fi RTT זמינה

יכול להיות שהתכונה Wi-Fi RTT קיימת במכשיר, אבל היא לא זמינה כי המשתמש השבית את ה-Wi-Fi. בהתאם ליכולות החומרה והקושחה שלהם, יכול להיות שחלק מהמכשירים לא יתמכו ב-Wi-Fi RTT אם נעשה בהם שימוש ב-SoftAP או בקישור. כדי לבדוק אם אפשר להשתמש ב-RTT ב-Wi-Fi, צריך להתקשר למספר isAvailable().

הזמינות של RTT ב-Wi-Fi עשויה להשתנות בכל שלב. האפליקציה שלכם צריכה לרשום את התג BroadcastReceiver כדי לקבל את המחרוזת ACTION_WIFI_RTT_STATE_CHANGED, שנשלחת כשהזמינות משתנה. כשהאפליקציה מקבלת את כוונה השידור, היא צריכה לבדוק את סטטוס הזמינות הנוכחי ולשנות את ההתנהגות שלה בהתאם.

לדוגמה:

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);

מידע נוסף זמין במאמר שידורים.

יצירת בקשת טווח

כדי ליצור בקשת טווח (RangingRequest), מציינים רשימה של נקודות AP או מכשירי Wi-Fi Aware שעבורם מבקשים טווח. אפשר לציין כמה נקודות גישה או מכשירי Wi-Fi Aware בבקשה אחת למדידת המרחק, והמרחקים לכל המכשירים נמדדים ומוחזרים.

לדוגמה, אפשר להשתמש בבקשה ב-method‏ addAccessPoint() כדי לציין נקודת גישה שבה רוצים למדוד את המרחק:

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();

נקודת גישה מזוהה באמצעות האובייקט ScanResult שלה, שאפשר לקבל באמצעות קריאה ל-WifiManager.getScanResults(). אפשר להשתמש ב-addAccessPoints(List<ScanResult>) כדי להוסיף כמה נקודות גישה בבת אחת.

אובייקטים מסוג ScanResult יכולים להכיל גם את IEEE 802.11mc (is80211mcResponder()) וגם את הטווח שנתמך על ידי IEEE 802.11az שאינו טריגר (is80211azNtbResponder()). במכשירים שתומכים ב-IEEE 802.11az NTB ranging, מתבצעת מדידת טווח של 802.11mc או 802.11az, בהתאם ליכולת של הנקודה לשיתוף אינטרנט. ברירת המחדל היא 802.11az אם הנקודה לשיתוף אינטרנט תומכת בשתיהן. מכשירים שלא תומכים ב-IEEE 802.11az מבצעים את כל הטווחים באמצעות פרוטוקול IEEE 802.11mc.

באופן דומה, בקשת מדידת מרחק יכולה להוסיף עמית Wi-Fi Aware באמצעות כתובת ה-MAC שלו או באמצעות PeerHandle, באמצעות השיטות addWifiAwarePeer(MacAddress peer) ו-addWifiAwarePeer(PeerHandle peer), בהתאמה. מידע נוסף על זיהוי עמיתים ב-Wi-Fi Aware זמין במסמכי העזרה של Wi-Fi Aware.

Request ranging

אפליקציה שולחת בקשת טווח באמצעות השיטה WifiRttManager.startRanging() ומספקת את הפרטים הבאים: RangingRequest כדי לציין את הפעולה, Executor כדי לציין את ההקשר של הקריאה החוזרת, ו-RangingResultCallback כדי לקבל את התוצאות.

לדוגמה:

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) { … }
});

פעולת הטווח מתבצעת באופן אסינכרוני, ותוצאות הטווח מוחזרות באחת מהקריאות החוזרות של RangingResultCallback:

• אם כל פעולת הטווח נכשלת, הפונקציה החוזרת (callback) onRangingFailure מופעלת עם קוד הסטטוס שמתואר בקטע RangingResultCallback. כשל כזה יכול לקרות אם השירות לא יכול לבצע פעולת סריקה באותו זמן – למשל, כי ה-Wi-Fi מושבת, כי האפליקציה ביקשה יותר מדי פעולות סריקה והיא מוגבלת, או בגלל בעיה בהרשאות.
• כשפעולת הטווח מסתיימת, מתבצעת הפעלה חוזרת של onRangingResults עם רשימת תוצאות שתואמת לרשימת הבקשות – תוצאה אחת לכל בקשה. סדר התוצאות לא תואם בהכרח לסדר הבקשות. חשוב לזכור שפעולה של מדידת מרחק עשויה להסתיים, אבל כל תוצאה עדיין עשויה להצביע על כשל במדידה הספציפית הזו.

פירוש תוצאות הטווח

כל אחת מהתוצאות שמוחזרות על ידי הפונקציה הלא סטטית onRangingResults מוגדרת באמצעות אובייקט RangingResult. מבצעים את הפעולות הבאות בכל בקשה.

1. זיהוי הבקשה

זיהוי הבקשה על סמך המידע שסופק בזמן יצירת RangingRequest: לרוב כתובת MAC שסופקה ב-ScanResult שמזהה נקודת גישה. ניתן לקבל את כתובת ה-MAC מתוצאת הטווח באמצעות method getMacAddress().

רשימת התוצאות בטווח עשויה להיות בסדר שונה מזה של האפליקציות להשוואה (נקודות הגישה) שצוינו בבקשת הטווח, לכן צריך להשתמש בכתובת ה-MAC כדי לזהות את הרשת השכנה, ולא בסדר התוצאות.

2. בודקים אם כל מדידה הצליחה

כדי לבדוק אם המדידה בוצעה בהצלחה, משתמשים בשיטה getStatus(). כל ערך שאינו STATUS_SUCCESS מציין כשל. כשל פירושו שכל שדות התוצאה הזו (למעט מזהה הבקשה שלמעלה) לא חוקיים, וששיטה get* המתאימה תיכשל עם חריג IllegalStateException.

3. הצגת תוצאות לכל מדידה מוצלחת

לכל מדידה מוצלחת (RangingResult), אפשר לאחזר את ערכי התוצאה באמצעות השיטות המתאימות של get:

• מרחק, במ"מ וסטיית תקן של המדידה:

  getDistanceMm()

  getDistanceStdDevMm()

• ערך ה-RSSI של החבילות ששימשו למדידות:

  getRssi()

• הזמן באלפיות השנייה שבו בוצעה המדידה (מציין את הזמן מאז ההפעלה):

  getRangingTimestampMillis()

• מספר המדידות שניסו לבצע ומספר המדידות שהצליחו (ועליהם מבוססות מדידות המרחק):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• משך הזמן המינימלי והמקסימלי שצריך להמתין במכשיר הלקוח בין מדידות של NTB ב-11az:

  getMinTimeBetweenNtbMeasurementsMicros() ו-getMaxTimeBetweenNtbMeasurementsMicros() מחזירים את ערכי הזמן המינימלי והמקסימלי. אם הבקשה למדידת הטווח הבאה מתבצעת לפני שחלף הזמן המינימלי, ה-API מחזיר את תוצאת הטווח שנשמרה במטמון. אם מדידת הטווח הבאה מופיעה אחרי שחלף הזמן המקסימלי, ה-API מסיים את סשן הטווח ללא הטריגר ומנהל משא ומתן על סשן טווח חדש עם התחנה המגיבת. לא מומלץ לבקש סשן חדש בטווח, כי הפעולה הזו מוסיפה תקורה לזמן המדידה בטווח. כדי לנצל את מלוא היתרונות של יעילות הטווח של 802.11az ללא טריגר, צריך להפעיל את בקשת הטווח הבאה בין זמן המדידה המינימלי למקסימלי שצוין במדידה הקודמת של RangingResult.

• חזרות בשדה אימון ארוך (LTF) שתחנות תגובה ותחנות יוזם משמשות בקידומת של תוצאת IEEE 802.11az NTB:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• מספר השידורים והקבלים של שידורי זמן מרחביים (STS) שתחנת ההפעלה השתמשה בהם בתוצאת IEEE 802.11az NTB:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

מכשירי Android שתומכים ב-WiFi-RTT

בטבלאות הבאות מפורטים חלק מהטלפונים, נקודות הגישה והמכשירים לקמעונאות, למחסנים ולמרכזי הפצה שתומכים ב-WiFi-RTT. הנתונים האלה רחוקים מלהיות מקיפים. אנחנו ממליצים לפנות אלינו כדי לרשום כאן את המוצרים שלכם שתומכים ב-RTT.

נקודות גישה

טלפונים

מכשירים לקמעונאות, למחסנים ולמרכזי הפצה