UWB HAL ইন্টারফেস

AOSP আল্ট্রা-ওয়াইডব্যান্ড (UWB) স্ট্যাক HAL সারফেস হিসেবে FiRa-এর সংজ্ঞায়িত UCI ইন্টারফেস ব্যবহার করে। UWB কমান্ড ইন্টারফেস (UCI) কমান্ড, উত্তর ও বিজ্ঞপ্তি পাঠাতে ও পেতে HAL ইন্টারফেস একটি অপেক পাইপ (IUwbChip::sendUciMessage() ও IUwbClientCallback::onUciMessage()) ব্যবহার করে। সব Android UWB ভেন্ডরকে অবশ্যই FiRa স্পেসিফিকেশন দ্বারা নির্ধারিত সব মেসেজ সাপোর্ট করতে হবে। UWB ফ্রেমওয়ার্ক ব্যাকওয়ার্ড কম্প্যাটিবল এবং ডিভাইসে UWB ভেন্ডরের মাধ্যমে প্রয়োগ করা যেকোনও UCI ভার্সনের সাথে কাজ করে। AOSP UWB ফ্রেমওয়ার্ক একটি মডিউল হওয়ায়, এটি মেজর FiRa স্ট্যান্ডার্ড রিলিজের জন্য টার্গেট করা ড্রাফ্ট UCI স্পেসিফিকেশন থেকে অনুমোদিত পরিবর্তন সংক্রান্ত অনুরোধের (CR) জন্য বেছে বেছে সহায়তা যোগ করতে পারে। এই ধরনের প্রয়োগ করা যেকোনও ড্রাফ্ট CR পরিবর্তন করা হতে পারে।

ইন্টারফেসের সংজ্ঞা

UWB HAL ইন্টারফেস স্থিতিশীল 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);

}

UWB ফ্রেমওয়ার্ক থেকে HAL কল ফ্লো

UWB স্ট্যাক ইনিশিয়ালাইজেশন, UWB স্ট্যাক ডিইনিশিয়ালাইজেশন এবং UWB সেশন শুরু ও বন্ধ করার প্রসেসের জন্য UWB ফ্রেমওয়ার্ক থেকে কল ফ্লোকে নিম্নলিখিত ছবিগুলি ব্যাখ্যা করে।

UWB স্ট্যাক ইনিশিয়ালাইজেশন

ছবি ১. UWB স্ট্যাক ইনিশিয়ালাইজেশন কল ফ্লো (UWB টগল চালু আছে)

UWB স্ট্যাক ডিইনিশিয়ালাইজেশন

ছবি ২. UWB স্ট্যাক ডিইনিশিয়ালাইজেশন কল ফ্লো (UWB টগল বন্ধ)

UWB সেশন শুরু ও বন্ধ করা

ছবি ৩. UWB সেশন শুরু/বন্ধ করার ফ্লো

UWB কান্ট্রি কোড কনফিগারেশন

ছবি ১-এ দেখানো হয়েছে, UWB ফ্রেমওয়ার্ক, UWB স্ট্যাক ইনিশিয়ালাইজ করার সময় ভেন্ডর-স্পেস UCI কমান্ড ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) ব্যবহার করে UWB কান্ট্রি কোড কনফিগার করে। UWB ফ্রেমওয়ার্ক নিম্নলিখিত সোর্স ব্যবহার করে UWB কান্ট্রি কোড নির্ধারণ করার চেষ্টা করে (অগ্রাধিকারের ক্রম অনুসারে তালিকাভুক্ত)। যে সোর্সে কান্ট্রি কোড নির্ধারণ করা হয়, UWB ফ্রেমওয়ার্ক সেখানে থেমে যায়।

  1. ওভাররাইড কান্ট্রি কোড: adb শেল কমান্ডের মাধ্যমে জোর করে প্রয়োগ করা কান্ট্রি কোড (স্থানীয় বা অটোমেটেড টেস্টিং)।
  2. টেলিফোনি কান্ট্রি কোড: সেলুলারের মাধ্যমে কান্ট্রি কোড পাওয়া গেছে। একাধিক সিম কার্ড থাকলে এবং সেগুলি আলাদা আলাদা কোড দেখালে, বেছে নেওয়া দেশের কোড নির্ধারণ করা যায় না।
  3. ওয়াই-ফাই কান্ট্রি কোড: ওয়াই-ফাই (80211.ad) থেকে পাওয়া কান্ট্রি কোড।
  4. শেষ জানা টেলিফোনি কান্ট্রি কোড: সেলুলারের মাধ্যমে শেষ জানা কান্ট্রি কোড উদ্ধার করা হয়েছে। একাধিক সিম কার্ড থেকে আলাদা আলাদা কোড পাওয়া গেলে, বেছে নেওয়া দেশের কোডটি অনির্দিষ্ট হয়।
  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 কন্ট্রোল প্যাকেটের ফর্ম্যাটের জন্য, UCI স্পেসিফিকেশনের 4.4.2 বিভাগ দেখুন।

