อินเทอร์เฟซ UWB HAL

สแต็กแถบความถี่กว้างพิเศษ 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

การเริ่มต้นสแต็ก UWB

รูปที่ 1. ขั้นตอนการเรียกการเริ่มต้นสแต็ก UWB (สลับ UWB)

การยกเลิกการกำหนดค่าเริ่มต้นของสแต็ก UWB

รูปที่ 2. โฟลว์การโทรยกเลิกการเริ่มต้นสแต็ก UWB (ปิดสวิตช์ UWB)

เซสชัน UWB เริ่มต้นและหยุด

รูปที่ 3 กระบวนการ เริ่ม/หยุดเซสชัน UWB

การกำหนดค่ารหัสประเทศ UWB

ดังที่แสดงในรูปที่ 1 กรอบงาน UWB จะกำหนดค่ารหัสประเทศ UWB ในระหว่างการเริ่มต้นสแต็ก UWB โดยใช้คำสั่ง 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 จะกำหนดค่ารหัสประเทศใหม่โดยใช้คำสั่ง 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 ค่า 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 ไบต์เพื่อกำหนดค่าการรายงานการวินิจฉัย บิตมาสก์นี้มีขนาด 1 ไบต์ใน Android 14 ขึ้นไป และ 4 ไบต์ใน Android 13 หรือต่ำกว่า

กำหนดค่าพารามิเตอร์นี้เฉพาะเมื่อ 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 ไบต์แสดงถึงการสนับสนุนคุณลักษณะการรบกวนเสาอากาศ

ค่า:

  • 1 : รองรับคุณสมบัติ
  • 0 : ไม่รองรับฟีเจอร์นี้
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

ค่า:

  • 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 เนื่องจากเหตุผลด้านกฎระเบียบ