مکان Wi-Fi: محدوده با RTT

شما می‌توانید از قابلیت مکان‌یابی وای‌فای که توسط API مربوط به Wi-Fi RTT (زمان رفت و برگشت) ارائه می‌شود، برای اندازه‌گیری فاصله تا نقاط دسترسی وای‌فای نزدیک که قابلیت RTT دارند و دستگاه‌های همتا که از Wi-Fi Aware پشتیبانی می‌کنند، استفاده کنید.

اگر فاصله تا سه یا چند نقطه دسترسی را اندازه‌گیری کنید، می‌توانید از یک الگوریتم چندلایه‌سازی برای تخمین موقعیت دستگاهی که به بهترین وجه با آن اندازه‌گیری‌ها مطابقت دارد، استفاده کنید. نتیجه معمولاً در محدوده ۱-۲ متر دقیق است.

با این دقت، می‌توانید سرویس‌های مبتنی بر مکان دقیق، مانند ناوبری داخلی، کنترل صوتی بدون ابهام (برای مثال، "این چراغ را روشن کن") و اطلاعات مبتنی بر مکان (برای مثال، "آیا پیشنهادات ویژه‌ای برای این محصول وجود دارد؟") را توسعه دهید.

دستگاه درخواست‌کننده برای اندازه‌گیری فاصله با Wi-Fi RTT نیازی به اتصال به نقاط دسترسی ندارد. برای حفظ حریم خصوصی، فقط دستگاه درخواست‌کننده قادر به تعیین فاصله تا نقطه دسترسی است؛ نقاط دسترسی این اطلاعات را ندارند. عملیات Wi-Fi RTT برای برنامه‌های پیش‌زمینه نامحدود است، اما برای برنامه‌های پس‌زمینه محدود می‌شود.

Wi-Fi RTT و قابلیت‌های مرتبط با اندازه‌گیری دقیق زمان (FTM) توسط استاندارد IEEE 802.11-2016 مشخص شده‌اند. Wi-Fi RTT به اندازه‌گیری دقیق زمان ارائه شده توسط FTM نیاز دارد، زیرا فاصله بین دو دستگاه را با اندازه‌گیری زمانی که یک بسته برای طی کردن یک سفر رفت و برگشت بین دستگاه‌ها طول می‌کشد و ضرب آن زمان در سرعت نور محاسبه می‌کند.

اندروید ۱۵ (سطح API 35) پشتیبانی از محدوده‌یابی مبتنی بر غیر تریگر (NTB) مبتنی بر IEEE 802.11az را معرفی کرد.

تفاوت‌های پیاده‌سازی بر اساس نسخه اندروید

Wi-Fi RTT در اندروید ۹ (سطح API 28) معرفی شد. هنگام استفاده از این پروتکل برای تعیین موقعیت دستگاه با استفاده از multilateration با دستگاه‌هایی که اندروید ۹ را اجرا می‌کنند، باید به داده‌های مکان‌های از پیش تعیین‌شده نقطه دسترسی (AP) در برنامه خود دسترسی داشته باشید. نحوه ذخیره و بازیابی این داده‌ها به شما بستگی دارد.

در دستگاه‌هایی که اندروید ۱۰ (سطح API 29) و بالاتر را اجرا می‌کنند، داده‌های مکانی AP می‌توانند به صورت اشیاء ResponderLocation نمایش داده شوند که شامل عرض جغرافیایی، طول جغرافیایی و ارتفاع هستند. برای APهای Wi-Fi RTT که از اطلاعات پیکربندی مکان/گزارش مدنی مکان (داده‌های LCI/LCR) پشتیبانی می‌کنند، پروتکل در طول فرآیند مسافت‌یابی، یک شیء ResponderLocation برمی‌گرداند.

