Giao diện UWB HAL

AOSP (Dự án nguồn mở Android) ngăn xếp băng tần siêu rộng (UWB) sử dụng Giao diện UCI doFiRa xác định làm bề mặt HAL. Giao diện HAL sử dụng một đường ống mờ (IUwbChip::sendUciMessage() và IUwbClientCallback::onUciMessage()) để gửi và nhận lệnh, phản hồi và thông báo qua giao diện lệnh (UCI) UWB. Tất cả nhà cung cấp Android UWB phải hỗ trợ tất cả các thông số kỹ thuật FiRa đã xác định tin nhắn. Khung UWB có khả năng tương thích ngược và hoạt động với mọi UCI phiên bản do nhà cung cấp UWB triển khai trên thiết bị. Vì AOSP UWB khung là một mô-đun, thì dịch vụ này cũng có thể chọn thêm tuỳ chọn hỗ trợ cho các yêu cầu thay đổi được phê duyệt (CR) từ nháp thông số kỹ thuật UCI nhắm đến các bản phát hành tiêu chuẩn FiRa chính. Bất kỳ loại nội dung nào như vậy Câu trả lời soạn trước được triển khai có thể thay đổi.

Định nghĩa giao diện

Giao diện UWB HAL được xác định bằng AIDL ổn định. Giao diện chính sử dụng gói android.hardware.uwb.

Sau đây là hai giao diện chính trong 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);

}

Luồng lệnh gọi HAL từ khung UWB

Các hình ảnh sau minh hoạ luồng lệnh gọi từ khung UWB cho Khởi tạo ngăn xếp UWB, huỷ khởi tạo ngăn xếp UWB, bắt đầu phiên UWB và dừng các quá trình.

Khởi chạy ngăn xếp UWB

Hình 1. Luồng lệnh gọi khởi chạy ngăn xếp UWB (bật/tắt UWB)

Huỷ khởi chạy ngăn xếp UWB

Hình 2. Luồng lệnh gọi huỷ khởi chạy ngăn xếp UWB (tắt nút UWB)

Bắt đầu và dừng phiên UWB

Hình 3. Quy trình bắt đầu/dừng phiên UWB

Cấu hình mã quốc gia UWB

Như được hiển thị trong Hình 1, khung UWB định cấu hình mã quốc gia UWB trong quá trình khởi chạy ngăn xếp UWB bằng lệnh UCI không gian nhà cung cấp ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). Khung UWB cố gắng xác định mã quốc gia UWB bằng các nguồn sau (được liệt kê theo mức độ ưu tiên đơn đặt hàng). Khung UWB dừng ở nguồn đầu tiên có mã quốc gia xác định.

  1. Ghi đè mã quốc gia: Mã quốc gia bị buộc thông qua lệnh shell adb (kiểm thử cục bộ hoặc tự động).
  2. Mã quốc gia của dịch vụ điện thoại: Mã quốc gia được truy xuất qua mạng di động. Nếu nhiều SIM trả về các mã khác nhau, mã quốc gia đã chọn là không tất định.
  3. Mã quốc gia Wi-Fi: Mã quốc gia truy xuất qua Wi-Fi (80211.ad).
  4. Mã quốc gia của điện thoại xác định gần đây nhất: Mã quốc gia đã biết gần đây nhất được truy xuất thông qua mạng di động. Nếu có nhiều SIM trả về các SIM khác nhau thì mã quốc gia được chọn là không xác định.
  5. Mã quốc gia của vị trí: Mã quốc gia được truy xuất từ LocationManager trình cung cấp vị trí kết hợp.
  6. Mã quốc gia mặc định của OEM: Mã quốc gia do nhà sản xuất thiết bị đặt.

