ارتباط فراپهن‌باند (UWB)

توجه: درحال‌حاضر، «فراپهن‌باند» فقط بااستفاده از Jetpack دردسترس است.

ارتباط فراپهن‌باند یک فناوری رادیویی است که بر محدوده دقیق (اندازه‌گیری مکان با دقت ۱۰ سانتی‌متر) بین دستگاه‌ها تمرکز دارد. این فناوری رادیویی می‌تواند از چگالی کم‌انرژی برای اندازه‌گیری‌های برد کوتاه استفاده کند و سیگنال‌دهی با پهنای باند بالا را در بخش بزرگی از طیف رادیویی انجام دهد. پهنای باند «فراپهن‌باند» بیشتر از ۵۰۰ مگاهرتز است (یا از ۲۰٪ پهنای باند کسری فراتر می‌رود).

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

ارتباط فراپهن‌باند بین دو دستگاه برقرار می‌شود که یکی «کنترل‌کننده» و دیگری «کنترل‌شونده» است. «کنترل‌کننده» کانال پیچیده (UwbComplexChannel) را که دو دستگاه هم‌رسانی خواهند کرد تعیین می‌کند و آغازگر است، درحالی‌که «کنترل‌شونده» پاسخ‌دهنده است.

یک «کنترل‌کننده» می‌تواند چندین «کنترل‌شونده» را مدیریت کند، اما یک «کنترل‌شونده» فقط می‌تواند در یک «کنترل‌کننده» مشترک شود. هر دو پیکربندی «کنترل‌کننده/آغازگر» و «کنترل‌شونده/پاسخ‌دهنده» پشتیبانی می‌شوند.

پارامترهای محدوده

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

پارامترهای فاصله‌یابی شامل نشانی محلی، کانال پیچیده، و کلید جلسه، و موارد دیگر است. توجه داشته باشید که این پارامترها ممکن است پس‌از پایان جلسه فاصله‌یابی بچرخند یا به‌نحوی تغییر کنند و برای بازراه‌اندازی فاصله‌یابی باید دوباره ارتباط برقرار شود.

محدوده پس‌زمینه

برنامه‌ای که در پس‌زمینه اجرا می‌شود می‌تواند جلسه فاصله‌یابی «فراپهن‌باند» را شروع کند، به‌شرطی که دستگاه از آن پشتیبانی کند. برای بررسی قابلیت‌های دستگاهتان، RangingCapabilities را ببینید.

برنامه هنگام اجرا در پس‌زمینه گزارش‌های فاصله‌یابی را دریافت نمی‌کند؛ برنامه هنگامی که به پیش‌زمینه منتقل می‌شود گزارش‌های فاصله‌یابی را دریافت می‌کند.

پیکربندی‌های STS

برنامه یا سرویس برای هر جلسه بااستفاده از «توالی مُهر زمان درهم‌ریخته» (STS) یک کلید جلسه فراهم می‌کند. STS ارائه‌شده از پیکربندی STS ایستا ایمن‌تر است. STS آماده‌سازی‌شده در همه دستگاه‌های سازگار با فراپهن‌باند که Android 14 یا بالاتر دارند پشتیبانی می‌شود.

دسته تهدید	STS ایستا	STS ارائه‌شده
هوا: ناظر منفعل	تعدیل‌شده	تعدیل‌شده
هوا: تقویت سیگنال	تعدیل‌شده	تعدیل‌شده
Air: حمله بازپخش/رله	مستعد	تعدیل‌شده

برای STS ارائه‌شده:

1. از uwbConfigType در RangingParameters که از STS ارائه‌شده پشتیبانی می‌کند استفاده کنید.

2. کلید ۱۶ بایتی را در فیلد sessionKeyInfo وارد کنید.

برای STS ایستا:

1. از uwbConfigType در RangingParameters که از STS ایستا پشتیبانی می‌کند استفاده کنید.

2. کلید ۸ بایتی را در فیلد sessionKeyInfo ارائه دهید.

قدم‌ها

برای استفاده از UWB API، این مراحل را دنبال کنید:

1. مطمئن شوید دستگاه‌های Android از Android 12 یا بالاتر استفاده می‌کنند و بااستفاده از PackageManager#hasSystemFeature("android.hardware.uwb") از فراپهن‌باند پشتیبانی می‌کنند.
2. اگر درحال اندازه‌گیری فاصله نسبت به دستگاه‌های اینترنت اشیا هستید، مطمئن شوید که آن‌ها با FiRa MAC 1.3 سازگار باشند.
3. دستگاه‌های همتای دارای قابلیت فراپهن‌باند را بااستفاده از سازوکار OOB انتخابی خودتان، مثل BluetoothLeScanner، کاوش کنید.
4. پارامترهای محدوده را بااستفاده از سازوکار OOB امنی که انتخاب می‌کنید، مثل BluetoothGatt، مبادله کنید.
5. اگر کاربر می‌خواهد جلسه را متوقف کند، دامنه جلسه را لغو کنید.

