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

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

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

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

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

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

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

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

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

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

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

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

הדרישות

• החומרה של המכשיר שמבצע את בקשת הטווח חייבת להטמיע את תקן 802.11-2016 FTM או תקן 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 (טווח שמבוסס על טריגר שאינו מבוסס על טריגרים).

הגדרה

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

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. בדיקה אם המכשיר תומך ב-RTT ב-Wi-Fi

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

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

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

יכול להיות שיש במכשיר RTT Wi-Fi, אבל הוא לא יהיה זמין כי המשתמש השבית את ה-Wi-Fi. בהתאם ליכולות החומרה והקושחה שלהם, חלק ייתכן שבמכשירים אין תמיכה ב-RTT ב-Wi-Fi אם נעשה שימוש ב-SoftAP או בשיתוף אינטרנט בין מכשירים. כדי לבדוק אם התכונה 'Wi-Fi RTT' זמינה, התקשרות 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 במסגרת בקשה בטווח יחיד; המערכת מודדת ומחזירה את המרחקים בין כל המכשירים.

לדוגמה, בקשה יכולה להשתמש 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 מבצעים או 802.11mc 802.11az בהתאם ליכולת של ה-AP, וברירת המחדל היא 802.11az כאשר סוכנות AP תומכת בשתיהן. מכשירים שאינם תומכים ב-IEEE 802.11az מבצעים את כל הפעולות באמצעות פרוטוקול IEEE 802.11mc.

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

טווח בקשות

אפליקציה מנפיקה בקשה טווח באמצעות 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:

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

פרשו תוצאות בטווח

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

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

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

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

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

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

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

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

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

  getDistanceMm()

  getDistanceStdDevMm()

• RSSI של המנות המשמשות למדידות:

  getRssi()

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

  getRangingTimestampMillis()

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

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

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

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

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

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

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

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

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

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

נקודות גישה

טלפונים

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