الاتصال الواسع النطاق (UWB)

ملاحظة: لا تتوفّر تقنية النطاق الفائق العرض (UWB) حاليًا إلا باستخدام Jetpack.

الاتصالات ذات النطاق الفائق العرض هي تقنية لاسلكية تركّز على تحديد المسافة بدقة بين الأجهزة (قياس الموقع الجغرافي بدقة تصل إلى 10 سم). يمكن أن تستخدم تكنولوجيا البث اللاسلكي هذه كثافة طاقة منخفضة لإجراء قياسات قصيرة المدى، وإرسال إشارات بمعدّل عالٍ لنقل البيانات على جزء كبير من الطيف اللاسلكي. يكون معدل نقل البيانات في النطاق الفائق العرض أكبر من 500 ميجاهرتز (أو يتجاوز ‎20% من معدل نقل البيانات الكسري).

جهاز التحكّم/المشغِّل في مقابل جهاز التحكّم فيه/المُجيب

يحدث الاتصال عبر النطاق الفائق العرض بين جهازَين، أحدهما جهاز تحكّم والآخر جهاز يتم التحكّم فيه. يحدِّد جهاز التحكّم القناة المعقدة (UwbComplexChannel) التي سيتشاركها الجهازان، وهو المشغِّل، في حين يكون جهاز التحكّم فيه هو المُجيب.

يمكن لعنصر التحكّم التعامل مع عناصر تحكّم متعددة، ولكن لا يمكن لعنصر التحكّم الاشتراك إلا في عنصر تحكّم واحد. تتوفّر كل من إعدادات جهاز التحكّم/المشغِّل وجهاز التحكّم فيه/المُجيب.

مَعلمات النطاق

يجب أن يتعرّف كلّ من جهاز التحكّم والجهاز الخاضع للتحكّم على بعضهما البعض وأن يتبادلا مَعلمات النطاق لبدء عملية النطاق. ويُترك هذا التبادل للتطبيقات لتنفيذه باستخدام آلية آمنة خارج النطاق (OOB) من اختيارها، مثل البلوتوث المنخفض الطاقة (BLE).

تشمل مَعلمات النطاق العنوان المحلي والقناة المعقدة ومفتاح الجلسة، من بين غيرها. يُرجى العلم أنّه قد يتم تدوير هذه المَعلمات أو تغييرها بأي شكل آخر بعد انتهاء جلسة تحديد النطاق ، ويجب إعادة إرسالها لإعادة بدء عملية تحديد النطاق.

قياس المسافة في الخلفية

يمكن للتطبيق الذي يعمل في الخلفية بدء جلسة قياس المسافة باستخدام النطاق الفائق العرض (UWB) إذا كان الجهاز يتوافق معها. للاطّلاع على إمكانات جهازك، يُرجى الاطّلاع على RangingCapabilities.

لا يتلقّى التطبيق تقارير النطاق عندما يكون قيد التشغيل في الخلفية، بل يتلقّى تقارير النطاق عندما ينتقل إلى المقدّمة.

إعدادات STS

يقدّم التطبيق أو الخدمة مفتاح جلسة لكل جلسة باستخدام تسلسل طابع زمني مشفَّر (STS). إنّ بروتوكول STS المُعدّ مسبقًا أكثر أمانًا من إعداد بروتوكول STS static. تتوفّر تقنية STS المُعدَّة مسبقًا على جميع الأجهزة المزوّدة بتقنية النطاق الفائق العرض (UWB) التي تعمل بالإصدار Android 14 أو إصدار أحدث.

فئة التهديد	STS الثابت	STS مُزوَّد بإمكانية الوصول
الهواء: مراقب سلبي	تم التخفيف من حدتها	تم التخفيف من حدتها
البثّ عبر الهواء: تضخيم الإشارة	تم التخفيف من حدتها	تم التخفيف من حدتها
الهواء: هجوم إعادة الإرسال/الإعادة	معرّض للإصابة	تم التخفيف من حدتها

بالنسبة إلى STS المزوَّد:

1. استخدِم uwbConfigType في RangingParameters الذي يتيح استخدام STS المُنشأ.

2. قدِّم المفتاح الذي يتكوّن من 16 بايت في الحقل sessionKeyInfo.

بالنسبة إلى STS الثابت:

1. استخدِم uwbConfigType في RangingParameters الذي يتيح بروتوكول STS الثابت.

2. قدِّم المفتاح المكوّن من 8 بايت في حقل sessionKeyInfo.

الخطوات

لاستخدام UWB API، اتّبِع الخطوات التالية:

1. تأكَّد من أنّ أجهزة Android تعمل بالإصدار 12 أو إصدار أحدث وأنّها تتوافق مع تقنية النطاق الفائق العرض (UWB) باستخدام PackageManager#hasSystemFeature("android.hardware.uwb").
2. في حال قياس المسافة مع أجهزة إنترنت الأشياء، تأكَّد من أنّها متوافقة مع معيار FiRa MAC 1.3.
3. يمكنك اكتشاف الأجهزة المشابهة المزوّدة بتقنية النطاق الفائق العرض باستخدام آلية الاتصال خارج نطاق الشبكة التي تختارها، مثل BluetoothLeScanner.
4. تبادل مَعلمات النطاق باستخدام آلية آمنة خارج نطاق الشبكة من اختيارك، مثل BluetoothGatt.
5. إذا أراد المستخدم إيقاف الجلسة، يجب إلغاء نطاق الجلسة.

قيود الاستخدام

تنطبق القيود التالية على استخدام UWB API:

1. يجب أن يكون التطبيق الذي يبدأ جلسات قياس النطاق الجديدة عبر النطاق الفائق العرض (UWB) هو تطبيق أو خدمة تعمل في المقدّمة ما لم تكن ميزة قياس النطاق في الخلفية متاحة كما هو موضّح سابقًا.
2. عند انتقال التطبيق إلى الخلفية (أثناء استمرار الجلسة)، قد يتوقف التطبيق عن تلقّي تقارير النطاق. ومع ذلك، سيظلّ يتم الاحتفاظ بجلسة النطاق الفائق العرض في الطبقات السفلية. عندما يعود التطبيق إلى المقدّمة، ستتم استعادة تقارير النطاق.

عيّنات الرموز البرمجية

نموذج تطبيق

للحصول على مثال شامل حول كيفية استخدام مكتبة UWB Jetpack، يمكنك الاطّلاع على نموذج التطبيق على Github. يتناول نموذج التطبيق هذا التحقّق من توافق النطاق الفائق العرض (UWB) على جهاز Android وتفعيل عملية الاكتشاف باستخدام آلية خارج نطاق الرؤية (OOB) وإعداد نطاق النطاق الفائق العرض بين جهازَين متوافقَين مع النطاق الفائق العرض. ويتناول العيّنة أيضًا حالات استخدام التحكّم في الجهاز ومشاركة الوسائط.

قياس المسافة باستخدام النطاق الفائق العرض (UWB)

يبدأ نموذج الرمز البرمجي هذا عملية قياس النطاق باستخدام النطاق الفائق العرض ويُنهيها لجهاز تحكّم:

// The coroutineScope responsible for handling uwb ranging.
// This will be initialized when startRanging is called.
var job: Job?

// A code snippet that initiates uwb ranging for a Controlee.
suspend fun startRanging() {

    // Get the ranging parameter of a partnering Controller using an OOB mechanism of choice.
    val partnerAddress : Pair<UwbAddress, UwbComplexChannel> = listenForPartnersAddress()

    // Create the ranging parameters.
    val partnerParameters = RangingParameters(
        uwbConfigType = UwbRangingParameters.UWB_CONFIG_ID_1,
        // SessionKeyInfo is used to encrypt the ranging session.
        sessionKeyInfo = null,
        complexChannel = partnerAddress.second,
        peerDevices = listOf(UwbDevice.createForAddress(partnerAddress.first)),
        updateRateType = UwbRangingParameters.RANGING_UPDATE_RATE_AUTOMATIC
    )

    // Initiate a session that will be valid for a single ranging session.
    val clientSession = uwbManager.clientSessionScope()

    // Share the localAddress of the current session to the partner device.
    broadcastMyParameters(clientSession.localAddress)

    val sessionFlow = clientSession.prepareSession(partnerParameters)

    // Start a coroutine scope that initiates ranging.
    CoroutineScope(Dispatchers.Main.immediate).launch {
        sessionFlow.collect {
            when(it) {
                is RangingResultPosition -> doSomethingWithPosition(it.position)
                is RangingResultPeerDisconnected -> peerDisconnected(it)
            }
        }
    }
}

// A code snippet that cancels uwb ranging.
fun cancelRanging() {

    // Canceling the CoroutineScope will stop the ranging.
    job?.let {
        it.cancel()
    }
}

إتاحة RxJava3

يتوفّر الآن دعم Rxjava3 للمساعدة في تحقيق التشغيل التفاعلي مع عملاء Java. توفّر هذه المكتبة طريقة للحصول على نتائج النطاقات كبث Observable أو Flowable، واسترداد UwbClientSessionScope كعنصر واحد.