این ویژگی به برنامه‌ها اجازه می‌دهد تا به جای نیاز به ذخیره این اطلاعات از قبل، مستقیماً از نقاط دسترسی (AP) درخواست موقعیت کنند. بنابراین، برنامه شما می‌تواند نقاط دسترسی را پیدا کند و موقعیت آنها را تعیین کند، حتی اگر قبلاً نقاط دسترسی شناخته نشده باشند، مانند زمانی که کاربر وارد یک ساختمان جدید می‌شود.

پشتیبانی از مسافت‌یابی IEEE 802.11az NTB در دستگاه‌هایی که اندروید ۱۵ (سطح API 35) و بالاتر دارند، موجود است. این بدان معناست که اگر دستگاه از حالت آغازگر IEEE 802.11az NTB (که با WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR مشخص شده است) پشتیبانی کند، برنامه شما می‌تواند هر دو AP سازگار با IEEE 802.11mc و IEEE 802.11az را با یک درخواست مسافت‌یابی واحد پیدا کند. API RangingResult گسترش یافته است تا اطلاعاتی در مورد حداقل و حداکثر مقداری که می‌تواند برای فاصله بین اندازه‌گیری‌های مسافت‌یابی استفاده شود، ارائه دهد و فاصله دقیق را در کنترل برنامه شما قرار دهد.

الزامات

• سخت‌افزار دستگاهی که درخواست مسافت‌یابی می‌دهد باید استاندارد 802.11-2016 FTM یا استاندارد 802.11az (مبتنی بر غیر تریگر) را پیاده‌سازی کند.
• دستگاهی که درخواست مسافت‌یابی می‌دهد باید اندروید ۹ (سطح API 28) یا بالاتر را اجرا کند. مسافت‌یابی مبتنی بر عدم تریگر IEEE 802.11az در دستگاه‌هایی که اندروید ۱۵ (سطح API 35) و بالاتر را اجرا می‌کنند، فعال است.
• دستگاهی که درخواست مسافت‌یابی می‌دهد باید سرویس‌های موقعیت مکانی‌اش فعال و اسکن وای‌فای‌اش روشن باشد (از مسیر تنظیمات > موقعیت مکانی ).
• اگر برنامه‌ای که درخواست مسافت‌یابی را ارسال می‌کند، اندروید ۱۳ (سطح API ۳۳) یا بالاتر را هدف قرار می‌دهد، باید مجوز NEARBY_WIFI_DEVICES را داشته باشد. اگر چنین برنامه‌ای نسخه‌های قدیمی‌تر اندروید را هدف قرار می‌دهد، باید مجوز ACCESS_FINE_LOCATION را داشته باشد.
• برنامه باید در حالی که برنامه قابل مشاهده است یا در یک سرویس پیش‌زمینه قرار دارد، محدوده نقاط دسترسی را جستجو کند. برنامه نمی‌تواند از پس‌زمینه به اطلاعات مکان دسترسی پیدا کند .
• نقطه دسترسی باید استاندارد IEEE 802.11-2016 FTM یا استاندارد IEEE 802.11az (مبتنی بر غیر تریگر) را پیاده‌سازی کند.

راه‌اندازی

برای تنظیم برنامه خود برای استفاده از Wi-Fi RTT، مراحل زیر را انجام دهید.

۱. درخواست مجوز

مجوزهای زیر را در مانیفست برنامه خود درخواست کنید:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<!-- If your app targets Android 13 (API level 33)
     or higher, you must declare the NEARBY_WIFI_DEVICES permission. -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
                 <!-- If your app derives location information from Wi-Fi APIs,
                      don't include the "usesPermissionFlags" attribute. -->
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                 <!-- If any feature in your app relies on precise location
                      information, don't include the "maxSdkVersion"
                      attribute. -->
                 android:maxSdkVersion="32" />

مجوزهای NEARBY_WIFI_DEVICES و ACCESS_FINE_LOCATION مجوزهای خطرناکی هستند، بنابراین باید هر بار که کاربر می‌خواهد عملیات اسکن RTT را انجام دهد، آنها را در زمان اجرا درخواست کنید. اگر مجوز قبلاً اعطا نشده باشد، برنامه شما باید از کاربر درخواست مجوز کند. برای اطلاعات بیشتر در مورد مجوزهای زمان اجرا، به بخش درخواست مجوزهای برنامه مراجعه کنید.

