النطاق بين الأجهزة

يقدّم Android 16 (المستوى 36 من واجهة برمجة التطبيقات) وحدة "تحديد النطاق"، التي توفّر واجهة موحّدة ومعيارية لتحديد النطاق بدقة بين الأجهزة. يمكنك استخدام واجهة برمجة التطبيقات هذه لقياس المسافة بين الأجهزة المجاورة وموضعها بدون الحاجة إلى التعامل مع كل تكنولوجيا قياس على حدة.

تتيح وحدة "تحديد النطاق" استخدام التكنولوجيات التالية:

إمكانات تحديد النطاق ومدى التوفّر

توفّر فئة RangingManager للتطبيقات معلومات حول تكنولوجيات قياس المسافة التي يتيحها الجهاز المحلي، بالإضافة إلى مدى توفّر كل تكنولوجيا وإمكاناتها. يمكن للتطبيقات تسجيل واجهة RangingCapabilitiesCallback لتلقّي تحديثات بشأن أي تغييرات في مدى توفّر أي تكنولوجيات متوافقة أو إمكاناتها.

أدوار الأجهزة

يجب أن يكون الجهاز المشارك في جلسة قياس المسافة جهازًا بادئًا أو مستجيبًا أو علامة Downlink-TDoA (DT-Tag) لجلسات UWB Downlink-TDoA على Android 17 (مستوى واجهة برمجة التطبيقات 37) والإصدارات الأحدث. يبدأ الجهاز المُرسِل جلسة قياس المسافة مع جهاز مُستجيب واحد أو أكثر. يستجيب جهاز المستجيب لطلبات تحديد النطاق من جهاز بادئ واحد فقط في كل مرة. في جلسة "فرق وقت الوصول في الرابط الهابط" (DL-TDoA) للنطاق الفائق العرض (UWB)، يستخدم الجهاز دور DEVICE_ROLE_DT_TAG لتلقّي الإشارات من عدة نقاط ربط للنطاق الفائق العرض (UWB). يمكنك تحديد دور جهاز معيّن في جلسة تحديد النطاق باستخدام الفئة RangingPreference.

أنواع جلسات تحديد النطاق

عند بدء جلسة قياس المسافة بين الأجهزة، غالبًا ما يكون من الضروري إنشاء عملية نقل بيانات خارج النطاق (OOB) لتبادل المَعلمات للجلسة.

يمكن لوحدة "تحديد النطاق" معالجة مفاوضات OOB نيابةً عنك، ولكنها تتيح أيضًا عمليات تنفيذ OOB المخصّصة.

الشكل 1: مسار OOB لأنواع الجلسات

التنفيذ التلقائي لعملية الإعداد الأولية

In this session type (RANGING_SESSION_OOB), the Ranging module handles OOB negotiations to start a ranging session. ويختار المَعلمات المناسبة استنادًا إلى الإعدادات المفضّلة لتقدير المسافة التي يوفّرها التطبيق، ويستخدم التقنيات المناسبة استنادًا إلى ما يتوافق مع كلا الجهازين. يستخدم نوع الجلسة هذا مواصفات OOB موحّدة. في الإصدار Android 16 QPR2 (المستوى 36.1 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن للأجهزة البادئة تقييد التقنيات التي يتم التفاوض عليها من خلال استدعاء setRangingTechnologyFilter على OobInitiatorRangingConfig.Builder.

تحدّد وحدة "تحديد النطاق" فقط تنسيق بيانات OOB وتسلسلها لاستخدامها في التفاعل مع جهاز آخر. ولا يتعامل مع عملية اكتشاف الأجهزة المشابهة أو إنشاء الاتصال.

تنفيذ مخصّص لتدفق OOB

في هذا النوع من الجلسات (RANGING_SESSION_RAW)، يتجاوز التطبيق مسار OOB الخاص بوحدة "تقدير المسافة" ويتعامل مع عملية التفاوض والمعلَمات الخاصة به. وهذا يعني أنّ التطبيق يجب أن يحدّد التقنيات التي يتوافق معها الجهاز النظير، وأن يتفاوض بشأن مَعلمات قياس المسافة، وأن يبدأ جلسة قياس المسافة.

الإعدادات المفضّلة لقياس المسافة

استخدِم عنصر RangingPreference لتحديد المَعلمات المحدّدة لجلسة تحديد النطاق. ويتضمن ذلك ما يلي:

  • دور الجهاز: يشير ذلك إلى ما إذا كان الجهاز هو البادئ أو المستجيب أو علامة DT-Tag على الإصدار 17 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 37) والإصدارات الأحدث.
  • إعدادات قياس المسافة: يحدّد عنصر RangingConfig نوع جلسة قياس المسافة والمعلَمات الأخرى اللازمة لبدء جلسة قياس المسافة.
  • إعدادات الجلسة: يحدّد عنصر SessionConfig المَعلمات التي سيتم فرضها على جلسة قياس النطاق، مثل حدّ القياس ودمج أداة الاستشعار وإعدادات الحدود الجغرافية والمزيد. على الإصدار Android 17 (مستوى واجهة برمجة التطبيقات 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" />

القيود والأحكام

قد تفرض وحدة &quot;تحديد النطاق&quot; قيودًا على تحديد النطاق لعدة أسباب، من بينها ما يلي:

  • يُسمح للتطبيقات الخارجية فقط بإجراء عمليات تحديد النطاق في الخلفية باستخدام النطاق الفائق العرض، وعلى الأجهزة المتوافقة فقط. ولا يُسمح بتحديد النطاق في الخلفية باستخدام تقنيات أخرى.
  • لا يُسمح بتحديد النطاق عند بلوغ الحد الأقصى لعدد جلسات تحديد النطاق المتزامنة حسب الجهاز.
  • قد يتم فرض قيود على تحديد النطاق بسبب مخاوف متعلقة بحالة النظام، مثل البطارية أو الأداء أو الذاكرة.

تتضمّن وحدة "تحديد النطاق" أيضًا القيود المعروفة التالية:

  • لا تتيح وحدة "تحديد النطاق" سوى إرسال بيانات تحديد النطاق إلى الأجهزة المشابهة باستخدام النطاق الفائق العرض. بالنسبة إلى التكنولوجيات الأخرى، لا توفّر وحدة &quot;تحديد النطاق&quot; بيانات تحديد النطاق إلا للجهاز المُبادر.
  • لا تتيح وحدة "قياس المسافة" سوى الإضافة الديناميكية للأجهزة في وضع قياس المسافة الأوّلي، وفقط للنطاق الفائق العرض.
  • لا تتيح وحدة "تحديد النطاق" جلسات النطاق الفائق العرض من جهاز واحد إلى أجهزة متعددة في عمليات التنفيذ التلقائية خارج النطاق. إذا مرّرت عدة معرّفات للأجهزة، تنشئ الوحدة جلسة فردية لكل جهاز نظير متوافق مع النطاق الفائق العرض.

إجراء جلسة تحديد النطاق

لإجراء جلسة قياس نطاق باستخدام وحدة قياس النطاق، اتّبِع الخطوات التالية:

  1. تأكَّد من أنّ جميع الأجهزة تعمل بنظام التشغيل Android 16 (مستوى واجهة برمجة التطبيقات 36) والإصدارات الأحدث.
  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 (مستوى واجهة برمجة التطبيقات 36.1) والإصدارات الأحدث، يمكنك استدعاء hasDistanceStandardDeviation وgetDistanceStandardDeviationMeters على RangingData لفحص الانحراف المعياري لقياسات المسافة عند توفّرها.
  • ميزات إضافية خاصة بالتكنولوجيا: في الإصدار 17 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 37) والإصدارات الأحدث، يمكنك استدعاء getRangingDataExtras في RangingData لاسترداد كائن RangingDataExtras يحتوي على بيانات وصفية خاصة بالتكنولوجيا، مثل BleSpecificData أو UwbSpecificData أو WifiRttSpecificData.
  • حالة حركة الجهاز الآخر: في الإصدار 17 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 37) والإصدارات الأحدث، يمكنك إلغاء onMotionReceived في RangingSession.Callback لتلقّي تحديثات MotionState (MOTION_NOT_DETECTED أو MOTION_SLIGHT أو MOTION_MODERATE أو MOTION_LARGE) عند تغيُّر حركة جهاز آخر.

