واجهة النطاق الفائق العرض (HAL)

بروتوكول AOSP حزمة النطاق الفائق العرض (UWB) تستخدم واجهة UCI المحدّدة من FiRa كسطح HAL. تستخدم واجهة HAL شريطًا غير شفاف (IUwbChip::sendUciMessage() وIUwbClientCallback::onUciMessage()) للإرسال وتلقّي أوامر واجهة أوامر النطاق الفائق العرض (UCI) واستجاباتها وإشعاراتها. على جميع مورّدي النطاق الفائق العرض (UWB) لنظام التشغيل Android إتاحة جميع مواصفات FiRa المحدَّدة الرسائل. إطار عمل النطاق الفائق العرض (UWB) متوافق مع الأنظمة القديمة ويعمل مع أي واجهة UCI. الإصدار الذي نفَّذه المورّد عبر النطاق الفائق العرض (UWB) على الجهاز. لأنّ النطاق الفائق العرض (UWB) لـ AOSP إطار العمل عبارة عن وحدة بل يمكنه أيضًا إضافة دعم بشكل انتقائي لطلبات التغيير المعتمدة (CRs) من مسودة مواصفات UCI المستهدفة للإصدارات الرئيسية لمعايير FiRa. أي إنّ مسودة الردود الجاهزة التي تمّ تنفيذها عرضة للتغيير.

تعريف الواجهة

يتم تحديد واجهة UWB HAL باستخدام ثابت AIDL. تستخدم الواجهة الرئيسية حزمة android.hardware.uwb.

في ما يلي الواجهتان الرئيسيتان في android.hardware.uwb. طرد.

مؤسسة IUwbChip.aidl

package android.hardware.uwb;

interface IUwbChip {

 String getName();

 void open(in android.hardware.uwb.IUwbClientCallback clientCallback);

 void close();

 void coreInit();

 void sessionInit(int sessionId);

 int getSupportedAndroidUciVersion();

 int sendUciMessage(in byte[] data);

}

IUwbClientCallback.aidl

package android.hardware.uwb;

interface IUwbClientCallback {

 oneway void onUciMessage(in byte[] data);

 oneway void onHalEvent(in android.hardware.uwb.UwbEvent event, in android.hardware.uwb.UwbStatus status);

}

تدفق طلب HAL من إطار عمل النطاق الفائق العرض (UWB)

توضح الصور التالية تدفق الاتصال من إطار عمل النطاق الفائق العرض (UWB) إعداد تكديس النطاق الفائق العرض (UWB) وإيقاف تشغيل حزمة النطاق الفائق العرض (UWB) وبدء جلسة النطاق الفائق العرض (UWB) وإيقاف العمليات.

إعداد حزمة النطاق الفائق العرض (UWB)

الشكل 1. مسار طلب إعداد حزمة النطاق الفائق العرض (UWB) (تفعيل النطاق الفائق العرض (UWB))

إيقاف إعداد تكديس النطاق الفائق العرض (UWB)

الشكل 2. مسار طلب إلغاء إعداد تكديس النطاق الفائق العرض (UWB) (إيقاف تشغيل النطاق الفائق العرض (UWB))

بدء جلسة النطاق الفائق العرض (UWB) وإيقافها

الشكل 3. مسار بدء/إيقاف جلسة النطاق الفائق العرض (UWB)

إعدادات رمز البلد للنطاق الفائق العرض (UWB)

كما هو موضح في الشكل 1، يضبط إطار عمل النطاق الفائق العرض (UWB) رمز البلد للنطاق الفائق العرض (UWB) أثناء إعداد تكديس النطاق الفائق العرض (UWB) باستخدام الأمر Seller-space UCI ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). يحاول إطار عمل النطاق الفائق العرض (UWB) تحديد رمز البلد للنطاق الفائق العرض (UWB) باستخدام المصادر التالية (المدرجة في الأولوية الترتيب). يتوقف إطار عمل النطاق الفائق العرض (UWB) عند المصدر الأول حيث رمز البلد الشركة.

  1. رمز تجاوز البلد: يتم فرض رمز البلد من خلال أمر adb shell (اختبار محلي أو مبرمَج)
  2. رمز البلد للاتصال الهاتفي: رمز البلد الذي تم استرداده من خلال شبكة الجوّال. في حال حذف هناك شرائح SIM متعددة تعرض رموزًا مختلفة، ورمز البلد الذي تم اختياره هو غير حتمي.
  3. رمز بلد Wi-Fi: رمز البلد الذي تم استرداده من خلال Wi-Fi (80211.ad).
  4. آخر رمز بلد معروف للاتصال الهاتفي: تم استرداد آخر رمز بلد معروف من خلال الشبكة الخلوية. في حال وجود شرائح SIM متعددة يظهر بإرجاعها مختلفًا فإن رمز البلد الذي تم اختياره غير محدد.
  5. رمز بلد الموقع: تم استرداد رمز البلد من LocationManager مقدم خدمة الموقع المدمج.
  6. رمز البلد التلقائي للمصنّع الأصلي للجهاز: رمز البلد الذي حدّدته الشركة المصنّعة للجهاز.