ইন্টারফেস ভার্সনিং

UCI স্পেসিফিকেশন UWB ভেন্ডরদের UCI_GET_DEVICE_INFO_RSP এবং UCI_GET_CAPS_INFO_RSP কমান্ড ব্যবহার করে ডিভাইসের মাধ্যমে প্রয়োগ করা UCI স্ট্যাকের ভার্সন প্রকাশ করতে দেয়। ফ্রেমওয়ার্ক এইসব কমান্ড ব্যবহার করে ডিভাইসের UCI ভার্সন ফেচ করে এবং সেই অনুযায়ী এর আচরণ পরিবর্তন করে।

UWB মডিউলে কাজ করে এমন ড্রাফ্ট CR-এর তালিকা

FiRa 2.0-এর জন্য নিম্নলিখিত ড্রাফ্ট CR, UWB মডিউল ভার্সন #330810000-এ কাজ করে:

Android UCI ইন্টারফেস (FiRa ভেন্ডর অংশ)

UCI স্পেসিফিকেশন, স্পেসিফিকেশন-সংজ্ঞায়িত সব মেসেজের জন্য গ্রুপ আইডেন্টিফায়ার (GID) এবং ওপকোড আইডেন্টিফায়ারের (OID) একটি সেট সংজ্ঞায়িত করে। এছাড়াও, স্পেসিফিকেশন একমাত্র ভেন্ডর ব্যবহারের জন্য সংরক্ষিত GID-এর একটি সেট রিজার্ভ করে। AOSP UWB স্ট্যাক, Android-নির্দিষ্ট কমান্ডের জন্য ভেন্ডর GID ও OID-এর কিছু অংশ ব্যবহার করে যা স্পেসিফিকেশনে উল্লেখ করা নেই। আরও বিবরণের জন্য, UCI-এর স্পেসিফিকেশনের ৮.৪ বিভাগ দেখুন।

Android-এর ব্যবহার করা এইসব ভেন্ডর মেসেজ android.hardware.uwb.fira_android HAL প্যাকেজে সংজ্ঞায়িত করা আছে।

ভেন্ডর ইন্টারফেস ভার্সনিং

UWB ভেন্ডরদের অবশ্যই android.hardware.uwb.fira_android HAL প্যাকেজের ভার্সন প্রকাশ করতে হবে যা ডিভাইসে IUwbChip.getSupportedAndroidUciVersion() কাজ করে। ব্যাকওয়ার্ড কম্প্যাটিবিলিটি ম্যানেজ করার জন্য ফ্রেমওয়ার্ক এই ভার্সনিং সংক্রান্ত তথ্য ব্যবহার করে।

Android GID ও OID-এর তালিকা

নিচের সারণীতে Android-এর জন্য GID ও OID-এর তালিকা দেওয়া হল। GID 0xE এবং 0xF Android OEM-এর ব্যবহারের জন্য রিজার্ভ করা আছে।

GID OID সংজ্ঞা
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 UWB পাওয়ার সংক্রান্ত পরিসংখ্যান পেতে কমান্ড ও রেসপন্স ব্যবহার করে। শুধুমাত্র তখনই কাজ করে যদি UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY 1-এ সেট করা থাকে।
ANDROID_SET_COUNTRY_CODE = 0x1

বর্তমান রেগুলেশন সংক্রান্ত দেশের কোড সেট করতে ব্যবহৃত হয় (SIM বা ওয়াই-ফাই অথবা OEM-এর হার্ডকোড ব্যবহার করে নির্ধারণ করা হয়)। দেশের কোডটি ISO-3166 দেশের কোডের সাথে সম্পর্কিত ২ বাইট ভ্যালু হিসেবে পাঠানো হয়। A 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]

APP_CONFIG-এ AOSP স্ট্যাকের দ্বারা সংজ্ঞায়িত নিম্নলিখিত টাইপ লেন্থ ভ্যালু (TLV) হল TLV-এর ভেন্ডর রিজার্ভ করা অংশ:

  • 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 SUPPORTED_DIAGNOSTICS-এর ভ্যালু 1 সহ রিটার্ন করলে তবেই এই প্যারামিটার কনফিগার করুন, এর অর্থ হল ডায়াগনস্টিকস রিপোর্টিং ফিচার কাজ করে।

