ב-Android 16 (רמת API 36) נוסף מודול הטווח, שמספק ממשק אחיד וסטנדרטי למדידת טווח מדויקת בין מכשירים. אתם יכולים להשתמש בממשק ה-API הזה כדי למדוד את המרחק והמיקום של מכשירים דומים, בלי שתצטרכו לטפל בכל טכנולוגיית מדידה בנפרד.
מודול הטווח תומך בטכנולוגיות הבאות:
- Ultra Wideband (UWB)
- מדידת ערוץ Bluetooth
- Wi-Fi NAN RTT
- טווח RSSI של Bluetooth
- זיהוי קרבה באמצעות Wi-Fi ב-Android 17 (רמת API 37) ומעלה
יכולות מדידת טווח וזמינות
הכיתה RangingManager מספקת לאפליקציות מידע על טכנולוגיות הטווח שנתמכות במכשיר המקומי, וגם על הזמינות והיכולות של כל טכנולוגיה. אפליקציות יכולות לרשום ממשק RangingCapabilitiesCallback כדי לקבל עדכונים על כל שינוי בזמינות או ביכולות של כל אחת מהטכנולוגיות הנתמכות.
תפקידי המכשירים
מכשיר שמשתתף בסשן מדידת טווח חייב להיות יוזם, משיב או תג Downlink-TDoA (DT-Tag) לסשנים של UWB Downlink-TDoA ב-Android 17 (רמת API 37) ומעלה. המכשיר היוזם מתחיל את סשן מדידת המרחק עם מכשיר מגיב אחד או יותר. מכשיר משיב מגיב לבקשות למדידת טווח רק מיוזם אחד בכל פעם. בסשן של הפרש זמני הגעה בקישור היורד (DL-TDoA) ב-UWB, המכשיר משתמש בתפקיד DEVICE_ROLE_DT_TAG כדי לקבל אותות מכמה עוגני UWB.
אתם יכולים לציין את התפקיד של מכשיר נתון בסשן מדידת טווח באמצעות המחלקה RangingPreference.
סוגי סשנים של מדידת טווח
כשמתחילים סשן של מדידת מרחק בין מכשירים, בדרך כלל צריך להגדיר העברת נתונים מחוץ לתחום (OOB) כדי להחליף פרמטרים לסשן.
מודול הטווח יכול לטפל במשא ומתן של OOB בשבילכם, אבל הוא גם תומך בהטמעות OOB בהתאמה אישית.
הטמעת ברירת מחדל של OOB
בסוג הסשן הזה (RANGING_SESSION_OOB), מודול הטווח מטפל במשא ומתן מחוץ לתחום כדי להתחיל סשן טווח. הוא בוחר פרמטרים מתאימים על סמך העדפות הטווח שסופקו על ידי האפליקציה, ומשתמש בטכנולוגיות המתאימות על סמך מה ששני המכשירים תומכים בו. סוג הסשן הזה משתמש במפרט OOB סטנדרטי. ב-Android 16 QPR2 (רמת API 36.1) ומעלה, היוזמים יכולים להגביל את הטכנולוגיות שמתנהל לגביהן משא ומתן על ידי קריאה ל-setRangingTechnologyFilter ב-OobInitiatorRangingConfig.Builder.
מודול הטווח מגדיר רק את פורמט הנתונים של OOB ואת הרצף שבו צריך להשתמש כדי לקיים אינטראקציה עם מכשיר מקביל. הוא לא מטפל בגילוי מכשירים או ביצירת חיבור.
הטמעה של OOB בהתאמה אישית
בסוג הסשן הזה (RANGING_SESSION_RAW), האפליקציה עוקפת את תהליך ה-OOB של מודול הטווח ומטפלת במשא ומתן ובפרמטרים של ה-OOB שלה. כלומר, האפליקציה צריכה לקבוע באילו טכנולוגיות המכשיר השני תומך, לנהל משא ומתן על הפרמטרים של מדידת המרחק ולהתחיל את סשן מדידת המרחק.
העדפות טווח
משתמשים באובייקט RangingPreference כדי לציין את הפרמטרים שנבחרו לסשן מדידת טווח. המצב הזה כולל את האפשרויות הבאות:
- תפקיד המכשיר. השדה הזה מציין אם המכשיר הוא היוזם, המגיב או תג DT ב-Android מגרסה 17 (רמת API 37) ואילך.
- הגדרת טווח. אובייקט
RangingConfigמציין את סוג הסשן של מדידת המרחק ופרמטרים אחרים שנדרשים כדי להתחיל סשן של מדידת מרחק. - הגדרת הסשן. אובייקט
SessionConfigמציין פרמטרים שצריך לאכוף בסשן מדידת הטווח, כמו מגבלת מדידה, שילוב חיישנים, הגדרת גבולות וירטואליים ועוד. ב-Android 17 (רמת API 37) ומעלה, אפשר גם להגדיר את מצב האנטנה (ANTENNA_MODE_DIRECTIONALאוANTENNA_MODE_OMNI) באמצעותsetAntennaModeב-SessionConfig.Builderאחרי שבודקים את המצבים הנתמכים באמצעותgetSupportedAntennaModesב-UwbRangingCapabilities.
הרשאת טווח
מודול הטווח משתמש בהרשאה מאוחדת (android.permission.RANGING) לטכנולוגיות טווח בין עמיתים. ההרשאה הזו נמצאת ברשימה NEARBY_DEVICES_PERMISSIONS.
<uses-permission android:name="android.permission.RANGING" />
הגבלות ומגבלות
יכולות להיות כמה סיבות לכך שמודול הטווח יגביל את הטווח, כולל:
- אפליקציות של צד שלישי יכולות לבצע מדידת טווח ברקע רק באמצעות Ultra Wideband (UWB), ורק במכשירים נתמכים. אסור לבצע מדידת טווח ברקע באמצעות טכנולוגיות אחרות.
- אי אפשר להשתמש ב-Ranging אם הגעתם למספר המקסימלי של סשנים בו-זמניים של Ranging במכשיר.
- יכול להיות שהמדידה תוגבל בגלל בעיות בתקינות המערכת, כמו סוללה, ביצועים או זיכרון.
למודול Ranging יש גם את המגבלות הידועות הבאות:
- מודול הטווח תומך רק בהעברת נתוני טווח למכשירי קצה ב-UWB. בטכנולוגיות אחרות, מודול הטווח מספק נתוני טווח רק למכשיר היוזם.
- מודול הטווח תומך רק בהוספה דינמית של מכשירים במצב טווח גולמי, ורק ב-UWB.
- מודול הטווח לא תומך בסשנים של Ultra Wideband (UWB) מסוג אחד לרבים בהטמעות OOB שמוגדרות כברירת מחדל. אם מעבירים כמה נקודות אחיזה של מכשירים, המודול יוצר סשן אחד לאחד לכל מכשיר מקביל שתומך ב-UWB.
ביצוע סשן מדידת טווח
כדי לבצע סשן מדידת טווח באמצעות המודול Ranging, פועלים לפי השלבים הבאים:
- מוודאים שבכל המכשירים מותקנת גרסת Android 16 (רמת API 36) ומעלה.
- מבקשים את ההרשאה
android.permission.RANGINGבקובץ המניפסט של האפליקציה. - הערכת היכולות והזמינות של טכנולוגיות למדידת טווח.
- לגלות מכשיר מקביל לפעולות מדידת טווח.
- יוצרים חיבור להחלפת נתונים מחוץ לתחום (out-of-band) באמצעות אחד מסוגי הסשנים שמתוארים בקטע סוגי סשנים של מדידת מרחק.
- להתחיל מדידת טווח ולקבל נתוני מדידת טווח באופן רציף.
- סיום סשן המדידה.
דוגמת הקוד הבאה ממחישה את השלבים האלה גם לתפקיד היוזם וגם לתפקיד המשיב.
class RangingApp { // Starts a ranging session on the initiator side. fun startRangingInitiator( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // Get the RangingManager which is the entry point for ranging module. val manager = context.getSystemService(RangingManager::class.java) // Create a new RangingSession using the provided executor and callback. val session = manager.createRangingSession(executor, callback) ?: return null // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for // the initiator role. val config = OobInitiatorRangingConfig.Builder() .setFastestRangingInterval(Duration.ofMillis(100)) .setSlowestRangingInterval(Duration.ofMillis(5000)) .setRangingMode(RANGING_MODE_AUTO) .setSecurityLevel(SECURITY_LEVEL_BASIC) .addDeviceHandle(deviceHandle) .build() // Create a RangingPreference, which specifies the role (initiator) and // configuration for the ranging session. val preference = RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build() // Start ranging session. Ranging data is delivered asynchronously through // callback.onResults; call stopRanging(session) when ranging is no longer needed. session.start(preference) return session } // Starts a ranging session on the responder side. fun startRangingResponder( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // Get the RangingManager which is the entry point for ranging module. val manager = context.getSystemService(RangingManager::class.java) // Create a new RangingSession using the provided executor and callback. val session = manager.createRangingSession(executor, callback) ?: return null // Create an OobResponderRangingConfig, which specifies the ranging parameters for // the responder role. val config = OobResponderRangingConfig.Builder(deviceHandle).build() // Create a RangingPreference, which specifies the role (responder) and // configuration for the ranging session. val preference = RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build() // Start the ranging session. Call stopRanging(session) when finished. session.start(preference) return session } // Stops an active ranging session. fun stopRanging(session: RangingSession) { session.stop() } }
טיפול בתוצאות של מדידת טווח ובתנועה של מכשירים אחרים
כשהסשן פעיל, RangingSession.Callback מספק מדידות של מרחק וזווית הגעה באובייקטים של RangingData דרך onResults:
- חוסר ודאות לגבי המרחק. ב-Android 16 QPR2 (רמת API 36.1) ואילך, צריך להפעיל את
hasDistanceStandardDeviationואתgetDistanceStandardDeviationMetersב-RangingDataכדי לבדוק את סטיית התקן של מדידות המרחק, אם היא זמינה. - תוספות ספציפיות לטכנולוגיה. ב-Android 17 (רמת API 37) ומעלה, צריך להפעיל את
getRangingDataExtrasב-RangingDataכדי לאחזר אובייקטRangingDataExtrasשמכיל מטא-נתונים ספציפיים לטכנולוגיה, כמוBleSpecificData,UwbSpecificDataאוWifiRttSpecificData. - מצב התנועה של המשתתף. ב-Android 17 (רמת API 37) ואילך, צריך לשנות את
onMotionReceivedב-RangingSession.Callbackכדי לקבל עדכונים שלMotionState(MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATEאוMOTION_LARGE) כשהתנועה של מכשיר מקביל משתנה.
יכולת פעולה הדדית של UWB עם מכשירי iOS
מודול הטווח תומך ביכולת פעולה הדדית עם מכשירי iOS באמצעות פס רחב במיוחד (UWB). כדי למדוד טווח עם מכשיר iOS, צריך להשתמש בהטמעה מותאמת אישית של OOB ולהגדיר את סשן מדידת הטווח עם פרמטרים ספציפיים שתואמים ל-Apple Nearby Interaction Accessory Protocol. לדוגמה, ראו את האפליקציה לדוגמה.
כשיוצרים את RangingPreference, משתמשים ב-RawRangingDevice וב-UwbRangingParams כדי לציין את ההגדרה. הפרמטרים הבאים חיוניים ליכולת הפעולה ההדדית ב-iOS:
- מזהה התצורה. שימוש ב-
UwbRangingParams.CONFIG_UNICAST_DS_TWR. - Session Key Info. צריך לספק מערך בייטים שמכיל את מזהה הספק ואת ה-Static STS IV.
- ערוץ מורכב. מגדירים את מספר הערוץ ואת אינדקס ההוראות המקדימות כך שיתאימו להגדרות של מכשיר ה-iOS.
בקטע הקוד הבא אפשר לראות איך יוצרים RangingPreference למכשיר יוזם שמודד את המרחק ממכשיר מגיב עם iOS:
// Create UwbRangingParams with iOS-specific configuration. val uwbRangingParams = UwbRangingParams.Builder( sessionId, UwbRangingParams.CONFIG_UNICAST_DS_TWR, sourceAddress, destinationAddress ) .setComplexChannel( UwbComplexChannel.Builder() .setChannel(channelNumber) .setPreambleIndex(preambleIndex) .build() ) .setRangingUpdateRate(updateRate) .setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV .setSlotDuration(slotDuration) .build() // Create RawRangingDevice. val rawRangingDevice = RawRangingDevice.Builder() .setRangingDevice(RangingDevice.Builder().build()) .setUwbRangingParams(uwbRangingParams) .build() // Create SessionConfig. val sessionConfig = SessionConfig.Builder() .setAngleOfArrivalNeeded(true) .setDataNotificationConfig( DataNotificationConfig.Builder() .setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE) .build() ) .build() // Create RangingPreference for the initiator. val preference = RangingPreference.Builder( RangingPreference.DEVICE_ROLE_INITIATOR, RawInitiatorRangingConfig.Builder() .addRawRangingDevice(rawRangingDevice) .build() ) .setSessionConfig(sessionConfig) .build()
UWB Downlink-TDoA API
ב-Android מגרסה 17 (רמת API 37) ומעלה, טווח Downlink Time Difference of Arrival (DL-TDoA) מאפשר למכשיר לקבוע את המיקום שלו ביחס לכמה עוגני UWB על ידי מדידת זמני ההגעה היחסיים של האותות.
בקטע הקוד הבא אפשר לראות איך משתמשים ב-RangingManager כדי לאמת את התמיכה ב-DL-TDoA, להגדיר את DlTdoaRangingParams ואת RawDtTagRangingConfig כדי להתחיל סשן ולקבל תוצאות של DlTdoaMeasurement:
class RangingApp { fun initDlTdoa(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Register for device capabilities. val capabilitiesCallback = object : RangingManager.RangingCapabilitiesCallback { override fun onRangingCapabilities(capabilities: RangingCapabilities) { // Make sure DL-TDoA is supported before starting the session. if (capabilities.uwbCapabilities?.isDlTdoaSupported == true) { startDlTDoASession(context) } } } rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback) } fun startDlTDoASession(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Create session and configure parameters. val executor = Executors.newSingleThreadExecutor() val rangingSession = rangingManager.createRangingSession(executor, RangingSessionCallback()) val rangingRoundIndexes = byteArrayOf(0) val config: ByteArray = byteArrayOf() // OOB config data val params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes) val rangingDevice = RangingDevice.Builder().build() val rawTagDevice = RawRangingDevice.Builder() .setRangingDevice(rangingDevice) .setDlTdoaRangingParams(params) .build() val dtTagConfig = RawDtTagRangingConfig.Builder(rawTagDevice).build() val preference = RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig) .setSessionConfig(SessionConfig.Builder().build()) .build() // Start the ranging session. rangingSession?.start(preference) } } private class RangingSessionCallback : RangingSession.Callback { override fun onDlTdoaResults(peer: RangingDevice, measurement: DlTdoaMeasurement) { // Process measurement results here. } override fun onOpened() { // ... } override fun onOpenFailed(reason: Int) { // ... } override fun onStarted(peer: RangingDevice, technology: Int) { // ... } override fun onStopped(peer: RangingDevice, technology: Int) { // ... } override fun onResults(peer: RangingDevice, data: RangingData) { // ... } override fun onClosed(reason: Int) { // ... } }
הגדרות של Out-of-band (OOB)
קטע הקוד הבא הוא דוגמה לנתוני הגדרת OOB של DL-TDoA ל-Wi-Fi ול-BLE:
// Wi-Fi Configuration (Vendor-Specific IE, FiRa CID 0x5A18FF, Config 0) val wifiConfig = byteArrayOf( 0xDD.toByte(), 0x30, 0x5A, 0x18, 0xFF.toByte(), // Wi-Fi VSE Header 0x5F, 0x1C, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x14, 0x01, 0x0A, // Preamble Code Index (10) 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x08, 0x02, 0x60, 0x09, // Slot Duration (2400 RSTU = 2 ms) 0x1B, 0x01, 0x0A, // Slots per Ranging Round (10) 0x09, 0x04, 0xFA.toByte(), 0x00, 0x00, 0x00, // Ranging Duration (250 ms) 0x52, 0x01, 0x00, // Initiator DT-Anchor Round Index (0) 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) ) // BLE Configuration (ADV_NONCONN_IND Service Data UUID 0xFFF3, Config 0) val bleConfig = byteArrayOf( 0x1E, 0x16, 0xF3.toByte(), 0xFF.toByte(), // BLE Service Data Header 0xF0.toByte(), // Fragment Indication Sub-Element (unfragmented) 0x5F, 0x09, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) )
אם אתם לא יכולים להשתמש בהגדרת OOB כי היא חסרה, או אם אתם צריכים לשנות ערכי ברירת מחדל שלא נמצאים בהגדרת OOB, אתם יכולים ליצור פרמטרים באמצעות DlTdoaRangingParams.Builder במקום להפעיל את DlTdoaRangingParams.createFromFiraConfigPacket:
val dlTdoaParams = DlTdoaRangingParams.Builder(1) .setComplexChannel( UwbComplexChannel.Builder() .setChannel(9).setPreambleIndex(10).build() ) .setDeviceAddress(deviceAddress) .setSessionKeyInfo(byteArrayOf(0x01, 0x02, 0x03, 0x04)) .setRangingIntervalMillis(240) .setSlotDuration(UwbRangingParams.DURATION_2_MS) .setSlotsPerRangingRound(20) .setRangingRoundIndexes(byteArrayOf(0x01, 0x05)) .build()
אפליקציה לדוגמה
באפליקציה לדוגמה ב-AOSP יש דוגמה מלאה לשימוש במודול Ranging. האפליקציה לדוגמה הזו כוללת את כל טכנולוגיות הטווח שנתמכות במודול Ranging, וכוללת תהליכים לשני סוגי הסשנים הנתמכים.
יכולת פעולה הדדית של UWB עם מכשירי iOS
האפליקציה לדוגמה ל-Android תומכת בהתחלת סשן מדידת מרחק ב-UWB עם האפליקציה לדוגמה ל-iOS.