Nếu khung UWB không thể xác định mã quốc gia của UWB, khung này sẽ gọi Lệnh UCI ANDROID_SET_COUNTRY_CODE có giá trị là DEFAULT_COUNTRY_CODE ("00") và thông báo cho các ứng dụng UWB rằng trạng thái ngăn xếp UWB là DISABLED. Sau này, khi khung UWB có thể hãy xác định một mã quốc gia hợp lệ, công cụ này sẽ định cấu hình mã quốc gia mới bằng cách sử dụng Lệnh ANDROID_SET_COUNTRY_CODE và thông báo cho các ứng dụng UWB rằng ngăn xếp UWB là READY.

Nếu không thể sử dụng UWB do quy định địa phương tại một quốc gia, đơn vị kiểm soát UWB trả về Mã trạng thái STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Sau đó, khung UWB thông báo cho các ứng dụng UWB rằng trạng thái ngăn xếp UWB là DISABLED.

Khi người dùng di chuyển đến một quốc gia khác, khung UWB sẽ định cấu hình một mã quốc gia bằng lệnh ANDROID_SET_COUNTRY_CODE UCI. Tuỳ thuộc vào mã trạng thái do đơn vị kiểm soát UWB trả về (dựa trên các quy định của UWB trong quốc gia mới), điều này có thể dẫn đến thay đổi về trạng thái ngăn xếp UWB.

Định dạng lệnh được xác định theo quy cách FIRA UCI

Để biết định dạng của gói kiểm soát UCI, hãy xem mục 4.4.2 của UCI .

Tạo phiên bản giao diện

Thông số kỹ thuật UCI cho phép nhà cung cấp UWB hiển thị phiên bản ngăn xếp UCI do thiết bị triển khai bằng cách sử dụng UCI_GET_DEVICE_INFO_RSP và UCI_GET_CAPS_INFO_RSP. Khung này sử dụng các lệnh này để tìm nạp phiên bản UCI của thiết bị và thay đổi hành vi của thiết bị cho phù hợp.

Danh sách câu trả lời soạn trước dự thảo mà mô-đun UWB hỗ trợ

Các CR dự thảo sau đây cho FiRa 2.0 được hỗ trợ bởi Mô-đun UWB phiên bản #330810000:

Giao diện UCI Android (phần nhà cung cấpFiRa)

Quy cách UCI xác định một bộ mã nhận dạng nhóm (GID) và mã hoạt động mã nhận dạng (OID) cho tất cả thông báo do quy cách xác định. Thông số kỹ thuật cũng dành riêng một bộ GID riêng cho nhà cung cấp. UWB AOSP (Dự án nguồn mở Android) ngăn xếp sử dụng một số GID và OID của nhà cung cấp này cho các lệnh dành riêng cho Android không được xác định trong thông số kỹ thuật. Để biết thông tin chi tiết, hãy xem mục 8.4 của UCI .

Những thông báo của nhà cung cấp mà Android sử dụng được xác định trong Gói HAL android.hardware.uwb.fira_android.

Tạo phiên bản giao diện nhà cung cấp

Nhà cung cấp UWB phải hiển thị phiên bản của android.hardware.uwb.fira_android Gói HAL được hỗ trợ trên thiết bị thông qua IUwbChip.getSupportedAndroidUciVersion(). Khung này sẽ sử dụng thông tin về phiên bản để xử lý khả năng tương thích ngược.

Danh sách GID và OID trên Android

Bảng sau đây liệt kê GID và OID cho Android. GID 0xE và 0xF được dành riêng cho Nhà sản xuất thiết bị gốc (OEM) Android sử dụng.

GID OID (giá trị nhận dạng do nhà xuất bản cung cấp) Định nghĩa
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 Dùng lệnh và phản hồi để nhận số liệu thống kê liên quan đến nguồn UWB. Chỉ được hỗ trợ nếu UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY được đặt thành 1.
ANDROID_SET_COUNTRY_CODE = 0x1

