اندروید 16 ماژول Ranging را معرفی می کند که یک رابط یکپارچه و استاندارد برای محدوده دقیق بین دستگاه ها ارائه می دهد. میتوانید از این سطح API برای اندازهگیری فاصله و موقعیت دستگاههای همتا استفاده کنید، بدون اینکه نیازی به مدیریت هر فناوری بهصورت جداگانه باشد.
ماژول Ranging از فناوری های زیر پشتیبانی می کند:
- فوق پهن باند
- صدای کانال بلوتوث
- Wi-Fi NAN RTT
- محدوده بلوتوث RSSI
محدوده قابلیت ها و در دسترس بودن
کلاس RangingManager
اطلاعاتی درباره فناوریهای محدوده پشتیبانی شده توسط دستگاه محلی و همچنین در دسترس بودن و قابلیتهای هر فناوری به برنامهها ارائه میدهد. برنامهها میتوانند برای Callback
ثبتنام کنند تا بهروزرسانیهایی را در مورد هرگونه تغییر در دسترس بودن یا قابلیتهای هر فناوری پشتیبانیشده دریافت کنند.
نقش های دستگاه
دستگاهی که در یک جلسه محدوده شرکت می کند باید آغازگر یا پاسخ دهنده باشد. دستگاه آغازگر جلسه محدوده را با یک یا چند دستگاه پاسخ دهنده شروع می کند. یک دستگاه پاسخدهنده به درخواستهای مختلف فقط از یک آغازگر در یک زمان پاسخ میدهد. می توانید نقش یک دستگاه معین را در یک جلسه محدوده با کلاس RangingPreference
مشخص کنید.
محدوده انواع جلسات
هنگام شروع یک جلسه محدوده بین دستگاه ها، اغلب لازم است که یک انتقال داده خارج از باند (OOB) برای تبادل پارامترها برای جلسه ایجاد شود.
ماژول Ranging می تواند مذاکرات OOB را برای شما انجام دهد، اما از پیاده سازی های سفارشی OOB نیز پشتیبانی می کند.