محدودیت‌های استفاده

محدودیت‌های زیر بر استفاده از UWB API اعمال می‌شود:

1. برنامه‌ای که جلسه‌های جدید فاصله‌یابی فراپهن‌باند را آغاز می‌کند باید برنامه یا سرویس پیش‌زمینه باشد، مگراینکه فاصله‌یابی پس‌زمینه همان‌طور که قبلاً نشان داده شد پشتیبانی شود.
2. وقتی برنامه به پس‌زمینه منتقل می‌شود (درحالی‌که جلسه درحال انجام است)، برنامه ممکن است دیگر گزارش‌های فاصله‌یابی را دریافت نکند. بااین‌حال، جلسه «فراپهن‌باند» همچنان در لایه‌های پایین‌تر حفظ خواهد شد. وقتی برنامه به پیش‌زمینه برمی‌گردد، گزارش‌های فاصله‌یابی ازسر گرفته می‌شود.

نمونه کدها

برنامه نمونه

برای مشاهده نمونه‌ای کامل از نحوه استفاده از کتابخانه Jetpack فراپهن‌باند، برنامه نمونه ما را در Github بررسی کنید. این برنامه نمونه شامل اعتبارسنجی سازگاری «فراپهن‌باند» در دستگاه Android، فعال کردن فرایند کشف بااستفاده از سازوکار OOB، و راه‌اندازی فاصله‌یابی «فراپهن‌باند» بین دو دستگاه با قابلیت «فراپهن‌باند» است. این نمونه همچنین موارد استفاده از کنترل دستگاه و هم‌رسانی رسانه را پوشش می‌دهد.

فاصله‌یابی فراپهن‌باند

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

// 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 دردسترس است. این کتابخانه روشی برای دریافت نتایج فاصله‌یابی به‌عنوان جریان «قابل‌مشاهده» یا «قابل‌جاری‌سازی» و بازیابی 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();

پشتیبانی بوم‌سازگان

دستگاه‌های شریک و کیت‌های توسعه نرم‌افزار طرف سوم پشتیبانی‌شده در اینجا آمده است.

دستگاه‌های همراه مجهز به فراپهن‌باند

از ژانویه ۲۰۲۵، این دستگاه‌ها از کتابخانه Android UWB Jetpack پشتیبانی می‌کنند:

فروشنده	مدل دستگاه
Google	‫Pixel Pro (‏6 pro و جدیدتر)،‏ Fold،‏ Tablet
Motorola	Edge 50 Ultra
Samsung	Galaxy Note 20،‏ Galaxy Plus و Ultra (S21 و جدیدتر)،‏ Galaxy Z Fold (‏Fold2 و جدیدتر)

توجه: فاصله‌یابی فراپهن‌باند پس‌زمینه در همه دستگاه‌ها به‌جز دستگاه‌های زیر پشتیبانی می‌شود:

• ‫Pixel 6 Pro،‏ Pixel 7 Pro، و Pixel Fold.
• تلفن‌های Samsung با Android نسخه ۱۳ یا پایین‌تر.
• تلفن‌های Samsung چینی با Android نسخه ۱۴ یا پایین‌تر.

کیت‌های توسعه نرم‌افزار طرف سوم

از آوریل ۲۰۲۳، این راه‌حل‌های شریک با کتابخانه Jetpack فعلی سازگار هستند.

• کیت توسعه فراپهن‌باند Estimote.
• Mobile Knowledge MK UWB Kit Mobile Edition 2.0.

مشکل شناخته‌شده: ترتیب بایت برای مک آدرس و فیلدهای شناسه فروشنده STS ثابت معکوس شده است

در Android 13 و نسخه‌های پایین‌تر، پشته UWB در Android به‌اشتباه ترتیب بایت را برای فیلدهای زیر معکوس می‌کند:

• «مک آدرس» دستگاه
• مک آدرس مقصد
• شناسه فروشنده STS ایستا

ترتیب بایت‌ها به‌این دلیل معکوس می‌شود که پشته Android با این فیلدها به‌عنوان مقدار رفتار می‌کند، نه آرایه. درحال همکاری با FiRa هستیم تا مشخصات UCI (CR-1112) را به‌روز کنیم تا صریحاً بیان شود که این فیلدها باید به‌عنوان آرایه درنظر گرفته شوند.

این مشکل ازطریق به‌روزرسانی «هسته سرویس‌های تلفن همراه Google» در نسخه 2320XXXX برطرف خواهد شد. برای سازگار بودن با دستگاه‌های Android از آن نقطه به بعد، فروشندگان اینترنت اشیاء باید پیاده‌سازی شما را اصلاح کنند تا از معکوس شدن ترتیب بایت این فیلدها جلوگیری شود.