إذا لم يتمكن إطار عمل النطاق الفائق العرض (UWB) من تحديد رمز بلد النطاق الفائق العرض (UWB)، فإنه يستدعي ANDROID_SET_COUNTRY_CODE أمر UCI بقيمة DEFAULT_COUNTRY_CODE ("00") ويرسل إشعارات إلى تطبيقات النطاق الفائق العرض (UWB) حالة تكديس النطاق الفائق العرض (UWB) هي DISABLED. وفي وقت لاحق، عندما يكون إطار عمل النطاق الفائق العرض (UWB) قادرًا على تحديد رمز بلد صالح، فإنه يهيئ رمز البلد الجديد باستخدام يتم استخدام الأمر ANDROID_SET_COUNTRY_CODE مع إرسال إشعار إلى تطبيقات النطاق الفائق العرض (UWB) حزمة النطاق الفائق العرض (UWB) READY.

في حال تعذّر استخدام النطاق الفائق العرض (UWB) وفقًا للوائح المحلية في البلد، ترسل وحدة التحكم في النطاق الفائق العرض (UWB) رمز الحالة STATUS_CODE_ANDROID_REGULATION_UWB_OFF. إطار عمل النطاق الفائق العرض (UWB) يُعلِم تطبيقات النطاق الفائق العرض (UWB) أنّ حالة حزمة النطاق الفائق العرض (UWB) هي DISABLED.

عندما يسافر المستخدم إلى بلد مختلف، يضبط إطار عمل النطاق الفائق العرض (UWB) رمز البلد باستخدام أمر ANDROID_SET_COUNTRY_CODE UCI. استنادًا إلى رمز الحالة الذي تعرضه وحدة التحكم في النطاق الفائق العرض (UWB) (استنادًا إلى لوائح النطاق الفائق العرض (UWB) في جديد)، فقد يؤدي هذا إلى تغيير في حالة تكديس النطاق الفائق العرض (UWB).

تنسيق الأمر المحدَّد لمواصفات FIRA UCI

لتنسيق حزم التحكم في UCI، يمكن مراجعة الفقرة 4.4.2 من UCI المواصفات.

تحديد إصدارات الواجهة

تسمح مواصفات UCI لمورّدي النطاق الفائق العرض (UWB) بعرض إصدار حزمة UCI تم تنفيذها من خلال الجهاز باستخدام UCI_GET_DEVICE_INFO_RSP UCI_GET_CAPS_INFO_RSP أمر. ويستخدم إطار العمل هذه الأوامر لجلب إصدار UCI للجهاز وتغيير سلوكه وفقًا لذلك.

قائمة بمسودات الردود الجاهزة التي يمكن استخدامها في وحدة النطاق الفائق العرض (UWB)

مسودة الردود الجاهزة التالية لـ FiRa 2.0 معتمدة من قبل الإصدار رقم 330810000 من وحدة UWB:

واجهة UCI في Android (جزء مورّد FiRa)

تحدد مواصفات UCI مجموعة من معرّفات المجموعات (GID) ورموز التشغيل لجميع الرسائل المحددة بالمواصفات. المواصفات أيضًا مجموعة من معرّفات GID المحجوزة حصريًا لاستخدام البائع. النطاق الفائق العرض (UWB) لـ AOSP بعض من معرّفات GIDs وOIDs للموردين للأوامر الخاصة بنظام Android التي لم يتم تحديدها في المواصفات. للحصول على التفاصيل، يُرجى مراجعة الفقرة 8.4 من UCI المواصفات.

يتم تحديد رسائل المورِّد هذه التي يستخدمها Android في حزمة HAL واحدة (android.hardware.uwb.fira_android)

إنشاء نُسخ من واجهة المورّد

على مورّدي النطاق الفائق العرض (UWB) الكشف عن إصدار android.hardware.uwb.fira_android حزمة HAL متوافقة مع الجهاز من خلال IUwbChip.getSupportedAndroidUciVersion() يستخدم إطار العمل هذا معلومات حول الإصدارات للتعامل مع التوافق مع الأنظمة القديمة.

