واجهة UWB HAL

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

إذا كان إطار عمل 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 للجهاز وتغيير سلوكه وفقًا لذلك.

قائمة بمسودات CRs التي تدعمها وحدة UWB

يتم دعم مسودات CRs التالية لـ FiRa 2.0 بواسطة إصدار وحدة UWB رقم #330810000:

واجهة Android UCI (جزء بائع FiRa)

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

يتم تعريف رسائل البائع التي يستخدمها Android في حزمة android.hardware.uwb.fira_android HAL.

إصدار واجهة البائع

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

قائمة معرفات GID وOIDs لنظام Android

يسرد الجدول التالي معرفات GID ومعرفات الكائنات لنظام Android. إن معرفات GID 0xE و 0xF محجوزة لمصنعي الأجهزة الأصلية الذين يعملون بنظام Android لاستخدامها.

دائرة المخابرات العامة معرف الكائن تعريف
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 محفوظة لاستخدام OEM.

ملحقات البائع لمواصفات UCI المحددة للرسائل

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

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

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

  • GID: 0001b (مجموعة تكوين جلسة UWB)
  • معرف الكائن: 000011b ( SESSION_SET_APP_CONFIG_CMD )
  • معرف الكائن: 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

فيما يلي TLVs المحددة بواسطة مكدس AOSP في الجزء المحجوز للبائع من TLVs في CAPS_INFO :

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

يسرد الجدول التالي معلمات رسائل قدرة UWB.

اسم المعلمة طول
(الثمانيات)		 بطاقة شعار
(المعرفات)		 إصدار واجهة البائع وصف
SUPPORTED_POWER_STATS_QUERY 1 0xC0 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

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

قيم:

  • 0x01 : القناة 5 مدعومة
  • 0x02 : القناة 6 مدعومة
  • 0x04 : القناة 8 مدعومة
  • 0x08 : القناة 9 مدعومة
  • 0x10 : القناة 10 مدعومة
  • 0x20 : القناة 12 مدعومة
  • 0x40 : القناة 13 مدعومة
  • 0x80 : القناة 14 مدعومة

رموز الحالة

فيما يلي رموز الحالة في مساحة البائع. يتم إرجاعها في استجابات UCI (مثل SESSION_START_RSP ) بواسطة نظام UWB الفرعي (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 لسبب تنظيمي.