رابط UWB HAL

پشته فوق پهن‌باند (UWB) AOSP از رابط UCI تعریف‌شده توسط FiRa به عنوان سطح HAL استفاده می‌کند. رابط HAL از یک لوله مات ( IUwbChip::sendUciMessage() و IUwbClientCallback::onUciMessage() ) برای ارسال و دریافت دستورات، پاسخ‌ها و اعلان‌های رابط فرمان UWB (UCI) استفاده می‌کند. همه فروشندگان UWB اندروید باید از تمام پیام‌های تعریف‌شده با مشخصات FiRa پشتیبانی کنند. چارچوب UWB با نسخه‌های قبلی سازگار است و با هر نسخه UCI پیاده‌سازی‌شده توسط فروشنده UWB روی دستگاه کار می‌کند. از آنجا که چارچوب UWB AOSP یک ماژول است، می‌تواند به صورت انتخابی از درخواست‌های تغییر تأییدشده (CR) از پیش‌نویس مشخصات UCI که برای انتشار استانداردهای اصلی FiRa هدف‌گذاری شده‌اند، پشتیبانی کند. هرگونه پیش‌نویس 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);

}

جریان تماس HAL از چارچوب UWB

تصاویر زیر جریان تماس از چارچوب UWB را برای فرآیندهای مقداردهی اولیه پشته UWB، مقداردهی اولیه مجدد پشته UWB و شروع و توقف جلسه UWB نشان می‌دهد.

مقداردهی اولیه پشته UWB

شکل 1. جریان فراخوانی مقداردهی اولیه پشته UWB (فعال کردن UWB)

غیرمقداردهی اولیه پشته UWB

شکل ۲. جریان فراخوانی مقداردهی اولیه پشته UWB (غیرفعال کردن UWB)

شروع و توقف جلسه UWB

شکل 3. جریان شروع/توقف جلسه UWB

پیکربندی کد کشور UWB

همانطور که در شکل 1 نشان داده شده است، چارچوب UWB کد کشور UWB را در طول مقداردهی اولیه پشته UWB با استفاده از دستور ANDROID_SET_COUNTRY_CODE (GID= 0xC , OID= 0x1 ) در فضای فروشنده UCI پیکربندی می‌کند. چارچوب UWB تلاش می‌کند تا کد کشور UWB را با استفاده از منابع زیر (که به ترتیب اولویت فهرست شده‌اند) تعیین کند. چارچوب UWB در اولین منبعی که کد کشور تعیین می‌شود، متوقف می‌شود.

  1. نادیده گرفتن کد کشور: کد کشور از طریق یک دستور adb shell (تست محلی یا خودکار) اعمال می‌شود.
  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 مراجعه کنید.

نسخه‌بندی رابط

مشخصات UCI به فروشندگان UWB اجازه می‌دهد تا نسخه پشته UCI پیاده‌سازی شده توسط دستگاه را با استفاده از دستورات UCI_GET_DEVICE_INFO_RSP و UCI_GET_CAPS_INFO_RSP افشا کنند. این چارچوب از این دستورات برای دریافت نسخه UCI دستگاه و تغییر رفتار آن بر اساس آن استفاده می‌کند.

فهرست CR های پیش نویس پشتیبانی شده توسط ماژول UWB

پیش‌نویس‌های CR زیر برای FiRa 2.0 توسط ماژول UWB نسخه #330810000 پشتیبانی می‌شوند:

رابط کاربری UCI اندروید (بخش فروشندگان FiRa)

مشخصات UCI مجموعه‌ای از شناسه‌های گروه (GID) و شناسه‌های آپ‌کد (OID) را برای همه پیام‌های تعریف‌شده توسط مشخصات تعریف می‌کند. این مشخصات همچنین مجموعه‌ای از GIDها را که منحصراً برای استفاده فروشنده رزرو شده‌اند، رزرو می‌کند. پشته AOSP UWB از برخی از این GIDها و OIDهای فروشنده برای دستورات خاص اندروید که در مشخصات تعریف نشده‌اند، استفاده می‌کند. برای جزئیات بیشتر، به بخش 8.4 مشخصات UCI مراجعه کنید.

این پیام‌های فروشنده که توسط اندروید استفاده می‌شوند، در بسته‌ی android.hardware.uwb.fira_android HAL تعریف شده‌اند.

نسخه‌بندی رابط فروشنده

