رابط UWB HAL

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

شکل 2. جریان فراخوانی اولیه سازی پشته UWB (خاموش کردن UWB)

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

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

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

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

  1. لغو کد کشور: کد کشور از طریق یک دستور پوسته adb (آزمایش محلی یا خودکار) اجباری شده است.
  2. کد کشور تلفن: کد کشور از طریق تلفن همراه بازیابی شده است. اگر چند سیم کارت وجود داشته باشد که کدهای متفاوتی را برمی گرداند، کد کشور انتخاب شده غیر قطعی است.
  3. کد کشور Wi-Fi: کد کشور از طریق Wi-Fi (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 شود.

فرمت فرمان تعریف شده با مشخصات UCI FIRA

برای فرمت بسته های کنترلی UCI، بخش 4.4.2 مشخصات 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) و شناسه‌های کد opcode (OID) را برای همه پیام‌های تعریف‌شده با مشخصات تعریف می‌کند. این مشخصات همچنین مجموعه ای از GID ها را رزرو می کند که منحصراً برای استفاده فروشنده رزرو شده اند. پشته AOSP UWB از برخی از این GID و OIDهای فروشنده برای دستورات مخصوص اندروید استفاده می کند که در مشخصات تعریف نشده اند. برای جزئیات، بخش 8.4 مشخصات UCI را ببینید.

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

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

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

لیست GID و OID اندروید

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

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

برای تنظیم کد کشور نظارتی فعلی (که با استفاده از سیم کارت یا Wi-Fi تعیین می شود، یا توسط OEM کدگذاری شده است) استفاده می شود. کد کشور به صورت یک مقدار 2 بایتی مطابق با کد کشور 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] و SESSION_GET_APP_CONFIG_[CMD|RSP]

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

  • 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

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

ارزش ها:

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

DIAGRAMS_FRAME_REPORTS_FIELDS 1 یا 4 0xE9 2

بیت ماسک 1 بایتی یا 4 بایتی برای پیکربندی گزارش تشخیصی. این بیت ماسک در اندروید 14 یا بالاتر 1 بایت و در اندروید 13 یا پایین تر 4 بایت است.

این پارامتر را فقط زمانی پیکربندی کنید که 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)
  • OID: 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 بایت که نشان دهنده پشتیبانی از ویژگی interleaving آنتن است.

ارزش ها:

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

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

ارزش ها:

  • 1 : ویژگی پشتیبانی می شود
  • 0 : ویژگی پشتیبانی نمی شود
SUPPORTED_DIAGNOSTICS 1 0xE7 2

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

ارزش ها:

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

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

ارزش ها:

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

کدهای وضعیت

در زیر کدهای وضعیت موجود در فضای فروشنده آمده است. اینها در پاسخ‌های UCI (مانند SESSION_START_RSP ) توسط زیرسیستم UWB (UWBS) برگردانده می‌شوند.

کد وضعیت ارزش توضیحات
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 باید به دلایل قانونی غیرفعال شود.