UWB HAL इंटरफ़ेस

AOSP का अल्ट्रा-वाइडबैंड (यूडब्ल्यूबी) स्टैक, एचएएल लेयर के तौर पर FiRa की ओर से तय किए गए यूसीआई इंटरफ़ेस का इस्तेमाल करता है. एचएएल इंटरफ़ेस, यूडब्ल्यूबी कमांड इंटरफ़ेस (यूसीआई) कमांड, जवाब, और सूचनाएँ भेजने और पाने के लिए, ओपेक पाइप (IUwbChip::sendUciMessage() और IUwbClientCallback::onUciMessage()) का इस्तेमाल करता है. Android UWB के सभी वेंडर को, FiRa की शर्तों के मुताबिक तय किए गए सभी मैसेज के साथ काम करना होगा. यूडब्ल्यूबी फ़्रेमवर्क, Android के पुराने वर्शन के साथ काम करता है. साथ ही, यह यूसीआई के किसी भी वर्शन के साथ काम करता है. यूसीआई का यह वर्शन, यूडब्ल्यूबी वेंडर ने डिवाइस पर लागू किया हो. AOSP UWB फ़्रेमवर्क एक मॉड्यूल है. इसलिए, यह FiRa के मुख्य स्टैंडर्ड रिलीज़ के लिए टारगेट किए गए ड्राफ़्ट यूसीआई स्पेसिफ़िकेशन से, मंज़ूर किए गए बदलाव के अनुरोधों (सीआर) के लिए भी सहायता जोड़ सकता है. लागू किए गए ऐसे किसी भी ड्राफ़्ट सीआर में बदलाव किया जा सकता है.

इंटरफ़ेस की परिभाषा

यूडब्ल्यूबी एचएएल इंटरफ़ेस को स्टेबल एआईडीएल का इस्तेमाल करके तय किया जाता है. मुख्य इंटरफ़ेस, 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);

}

यूडब्ल्यूबी फ़्रेमवर्क से एचएएल कॉल फ़्लो

इन इमेज में, यूडब्ल्यूबी स्टैक को शुरू करने, बंद करने, और यूडब्ल्यूबी सेशन को शुरू और बंद करने की प्रोसेस के लिए, यूडब्ल्यूबी फ़्रेमवर्क से कॉल फ़्लो दिखाया गया है.

यूडब्ल्यूबी स्टैक को शुरू करना

पहली इमेज. यूडब्ल्यूबी स्टैक को शुरू करने के लिए कॉल फ़्लो (यूडब्ल्यूबी टॉगल चालू होने पर)

यूडब्ल्यूबी स्टैक को बंद करना

दूसरी इमेज. यूडब्ल्यूबी स्टैक को बंद करने के लिए कॉल फ़्लो (यूडब्ल्यूबी टॉगल बंद है)

UWB सेशन शुरू और बंद करना

तीसरी इमेज. UWB सेशन शुरू/बंद करने का फ़्लो

UWB देश के कोड का कॉन्फ़िगरेशन

पहले फ़िगर में दिखाया गया है कि UWB फ़्रेमवर्क, UWB स्टैक के शुरू होने के दौरान UWB देश के कोड को कॉन्फ़िगर करता है. इसके लिए, वेंडर-स्पेस वाली UCI कमांड ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) का इस्तेमाल किया जाता है. UWB फ़्रेमवर्क, UWB देश के कोड का पता लगाने की कोशिश करता है. इसके लिए, इन सोर्स का इस्तेमाल किया जाता है. इन्हें प्राथमिकता के क्रम में दिखाया गया है. यूडब्ल्यूबी फ़्रेमवर्क, उस पहले सोर्स पर रुक जाता है जहां देश का कोड तय किया जाता है.

  1. देश के कोड को बदलें: adb shell कमांड के ज़रिए देश के कोड को बदला गया है (लोकल या ऑटोमेटेड टेस्टिंग).
  2. टेलीफ़ोनी देश का कोड: यह कोड, मोबाइल नेटवर्क से मिलता है. अगर एक से ज़्यादा सिम कार्ड अलग-अलग कोड दिखाते हैं, तो देश का कोड चुनने का कोई तय तरीका नहीं होता.
  3. वाई-फ़ाई का देश कोड: वाई-फ़ाई (80211.ad) से मिला देश कोड.
  4. टेलीफ़ोनी का आखिरी बार इस्तेमाल किया गया देश कोड: यह वह देश कोड है जिसे मोबाइल नेटवर्क के ज़रिए पिछली बार ऐक्सेस किया गया था. अगर एक से ज़्यादा सिम कार्ड अलग-अलग कोड दिखाते हैं, तो देश का कोड चुनने का कोई तय तरीका नहीं होता.
  5. जगह का देश कोड: यह कोड, LocationManager कई तरह से जांची गई सही जगह की जानकारी देने वाला एपीआई से मिला है.
  6. ओईएम का डिफ़ॉल्ट देश कोड: डिवाइस बनाने वाली कंपनी की ओर से सेट किया गया देश कोड.