فروشندگان UWB باید نسخه بسته android.hardware.uwb.fira_android HAL پشتیبانی شده در دستگاه را از طریق IUwbChip.getSupportedAndroidUciVersion() افشا کنند. این چارچوب از این اطلاعات نسخه‌بندی برای مدیریت سازگاری معکوس استفاده می‌کند.

فهرست GIDها و OIDهای اندروید

جدول زیر GIDها و OIDهای اندروید را فهرست می‌کند. GIDهای 0xE و 0xF برای استفاده تولیدکنندگان اصلی تجهیزات (OEM) اندروید رزرو شده‌اند.

شناسه GID شناسه تعریف
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 توسط دستور و پاسخ برای دریافت آمار مربوط به توان UWB استفاده می‌شود. فقط در صورتی پشتیبانی می‌شود که UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY روی 1 تنظیم شده باشد.
ANDROID_SET_COUNTRY_CODE = 0x1

برای تنظیم کد کشور فعلی (که با استفاده از سیم‌کارت یا وای‌فای تعیین می‌شود، یا توسط OEM کدگذاری شده است) استفاده می‌شود. کد کشور به صورت یک مقدار ۲ بایتی مربوط به کد کشور ISO-3166 ارسال می‌شود. مقدار 00 برای نشان دادن ناشناخته بودن کد کشور استفاده می‌شود.

ANDROID_RANGE_DIAGNOSTICS = 0x2 توسط اعلان برای دریافت آمار تشخیص مسافت UWB استفاده می‌شود. فقط در صورتی پشتیبانی می‌شود که UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS روی 1 تنظیم شده باشد.
OEM = 0xE,0xF 0x00 - 0x3F برای استفاده OEM رزرو شده است.

افزونه‌های فروشنده برای پیام‌های تعریف‌شده با مشخصات UCI

این بخش جزئیات افزونه‌های فروشنده برای پیام‌های تعریف‌شده توسط مشخصات UCI را شرح می‌دهد.