Dùng để đặt mã quốc gia theo quy định hiện hành (được xác định bằng SIM hoặc Wi-Fi hoặc do OEM (Nhà sản xuất thiết bị gốc) mã hoá cứng). Mã quốc gia đã được gửi thành một giá trị 2 byte tương ứng với mã quốc gia ISO-3166. Đáp giá trị của 00 dùng để cho biết rằng mã quốc gia chưa biết.
ANDROID_RANGE_DIAGNOSTICS = 0x2 Thông báo sử dụng để nhận số liệu thống kê chẩn đoán về các phạm vi UWB. Chỉ được hỗ trợ nếu Đã đặt UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS đến 1.
OEM = 0xE,0xF 0x00 - 0x3F Dành riêng cho OEM sử dụng.

Thông báo do nhà cung cấp mở rộng cho quy cách UCI

Phần này mô tả chi tiết về các tiện ích của nhà cung cấp cho UCI các thông báo do quy cách xác định.

SESSION_SET_APP_CONFIG_[CMD|RSP] và SESSION_GET_APP_CONFIG_[CMD|RSP]

Sau đây là các giá trị độ dài loại (TLV) được xác định theo ngăn xếp AOSP trong phần đặt trước của nhà cung cấp trong TLV trong APP_CONFIG:

  • GID: 0001b (nhóm cấu hình phiên UWB)
  • OID: 000011b (SESSION_SET_APP_CONFIG_CMD)
  • OID: 000100b (SESSION_GET_APP_CONFIG_CMD)

Bảng sau đây liệt kê các tham số cho thông báo cấu hình phiên UWB.

Tên thông số Độ dài
(số bát phân)		 Thẻ
(mã)		 Phiên bản giao diện nhà cung cấp Mô tả
NB_OF_RANGE_MEASUREMENTS 1 0xE3 1 Tỷ lệ xen kẽ nếu bạn đặt AOA_RESULT_REQ đến 0xF0. Chỉ được hỗ trợ nếu UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING được đặt thành 1.
NB_OF_AZIMUTH_MEASUREMENTS 1 0xE4 1
NB_OF_ELEVATION_MEASUREMENTS 1 0xE5 1
ENABLE_DIAGNOSTICS 1 0xE8 2

Giá trị 1 byte để bật hoặc tắt tính năng báo cáo chẩn đoán. Chỉ định cấu hình tham số này khi CORE_GET_CAPS_INFO_RSP sẽ trả về SUPPORTED_DIAGNOSTICS có giá trị là 1 cho biết tính năng báo cáo chẩn đoán được hỗ trợ.

Giá trị:

  • 1: Đã bật tính năng
  • 0: Tính năng đã bị vô hiệu hoá
DIAGRAMS_FRAME_REPORTS_FIELDS 1 hoặc 4 0xE9 2

Mặt nạ bit 1 byte hoặc 4 byte để định cấu hình báo cáo chẩn đoán. Chiến dịch này bitmask là 1 byte trong Android 14 trở lên và 4 byte trong Android 13 trở xuống.

Chỉ định cấu hình thông số này khi Trả lại hàng với mức phí CORE_GET_CAPS_INFO_RSP SUPPORTED_DIAGNOSTICS với giá trị 1 cho biết tính năng báo cáo chẩn đoán có được hỗ trợ.

Định nghĩa về bit:

  • b0 (0x01): Kích hoạt các trường RSSI
  • b1 (0x02): Kích hoạt các trường AoA
  • b2 (0x04): Kích hoạt các trường CIR

CORE_GET_CAPS_INFO_RSP

Sau đây là các TLV được xác định bởi ngăn xếp AOSP trong phần đặt trước của nhà cung cấp của TLV trong CAPS_INFO:

  • GID: 0000b (nhóm lõi UWB)
  • OID: 000011b (CORE_GET_CAPS_INFO_RSP)

Bảng sau đây liệt kê các tham số cho thông báo về chức năng UWB.

Tên thông số Độ dài
(số bát phân)		 Thẻ
(mã)		 Phiên bản giao diện nhà cung cấp Mô tả
SUPPORTED_POWER_STATS_QUERY 1 0xC0 1

Giá trị 1 byte cho biết có hỗ trợ truy vấn số liệu thống kê về nguồn điện.

Giá trị:

  • 1: Tính năng được hỗ trợ
  • 0: Tính năng không được hỗ trợ
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

