موقع Wi-Fi: بدءًا من ميزة "المراسلة النصية في الوقت الفعلي"

يمكنك استخدام وظيفة تحديد الموقع الجغرافي عبر شبكة Wi-Fi المقدَّمة من واجهة برمجة التطبيقات Wi-Fi RTT (Round-Trip-Time) API لقياس المسافة إلى نقاط وصول Wi-Fi المجاورة المزوّدة بتقنية RTT والأجهزة المشابهة التي تتضمّن ميزة Wi-Fi Aware.

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

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

لا يحتاج الجهاز المُرسِل إلى الاتصال بنقاط الوصول لقياس المسافة باستخدام تقنية RTT في Wi-Fi. للحفاظ على الخصوصية، لا يمكن سوى للجهاز المُرسِل تحديد المسافة إلى نقطة الوصول، ولا تملك نقاط الوصول هذه المعلومات. لا تُفرض أي قيود على عمليات قياس وقت الاستجابة لشبكة Wi-Fi للتطبيقات التي تعمل في المقدّمة، ولكن يتم تقليلها للتطبيقات التي تعمل في الخلفية.

يتم تحديد وقت استجابة Wi-Fi وإمكانات القياس الدقيق للوقت (FTM) ذات الصلة بواسطة معيار IEEE 802.11-2016. تتطلّب ميزة "وقت استجابة Wi-Fi" قياسًا دقيقًا للوقت يقدّمه إطار عمل إدارة الشبكة (FTM) لأنّه يحسب المسافة بين جهازين من خلال قياس الوقت الذي تستغرقه الحزمة في رحلة ذهاب وإياب بين الجهازين وضرب هذا الوقت بسرعة الضوء.

وفّر نظام Android 15 (المستوى 35 لواجهة برمجة التطبيقات) إمكانية استخدام قياس المسافة بالاستناد إلى تقنية IEEE 802.11az التي لا تعتمد على عامل تشغيل (NTB).

الاختلافات في التنفيذ استنادًا إلى إصدار Android

تم تقديم ميزة "وقت استجابة Wi-Fi" في Android 9 (المستوى 28 من واجهة برمجة التطبيقات). عند استخدام هذا البروتوكول لتحديد موضع جهاز باستخدام تقنية التحديد بالاستناد إلى عدة مصادر مع الأجهزة التي تعمل بالإصدار Android 9، يجب أن يكون لديك إذن الوصول إلى بيانات مواقع نقاط الوصول (AP) المُحدَّدة مسبقًا في تطبيقك. ولك القرار في تحديد كيفية تخزين هذه البيانات واستردادها.

على الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن تمثيل بيانات الموقع الجغرافي لنقطة الوصول باستخدام ResponderLocation عناصر تشمل خط العرض وخط الطول والارتفاع. بالنسبة إلى نقاط الوصول التي تستخدم تقنية RTT في شبكة Wi-Fi والتي تتيح الحصول على معلومات إعداد الموقع الجغرافي/تقرير الموقع الجغرافي (بيانات LCI/LCR)، سيعرض البروتوكول عنصرًا من النوع ResponderLocation أثناء عملية تحديد المسافة.

تتيح هذه الميزة للتطبيقات طلب معلومات الموقع الجغرافي من نقاط الوصول مباشرةً بدلاً من تخزين هذه المعلومات مسبقًا. وبالتالي، يمكن لتطبيقك العثور على نقاط الوصول وتحديد مواقعها حتى إذا لم تكن معروفة من قبل، مثلاً عندما يدخل مستخدم إلى مبنى جديد.

تتوفّر إمكانية قياس النطاق باستخدام بروتوكول IEEE 802.11az لتحديد النطاق بدون إرسال البيانات (NTB) على الأجهزة التي تعمل بنظام التشغيل Android 15 (المستوى 35 من واجهة برمجة التطبيقات) والإصدارات الأحدث. وهذا يعني أنّه إذا كان الجهاز متوافقًا مع وضع IEEE 802.11az المشغِّل لبروتوكول NTB (المشار إليه بالرمز WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR)، يمكن لتطبيقك العثور على نقاط الوصول المتوافقة مع كل من IEEE 802.11mc وIEEE 802.11az من خلال طلب واحد للنطاق. تم توسيع نطاق واجهة برمجة التطبيقات RangingResult لتوفير معلومات حول الحد الأدنى والأقصى للقيمة التي يمكن استخدامها للفاصل الزمني بين عمليات القياس المختلفة، مع ترك الفاصل الزمني الدقيق في عنصر التحكّم في تطبيقك.