قائمة معرّفات GID وOID في نظام التشغيل Android

يسرد الجدول التالي معرّفات GID وOIDs لنظام التشغيل Android. رقما تعريف المجموعة (GID) 0xE و0xF أن يستخدمها المصنّعون الأصليون لأجهزة Android.

GID معرّف الكائنات (OID) التعريف
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 يتم استخدام ذلك الأمر والاستجابة للحصول على الإحصاءات المتعلّقة بطاقة النطاق الفائق العرض (UWB). لا تتوفَّر هذه الميزة إلّا في حال UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY تم ضبطها على 1.
ANDROID_SET_COUNTRY_CODE = 0x1

يُستخدم لضبط رمز البلد التنظيمي الحالي (يتم تحديده باستخدام شريحة SIM أو شبكة Wi-Fi أو بترميز ثابت لدى المصنّع الأصلي للجهاز). يتم إرسال رمز البلد. كقيمة 2 بايت تتوافق مع رمز البلد ISO-3166. حاسمة تُستخدم قيمة 00 للإشارة إلى أن رمز البلد غير معروف.
ANDROID_RANGE_DIAGNOSTICS = 0x2 يستخدم الإشعار في الإشعار للحصول على إحصاءات بيانات التشخيص لنطاق النطاق الفائق العرض (UWB) لا تتوفَّر هذه الميزة إلّا في حال تم ضبط UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS إلى 1.
OEM = 0xE,0xF 0x00 - 0x3F محجوزة لاستخدام المصنّع الأصلي للجهاز.

إضافات المورّدين للرسائل المحدَّدة بمواصفات UCI

يصف هذا القسم تفاصيل إضافات المورّدين في UCI الرسائل المحددة بالمواصفات.

SESSION_SET_APP_CONFIG_[CMD|RSP] وSESSION_GET_APP_CONFIG_[CMD|RSP]

في ما يلي قيم طول النوع (TLV) المحددة بواسطة تكديس AOSP في حجز البائع جزءًا من TLV في APP_CONFIG:

  • GID: 0001b (مجموعة ضبط جلسة النطاق الفائق العرض (UWB))
  • معرّف OID: 000011b (SESSION_SET_APP_CONFIG_CMD)
  • معرّف OID: 000100b (SESSION_GET_APP_CONFIG_CMD)

يسرد الجدول التالي المَعلمات لرسائل إعداد جلسة النطاق الفائق العرض (UWB).

اسم المعلمة الطول
(ثُمانيات)		 العلامة
(الأرقام التعريفية)		 إصدار واجهة المورّد الوصف
NB_OF_RANGE_MEASUREMENTS 1 0xE3 1 نسبة التداخل في حال ضبط AOA_RESULT_REQ إلى 0xF0. لا يتم دعمها إلا إذا كانت UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING تم الضبط على 1
NB_OF_AZIMUTH_MEASUREMENTS 1 0xE4 1
NB_OF_ELEVATION_MEASUREMENTS 1 0xE5 1
ENABLE_DIAGNOSTICS 1 0xE8 2

قيمة 1 بايت لتفعيل تقارير بيانات التشخيص أو إيقافها ضبط هذه المعلمة فقط عند CORE_GET_CAPS_INFO_RSP يكون ناتجها SUPPORTED_DIAGNOSTICS بقيمة 1 الذي يشير إلى أن ميزة إعداد تقارير بيانات التشخيص هي

القيم:

  • 1: تم تفعيل الميزة.
  • 0: تم إيقاف الميزة
DIAGRAMS_FRAME_REPORTS_FIELDS 1 أو 4 0xE9 2

قناع بت بحجم 1 بايت أو 4 بايت لإعداد تقارير بيانات التشخيص. هذا النمط قناع البت هو 1 بايت في Android 14 أو أعلى 4 بايت في نظام Android 13 أو الإصدارات الأقدم

يجب ضبط هذه المعلمة فقط عندما يمكن إرجاع المشتريات مقابل CORE_GET_CAPS_INFO_RSP. SUPPORTED_DIAGNOSTICS بقيمة 1 يشير إلى توفّر ميزة إعداد تقارير بيانات التشخيص

تعريفات البت:

  • b0 (0x01): تفعيل حقول RSSI
  • b1 (0x02): تفعيل حقول AoA
  • b2 (0x04): تفعيل حقول CIR

CORE_GET_CAPS_INFO_RSP

في ما يلي ملفات TLV التي تحدّدها تكديس AOSP في المورّد المخصص من TLV في CAPS_INFO:

  • GID: 0000b (مجموعة UWB الأساسية)
  • معرّف OID: 000011b (CORE_GET_CAPS_INFO_RSP)