Giá trị 1 byte cho biết có hỗ trợ xen kẽ ăng-ten của chúng tôi.

Giá trị:

  • 1: Tính năng được hỗ trợ
  • 0: Tính năng không được hỗ trợ
SUPPORTED_MIN_RANGING_INTERVAL_MS 4 0xE4 2 Giá trị 4 byte cho biết khoảng thời gian tối thiểu được hỗ trợ trong mili giây.
SUPPORTED_RANGE_DATA_NTF_CONFIG 4 0xE5 2 Mặt nạ bit 4 byte cho biết các thuộc tính Giá trị RANGE_DATA_NTF_CONFIG. Bitmask trong đó mỗi bit tương ứng với các giá trị được sử dụng trong RANGE_DATA_NTF_CONFIG trong SET_APP_CFG_CMD.
SUPPORTED_RSSI_REPORTING 1 0xE6 2

Giá trị 1 byte cho biết có hỗ trợ báo cáo RSSI.

Giá trị:

  • 1: Tính năng được hỗ trợ
  • 0: Tính năng không được hỗ trợ
SUPPORTED_DIAGNOSTICS 1 0xE7 2

Giá trị 1 byte cho biết có hỗ trợ báo cáo chẩn đoán.

Giá trị:

  • 1: Tính năng được hỗ trợ
  • 0: Tính năng không được hỗ trợ
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 Giá trị 4 byte cho biết thời lượng vị trí tối thiểu được hỗ trợ trong RSTU.
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2 Giá trị 4 byte cho biết số phạm vi FiRa tối đa được hỗ trợ phiên hoạt động.
SUPPORTED_CHANNELS_AOA 2 0xEA 2

Mặt nạ bit 2 byte để chỉ ra các kênh hỗ trợ AoA. Một 1 trong mặt nạ bit tương ứng với một kênh UWB cụ thể.

Giá trị:

  • 0x01: Kênh 5 được hỗ trợ
  • 0x02: Hỗ trợ kênh 6
  • 0x04: Hỗ trợ kênh 8
  • 0x08: Hỗ trợ kênh 9
  • 0x10: Kênh 10 được hỗ trợ
  • 0x20: Kênh 12 được hỗ trợ
  • 0x40: Kênh 13 được hỗ trợ
  • 0x80: Kênh 14 được hỗ trợ

Mã trạng thái

Sau đây là các mã trạng thái trong môi trường của nhà cung cấp. Những kết quả này được trả về trong Phản hồi UCI (chẳng hạn như SESSION_START_RSP) của hệ thống con UWB (UWBS).

Mã trạng thái Giá trị Mô tả
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

Mã trạng thái được trả về khi phiên khoảng thời gian hiện tại không thể được trả về đã bắt đầu do xung đột với các phiên khác nhau của CCC hoặc FiRa.
STATUS_REGULATION_UWB_OFF 0x53

Mã trạng thái được trả về khi phiên khoảng thời gian hiện tại không thể được trả về bắt đầu vì các lý do liên quan đến quy định của UWB.

Mã lý do thay đổi trạng thái trong SESSION_STATUS_NTF

Sau đây là các mã lý do thay đổi trạng thái được xác định trong không gian của nhà cung cấp cho trường trạng thái do UWBS trả về trong SESSION_STATUS_NTF. Thông báo này được UWBS gửi khi trạng thái của một phiên hoạt động thay đổi (ví dụ: từ ACTIVE đến IDLE).

Mã lý do thay đổi trạng thái Giá trị Mô tả
REASON_ERROR_INVALID_CHANNEL_WITH_AOA 0x80

Trạng thái phiên đã thay đổi vì kênh được định cấu hình không hỗ trợ nhiều loại AoA.
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x81

Trạng thái phiên đã thay đổi do xung đột với CCC hoặc FiRa khác các phiên khác nhau.
REASON_REGULATION_UWB_OFF 0x82

Trạng thái phiên đã thay đổi vì UWB phải bị tắt do lý do liên quan đến quy định.