ממשק HAL של UWB

‫Ultra-wideband (UWB) stack של AOSP משתמש ב-FiRa-defined UCI interface כמשטח HAL. ממשק ה-HAL משתמש בצינור אטום (IUwbChip::sendUciMessage() ו-IUwbClientCallback::onUciMessage()) כדי לשלוח ולקבל פקודות, תגובות והתראות של ממשק הפקודות של UWB ‏ (UCI). כל הספקים של UWB ב-Android חייבים לתמוך בכל ההודעות שמוגדרות במפרט של FiRa. מסגרת ה-UWB תואמת לדורות קודמים ועובדת עם כל גרסת UCI שהספק של ה-UWB הטמיע במכשיר. מכיוון ש-AOSP UWB framework הוא מודול, אפשר גם להוסיף לו באופן סלקטיבי תמיכה בבקשות לשינוי (CR) שאושרו מתוך מפרטי UCI בטיוטה שמיועדים למהדורות מרכזיות של תקני FiRa. כל טיוטת בקשה לשינוי כזו שתיושם עשויה להשתנות.

הגדרת הממשק

ממשק ה-HAL של UWB מוגדר באמצעות 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 מפסיקה במקור הראשון שבו נקבע קוד המדינה.

1. החלפת קוד המדינה: קוד המדינה שנכפה באמצעות פקודת adb shell (בדיקה מקומית או אוטומטית).
2. קידומת חיוג של מדינה: קידומת המדינה שאוחזרה דרך הרשת הסלולרית. אם יש כמה כרטיסי SIM שמחזירים קודים שונים, קוד המדינה שנבחר הוא לא דטרמיניסטי.
3. קוד המדינה של Wi-Fi: קוד המדינה שאוחזר דרך Wi-Fi ‏ (80211.ad).
4. קידומת המדינה האחרונה הידועה של הטלפון: קידומת המדינה האחרונה הידועה שאוחזרה דרך הרשת הסלולרית. אם יש כמה כרטיסי SIM שמחזירים קודים שונים, קוד המדינה שנבחר הוא לא דטרמיניסטי.
5. קוד המדינה שבה נמצא המיקום: קוד המדינה שאוחזר מLocationManager ספק המיקום המשולב.
6. קוד המדינה שמוגדר כברירת מחדל על ידי יצרן המכשיר.

אם מסגרת ה-UWB לא מצליחה לקבוע קוד מדינה של UWB, היא קוראת לפקודת ה-UCI‏ ANDROID_SET_COUNTRY_CODE עם הערך 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 מגדירה קוד מדינה חדש באמצעות פקודת ה-UCI‏ ANDROID_SET_COUNTRY_CODE. בהתאם לקוד הסטטוס שמוחזר על ידי בקר ה-UWB (בהתבסס על תקנות ה-UWB במדינה החדשה), יכול להיות שיוביל לשינוי במצב מחסנית ה-UWB.

פורמט הפקודות שמוגדר במפרט FIRA UCI

למידע על הפורמט של מנות בקרה של UCI, אפשר לעיין בסעיף 4.4.2 במפרט של UCI.

ניהול גרסאות של הממשק

מפרט ה-UCI מאפשר לספקי UWB לחשוף את הגרסה של מחסנית ה-UCI שהוטמעה במכשיר באמצעות הפקודות UCI_GET_DEVICE_INFO_RSP ו-UCI_GET_CAPS_INFO_RSP. המסגרת משתמשת בפקודות האלה כדי לאחזר את גרסת ה-UCI של המכשיר ולשנות את ההתנהגות שלו בהתאם.

רשימה של בקשות לשינוי (CR) בטיוטה שנתמכות על ידי מודול ה-UWB

מודול UWB בגרסה ‎ #330810000 תומך בטיוטות הבאות של CR ל-FiRa 2.0:

• CR 287
• תמיכה ב-SUS API ובמפרט UCI לממשק של מפתח דיגיטלי של CCC דרישות

ממשק Android UCI (החלק של ספק FiRa)

במפרט UCI מוגדרת קבוצה של מזהי קבוצה (GID) ומזהי אופקוד (OID) לכל ההודעות שמוגדרות במפרט. במפרט מוגדר גם סט של GID ששמורים לשימוש הספקים בלבד. במערך ה-UWB של AOSP נעשה שימוש בחלק מהמזהים האלה של ספקים ושל OID עבור פקודות ספציפיות ל-Android שלא מוגדרות במפרט. פרטים נוספים מופיעים בקטע 8.4 במפרט של UCI.

ההודעות האלה של הספק שמשמשות את Android מוגדרות בחבילת android.hardware.uwb.fira_android HAL.

ניהול גרסאות של ממשק הספק

ספקי UWB צריכים לחשוף את הגרסה של חבילת android.hardware.uwb.fira_androidHAL שנתמכת במכשיר באמצעות IUwbChip.getSupportedAndroidUciVersion(). המסגרת משתמשת במידע על ניהול הגרסאות כדי לטפל בתאימות לדורות קודמים.

רשימה של מזהי GID ו-OID ב-Android

בטבלה הבאה מפורטים ה-GID וה-OID של Android. מספרי ה-GID‏ 0xE ו-0xF שמורים לשימוש של יצרני ציוד מקורי (OEM) של Android.

תוספים של ספקים להודעות שמוגדרות במפרט 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.

CORE_GET_CAPS_INFO_RSP

אלה הם ערכי ה-TLV שמוגדרים על ידי מחסנית ה-AOSP בחלק השמור לספקים של ערכי ה-TLV ב-CAPS_INFO:

• GID: 0000b (UWB core group)
• OID: 000011b (CORE_GET_CAPS_INFO_RSP)

בטבלה הבאה מפורטים הפרמטרים של הודעות לגבי יכולת UWB.

קודי סטטוס

אלה קודי הסטטוס במרחב של הספק. הם מוחזרים בתגובות של UCI (כמו SESSION_START_RSP) על ידי מערכת המשנה של UWB ‏ (UWBS).

קוד הסיבה לשינוי הסטטוס ב-SESSION_STATUS_NTF

בהמשך מפורטים קודי הסיבות לשינוי הסטטוס שמוגדרים במרחב הספק בשדה הסטטוס שמוחזר על ידי UWBS ב-SESSION_STATUS_NTF. ההתראה הזו נשלחת על ידי UWBS כשמצב ההפעלה של סשן מדידת המרחק משתנה (לדוגמה, מ-ACTIVE ל-IDLE).