อินเทอร์เฟซ 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 หลักๆ เช่น คำตอบสำเร็จรูปฉบับร่างที่นำไปใช้อาจมีการเปลี่ยนแปลง

คำจำกัดความอินเทอร์เฟซ

อินเทอร์เฟซ UWB HAL ได้รับการกำหนดโดยใช้ AIDL เวอร์ชันเสถียร อินเทอร์เฟซหลักใช้แพ็กเกจ android.hardware.uwb

ต่อไปนี้คืออินเทอร์เฟซหลัก 2 รายการใน 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. ลบล้างรหัสประเทศ: รหัสประเทศที่บังคับผ่านคำสั่ง Shell adb (การทดสอบเฉพาะที่หรือการทดสอบอัตโนมัติ)
  2. รหัสประเทศของโทรศัพท์: รหัสประเทศที่ดึงผ่านเครือข่ายมือถือ ถ้า มีหลายซิมที่แสดงผลต่างกัน รหัสประเทศ ไม่มีการกำหนดทิศทาง
  3. รหัสประเทศของ Wi-Fi: รหัสประเทศที่ดึงผ่าน Wi-Fi (80211.ad)
  4. รหัสประเทศของโทรศัพท์ที่ทราบล่าสุด: รหัสประเทศที่ทราบล่าสุด ผ่านเครือข่ายมือถือ หากมีหลายซิมที่แสดงผลแตกต่างกัน รหัสประเทศที่เลือกจะไม่กำหนด
  5. รหัสประเทศของสถานที่ตั้ง: รหัสประเทศที่ดึงมาจาก LocationManager Fused Location Provider
  6. รหัสประเทศเริ่มต้นของ OEM: รหัสประเทศที่ผู้ผลิตอุปกรณ์กำหนด

หากเฟรมเวิร์ก UWB ไม่สามารถระบุรหัสประเทศของ 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 โปรดดู ส่วนที่ 4.4.2 ของ UCI ข้อกำหนดเฉพาะ

การกำหนดเวอร์ชันอินเทอร์เฟซ

ข้อกำหนด UCI ช่วยให้ผู้ให้บริการ UWB แสดงเวอร์ชันของสแต็ก UCI ที่อุปกรณ์นำไปใช้งานโดยใช้ UCI_GET_DEVICE_INFO_RSP และ คำสั่ง UCI_GET_CAPS_INFO_RSP โดยเฟรมเวิร์กจะใช้คำสั่งเหล่านี้เพื่อดึงข้อมูล เวอร์ชัน UCI ของอุปกรณ์และเปลี่ยนลักษณะการทำงานของอุปกรณ์ให้สอดคล้องกัน

รายการคำตอบสำเร็จรูปฉบับร่างที่โมดูล UWB รองรับ

คำตอบสำเร็จรูปฉบับร่างต่อไปนี้สำหรับ FiRa 2.0 ได้รับการสนับสนุนโดย โมดูล UWB เวอร์ชัน #330810000:

อินเทอร์เฟซ Android UCI (ส่วนผู้ให้บริการ FiRa)

ข้อกำหนด UCI จะกำหนดชุดของตัวระบุกลุ่ม (GID) และ Opcode (OID) สำหรับข้อความที่กำหนดขึ้นทั้งหมด ข้อกำหนด ยังจองชุด GID ที่สงวนไว้สำหรับการใช้งานของผู้ให้บริการโดยเฉพาะ AOSP UWB สแต็กจะใช้ GID และ OID ของผู้ให้บริการเหล่านี้บางส่วนสำหรับคำสั่งเฉพาะของ Android ที่ ไม่ได้กำหนดไว้ในข้อกำหนด โปรดดูรายละเอียดที่หัวข้อ ส่วนที่ 8.4 ของ UCI ข้อกำหนดเฉพาะ

ข้อความของผู้ให้บริการที่ Android ใช้จะระบุไว้ใน แพ็กเกจ HAL android.hardware.uwb.fira_android

การกำหนดเวอร์ชันอินเทอร์เฟซของผู้ให้บริการ

ผู้ให้บริการ UWB ต้องแสดงเวอร์ชันของ android.hardware.uwb.fira_android รองรับแพ็กเกจ HAL ในอุปกรณ์ผ่าน IUwbChip.getSupportedAndroidUciVersion() เฟรมเวิร์กนี้ ข้อมูลการกำหนดเวอร์ชันเพื่อจัดการความเข้ากันได้แบบย้อนหลัง

รายการ GID และ OID ของ Android

ตารางต่อไปนี้แสดงรายการ GID และ OID สำหรับ Android GID 0xE และ 0xF สงวนไว้ให้ OEM ของ Android ใช้

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 ไบต์เพื่อกำหนดค่าการรายงานการวินิจฉัย ช่วงเวลานี้ บิตมาสก์คือ 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 ค่า บิตมาสก์ที่แต่ละบิตสอดคล้องกับค่าที่ใช้ใน 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 เนื่องจาก เหตุผลด้านกฎระเบียบ