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

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

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

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

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

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

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

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

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

  1. إلغاء رمز البلد: يتم فرض رمز البلد من خلال أمر shell adb (اختبار محلي أو آلي).
  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) بسبب اللوائح المحلية في بلد معيّن، يعرض جهاز التحكّم في تقنية النطاق الفائق العرض رمز الحالة STATUS_CODE_ANDROID_REGULATION_UWB_OFF. بعد ذلك، يُرسِل إطار عمل UWB إعلامًا إلى تطبيقات UWB بأنّ حالة حِزمة UWB هي DISABLED.

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

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

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

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

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

قائمة مسودات طلبات الحصول على إذن بالطرح متوافقة مع وحدة النطاق الفائق العرض (UWB)

تتيح وحدة النطاق الفائق العرض (UWB) الإصدار 330810000 مسودة طلبات إعادة النظر التالية في FiRa 2.0:

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

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

يتم تعريف رسائل المورّدين هذه التي يستخدمها Android في ملف برمجي android.hardware.uwb.fira_android HAL.

إصدارات واجهة المورّد

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

قائمة أرقام تعريف Google وأرقام تعريف OpenID الخاصة بنظام التشغيل 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، أو يتم ترميزه بشكل ثابت من قِبل المصنّع الأصلي للجهاز). يتم إرسال رمز البلد كقيمة مكونة من بايتين تتوافق مع رمز البلد وفقًا لمعيار 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 في الجزء المحجوز للمورّد من قيم طول النوع في 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): تفعيل حقول "اتجاهات الإعلانات"
  • 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: الميزة متاحة
  • 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

قيمة بايت واحد تشير إلى توفّر ميزة إعداد تقارير RSSI

القيم:

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

قيمة بايت واحد تشير إلى توفّر ميزة إعداد تقارير بيانات التشخيص

القيم:

  • 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

قناع بتّين للإشارة إلى القنوات المتوافقة مع تقنية 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

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

تغيّرت حالة الجلسة بسبب تعارض مع جلسات تحديد النطاق الأخرى من CCC أو FiRa

REASON_REGULATION_UWB_OFF 0x82

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