private final UwbManager uwbManager;

// Retrieve uwbManager.clientSessionScope as a Single object
Single<UwbClientSessionScope> clientSessionScopeSingle =
                UwbManagerRx.clientSessionScopeSingle(uwbManager);
UwbClientSessionScope uwbClientSessionScope = clientSessionScopeSingle.blockingGet();

// Retrieve uwbClientSessionScope.prepareSession Flow as an Observable object
Observable<RangingResult> rangingResultObservable =
                UwbClientSessionScopeRx.rangingResultsObservable(clientSessionScope,
                        rangingParameters);

// Consume ranging results from Observable
rangingResultObservable.subscribe(
   rangingResult -> doSomethingWithRangingResult(result), // onNext
   (error) -> doSomethingWithError(error), // onError
   () -> doSomethingOnResultEventsCompleted(), //onCompleted
);
// Unsubscribe
rangingResultObservable.unsubscribe();
   

// Retrieve uwbClientSessionScope.prepareSession Flow as a Flowable object
Flowable<RangingResult> rangingResultFlowable =
                UwbClientSessionScopeRx.rangingResultsFlowable(clientSessionScope,
                        rangingParameters);

// Consume ranging results from Flowable using Disposable
Disposable disposable = rangingResultFlowable
   .delay(1, TimeUnit.SECONDS)
   .subscribeWith(new DisposableSubscriber<RangingResult> () {
      @Override public void onStart() {
          request(1);
      }
      
      @Override public void onNext(RangingResult rangingResult) {
             doSomethingWithRangingResult(rangingResult);
             request(1);
      }


      @Override public void onError(Throwable t) {
             t.printStackTrace();
      }


         @Override public void onComplete() {
            doSomethingOnEventsCompleted();
         }
   });

// Stop subscription
disposable.dispose();

دعم المنظومة المتكاملة

في ما يلي أجهزة الشركاء وحِزم SDK التابعة لجهات خارجية المتوافقة.

الأجهزة الجوّالة المزوّدة بتقنية النطاق الفائق العرض (UWB)

اعتبارًا من كانون الثاني (يناير) 2025، تتيح هذه الأجهزة استخدام مكتبة Android UWB Jetpack:

المورّد	طراز الجهاز
Google	هواتف Pixel Pro (هاتف Pixel 6 Pro والإصدارات الأحدث) وFold وTablet
Motorola	Edge 50 Ultra
Samsung	هواتف Galaxy Note 20 وGalaxy Plus وUltra (S21 والإصدارات الأحدث) وGalaxy Z Fold (Fold2 والإصدارات الأحدث)

ملاحظة: تتوفّر ميزة قياس المسافة عبر النطاق الفائق العرض (UWB) في الخلفية على جميع الأجهزة باستثناء ما يلي:

• ‫Pixel 6 Pro وPixel 7 Pro
• هواتف Samsung التي تعمل بنظام التشغيل Android 13 أو إصدار أقدم
• هواتف Samsung الصينية التي تعمل بنظام التشغيل Android 14 أو إصدار أقدم

حِزم تطوير البرامج (SDK) التابعة لجهات خارجية

اعتبارًا من نيسان (أبريل) 2023، أصبحت حلول الشركاء هذه متوافقة مع مكتبة Jetpack الحالية.

• مجموعة تطوير النطاق الفائق العرض (UWB) من Estimote
• MK UWB Kit Mobile Edition 2.0: المعرفة المخصّصة للأجهزة الجوّالة

مشكلة معروفة: عكس ترتيب البايت لعنوان MAC وحقول معرّف مورّد STS الثابت

في نظام التشغيل Android 13 والإصدارات الأقدم، تعكس حِزمة UWB في Android ترتيب البايت بشكل غير صحيح للحقول التالية:

• عنوان MAC للجهاز
• عنوان MAC للجهاز الوجهة
• رقم تعريف مورّد STS الثابت

يحدث عكس ترتيب البايت لأنّ حِزمة Android تتعامل مع هذه الحقول كقيم، وليس كصفائف. نحن نعمل مع FiRa لتعديل مواصفات UCI (CR-1112) لتحديد صراحةً أنّه يجب التعامل مع هذه الحقول كصفائف.

سيتم حلّ هذه المشكلة من خلال تحديث GMS Core في الإصدار 2320XXXX. وبدءًا من ذلك الحين، يجب أن يكون بائعو أجهزة إنترنت الأشياء متوافقين مع أجهزة Android، لذا عليهم تعديل عملية التنفيذ لتجنّب عكس ترتيب البايتات في هذه الحقول.