ממשק UWB HAL

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

הגדרת הממשק

ממשק UWB HAL מוגדר באמצעות 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 framework

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

רשימה של טיוטות של תגובות מוכנות מראש שנתמכות על ידי מודול ה-UWB

טיוטות התגובה המוכנה מראש הבאות עבור FiRa 2.0 נתמכות על ידי גרסה מס' 330810000 של מודול UWB:

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

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

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

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

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

רשימת מזהי 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, או בקידוד קשיח על ידי ה-OEM). קוד המדינה נשלח כערך של 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]

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

אלה רכיבי ה-TLV שהוגדרו על ידי סטאק AOSP בספק השמור החלק של מלאי המוצרים (TLV) ב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 ערכים. Bitmask שבה כל ביט תואם לערכים שבהם נעשה שימוש RANGE_DATA_NTF_CONFIG בSET_APP_CFG_CMD.
SUPPORTED_RSSI_REPORTING 1 0xE6 2

ערך של 1 בייט שמציין תמיכה בדיווח RSSI.

ערכים:

  • 1: יש תמיכה בתכונות
  • 0: התכונה לא נתמכת
SUPPORTED_DIAGNOSTICS 1 0xE7 2

ערך של 1 בייט שמציין תמיכה בדיווח על אבחון.

ערכים:

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