محدوده بین دستگاه‌ها

Android 16 (سطح API‏ ۳۶) ماژول «محدوده» را معرفی می‌کند که یک میانای یکپارچه و استانداردشده برای تعیین محدوده دقیق بین دستگاه‌ها ارائه می‌دهد. می‌توانید از این سطح میانای برنامه‌سازی کاربردی برای اندازه‌گیری فاصله و موقعیت دستگاه‌های همتا بدون نیاز به مدیریت جداگانه هر فناوری فاصله‌یابی استفاده کنید.

واحد «فاصله‌یابی» از فناوری‌های زیر پشتیبانی می‌کند:

قابلیت‌های فاصله‌یابی و دردسترس بودن

کلاس RangingManager اطلاعاتی درباره فناوری‌های فاصله‌یابی پشتیبانی‌شده توسط دستگاه محلی و همچنین دردسترس بودن و قابلیت‌های هر فناوری را به برنامه‌ها ارائه می‌دهد. برنامه‌ها می‌توانند میانای RangingCapabilitiesCallback را ثبت کنند تا به‌روزرسانی‌های مربوط به هرگونه تغییر در دردسترس بودن یا قابلیت‌های فناوری‌های پشتیبانی‌شده را دریافت کنند.

نقش‌های دستگاه

دستگاهی که در جلسه فاصله‌یابی شرکت می‌کند باید آغازگر، پاسخ‌دهنده، یا برچسب Downlink-TDoA (برچسب DT) برای جلسات UWB Downlink-TDoA در Android 17 (سطح ای‌پی‌آی ۳۷) و بالاتر باشد. دستگاه آغازگر جلسه فاصله‌یابی را با یک یا چند دستگاه پاسخ‌دهنده شروع می‌کند. دستگاه پاسخ‌دهنده در هر زمان فقط به درخواست‌های فاصله‌یابی یک آغازگر پاسخ می‌دهد. در جلسه «تفاوت زمان رسیدن فراپیوند پایین» (DL-TDoA) فراپهن‌باند، دستگاه از نقش DEVICE_ROLE_DT_TAG برای دریافت سیگنال از چند لنگر فراپهن‌باند استفاده می‌کند. می‌توانید نقش دستگاه موردنظر را در جلسه فاصله‌یابی با کلاس RangingPreference مشخص کنید.

انواع جلسه فاصله‌یابی

هنگام شروع جلسه فاصله‌یابی بین دستگاه‌ها، اغلب لازم است یک انتقال داده خارج از باند (OOB) برای تبادل پارامترهای جلسه برقرار شود.

ماژول «فاصله‌یابی» می‌تواند مذاکرات OOB را برای شما انجام دهد، اما از پیاده‌سازی‌های سفارشی OOB نیز پشتیبانی می‌کند.

شکل ۱. جریان OOB برای انواع جلسه.

پیاده‌سازی پیش‌فرض OOB

در این نوع جلسه (RANGING_SESSION_OOB)، واحد «فاصله‌یابی» مذاکرات OOB را برای شروع جلسه فاصله‌یابی مدیریت می‌کند. این API پارامترهای مناسب را براساس اولویت‌های فاصله‌یابی ارائه‌شده توسط برنامه انتخاب می‌کند و از فناوری‌های مناسب براساس آنچه هر دو دستگاه پشتیبانی می‌کنند استفاده می‌کند. این نوع جلسه از مشخصات OOB استانداردشده استفاده می‌کند. در Android 16 QPR2 (سطح میانای برنامه‌سازی کاربردی ۳۶.۱) و بالاتر، آغازگران می‌توانند با فراخوانی setRangingTechnologyFilter در OobInitiatorRangingConfig.Builder، فناوری‌هایی را که درباره آن‌ها مذاکره می‌شود محدود کنند.

ماژول «محدوده» فقط قالب و توالی داده‌های OOB را برای استفاده در تعامل با دستگاه همتا تعریف می‌کند. این API مدیریت شناسایی دستگاه همتا یا برقراری اتصال را انجام نمی‌دهد.

پیاده‌سازی OOB سفارشی