يسرد الجدول التالي المَعلمات لرسائل إمكانية استخدام النطاق الفائق العرض (UWB).

اسم المعلمة الطول
(ثُمانيات)		 العلامة
(الأرقام التعريفية)		 إصدار واجهة المورّد الوصف
SUPPORTED_POWER_STATS_QUERY 1 0xC0 1

قيمة 1 بايت تشير إلى دعم طلب البحث عن إحصاءات الطاقة.

القيم:

  • 1: ميزة متوافقة
  • 0: الميزة غير متاحة
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

قيمة 1 بايت تشير إلى دعم تداخل الهوائي الجديدة.

القيم:

  • 1: ميزة متوافقة
  • 0: الميزة غير متاحة
SUPPORTED_MIN_RANGING_INTERVAL_MS 4 0xE4 2 قيمة 4 بايت تشير إلى الحد الأدنى المتوافق لفاصل النطاق في مللي ثانية.
SUPPORTED_RANGE_DATA_NTF_CONFIG 4 0xE5 2 قناع بت بسعة 4 بايت يشير إلى التوافق RANGE_DATA_NTF_CONFIG قيمة قناع بت حيث يتجاوب كل بت مع القيم المستخدمة في RANGE_DATA_NTF_CONFIG في SET_APP_CFG_CMD.
SUPPORTED_RSSI_REPORTING 1 0xE6 2

قيمة 1 بايت تشير إلى إتاحة تقارير RSSI.

القيم:

  • 1: ميزة متوافقة
  • 0: الميزة غير متاحة
SUPPORTED_DIAGNOSTICS 1 0xE7 2

قيمة 1 بايت تشير إلى إتاحة تقارير بيانات التشخيص.

القيم:

  • 1: ميزة متوافقة
  • 0: الميزة غير متاحة
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 قيمة 4 بايت تشير إلى الحد الأدنى المسموح به لمدة الخانة في RSTU
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2 قيمة 4 بايت تشير إلى الحد الأقصى المسموح به لعدد FiRa بدءًا من الجلسات.
SUPPORTED_CHANNELS_AOA 2 0xEA 2

قناع بت 2 بايت للإشارة إلى القنوات التي تدعم AoA. على كل ويتجاوب 1 في قناع البت مع قناة النطاق الفائق العرض (UWB) المحددة.

القيم:

  • 0x01: القناة 5 متوافقة
  • 0x02: القناة 6 متوافقة
  • 0x04: القناة 8 متوافقة
  • 0x08: القناة 9 متوفّرة
  • 0x10: القناة 10 متاحة
  • 0x20: القناة 12 متوافقة
  • 0x40: القناة 13 متوافقة
  • 0x80: القناة 14 متوافقة

رموز الحالة

فيما يلي رموز الحالة في مساحة المورد. ويتم إرجاعها في استجابات UCI (مثل SESSION_START_RSP) من خلال النظام الفرعي للنطاق الفائق العرض (UWBS)

رمز الحالة القيمة الوصف
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

رمز الحالة الذي يتم عرضه عندما يتعذّر تحديد جلسة النطاق الحالية بدأت بسبب التعارض مع جلسات أخرى تتراوح بين CCC أو FiRa.
STATUS_REGULATION_UWB_OFF 0x53

رمز الحالة الذي يتم عرضه عندما يتعذّر تحديد جلسة النطاق الحالية لأسباب تنظيمية تتعلق باستخدام النطاق الفائق العرض (UWB)

رمز سبب تغيير الولاية في SESSION_STATUS_NTF

فيما يلي رموز أسباب تغيير الولاية المحددة في مساحة البائع حقل الحالة الذي يعرضه النطاق الفائق العرض (UWBS) في SESSION_STATUS_NTF. هذا الإشعار يتم إرساله بواسطة النطاق الفائق العرض (UWBS) عندما تتغير حالة جلسات متعددة (على سبيل المثال، من ACTIVE إلى IDLE).

رمز سبب تغيير الولاية القيمة الوصف
REASON_ERROR_INVALID_CHANNEL_WITH_AOA 0x80

تغيّرت حالة الجلسة لأنّ القناة التي تم ضبطها لم تتغيّر. ويدعم نطاق AoA.
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x81

تم تغيير حالة الجلسة بسبب التعارض مع CCC أو FiRa الأخرى. جلسات متعددة.
REASON_REGULATION_UWB_OFF 0x82

تم تغيير حالة الجلسة لأنّه يجب إيقاف النطاق الفائق العرض (UWB) بسبب سبب تنظيمي.