ממשק UWB HAL

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

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

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

התגובות המוכנות מראש הבאות ל-FiRa 2.0 נתמכות במודול UWB בגרסה 330810000:

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

במפרט UCI מוגדר קבוצה של מזהי קבוצות (GID) ומזהי opcode (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(). ה-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 שמורה לשימוש של יצרני ציוד מקורי.

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