۲. بررسی کنید که آیا دستگاه از Wi-Fi RTT پشتیبانی می‌کند یا خیر.

برای بررسی اینکه آیا دستگاه از Wi-Fi RTT پشتیبانی می‌کند یا خیر، از API PackageManager استفاده کنید:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_RTT);

۳. بررسی کنید که آیا Wi-Fi RTT در دسترس است یا خیر

ممکن است Wi-Fi RTT در دستگاه وجود داشته باشد، اما به دلیل غیرفعال کردن Wi-Fi توسط کاربر، در دسترس نباشد. بسته به قابلیت‌های سخت‌افزاری و میان‌افزار، برخی از دستگاه‌ها ممکن است در صورت استفاده از SoftAP یا اتصال به اینترنت، از Wi-Fi RTT پشتیبانی نکنند. برای بررسی اینکه آیا Wi-Fi RTT در دسترس است یا خیر، تابع isAvailable() را فراخوانی کنید.

در دسترس بودن Wi-Fi RTT می‌تواند در هر زمانی تغییر کند. برنامه شما باید یک BroadcastReceiver برای دریافت ACTION_WIFI_RTT_STATE_CHANGED ثبت کند، که هنگام تغییر در دسترس بودن ارسال می‌شود. هنگامی که برنامه شما قصد پخش را دریافت می‌کند، برنامه باید وضعیت فعلی در دسترس بودن را بررسی کرده و رفتار خود را بر اساس آن تنظیم کند.

برای مثال:

val filter = IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED)
val myReceiver = object: BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (wifiRttManager.isAvailable) {
            …
        } else {
            …
        }
    }
}
context.registerReceiver(myReceiver, filter)

IntentFilter filter =
    new IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (wifiRttManager.isAvailable()) {
            …
        } else {
            …
        }
    }
};
context.registerReceiver(myReceiver, filter);

برای اطلاعات بیشتر، به بخش پخش‌ها مراجعه کنید.

ایجاد درخواست دسته‌بندی

یک درخواست تعیین محدوده ( RangingRequest ) با مشخص کردن لیستی از نقاط دسترسی یا جفت‌های Wi-Fi Aware که از آنها یک محدوده درخواست می‌شود، ایجاد می‌شود. چندین نقطه دسترسی یا جفت‌های Wi-Fi Aware را می‌توان در یک درخواست تعیین محدوده مشخص کرد؛ فواصل تا همه دستگاه‌ها اندازه‌گیری و بازگردانده می‌شوند.

برای مثال، یک درخواست می‌تواند از متد addAccessPoint() برای مشخص کردن یک نقطه دسترسی که فاصله تا آن اندازه‌گیری می‌شود، استفاده کند:

val req: RangingRequest = RangingRequest.Builder().run {
    addAccessPoint(ap1ScanResult)
    addAccessPoint(ap2ScanResult)
    build()
}

RangingRequest.Builder builder = new RangingRequest.Builder();
builder.addAccessPoint(ap1ScanResult);
builder.addAccessPoint(ap2ScanResult);

RangingRequest req = builder.build();

یک نقطه دسترسی توسط شیء ScanResult آن شناسایی می‌شود که می‌توان آن را با فراخوانی WifiManager.getScanResults() به دست آورد. می‌توانید addAccessPoints(List<ScanResult>) برای اضافه کردن چندین نقطه دسترسی به صورت دسته‌ای استفاده کنید.