المتطلبات

• يجب أن تطبِّق الأجهزة التي تقدّم طلب قياس المسافة معيار FTM‏ (قياس المسافة بدون إشارة) 802.11-2016 أو معيار 802.11az (قياس المسافة بدون إشارة بدء).
• يجب أن يعمل الجهاز الذي يُرسل طلب تحديد المسافة بالأجهزة بالإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) أو إصدار أحدث. يتم تفعيل قياس المسافة غير المستند إلى عامل تشغيل IEEE 802.11az على الأجهزة التي تعمل بالإصدار 15 من نظام التشغيل Android (المستوى 35 لواجهة برمجة التطبيقات) والإصدارات الأحدث.
• يجب أن يكون تفعيل خدمات الموقع الجغرافي مفعَّلاً على الجهاز الذي يُرسل طلب قياس المسافة ويكون البحث عن شبكات Wi-Fi مفعَّلاً (ضمن الإعدادات > الموقع الجغرافي).
• إذا كان التطبيق الذي يُرسل طلب تحديد النطاق يستهدف الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يجب أن يكون لديه إذن NEARBY_WIFI_DEVICES. إذا كان هذا التطبيق يستهدف إصدارًا أقدم من Android، يجب أن يحصل على إذن ACCESS_FINE_LOCATION بدلاً من ذلك.
• يجب أن يطلب التطبيق نطاق نقاط الوصول عندما يكون مرئيًا أو في خدمة تعمل في المقدّمة. لا يمكن للتطبيق الوصول إلى معلومات الموقع الجغرافي من الخلفية.
• يجب أن تطبِّق نقطة الوصول معيار FTM‏ IEEE 802.11-2016 أو معيار IEEE 802.11az (قياس المسافة غير المستند إلى عامل تشغيل).

ضبط إعدادات الجهاز

لإعداد تطبيقك لاستخدام ميزة "وقت استجابة Wi-Fi"، اتّبِع الخطوات التالية:

1. طلب الأذونات

اطلب الأذونات التالية في ملف بيان تطبيقك:

<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. على تطبيقك طلب إذن المستخدم إذا لم يتم منحه من قبل. لمزيد من المعلومات عن أذونات وقت التشغيل، يُرجى الاطّلاع على طلب أذونات التطبيق.

‫2- التحقّق مما إذا كان الجهاز متوافقًا مع تقنية Wi-Fi RTT

للتحقّق مما إذا كان الجهاز متوافقًا مع ميزة "وقت الاستجابة للتحدث" عبر Wi-Fi، استخدِم واجهة برمجة التطبيقات PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3- التحقّق مما إذا كانت ميزة "وقت استجابة Wi-Fi" متاحة

قد تكون ميزة "المراسلة النصية في الوقت الفعلي" عبر Wi-Fi متوفّرة على الجهاز، ولكن قد لا تكون متاحة لأنّ المستخدم أوقف شبكة Wi-Fi. استنادًا إلى إمكانات الأجهزة والبرامج الثابتة، قد لا تتوافق بعض الأجهزة مع تقنية Wi-Fi RTT في حال استخدام SoftAP أو ربط الجهاز. للتأكّد مما إذا كانت ميزة "المراسلة النصية في الوقت الفعلي" عبر شبكة Wi-Fi متاحة، يُرجى الاتصال بالرقم isAvailable().

يمكن أن يتغيّر مدى توفّر ميزة "وقت استجابة Wi-Fi" في أي وقت. يجب أن يسجِّل تطبيقك علامة إشتراك في 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 على نقاط وصول متوافقة مع معيارَي IEEE 802.11mc (is80211mcResponder()) و IEEE 802.11az لقياس المسافة بدون تنشيط (is80211azNtbResponder()). إنّ الأجهزة المتوافقة مع نطاق IEEE 802.11az NTB تُجري نطاق 802.11mc أو 802.11az استنادًا إلى قدرة نقطة الوصول، ويتم ضبطها تلقائيًا على 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. في كل طلب، اتّبِع الخطوات التالية:

1. تحديد الطلب

تحديد الطلب استنادًا إلى المعلومات المقدَّمة عند إنشاء RangingRequest: غالبًا ما يكون عنوان MAC المقدَّم فيScanResult يحدِّد نقطة وصول يمكن الحصول على عنوان MAC من نتيجة النطاق باستخدام الأسلوب getMacAddress().

قد تكون قائمة نتائج تحديد المسافة مرتبة بترتيب مختلف عن نقاط الاتصال (نقاط الوصول) المحدّدة في طلب تحديد المسافة، لذا عليك استخدام عنوان MAC لتحديد نقطة الاتصال، وليس ترتيب النتائج.

‫2- تحديد ما إذا كان كل قياس ناجحًا

لتحديد ما إذا كان القياس ناجحًا، استخدِم الطريقة getStatus(). تشير أي قيمة أخرى غير STATUS_SUCCESS إلى حدوث خطأ. ويعني تعذُّر إكمال العملية أنّ جميع الحقول الأخرى لهذه النتيجة (باستثناء معرّف الطلب أعلاه) غير صالحة، ولن تنجح طريقة get* المقابلة مع استثناء IllegalStateException.

3- الحصول على نتائج لكل قياس ناجح

بالنسبة إلى كل قياس ناجح (RangingResult)، يمكنك استرداد قيم النتيجة باستخدام طرق get ذات الصلة:

• المسافة، بالمليمتر، والانحراف المعياري للقياس:

  getDistanceMm()

  getDistanceStdDevMm()

• مؤشر RSSI للحِزم المستخدَمة في عمليات القياس:

  getRssi()

• الوقت بالمللي ثانية الذي تم فيه إجراء القياس (يشير إلى الوقت منذ بدء التشغيل):

  getRangingTimestampMillis()

• عدد القياسات التي تمّت محاولة إجرائها وعدد القياسات التي تمّ إجراؤها بنجاح (والتي تستند إليها قياسات المسافة):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• الحد الأدنى والحد الأقصى للوقت الذي يجب أن ينتظره جهاز العميل بين قياسات 11az NTB:

  getMinTimeBetweenNtbMeasurementsMicros() وgetMaxTimeBetweenNtbMeasurementsMicros() يعرضان الحد الأدنى والحد الأقصى للوقت. إذا تم طلب قياس النطاق التالي قبل انقضاء الحد الأدنى من الوقت، ستعرِض واجهة برمجة التطبيقات نتيجة النطاق التي تم تخزينها مؤقتًا. إذا تم طلب قياس تحديد المدى التالي بعد انقضاء الحد الأقصى للوقت، تُنهي واجهة برمجة التطبيقات جلسة تحديد المدى غير المشغّلة بالاستناد إلى إشارة وتفاوض على جلسة تحديد مدى جديدة مع المحطة التي تستجيب للإشارة. يجب تجنُّب طلب جلسة قياس جديدة، لأنّ ذلك يؤدي إلى زيادة وقت قياس النطاق. للاستفادة إلى أقصى حد من كفاءة قياس المسافة غير المستندة إلى عامل تشغيل في معيار 802.11az، يمكنك بدء طلب قياس المسافة التالي بين الحد الأدنى والحد الأقصى لوقت القياس المحدَّدَين في قياس RangingResult السابق.

• تكرارات حقل التدريب الطويل (LTF) التي تستخدمها محطتا المُجيب والمُشغِّل في مقدّمة نتيجة IEEE 802.11az NTB:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• عدد سلاسل الوقت المكاني (STS) للإرسال والاستقبال التي استخدمتها المحطة المُشغِّلة لنتيجة NTB في IEEE 802.11az:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

أجهزة Android المتوافقة مع تقنية WiFi-RTT

تسرد الجداول التالية بعض الهواتف ونقاط الوصول وأجهزة البيع بالتجزئة ومراكز التخزين والتوزيع التي تتيح تقنية WiFi-RTT. وهذه المراجع ليست شاملة على الإطلاق. ننصحك بالاتصال بنا لإدراج منتجاتك المزوّدة بتقنية RTT هنا.

نقاط الوصول

الهواتف

أجهزة البيع بالتجزئة ومراكز التخزين والتوزيع