UWB HAL इंटरफ़ेस

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

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

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

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

UWB स्टैक को शुरू करना

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

UWB स्टैक को डी-इनिशियलाइज़ करना

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

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

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

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

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

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

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

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

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

FIRA UCI स्पेसिफ़िकेशन के मुताबिक निर्देश का फ़ॉर्मैट

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

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

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

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

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

Android यूसीआई इंटरफ़ेस (FiRa वेंडर का हिस्सा)

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

Android के ज़रिए इस्तेमाल किए जाने वाले वेंडर मैसेज, android.hardware.uwb.fira_android HAL पैकेज में बताए गए हैं.

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

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

Android GID और OID की सूची

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

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

इसका इस्तेमाल, देश के मौजूदा रेगुलेटरी कोड को सेट करने के लिए किया जाता है. यह कोड, सिम या वाई-फ़ाई का इस्तेमाल करके तय किया जाता है या OEM ने इसे हार्डकोड किया होता है. देश का कोड, आईएसओ-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]

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

  • GID: 0001b (UWB सेशन कॉन्फ़िगरेशन ग्रुप)
  • OID: 000011b (SESSION_SET_APP_CONFIG_CMD)
  • ओआईडी: 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

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

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

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

CORE_GET_CAPS_INFO_RSP

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

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

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

पैरामीटर का नाम लंबाई
(ऑक्टेट)		 टैग
(आईडी)		 वेंडर इंटरफ़ेस का वर्शन ब्यौरा
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 इस्तेमाल की जा सकने वाली 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: सुविधा काम करती है
  • 0: यह सुविधा काम नहीं करती
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 चार बाइट की वैल्यू, जो RSTU में इस्तेमाल की जा सकने वाली स्लॉट की कम से कम अवधि दिखाती है.
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2 चार बाइट की वैल्यू, जो FiRa रेंजिंग के लिए इस्तेमाल किए जा सकने वाले सबसे ज़्यादा सेशन की संख्या दिखाती है.
SUPPORTED_CHANNELS_AOA 2 0xEA 2

AoA की सुविधा वाले चैनलों के बारे में बताने के लिए, दो बाइट का बिटमास्क. बिटमास्क में मौजूद हर 1, किसी खास UWB चैनल से जुड़ा होता है.

वैल्यू:

  • 0x01: Channel 5 पर काम करता है
  • 0x02: चैनल 6 के साथ काम करता है
  • 0x04: चैनल 8 के साथ काम करता है
  • 0x08: Channel 9 के साथ काम करता है
  • 0x10: चैनल 10 के साथ काम करता है
  • 0x20: चैनल 12 के साथ काम करता है
  • 0x40: चैनल 13 के साथ काम करता है
  • 0x80: चैनल 14 के साथ काम करता है

स्टेटस कोड

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

स्टेटस कोड वैल्यू ब्यौरा
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

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

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

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

अन्य सीसीसी या FiRa रेंजिंग सेशन के साथ होने वाली गड़बड़ी की वजह से, सेशन की स्थिति बदल गई.
REASON_REGULATION_UWB_OFF 0x82

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