در این نوع جلسه (RANGING_SESSION_RAW)، برنامه جریان OOB واحد «فاصله‌یابی» را دور می‌زند و مذاکره و پارامترهای OOB خود را مدیریت می‌کند. یعنی برنامه باید تعیین کند که دستگاه همتا از کدام فناوری‌ها پشتیبانی می‌کند، پارامترهای فاصله‌یابی را مذاکره کند، و جلسه فاصله‌یابی را شروع کند.

اولویت‌های فاصله‌یابی

از شیء RangingPreference برای مشخص کردن پارامترهای انتخاب‌شده برای جلسه فاصله‌یابی استفاده کنید. این موارد عبارت‌اند از:

  • نقش دستگاه. این نشان می‌دهد که آیا دستگاه آغازگر، پاسخ‌دهنده، یا DT-Tag در Android 17 (سطح ای‌پی‌آی ۳۷) و بالاتر است یا نه.
  • پیکربندی فاصله‌یابی. شیء RangingConfig نوع جلسه فاصله‌یابی و پارامترهای دیگر موردنیاز برای شروع جلسه فاصله‌یابی را مشخص می‌کند.
  • پیکربندی جلسه. شیء SessionConfig پارامترهایی را مشخص می‌کند که باید در جلسه فاصله‌یابی اعمال شوند، مانند حد اندازه‌گیری، ادغام حسگر، پیکربندی حصار جغرافیایی، و غیره. در Android 17 (سطح ای‌پی‌آی ۳۷) و بالاتر، می‌توانید حالت آنتن (ANTENNA_MODE_DIRECTIONAL یا ANTENNA_MODE_OMNI) را نیز با setAntennaMode در SessionConfig.Builder پس‌از بررسی حالت‌های پشتیبانی‌شده با getSupportedAntennaModes در UwbRangingCapabilities پیکربندی کنید.

اجازه فاصله‌یابی

پیمانه «فاصله‌یابی» از اجازه‌ای یکپارچه (android.permission.RANGING) برای فناوری‌های فاصله‌یابی همتا به همتا استفاده می‌کند. این اجازه در فهرست NEARBY_DEVICES_PERMISSIONS قرار دارد.

<uses-permission android:name="android.permission.RANGING" />

محدودیت‌ها و موانع

مدول «محدوده» ممکن است به‌دلایل مختلفی ازجمله موارد زیر، محدوده را محدود کند:

  • برنامه‌های طرف سوم فقط مجازند با فراپهن‌باند و فقط در دستگاه‌های پشتیبانی‌شده، محدوده پس‌زمینه را اجرا کنند. محدوده در پس‌زمینه با فناوری‌های دیگر مجاز نیست.
  • وقتی حداکثر تعداد جلسه‌های هم‌زمان فاصله‌یابی در دستگاه رسیده باشد، فاصله‌یابی مجاز نیست.
  • ممکن است به‌دلیل نگرانی‌های مربوط به سلامت سیستم، مانند باتری، عملکرد، یا حافظه، فاصله‌یابی محدود شود.

واحد Ranging محدودیت‌های شناخته‌شده زیر را نیز دارد:

  • مدول «فاصله‌یابی» فقط از ارسال داده‌های فاصله‌یابی به دستگاه‌های همتا برای فراپهن‌باند پشتیبانی می‌کند. برای فناوری‌های دیگر، واحد «فاصله‌یابی» فقط داده‌های فاصله‌یابی را به دستگاه آغازگر ارائه می‌دهد.
  • واحد «فاصله‌یابی» فقط از افزودن پویای دستگاه‌ها در حالت فاصله‌یابی خام و فقط برای فراپهن‌باند پشتیبانی می‌کند.
  • ماژول «محدوده» از جلسه‌های باند فوق‌وسیع یک‌به‌چند برای پیاده‌سازی‌های پیش‌فرض OOB پشتیبانی نمی‌کند. اگر چند دسته دستگاه را ارسال کنید، این واحد برای هر دستگاه همتایی که از فراپهن‌باند پشتیبانی می‌کند یک جلسه یک‌به‌یک ایجاد می‌کند.

برگزاری جلسه فاصله‌یابی