अगर UWB फ़्रेमवर्क, UWB देश का कोड तय नहीं कर पाता है, तो वह ANDROID_SET_COUNTRY_CODE UCI कमांड को DEFAULT_COUNTRY_CODE ("00") वैल्यू के साथ कॉल करता है. साथ ही, UWB ऐप्लिकेशन को सूचना देता है कि UWB स्टैक की स्थिति DISABLED है. बाद में, जब UWB फ़्रेमवर्क, देश का मान्य कोड पता कर लेता है, तब वह ANDROID_SET_COUNTRY_CODE कमांड का इस्तेमाल करके, देश के नए कोड को कॉन्फ़िगर करता है. साथ ही, UWB ऐप्लिकेशन को सूचना देता है कि UWB स्टैक READY है.

अगर किसी देश में स्थानीय कानूनों की वजह से, यूडब्ल्यूबी का इस्तेमाल नहीं किया जा सकता, तो यूडब्ल्यूबी कंट्रोलर, STATUS_CODE_ANDROID_REGULATION_UWB_OFF स्टेटस कोड दिखाता है. इसके बाद, यूडब्ल्यूबी फ़्रेमवर्क, यूडब्ल्यूबी ऐप्लिकेशन को सूचना देता है कि यूडब्ल्यूबी स्टैक की स्थिति DISABLED है.

जब कोई व्यक्ति किसी दूसरे देश की यात्रा करता है, तो यूडब्ल्यूबी फ़्रेमवर्क, ANDROID_SET_COUNTRY_CODE यूसीआई कमांड का इस्तेमाल करके नया देश कोड कॉन्फ़िगर करता है. यूडब्ल्यूबी कंट्रोलर से मिले स्टेटस कोड के आधार पर, यूडब्ल्यूबी स्टैक की स्थिति में बदलाव हो सकता है. यह स्टेटस कोड, नए देश में यूडब्ल्यूबी से जुड़े नियमों के आधार पर मिलता है.

FIRA UCI स्पेसिफ़िकेशन में तय किए गए निर्देश का फ़ॉर्मैट

यूसीआई कंट्रोल पैकेट के फ़ॉर्मैट के लिए, यूसीआई स्पेसिफ़िकेशन का सेक्शन 4.4.2 देखें.

इंटरफ़ेस का वर्शन

यूसीआई स्पेसिफ़िकेशन की मदद से, यूडब्ल्यूबी वेंडर, डिवाइस में लागू किए गए यूसीआई स्टैक के वर्शन को दिखा सकते हैं. इसके लिए, उन्हें UCI_GET_DEVICE_INFO_RSP और UCI_GET_CAPS_INFO_RSP कमांड का इस्तेमाल करना होगा. फ़्रेमवर्क इन कमांड का इस्तेमाल करके, डिवाइस के यूसीआई वर्शन को फ़ेच करता है और उसके हिसाब से डिवाइस के व्यवहार में बदलाव करता है.

UWB मॉड्यूल के साथ काम करने वाले ड्राफ़्ट सीआर की सूची

FiRa 2.0 के लिए, ड्राफ़्ट किए गए इन सीआर को UWB मॉड्यूल के वर्शन #330810000 के साथ इस्तेमाल किया जा सकता है:

Android UCI इंटरफ़ेस (FiRa वेंडर का हिस्सा)

यूसीआई स्पेसिफ़िकेशन, स्पेसिफ़िकेशन में तय किए गए सभी मैसेज के लिए, ग्रुप आइडेंटिफ़ायर (GID) और ऑपकोड आइडेंटिफ़ायर (OID) का सेट तय करता है. इस स्पेसिफ़िकेशन में, वेंडर के इस्तेमाल के लिए खास तौर पर आरक्षित किए गए GID का एक सेट भी शामिल है. AOSP UWB स्टैक, Android के लिए खास तौर पर तैयार की गई कुछ कमांड के लिए, वेंडर के इन GID और OID का इस्तेमाल करता है. हालांकि, इन्हें स्पेसिफ़िकेशन में तय नहीं किया गया है. ज़्यादा जानकारी के लिए, यूसीआई की खास बातों का सेक्शन 8.4 देखें.

Android में इस्तेमाल किए जाने वाले वेंडर के इन मैसेज को android.hardware.uwb.fira_android एचएएल पैकेज में तय किया गया है.

वेंडर इंटरफ़ेस वर्शनिंग