و [[SESSION_SET_APP_CONFIG_[CMD|RSP]]

مقادیر طول نوع (TLV) که توسط پشته AOSP در بخش رزرو شده توسط فروشنده از TLV ها در APP_CONFIG تعریف شده اند، در زیر آمده است:

  • GID: 0001b (گروه پیکربندی جلسه UWB)
  • شناسه برنامه (OID): 000011b ( SESSION_SET_APP_CONFIG_CMD )
  • شناسه برنامه کاربردی: ۰۰۰۱۰۰b ( SESSION_GET_APP_CONFIG_CMD )

جدول زیر پارامترهای مربوط به پیام‌های پیکربندی جلسه UWB را فهرست می‌کند.

نام پارامتر طول
(هشت‌تایی)		 برچسب
(شناسنامه‌ها)		 نسخه رابط فروشنده توضیحات
NB_OF_RANGE_MEASUREMENTS ۱ 0xE3 ۱ نسبت جایگذاری اگر AOA_RESULT_REQ روی 0xF0 تنظیم شده باشد. فقط در صورتی پشتیبانی می‌شود که UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING روی 1 تنظیم شده باشد.
NB_OF_AZIMUTH_MEASUREMENTS ۱ 0xE4 ۱
NB_OF_ELEVATION_MEASUREMENTS ۱ 0xE5 ۱
ENABLE_DIAGNOSTICS ۱ 0xE8 ۲

مقدار ۱ بایتی برای فعال یا غیرفعال کردن گزارش‌دهی تشخیصی. این پارامتر را فقط زمانی پیکربندی کنید که CORE_GET_CAPS_INFO_RSP SUPPORTED_DIAGNOSTICS با مقدار 1 برگرداند که نشان می‌دهد ویژگی گزارش‌دهی تشخیصی پشتیبانی می‌شود.

ارزش‌ها:

  • 1 : ویژگی فعال شد
  • 0 : ویژگی غیرفعال است

DIAGRAMS_FRAME_REPORTS_FIELDS ۱ یا ۴ 0xE9 ۲

ماسک بیتی ۱ بایتی یا ۴ بایتی برای پیکربندی گزارش‌های تشخیصی. این ماسک بیتی در اندروید ۱۴ یا بالاتر ۱ بایتی و در اندروید ۱۳ یا پایین‌تر ۴ بایتی است.

این پارامتر را فقط زمانی پیکربندی کنید که CORE_GET_CAPS_INFO_RSP SUPPORTED_DIAGNOSTICS با مقدار 1 برگرداند که نشان می‌دهد ویژگی گزارش‌دهی تشخیصی پشتیبانی می‌شود.

تعاریف بیت:

  • b0 (0x01) : فعال کردن فیلدهای RSSI
  • b1 (0x02) : فعال کردن فیلدهای AoA
  • b2 (0x04) : فعال کردن فیلدهای CIR

اطلاعات کلیدی CORE_GET_CAPS_INFO_RSP

موارد زیر TLV های تعریف شده توسط پشته AOSP در بخش رزرو شده توسط فروشنده از TLV ها در CAPS_INFO هستند:

  • GID: 0000b (گروه اصلی UWB)
  • شناسه برنامه کاربردی: 000011b ( CORE_GET_CAPS_INFO_RSP )

جدول زیر پارامترهای مربوط به پیام‌های قابلیت UWB را فهرست می‌کند.

نام پارامتر طول
(هشت‌تایی)		 برچسب
(شناسنامه‌ها)		 نسخه رابط فروشنده توضیحات
SUPPORTED_POWER_STATS_QUERY ۱ 0xC0 ۱

مقدار ۱ بایتی که نشان‌دهنده پشتیبانی از پرس‌وجوی وضعیت برق است.

ارزش‌ها:

  • 1 : پشتیبانی از ویژگی
  • 0 : این ویژگی پشتیبانی نمی‌شود
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING ۱ 0xE3 ۱

مقدار ۱ بایتی که نشان‌دهنده پشتیبانی از ویژگی تداخل آنتن است.

ارزش‌ها:

  • 1 : پشتیبانی از ویژگی
  • 0 : این ویژگی پشتیبانی نمی‌شود
SUPPORTED_MIN_RANGING_INTERVAL_MS ۴ 0xE4 ۲ مقدار ۴ بایتی که حداقل فاصله‌ی رنج پشتیبانی‌شده را بر حسب میلی‌ثانیه نشان می‌دهد.
SUPPORTED_RANGE_DATA_NTF_CONFIG ۴ 0xE5 ۲ یک ماسک بیتی ۴ بایتی که مقادیر پشتیبانی‌شده‌ی RANGE_DATA_NTF_CONFIG را نشان می‌دهد. ماسک بیتی که در آن هر بیت مربوط به مقادیر استفاده‌شده در RANGE_DATA_NTF_CONFIG در SET_APP_CFG_CMD است.
SUPPORTED_RSSI_REPORTING ۱ 0xE6 ۲

مقدار ۱ بایتی که پشتیبانی از گزارش‌دهی RSSI را نشان می‌دهد.

ارزش‌ها:

  • 1 : پشتیبانی از ویژگی
  • 0 : این ویژگی پشتیبانی نمی‌شود
SUPPORTED_DIAGNOSTICS ۱ 0xE7 ۲

مقدار ۱ بایتی که پشتیبانی از گزارش‌های تشخیصی را نشان می‌دهد.

ارزش‌ها:

  • 1 : پشتیبانی از ویژگی
  • 0 : این ویژگی پشتیبانی نمی‌شود
SUPPORTED_MIN_SLOT_DURATION_RSTU ۴ 0xE8 ۲ مقدار ۴ بایتی که حداقل مدت زمان اسلات پشتیبانی شده در RSTU را نشان می‌دهد.
SUPPORTED_MAX_RANGING_SESSION_NUMBER ۴ 0xE9 ۲ مقدار ۴ بایتی که حداکثر تعداد جلسات مسافت‌یابی FiRa پشتیبانی‌شده را نشان می‌دهد.
SUPPORTED_CHANNELS_AOA ۲ 0xEA ۲

ماسک بیتی ۲ بایتی برای نشان دادن کانال‌هایی که از AoA پشتیبانی می‌کنند. هر 1 در ماسک بیتی مربوط به یک کانال UWB خاص است.

ارزش‌ها:

  • 0x01 : کانال 5 پشتیبانی می‌شود
  • 0x02 : کانال 6 پشتیبانی می‌شود
  • 0x04 : کانال 8 پشتیبانی می‌شود
  • 0x08 : کانال 9 پشتیبانی می‌شود
  • 0x10 : کانال 10 پشتیبانی می‌شود
  • 0x20 : کانال 12 پشتیبانی می‌شود
  • 0x40 : کانال ۱۳ پشتیبانی می‌شود
  • 0x80 : کانال 14 پشتیبانی می‌شود

کدهای وضعیت

کدهای وضعیت زیر در فضای فروشنده وجود دارند. این کدها توسط زیرسیستم 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 تعریف شده‌اند، در ادامه آمده‌اند. این اعلان توسط 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 به دلیل قانونی باید غیرفعال شود.