यूडब्ल्यूबी एचएएल इंटरफ़ेस

AOSP के अल्ट्रा-वाइडबैंड (यूडब्ल्यूबी) स्टैक में, एचएएल के प्लैटफ़ॉर्म के तौर पर FiRa के तय किए गए यूसीआई इंटरफ़ेस का इस्तेमाल किया जाता है. HAL इंटरफ़ेस, UWB कमांड इंटरफ़ेस (यूसीआई) के निर्देश, जवाब, और सूचनाएं भेजने और पाने के लिए, एक अपारदर्शी पाइप (IUwbChip::sendUciMessage() और IUwbClientCallback::onUciMessage()) का इस्तेमाल करता है. Android के सभी यूडब्ल्यूबी वेंडर को 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 देश कोड को कॉन्फ़िगर करता है. इसके लिए, वेंडर-स्पेस यूसीआई कमांड ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) का इस्तेमाल किया जाता है. UWB फ़्रेमवर्क, नीचे दिए गए सोर्स का इस्तेमाल करके, UWB देश कोड का पता लगाने की कोशिश करता है. ये सोर्स प्राथमिकता के क्रम में दिए गए हैं. यूडब्ल्यूबी फ़्रेमवर्क उस पहले सोर्स पर रुक जाता है जहां देश कोड तय किया जाता है.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Android जीआईडी और ओआईडी की सूची

नीचे दी गई टेबल में Android के लिए जीआईडी और ओआईडी की सूची दी गई है. 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)
  • 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

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

वैल्यू:

  • 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 स्टैक के ज़रिए तय किए गए टीएलवी यहां दिए गए हैं:

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

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

वैल्यू:

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

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