اشیاء ScanResult می‌توانند شامل هر دو نوع AP پشتیبانی‌شده با IEEE 802.11mc ( is80211mcResponder() ) و IEEE 802.11az بدون نیاز به فعال‌سازی ( is80211azNtbResponder() ) باشند. دستگاه‌هایی که از مسافت‌یابی NTB با استاندارد IEEE 802.11az پشتیبانی می‌کنند، بسته به قابلیت AP، مسافت‌یابی 802.11mc یا 802.11az را انجام می‌دهند و در صورت پشتیبانی AP از هر دو، به طور پیش‌فرض از 802.11az استفاده می‌کنند. دستگاه‌هایی که از IEEE 802.11az پشتیبانی نمی‌کنند، تمام مسافت‌یابی‌ها را با استفاده از پروتکل IEEE 802.11mc انجام می‌دهند.

به طور مشابه، یک درخواست تعیین محدوده می‌تواند یک همتای Wi-Fi Aware را با استفاده از آدرس MAC یا PeerHandle خود، به ترتیب با استفاده از متدهای addWifiAwarePeer(MacAddress peer) و addWifiAwarePeer(PeerHandle peer) اضافه کند. برای اطلاعات بیشتر در مورد کشف همتایان Wi-Fi Aware، به مستندات Wi-Fi Aware مراجعه کنید.

درخواست محدوده

یک برنامه با استفاده از متد WifiRttManager.startRanging() یک درخواست تعیین محدوده ارسال می‌کند و موارد زیر را ارائه می‌دهد: یک RangingRequest برای مشخص کردن عملیات، یک Executor برای مشخص کردن زمینه فراخوانی و یک RangingResultCallback برای دریافت نتایج.

برای مثال:

val mgr = context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE) as WifiRttManager
val request: RangingRequest = myRequest
mgr.startRanging(request, executor, object : RangingResultCallback() {

    override fun onRangingResults(results: List<RangingResult>) { … }

    override fun onRangingFailure(code: Int) { … }
})

WifiRttManager mgr =
      (WifiRttManager) Context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE);

RangingRequest request ...;
mgr.startRanging(request, executor, new RangingResultCallback() {

  @Override
  public void onRangingFailure(int code) { … }

  @Override
  public void onRangingResults(List<RangingResult> results) { … }
});

عملیات تعیین محدوده به صورت غیرهمزمان انجام می‌شود و نتایج تعیین محدوده در یکی از فراخوانی‌های تابع RangingResultCallback برگردانده می‌شوند:

• اگر کل عملیات تعیین محدوده با شکست مواجه شود، فراخوانی onRangingFailure با کد وضعیتی که در RangingResultCallback شرح داده شده است، آغاز می‌شود. چنین خرابی ممکن است در صورتی رخ دهد که سرویس نتواند یک عملیات تعیین محدوده را در آن زمان اجرا کند - برای مثال، به دلیل غیرفعال بودن Wi-Fi، یا به دلیل درخواست تعداد زیادی عملیات تعیین محدوده توسط برنامه و محدود شدن آن، یا به دلیل مشکل مجوز.
• وقتی عملیات تعیین محدوده کامل شد، تابع فراخوانی onRangingResults با فهرستی از نتایج که با فهرست درخواست‌ها مطابقت دارند، فعال می‌شود - یک نتیجه برای هر درخواست. ترتیب نتایج لزوماً با ترتیب درخواست‌ها مطابقت ندارد. توجه داشته باشید که عملیات تعیین محدوده ممکن است کامل شود اما هر نتیجه همچنان نشان‌دهنده‌ی شکست در آن اندازه‌گیری خاص باشد.

تفسیر نتایج حاصل از اندازه‌گیری

هر یک از نتایج برگردانده شده توسط تابع فراخوانی onRangingResults توسط یک شیء RangingResult مشخص می‌شود. در هر درخواست، موارد زیر را انجام دهید.

۱. درخواست را مشخص کنید

درخواست را بر اساس اطلاعات ارائه شده هنگام ایجاد RangingRequest شناسایی کنید: اغلب یک آدرس MAC ارائه شده در ScanResult که یک نقطه دسترسی را شناسایی می‌کند. آدرس MAC را می‌توان از نتیجه‌ی تعیین محدوده با استفاده از متد getMacAddress() بدست آورد.

