ממשק UWB HAL

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

הגדרת ממשק

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

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

רשימת טיוטות של בקשות תיקון נתמכות במודול UWB

טיוטות הבקשות הבאות לתיקון (CR) עבור FiRa 2.0 נתמכות במודול UWB בגרסה 330810000:

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

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

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

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

ספקי UWB חייבים לחשוף את הגרסה של חבילת ה-HAL ‏android.hardware.uwb.fira_android שנתמכת במכשיר דרך IUwbChip.getSupportedAndroidUciVersion(). המסגרת משתמשת במידע הזה לגבי ניהול הגרסאות כדי לטפל בתאימות לאחור.

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

בטבלה הבאה מפורטים מזהי ה-GID וה-OID ל-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, או מוטמע בקוד על ידי יצרן הציוד המקורי). קוד המדינה נשלח בתור ערך של 2 בייטים שתואם לקוד המדינה לפי תקן 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 בחלק ששמור לספקי TLV ב-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 בייטים להגדרת דיווח על אבחון. מסכת הביטים הזו היא ביייט אחד ב-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)
  • 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 ביייט שמציין תמיכה בתכונה של מיזוג אנטנות.

ערכים:

  • 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

ערך של בית אחד (byte) שמציין את התמיכה בדיווח על 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 מסיבה רגולטורית.