ממשק HAL של UWB

מערך (stack) של Ultra Wideband ‏(UWB) ב-AOSP משתמש בממשק UCI שהוגדר על ידי FiRa כמשטח 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 stack (המתג 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. קוד המדינה שמוגדר כברירת מחדל על ידי יצרן הציוד המקורי (OEM): קוד המדינה שהוגדר על ידי יצרן המכשיר.

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

אלה ערכי האורך של הסוג (TLVs) שמוגדרים על ידי מחסנית AOSP בחלק השמור של הספק ב-TLVs ב-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).