فهرست نتایج مسافت‌یابی ممکن است ترتیب متفاوتی نسبت به نظیرها (نقاط دسترسی) مشخص شده در درخواست مسافت‌یابی داشته باشد، بنابراین باید از آدرس MAC برای شناسایی نظیر استفاده کنید، نه ترتیب نتایج.

۲. تعیین کنید که آیا هر اندازه‌گیری موفقیت‌آمیز بوده است یا خیر

برای تعیین اینکه آیا یک اندازه‌گیری موفقیت‌آمیز بوده است، از متد getStatus() استفاده کنید. هر مقداری غیر از STATUS_SUCCESS نشان دهنده‌ی یک شکست است. شکست به این معنی است که تمام فیلدهای دیگر این نتیجه (به جز شناسه درخواست فوق) نامعتبر هستند و متد get* مربوطه با یک استثنای IllegalStateException شکست خواهد خورد.

۳. برای هر اندازه‌گیری موفق، نتایج را دریافت کنید

برای هر اندازه‌گیری موفق ( RangingResult )، می‌توانید مقادیر نتیجه را با متدهای get مربوطه بازیابی کنید:

• فاصله، بر حسب میلی‌متر، و انحراف معیار اندازه‌گیری:

  getDistanceMm()

  getDistanceStdDevMm()

• RSSI بسته‌های مورد استفاده برای اندازه‌گیری‌ها:

  getRssi()

• زمان اندازه‌گیری بر حسب میلی‌ثانیه (نشان‌دهنده زمان از زمان بوت):

  getRangingTimestampMillis()

• تعداد اندازه‌گیری‌های انجام‌شده و تعداد اندازه‌گیری‌های موفق (که اندازه‌گیری‌های فاصله بر اساس آنها انجام شده است):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• حداقل و حداکثر زمانی که یک دستگاه کلاینت باید بین اندازه‌گیری‌های NTB 11az منتظر بماند:

  getMinTimeBetweenNtbMeasurementsMicros() و getMaxTimeBetweenNtbMeasurementsMicros() حداقل و حداکثر زمان را برمی‌گردانند. اگر اندازه‌گیری بعدیِ مسافت‌یابی قبل از گذشت حداقل زمان درخواست شود، API نتیجه‌ی مسافت‌یابی ذخیره‌شده را برمی‌گرداند. اگر اندازه‌گیری بعدیِ مسافت‌یابی پس از گذشت حداکثر زمان درخواست شود، API جلسه‌ی مسافت‌یابی بدون تریگر را خاتمه می‌دهد و یک جلسه‌ی مسافت‌یابی جدید را با ایستگاه پاسخ‌دهنده مذاکره می‌کند. شما باید از درخواست یک جلسه‌ی مسافت‌یابی جدید خودداری کنید، زیرا سربار به زمان اندازه‌گیری مسافت‌یابی اضافه می‌کند. برای بهره‌مندی کامل از کارایی مسافت‌یابی مبتنی بر تریگر 802.11az، درخواست مسافت‌یابی بعدی را بین حداقل و حداکثر زمان اندازه‌گیری مشخص‌شده در اندازه‌گیری قبلیِ RangingResult راه‌اندازی کنید.

• تکرارهای میدان آموزش طولانی (LTF) که ایستگاه‌های پاسخ‌دهنده و آغازگر در مقدمه برای IEEE 802.11az NTB استفاده کردند، نتیجه زیر را به همراه داشت:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• تعداد جریان‌های زمانی مکانی (STS) ارسال و دریافت که ایستگاه آغازگر برای نتیجه IEEE 802.11az NTB استفاده کرده است:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

دستگاه‌های اندرویدی که از WiFi-RTT پشتیبانی می‌کنند

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

نقاط دسترسی

تلفن‌ها

دستگاه‌های مرکز خرده‌فروشی، انبارداری و توزیع