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

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

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

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

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

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

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

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

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

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

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

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

المتطلبات

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

نقاط الوصول

الهواتف

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