สแต็กแถบความถี่กว้างพิเศษ AOSP (UWB) ใช้ อินเทอร์เฟซ UCI ที่กำหนดโดย FiRa เป็นพื้นผิว HAL อินเทอร์เฟซ HAL ใช้ไปป์ทึบแสง ( IUwbChip::sendUciMessage()
และ IUwbClientCallback::onUciMessage()
) เพื่อส่งและรับคำสั่ง UWB command interface (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
รูปที่ 1. ขั้นตอนการเรียกการเริ่มต้นสแต็ก UWB (สลับ UWB)
รูปที่ 2. โฟลว์การโทรยกเลิกการเริ่มต้นสแต็ก UWB (ปิดสวิตช์ UWB)
รูปที่ 3 กระบวนการ เริ่ม/หยุดเซสชัน UWB
การกำหนดค่ารหัสประเทศ UWB
ดังที่แสดงในรูปที่ 1 กรอบงาน UWB จะกำหนดค่ารหัสประเทศ UWB ในระหว่างการเริ่มต้นสแต็ก UWB โดยใช้คำสั่ง UCI พื้นที่ผู้ขาย ANDROID_SET_COUNTRY_CODE
(GID= 0xC
, OID= 0x1
) กรอบงาน UWB พยายามกำหนดรหัสประเทศ UWB โดยใช้แหล่งที่มาต่อไปนี้ (แสดงรายการตามลำดับความสำคัญ) กรอบงาน UWB หยุดที่แหล่งแรกซึ่งมีการกำหนดรหัสประเทศ
- ลบล้างรหัสประเทศ: รหัสประเทศบังคับผ่านคำสั่งเชลล์ adb (การทดสอบในท้องถิ่นหรืออัตโนมัติ)
- รหัสประเทศของระบบโทรศัพท์: รหัสประเทศที่ดึงข้อมูลผ่านโทรศัพท์มือถือ หากมีหลายซิมที่ส่งคืนรหัสต่างกัน รหัสประเทศที่เลือกนั้นไม่สามารถกำหนดได้
- รหัสประเทศ Wi-Fi: รหัสประเทศที่ดึงข้อมูลผ่าน Wi-Fi (80211.ad)
- รหัสประเทศของโทรศัพท์ที่ทราบล่าสุด: รหัสประเทศที่ทราบล่าสุดที่ดึงข้อมูลผ่านโทรศัพท์มือถือ หากมีหลายซิมที่ส่งคืนรหัสต่างกัน รหัสประเทศที่เลือกนั้นไม่สามารถกำหนดได้
- รหัสประเทศของสถานที่ตั้ง: รหัสประเทศที่ดึงมาจากผู้ให้บริการตำแหน่งที่หลอม
LocationManager
- รหัสประเทศเริ่มต้นของ 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 จะกำหนดค่ารหัสประเทศใหม่โดยใช้คำสั่ง UCI ANDROID_SET_COUNTRY_CODE
ขึ้นอยู่กับรหัสสถานะที่ส่งคืนโดยตัวควบคุม UWB (ตามข้อบังคับ UWB ในประเทศใหม่) สิ่งนี้อาจนำไปสู่การเปลี่ยนแปลงในสถานะสแต็ก UWB
รูปแบบคำสั่งที่กำหนดโดยข้อกำหนด FIRA UCI
สำหรับรูปแบบของแพ็กเก็ตควบคุม 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:
อินเทอร์เฟซ Android UCI (ส่วนของผู้จำหน่าย FiRa)
ข้อกำหนด UCI กำหนดชุดของตัวระบุกลุ่ม (GID) และตัวระบุ opcode (OID) สำหรับข้อความที่กำหนดตามข้อกำหนดทั้งหมด ข้อกำหนดนี้ยังสงวนชุดของ GID ที่สงวนไว้สำหรับการใช้งานของผู้จำหน่ายโดยเฉพาะ สแต็ก AOSP UWB ใช้ GID และ OID ของผู้จำหน่ายเหล่านี้บางส่วนสำหรับคำสั่งเฉพาะของ Android ที่ไม่ได้กำหนดไว้ในข้อกำหนด สำหรับรายละเอียด โปรดดู ส่วนที่ 8.4 ของข้อกำหนด UCI
ข้อความของผู้จำหน่ายเหล่านี้ที่ใช้โดย Android ถูกกำหนดไว้ในแพ็คเกจ android.hardware.uwb.fira_android
HAL
การกำหนดเวอร์ชันอินเทอร์เฟซของผู้ขาย
ผู้จำหน่าย UWB ต้องเปิดเผยเวอร์ชันของแพ็คเกจ android.hardware.uwb.fira_android
HAL ที่รองรับบนอุปกรณ์ผ่าน IUwbChip.getSupportedAndroidUciVersion()
เฟรมเวิร์กใช้ข้อมูลการกำหนดเวอร์ชันนี้เพื่อจัดการความเข้ากันได้แบบย้อนหลัง
รายการ Android GID และ OID
ตารางต่อไปนี้แสดงรายการ GID และ OID สำหรับ Android GID 0xE
และ 0xF
สงวนไว้สำหรับ Android OEM ที่จะใช้
จีไอดี | ออยด์ | คำนิยาม |
---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | ใช้โดยคำสั่งและการตอบกลับเพื่อรับสถิติที่เกี่ยวข้องกับพลังงาน UWB รองรับเฉพาะเมื่อ UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY ถูกตั้งค่าเป็น 1 |
ANDROID_SET_COUNTRY_CODE = 0x1 | ใช้เพื่อตั้งค่ารหัสประเทศตามข้อบังคับปัจจุบัน (กำหนดโดยใช้ SIM หรือ Wi-Fi หรือฮาร์ดโค้ดโดย OEM) รหัสประเทศจะถูกส่งเป็นค่า 2 ไบต์ซึ่งสอดคล้องกับรหัสประเทศ ISO-3166 ค่า | |
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 ไบต์เพื่อเปิดหรือปิดใช้งานการรายงานการวินิจฉัย กำหนดค่าพารามิเตอร์นี้เฉพาะเมื่อ ค่า:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 หรือ 4 | 0xE9 | 2 | บิตมาสก์ 1 ไบต์หรือ 4 ไบต์เพื่อกำหนดค่าการรายงานการวินิจฉัย บิตมาสก์นี้มีขนาด 1 ไบต์ใน Android 14 ขึ้นไป และ 4 ไบต์ใน Android 13 หรือต่ำกว่า กำหนดค่าพารามิเตอร์นี้เฉพาะเมื่อ คำจำกัดความของบิต:
|
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 ไบต์บ่งชี้ถึงการสนับสนุนสำหรับการสืบค้นสถิติพลังงาน ค่า:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | ค่า 1 ไบต์แสดงถึงการสนับสนุนคุณลักษณะการรบกวนเสาอากาศ ค่า:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | ค่า 4 ไบต์ซึ่งระบุช่วงเวลาขั้นต่ำที่รองรับในหน่วยมิลลิวินาที |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | บิตมาสก์ 4 ไบต์ที่ระบุค่า RANGE_DATA_NTF_CONFIG ที่สนับสนุน Bitmask โดยที่แต่ละบิตสอดคล้องกับค่าที่ใช้ใน RANGE_DATA_NTF_CONFIG ใน SET_APP_CFG_CMD |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | ค่า 1 ไบต์บ่งชี้ถึงการสนับสนุนการรายงาน RSSI ค่า:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | ค่า 1 ไบต์บ่งชี้ถึงการสนับสนุนการรายงานการวินิจฉัย ค่า:
|
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 แต่ละ ค่า:
|
รหัสสถานะ
ต่อไปนี้เป็นรหัสสถานะในพื้นที่ผู้จัดจำหน่าย สิ่งเหล่านี้จะถูกส่งกลับในการตอบกลับ 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 เนื่องจากเหตุผลด้านกฎระเบียบ |