اجرای پیش فرض OOB
در این نوع جلسه ( RANGING_SESSION_OOB
)، ماژول Ranging مذاکرات OOB را برای شروع یک جلسه محدوده انجام می دهد. پارامترهای مناسب را بر اساس اولویتهای دامنه ارائه شده توسط برنامه انتخاب میکند و از فناوریهای مناسب بر اساس آنچه هر دو دستگاه پشتیبانی میکنند استفاده میکند. این نوع جلسه از OOB specification
استفاده می کند.
ماژول Ranging فقط قالب و توالی داده OOB را برای تعامل با دستگاه همتا تعریف می کند. به کشف دستگاه همتا یا برقراری اتصال رسیدگی نمی کند.
پیاده سازی OOB سفارشی
در این نوع جلسه ( RANGING_SESSION_RAW
)، برنامه جریان OOB ماژول Ranging را دور می زند و مذاکرات و پارامترهای OOB خود را مدیریت می کند. این بدان معناست که برنامه تا حد زیادی تعیین می کند که دستگاه همتا از چه فناوری هایی پشتیبانی می کند، در مورد پارامترهای محدوده مذاکره می کند و جلسه محدوده را آغاز می کند.
تنظیم اولویت ها
از یک شی RangingPreference
برای تعیین پارامترهای مورد نظر برای یک جلسه محدوده استفاده کنید. این شامل موارد زیر است:
- نقش دستگاه این نشان می دهد که آیا دستگاه آغازگر یا پاسخ دهنده خواهد بود.
- پیکربندی محدوده یک شی
RangingConfig
نوع جلسه محدوده و سایر پارامترهای مورد نیاز برای شروع یک جلسه محدوده را مشخص می کند. - پیکربندی جلسه یک شی
SessionConfig
پارامترهایی را مشخص می کند که باید در جلسه محدوده اعمال شوند مانند حد اندازه گیری، ترکیب حسگر، پیکربندی geofence و موارد دیگر.
مجوز محدوده
ماژول Ranging به یک مجوز یکپارچه جدید ( android.permission.RANGING
) برای دسترسی به تمام فناوری های محدوده فعلی و آینده نیاز دارد. این مجوز در لیست NEARBY_DEVICES_PERMISSIONS
است.
<uses-permission android:name="android.permission.RANGING" />
محدودیت ها و محدودیت ها
ماژول Ranging ممکن است محدوده را به دلایل مختلفی محدود کند، از جمله موارد زیر:
- برنامه های شخص ثالث فقط مجاز به انجام محدوده پس زمینه با باند فوق العاده و فقط در دستگاه های پشتیبانی شده هستند. تغییر در پس زمینه با سایر فناوری ها مجاز نیست.
- زمانی که به حداکثر تعداد جلسات محدوده همزمان بر اساس دستگاه رسیده باشد، محدوده مجاز نیست.
- محدوده ممکن است به دلیل نگرانی های مربوط به سلامت سیستم مانند باتری، عملکرد یا حافظه محدود شود.
ماژول Ranging همچنین دارای محدودیت های شناخته شده زیر است:
- ماژول Ranging فقط از تحویل داده های محدوده به دستگاه های همتا برای باند فوق العاده پشتیبانی می کند. برای سایر فناوریها، ماژول Ranging فقط دادههای محدوده را به دستگاه آغازگر تحویل میدهد.
- ماژول Ranging فقط از افزودن پویا دستگاه ها در حالت محدوده خام و فقط برای باند فوق العاده پشتیبانی می کند.
- ماژول Ranging از جلسات یک به چند باند فوق گسترده برای پیاده سازی های OOB پیش فرض پشتیبانی نمی کند. اگر چندین دسته دستگاه را پاس کنید، ماژول یک جلسه یک به یک برای هر دستگاه همتا که از پهنای باند فوق العاده پشتیبانی می کند ایجاد می کند.
یک جلسه دامنه دار برگزار کنید
برای انجام یک جلسه محدوده با استفاده از ماژول Ranging، این مراحل را دنبال کنید:
- بررسی کنید که همه دستگاهها روی Android 16 یا بالاتر کار میکنند.
- مجوز
android.permission.RANGING
را در مانیفست برنامه درخواست کنید. - ارزیابی قابلیت ها و در دسترس بودن فناوری های دامنه دار.
- یک دستگاه همتا برای محدوده عملیات کشف کنید.
- با استفاده از هر یک از انواع جلسه شرح داده شده در Ranging Session نوع ها ، اتصالی را برای تبادل خارج از باند ایجاد کنید.
- محدوده بندی را آغاز کنید و به طور مداوم داده های محدوده را بدست آورید.
- جلسه محدوده را خاتمه دهید.
نمونه کد زیر این مراحل را هم برای نقش آغازگر و هم برای نقش پاسخ دهنده نشان می دهد.
کاتلین
class RangingApp {
// Starts a ranging session on the initiator side.
fun startRangingInitiator(
context: Context,
deviceHandle: DeviceHandle,
executor: Executor,
callback: RangingSessionCallback
) {
// 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)
// 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.
session.start(preference)
// If successful, the ranging data will be sent through callback#onResults
// Stop ranging session
session.stop()
}
// Starts a ranging session on the responder side.
fun startRangingResponder(
context: Context,
deviceHandle: DeviceHandle,
executor: Executor,
callback: RangingSessionCallback
) {
// 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)
// 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.
session.start(preference)
// Stop the ranging session
session.stop()
}
}
جاوا
public class RangingApp {
// Starts a ranging session on the initiator side.
void startRangingInitiator(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {
// Get the RangingManager which is the entry point for ranging module.
RangingManager manager = context.getSystemService(RangingManager.class);
// Create a new RangingSession using the provided executor and callback.
RangingSession session = manager.createRangingSession(executor, callback);
// Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
// the initiator role.
OobInitiatorRangingConfig config = new 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.
RangingPreference preference =
new RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build();
// Start ranging session.
session.start(preference);
// If successful, the ranging data will be sent through callback#onResults
// Stop ranging session
session.stop();
}
// Starts a ranging session on the responder side.
void startRangingResponder(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {
// Get the RangingManager which is the entry point for ranging module.
RangingManager manager = context.getSystemService(RangingManager.class);
// Create a new RangingSession using the provided executor and callback.
RangingSession session = manager.createRangingSession(executor, callback);
// Create an OobResponderRangingConfig, which specifies the ranging parameters for
// the responder role.
OobResponderRangingConfig config = new OobResponderRangingConfig.Builder( deviceHandle).build();
// Create a RangingPreference, which specifies the role (responder) and
// configuration for the ranging session.
RangingPreference preference =
new RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build();
// Start the ranging session.
session.start(preference);
// Stop the ranging session
session.stop();
}
}
نمونه برنامه
برای مثال سرتاسر نحوه استفاده از ماژول Ranging، به برنامه نمونه در AOSP مراجعه کنید. این برنامه نمونه همه فناوریهای محدوده پشتیبانی شده توسط ماژول Ranging را پوشش میدهد و شامل جریانهایی برای هر دو نوع جلسه پشتیبانیشده است.