تستخدم مجموعة 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.
الشكل 1. تدفق استدعاء تهيئة مكدس UWB (تشغيل UWB)
الشكل 2. تدفق استدعاء إلغاء تهيئة مكدس UWB (إيقاف تشغيل UWB)
الشكل 3. بدء/إيقاف تدفق جلسة UWB
تكوين رمز البلد UWB
كما هو موضح في الشكل 1، يقوم إطار عمل UWB بتكوين رمز بلد UWB أثناء تهيئة مكدس UWB باستخدام أمر UCI لمساحة البائع ANDROID_SET_COUNTRY_CODE
(GID= 0xC
، OID= 0x1
). يحاول إطار UWB تحديد رمز البلد UWB باستخدام المصادر التالية (المدرجة بترتيب الأولوية). يتوقف إطار عمل UWB عند المصدر الأول حيث يتم تحديد رمز البلد.
- تجاوز رمز البلد: يتم فرض رمز البلد من خلال أمر adb Shell (اختبار محلي أو آلي).
- رمز البلد الخاص بالمهاتفة: يتم استرداد رمز البلد عبر الهاتف الخلوي. إذا كانت هناك شرائح SIM متعددة تعرض رموزًا مختلفة، فإن رمز البلد الذي تم اختياره يكون غير محدد.
- رمز بلد Wi-Fi: تم استرداد رمز البلد من خلال Wi-Fi (80211.ad).
- آخر رمز بلد معروف للاتصال الهاتفي: تم استرداد آخر رمز بلد معروف عبر الهاتف الخلوي. إذا كانت هناك شرائح SIM متعددة تعرض رموزًا مختلفة، فإن رمز البلد الذي تم اختياره يكون غير محدد.
- رمز البلد للموقع: تم استرداد رمز البلد من موفر الموقع المدمج
LocationManager
. - رمز البلد الافتراضي لـ 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. يتم استخدام القيمة | |
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 بايت لتمكين أو تعطيل تقارير التشخيص. قم بتكوين هذه المعلمة فقط عندما يقوم قيم:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 أو 4 | 0xE9 | 2 | قناع بت 1 بايت أو 4 بايت لتكوين تقارير التشخيص. يبلغ حجم هذا القناع البتي 1 بايت في Android 14 أو الإصدارات الأحدث و4 بايت في Android 13 أو الإصدارات الأقدم. قم بتكوين هذه المعلمة فقط عندما يقوم تعريفات البت:
|
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 | تشير قيمة بايت واحدة إلى دعم استعلام إحصائيات الطاقة. قيم:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | تشير قيمة بايت واحدة إلى دعم ميزة تشذير الهوائي. قيم:
|
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. قيم:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | تشير قيمة بايت واحدة إلى دعم تقارير التشخيص. قيم:
|
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. يتوافق كل قيم:
|
رموز الحالة
فيما يلي رموز الحالة في مساحة البائع. يتم إرجاعها في استجابات 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 لسبب تنظيمي. |