यूडब्ल्यूबी वेंडर को, डिवाइस पर काम करने वाले android.hardware.uwb.fira_android HAL पैकेज का वर्शन IUwbChip.getSupportedAndroidUciVersion() के ज़रिए दिखाना होगा. फ़्रेमवर्क, वर्शन की इस जानकारी का इस्तेमाल, पुराने सिस्टम के साथ काम करने की सुविधा को मैनेज करने के लिए करता है.

Android GID और OID की सूची

यहां दी गई टेबल में, Android के लिए GID और OID दिए गए हैं. GID 0xE और 0xF, Android ओईएम के इस्तेमाल के लिए रिज़र्व किए गए हैं.

GID ओआईडी परिभाषा
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 इस कुकी का इस्तेमाल कमांड और जवाब देने के लिए किया जाता है, ताकि UWB की पावर से जुड़े आंकड़े मिल सकें. यह सुविधा सिर्फ़ तब काम करती है, जब UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY को 1 पर सेट किया गया हो.
ANDROID_SET_COUNTRY_CODE = 0x1

इस कुकी का इस्तेमाल, देश के मौजूदा कानूनी कोड को सेट करने के लिए किया जाता है. यह कोड, सिम या वाई-फ़ाई का इस्तेमाल करके या ओईएम के ज़रिए हार्डकोड करके तय किया जाता है. देश का कोड, आईएसओ-3166 देश के कोड के हिसाब से दो बाइट की वैल्यू के तौर पर भेजा जाता है. 00 की वैल्यू का इस्तेमाल यह दिखाने के लिए किया जाता है कि देश का कोड पता नहीं है.
ANDROID_RANGE_DIAGNOSTICS = 0x2 इस कुकी का इस्तेमाल सूचना देने वाली सुविधा करती है, ताकि UWB रेंजिंग के डाइग्नोस्टिक्स के आंकड़े मिल सकें. यह सुविधा सिर्फ़ तब काम करती है, जब UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS को 1 पर सेट किया गया हो.
OEM = 0xE,0xF 0x00 - 0x3F इसे ओईएम के इस्तेमाल के लिए रिज़र्व किया गया है.

यूसीआई स्पेसिफ़िकेशन के हिसाब से तय किए गए मैसेज के लिए वेंडर एक्सटेंशन

इस सेक्शन में, यूसीआई स्पेसिफ़िकेशन के हिसाब से तय किए गए मैसेज के वेंडर एक्सटेंशन के बारे में जानकारी दी गई है.

SESSION_SET_APP_CONFIG_[CMD|RSP] और SESSION_GET_APP_CONFIG_[CMD|RSP]

यहां, AOSP स्टैक के ज़रिए तय की गई टाइप लेंथ वैल्यू (टीएलवी) दी गई हैं. ये टीएलवी, APP_CONFIG में मौजूद टीएलवी के वेंडर के लिए रिज़र्व किए गए हिस्से में मौजूद होती हैं:

  • GID: 0001b (UWB सेशन कॉन्फ़िगरेशन ग्रुप)
  • ओआईडी: 000011b (SESSION_SET_APP_CONFIG_CMD)
  • ओआईडी: 000100b (SESSION_GET_APP_CONFIG_CMD)

इस टेबल में, यूडब्ल्यूबी सेशन कॉन्फ़िगरेशन मैसेज के पैरामीटर दिए गए हैं.

पैरामीटर का नाम लंबाई
(ऑक्टेट)		 टैग
(आईडी)		 वेंडर इंटरफ़ेस का वर्शन ब्यौरा
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 या उसके बाद के वर्शन में 1 बाइट का होता है. वहीं, Android 13 या उससे पहले के वर्शन में यह 4 बाइट का होता है.

इस पैरामीटर को सिर्फ़ तब कॉन्फ़िगर करें, जब CORE_GET_CAPS_INFO_RSP, SUPPORTED_DIAGNOSTICS के साथ 1 वैल्यू दिखाता हो. इससे पता चलता है कि डायग्नोस्टिक्स रिपोर्टिंग की सुविधा काम करती है.

बिट की परिभाषाएं:

  • b0 (0x01): आरएसएसआई फ़ील्ड चालू करें
  • b1 (0x02): AoA फ़ील्ड चालू करें
  • b2 (0x04): सीआईआर फ़ील्ड चालू करें

CORE_GET_CAPS_INFO_RSP

यहां दिए गए टीएलवी, CAPS_INFO में वेंडर के लिए रिज़र्व किए गए टीएलवी के हिस्से में, एओएसपी स्टैक के ज़रिए तय किए जाते हैं:

  • GID: 0000b (यूडब्ल्यूबी कोर ग्रुप)
  • ओआईडी: 000011b (CORE_GET_CAPS_INFO_RSP)

यहां दी गई टेबल में, यूडब्ल्यूबी की सुविधा वाले मैसेज के पैरामीटर दिए गए हैं.

