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

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

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

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

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

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

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

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

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

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

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

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

المتطلبات

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

الإعداد

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

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 RTT، استخدِم واجهة برمجة التطبيقات PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3- التحقّق من توفّر ميزة Wi-Fi RTT

قد تتوفّر ميزة Wi-Fi RTT على الجهاز، ولكن قد لا تكون متاحة لأنّ المستخدم أوقف Wi-Fi. قد لا تتوافق بعض الأجهزة مع ميزة "المراسلة النصية في الوقت الفعلي عبر Wi-Fi" إذا كانت ميزة SoftAP أو ميزة "الوصول إلى الإنترنت" قيد الاستخدام، وذلك حسب إمكانيات الأجهزة والبرامج الثابتة. للتحقّق من توفّر ميزة "RTT عبر Wi-Fi"، يمكنك الاتصال بالرقم 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 على نقاط وصول متوافقة مع معيار 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) للإرسال والاستقبال التي استخدمتها المحطة البادئة للحصول على نتيجة IEEE 802.11az NTB:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

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

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

نقاط الوصول

الهواتف

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