ভ্যালু:

  • 1: ফিচার চালু করা হয়েছে
  • 0: ফিচার বন্ধ করা আছে
DIAGRAMS_FRAME_REPORTS_FIELDS ১ বা ৪ 0xE9 2

ডায়াগনস্টিক রিপোর্টিং কনফিগার করতে ১-বাইট বা ৪-বাইট বিটমাস্ক। এই বিটমাস্ক Android 14 বা এর পরের যেকোনও ভার্সনে ১ বাইট এবং Android 13 বা এর আগের যেকোনও ভার্সনে ৪ বাইট।

এই প্যারামিটার তখনই কনফিগার করুন যখন CORE_GET_CAPS_INFO_RSP 1 ভ্যালু সহ SUPPORTED_DIAGNOSTICS রিটার্ন করে যা থেকে বোঝা যায় যে ডায়াগনস্টিকস রিপোর্টিং ফিচার কাজ করে।

বিটের সংজ্ঞা:

  • b0 (0x01): RSSI ফিল্ড অ্যাক্টিভেট করুন
  • b1 (0x02): AoA ফিল্ড অ্যাক্টিভেট করা
  • b2 (0x04): CIR ফিল্ড অ্যাক্টিভেট করা

CORE_GET_CAPS_INFO_RSP

CAPS_INFO-এর ভেন্ডর রিজার্ভ করা অংশে AOSP স্ট্যাকের দ্বারা নির্ধারিত TLV নিচে দেওয়া হল:

  • GID: 0000b (UWB কোর গ্রুপ)
  • 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 ভ্যালু দেখায়। বিটমাস্ক যেখানে প্রতিটি বিট RANGE_DATA_NTF_CONFIG-এ ব্যবহৃত ভ্যালুর সাথে সম্পর্কিত SET_APP_CFG_CMD।
SUPPORTED_RSSI_REPORTING 1 0xE6 2

RSSI রিপোর্টিং কাজ করে কিনা তা ১ বাইট ভ্যালু থেকে বোঝা যায়।

ভ্যালু:

  • 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: চ্যানেল ৫ কাজ করে
  • 0x02: চ্যানেল ৬ কাজ করে
  • 0x04: চ্যানেল ৮ কাজ করে
  • 0x08: চ্যানেল ৯ কাজ করে
  • 0x10: চ্যানেল ১০ কাজ করে
  • 0x20: চ্যানেল ১২ কাজ করে
  • 0x40: চ্যানেল ১৩ কাজ করে
  • 0x80: চ্যানেল ১৪ কাজ করে

স্ট্যাটাস কোড

ভেন্ডর স্পেসে নিম্নলিখিত স্ট্যাটাস কোড থাকে। এগুলি UWB সাবসিস্টেম (UWBS) দ্বারা UCI উত্তরে (যেমন SESSION_START_RSP) ফেরত দেওয়া হয়।

স্ট্যাটাস কোড মান বর্ণনা
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

অন্য CCC বা FiRa রেঞ্জিং সেশনের সাথে বিরোধের কারণে বর্তমান রেঞ্জিং সেশন শুরু করা না গেলে স্ট্যাটাস কোড রিটার্ন করা হয়।
STATUS_REGULATION_UWB_OFF 0x53

UWB রেগুলেশন সংক্রান্ত কারণে বর্তমান রেঞ্জিং সেশন শুরু করা না গেলে এই স্ট্যাটাস কোড ফেরত দেওয়া হয়।

SESSION_STATUS_NTF-এ স্টেট পরিবর্তন করার কারণ সংক্রান্ত কোড

UWBS-এর মাধ্যমে SESSION_STATUS_NTF-এ রিটার্ন করা স্ট্যাটাস ফিল্ডের জন্য ভেন্ডর স্পেসে নিম্নলিখিত স্ট্যাটাস পরিবর্তন সংক্রান্ত কারণ কোডগুলি সংজ্ঞায়িত করা হয়েছে। রেঞ্জিং সেশনের স্টেট পরিবর্তন হলে (যেমন, ACTIVE থেকে IDLE) UWBS এই বিজ্ঞপ্তি পাঠায়।

স্ট্যাটাস পরিবর্তনের কারণ কোড মান বর্ণনা
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 বন্ধ করতে হবে বলে সেশন স্টেট পরিবর্তন করা হয়েছে।