برای انجام جلسه فاصله‌یابی بااستفاده از ماژول «فاصله‌یابی»، این مراحل را دنبال کنید:

  1. درستی‌سنجی کنید که همه دستگاه‌ها Android 16 (سطح میانای برنامه‌سازی کاربردی ۳۶) و بالاتر را اجرا می‌کنند.
  2. در مانیفست برنامه، اجازه android.permission.RANGING را درخواست کنید.
  3. ارزیابی قابلیت‌ها و دردسترس بودن فناوری‌های فاصله‌یابی.
  4. دستگاه همتایی را برای عملیات فاصله‌یابی پیدا کنید.
  5. بااستفاده از یکی از انواع جلسه شرح‌داده‌شده در انواع جلسه فاصله‌یابی، اتصالی برای تبادل خارج‌از باند برقرار کنید.
  6. فاصله‌یابی را شروع کند و به‌طور مداوم داده‌های فاصله‌یابی را دریافت کند.
  7. جلسه فاصله‌یابی را خاتمه دهید.

نمونه کد زیر این مراحل را هم برای نقش آغازگر و هم برای نقش پاسخ‌دهنده نشان می‌دهد.

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‏ ۳۶.۱) و بالاتر، hasDistanceStandardDeviation و getDistanceStandardDeviationMeters را در RangingData فراخوانی کنید تا انحراف معیار اندازه‌گیری‌های فاصله را درصورت دردسترس بودن بررسی کنید.
  • موارد اضافی مختص فناوری. در Android 17 (سطح API‏ ۳۷) و بالاتر، getRangingDataExtras را در RangingData فراخوانی کنید تا شیء RangingDataExtras حاوی فراداده‌های خاص فناوری، مانند BleSpecificData، UwbSpecificData، یا WifiRttSpecificData را بازیابی کنید.
  • وضعیت حرکت همتا. در Android 17 (سطح API‏ ۳۷) و بالاتر، onMotionReceived را در RangingSession.Callback لغو کنید تا وقتی حرکت دستگاه همتا تغییر می‌کند، به‌روزرسانی‌های MotionState (MOTION_NOT_DETECTED، MOTION_SLIGHT، MOTION_MODERATE، یا MOTION_LARGE) را دریافت کنید.

تعامل‌پذیری فراپهن‌باند با دستگاه‌های iOS

ماژول «محدوده» از قابلیت همکاری با دستگاه‌های iOS بااستفاده از فراپهن‌باند (UWB) پشتیبانی می‌کند. برای فاصله‌یابی با دستگاه iOS، باید از پیاده‌سازی OOB سفارشی استفاده کنید و جلسه فاصله‌یابی را با پارامترهای خاصی پیکربندی کنید که با پروتکل لوازم جانبی تعامل با اطراف Apple مطابقت داشته باشد. برای مشاهده نمونه، به برنامه نمونه مراجعه کنید.

هنگام ایجاد RangingPreference، از RawRangingDevice و UwbRangingParams برای مشخص کردن پیکربندی استفاده کنید. پارامترهای زیر برای هم‌کنش‌پذیری iOS بسیار مهم هستند:

  • شناسه پیکربندی. از UwbRangingParams.CONFIG_UNICAST_DS_TWR استفاده کنید.
  • اطلاعات کلید جلسه. آرایه بایتی حاوی شناسه فروشنده و 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‏ ۳۷) و بالاتر، فاصله‌یابی «تفاوت زمان رسیدن در اتصال پایین‌سو» (DL-TDoA) به دستگاه امکان می‌دهد موقعیت خود را نسبت به چندین لنگر «فراپهن‌باند» با اندازه‌گیری زمان‌های نسبی رسیدن سیگنال‌ها تعیین کند.

قطعه زیر نحوه استفاده از 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) {
        // ...
    }
}

پیکربندی‌های خارج از باند (OOB)

قطعه زیر نمونه‌ای از داده‌های پیکربندی DL-TDoA OOB برای 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 مراجعه کنید. این برنامه نمونه همه فناوری‌های فاصله‌یابی را که توسط مدول «فاصله‌یابی» پشتیبانی می‌شود پوشش می‌دهد و شامل جریان‌هایی برای هر دو نوع جلسه پشتیبانی‌شده است.

تعامل‌پذیری فراپهن‌باند با دستگاه‌های iOS

برنامه نمونه Android از شروع جلسه فاصله‌یابی فراپهن‌باند با برنامه نمونه iOS پشتیبانی می‌کند.

شکل ۲. استفاده از فراپهن‌باند Android و iOS.