पैरामीटर का नाम लंबाई
(ऑक्टेट)		 टैग
(आईडी)		 वेंडर इंटरफ़ेस का वर्शन ब्यौरा
SUPPORTED_POWER_STATS_QUERY 1 0xC0 1

यह एक बाइट की वैल्यू होती है. इससे पता चलता है कि पावर स्टैट्स क्वेरी की सुविधा उपलब्ध है या नहीं.

वैल्यू:

  • 1: यह सुविधा काम करती है
  • 0: यह सुविधा काम नहीं करती
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

एक बाइट की वैल्यू, जो एंटीना इंटरलीविंग की सुविधा के बारे में बताती है.

वैल्यू:

  • 1: यह सुविधा काम करती है
  • 0: यह सुविधा काम नहीं करती
SUPPORTED_MIN_RANGING_INTERVAL_MS 4 0xE4 2 यह चार बाइट की वैल्यू होती है. इससे पता चलता है कि रेंजिंग के लिए कम से कम कितने मिलीसेकंड का इंटरवल इस्तेमाल किया जा सकता है.
SUPPORTED_RANGE_DATA_NTF_CONFIG 4 0xE5 2 यह 4 बाइट का बिटमास्क होता है. इससे RANGE_DATA_NTF_CONFIG की इस्तेमाल की जा सकने वाली वैल्यू के बारे में पता चलता है. बिटमास्क, जहां हर बिट, SET_APP_CFG_CMD में RANGE_DATA_NTF_CONFIG में इस्तेमाल की गई वैल्यू से मेल खाता है.
SUPPORTED_RSSI_REPORTING 1 0xE6 2

यह एक बाइट की वैल्यू होती है. इससे पता चलता है कि आरएसएसआई रिपोर्टिंग की सुविधा उपलब्ध है या नहीं.

वैल्यू:

  • 1: यह सुविधा काम करती है
  • 0: यह सुविधा काम नहीं करती
SUPPORTED_DIAGNOSTICS 1 0xE7 2

यह 1 बाइट की वैल्यू होती है. इससे पता चलता है कि डाइग्नोस्टिक्स रिपोर्टिंग की सुविधा उपलब्ध है या नहीं.

वैल्यू:

  • 1: यह सुविधा काम करती है
  • 0: यह सुविधा काम नहीं करती
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 यह चार बाइट की वैल्यू होती है. इससे RSTU में, कम से कम कितने समय के लिए स्लॉट बुक किया जा सकता है, यह पता चलता है.
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2 यह 4 बाइट की वैल्यू है. इससे पता चलता है कि FiRa रेंजिंग के ज़्यादा से ज़्यादा कितने सेशन इस्तेमाल किए जा सकते हैं.
SUPPORTED_CHANNELS_AOA 2 0xEA 2

यह दो बाइट का बिटमास्क होता है. इससे उन चैनलों के बारे में पता चलता है जो AoA के साथ काम करते हैं. बिटमास्क में मौजूद हर 1, किसी खास यूडब्ल्यूबी चैनल से मेल खाता है.

वैल्यू:

  • 0x01: Channel 5 पर उपलब्ध है
  • 0x02: चैनल 6 के साथ काम करता है
  • 0x04: Channel 8 की सुविधा उपलब्ध है
  • 0x08: Channel 9 के साथ काम करता है
  • 0x10: Channel 10 पर काम करता है
  • 0x20: चैनल 12 पर काम करता है
  • 0x40: चैनल 13 पर काम करता है
  • 0x80: Channel 14 supported

स्टेटस कोड

वेंडर स्पेस में ये स्टेटस कोड मौजूद हैं. इन्हें यूडब्ल्यूबी सबसिस्टम (UWBS) से, यूसीआई रिस्पॉन्स (जैसे कि SESSION_START_RSP) में दिखाया जाता है.

स्टेटस कोड मान ब्यौरा
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

यह स्टेटस कोड तब दिखता है, जब अन्य CCC या FiRa रेंजिंग सेशन के साथ टकराव की वजह से, मौजूदा रेंजिंग सेशन शुरू नहीं किया जा सकता.
STATUS_REGULATION_UWB_OFF 0x53

यह स्टेटस कोड तब दिखता है, जब यूडब्ल्यूबी से जुड़े कानूनी नियमों का पालन न करने की वजह से, रेंजिंग का मौजूदा सेशन शुरू नहीं किया जा सकता.

SESSION_STATUS_NTF में स्थिति बदलने की वजह का कोड

यहां वेंडर स्पेस में, स्थिति में बदलाव की वजह बताने वाले कोड दिए गए हैं. ये कोड, SESSION_STATUS_NTF में UWBS से मिले स्टेटस फ़ील्ड के लिए हैं. यह सूचना, 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

नियमों से जुड़ी किसी वजह से, यूडब्ल्यूबी को बंद करना ज़रूरी है. इसलिए, सेशन की स्थिति बदल गई है.