إمكانية التشغيل التفاعلي لتقنية النطاق الفائق العرض (UWB) مع أجهزة iOS

تتيح وحدة "تقدير المسافة" إمكانية التشغيل التفاعلي مع أجهزة iOS التي تستخدم النطاق الفائق العرض (UWB). لتحديد النطاق باستخدام جهاز iOS، يجب استخدام تنفيذ مخصّص لبروتوكول OOB وضبط جلسة تحديد النطاق باستخدام مَعلمات محدّدة تتطابق مع بروتوكول Apple Nearby Interaction Accessory. للاطّلاع على مثال، يمكنك مراجعة نموذج التطبيق.

عند إنشاء RangingPreference، استخدِم RawRangingDevice وUwbRangingParams لتحديد الإعدادات. المَعلمات التالية ضرورية لإمكانية التشغيل التفاعلي على iOS:

  • رقم تعريف الإعدادات: استخدِم UwbRangingParams.CONFIG_UNICAST_DS_TWR.
  • معلومات مفتاح الجلسة: يجب تقديم مصفوفة بايت تحتوي على معرّف المورّد وناقل الحركة الثابت لخدمة STS.
  • القنوات المعقّدة: اضبط رقم القناة وفهرس المقدمة لمطابقة إعدادات جهاز 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 (مستوى واجهة برمجة التطبيقات 37) والإصدارات الأحدث، يتيح قياس المسافة باستخدام تقنية "فرق وقت الوصول في الرابط الهابط" (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) {
        // ...
    }
}

عمليات الضبط خارج النطاق (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)
)

إذا لم تتمكّن من استخدام إعدادات جاهزة للاستخدام بسبب عدم توفّرها، أو إذا كنت بحاجة إلى تغيير القيم التلقائية غير المتوفّرة في الإعدادات الجاهزة للاستخدام، يمكنك إنشاء المَعلمات باستخدام 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()

نموذج تطبيق

للاطّلاع على مثال شامل حول كيفية استخدام وحدة "تقدير المسافة"، يمكنك مراجعة نموذج التطبيق في مشروع Android المفتوح المصدر (AOSP). يغطي نموذج التطبيق هذا جميع تقنيات قياس المسافة التي تتيحها وحدة قياس المسافة، ويتضمّن مسارات لكلا نوعَي الجلسات المتوافقة.

إمكانية التشغيل التفاعلي لتقنية النطاق الفائق العرض (UWB) مع أجهزة iOS

يتيح نموذج تطبيق Android بدء جلسة قياس المسافة باستخدام النطاق الفائق العرض (UWB) مع نموذج تطبيق iOS.

الشكل 2. استخدام تقنية النطاق الفائق العرض (UWB) على أجهزة Android وiOS