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

AOSP ใช้สแต็กแถบความถี่กว้างยิ่งยวด (UWB) ที่ใช้อินเทอร์เฟซ UCI ที่ FiRa กำหนดเป็นแพลตฟอร์ม HAL อินเทอร์เฟซ HAL ใช้ไปป์ทึบ (IUwbChip::sendUciMessage() และ IUwbClientCallback::onUciMessage()) เพื่อส่งและรับคําสั่ง การตอบกลับ และการแจ้งเตือนของอินเทอร์เฟซคําสั่ง UWB (UCI) ผู้ให้บริการ UWB ทั้งหมดของ Android ต้องรองรับข้อความทั้งหมดที่ระบุไว้ในข้อกำหนดของ FiRa เฟรมเวิร์ก UWB ใช้งานย้อนหลังได้และทำงานร่วมกับ UCI เวอร์ชันใดก็ได้ที่ผู้ให้บริการ UWB ติดตั้งใช้งานในอุปกรณ์ เนื่องจากเฟรมเวิร์ก UWB ของ AOSP เป็นโมดูล จึงสามารถเพิ่มการรองรับคำขอเปลี่ยนแปลง (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. ลบล้างรหัสประเทศ: บังคับใช้รหัสประเทศผ่านคําสั่ง adb shell (การทดสอบในเครื่องหรือการทดสอบอัตโนมัติ)
  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 ในประเทศใหม่)

รูปแบบคำสั่งที่กําหนดโดยข้อกําหนด FIRA UCI

สำหรับรูปแบบของแพ็กเก็ตควบคุม UCI โปรดดูส่วน 4.4.2 ของข้อมูลจำเพาะ UCI

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

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

รายการ CR ฉบับร่างที่โมดูล UWB รองรับ

โมดูล UWB เวอร์ชัน #330810000 รองรับร่างคำขอแจ้งข้อบกพร่อง (CR) สำหรับ FiRa 2.0 ต่อไปนี้

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

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

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

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

ผู้ให้บริการ UWB ต้องแสดงเวอร์ชันของแพ็กเกจ HAL android.hardware.uwb.fira_android ที่รองรับในอุปกรณ์ดังกล่าวผ่าน 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 ด้วยเหตุผลด้านกฎระเบียบ