Ngăn xếp băng thông siêu rộng (UWB) AOSP sử dụng giao diện UCI do FiRa xác định làm bề mặt HAL. Giao diện HAL sử dụng một ống mờ ( IUwbChip::sendUciMessage() và IUwbClientCallback::onUciMessage() ) để gửi và nhận các lệnh, phản hồi và thông báo của giao diện lệnh UWB (UCI). Tất cả các nhà cung cấp Android UWB phải hỗ trợ tất cả các thông báo được xác định theo đặc tả FiRa. Khung UWB tương thích ngược và hoạt động với mọi phiên bản UCI do nhà cung cấp UWB triển khai trên thiết bị. Vì khung AOSP UWB là một mô-đun nên nó cũng có thể bổ sung hỗ trợ có chọn lọc cho các yêu cầu thay đổi (CR) đã được phê duyệt từ các thông số kỹ thuật UCI dự thảo được nhắm mục tiêu cho các bản phát hành tiêu chuẩn FiRa chính. Bất kỳ CR dự thảo nào được thực hiện đều 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 gói 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 cuộc gọi HAL từ khung UWB
Các hình ảnh sau đây minh họa luồng cuộc gọi từ khung UWB cho quá trình khởi tạo ngăn xếp UWB, hủy khởi tạo ngăn xếp UWB và các quá trình bắt đầu và dừng phiên UWB.
Hình 1. Luồng lệnh gọi khởi tạo ngăn xếp UWB (Bật UWB)
Hình 2. Luồng lệnh gọi khử khởi tạo ngăn xếp UWB (tắt UWB)
Hình 3. Luồng 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 tạo ngăn xếp UWB bằng cách sử dụ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ách sử dụng các nguồn sau (được liệt kê theo thứ tự ưu tiên). Khung UWB dừng ở nguồn đầu tiên nơi xác định mã quốc gia.
- Ghi đè mã quốc gia: Mã quốc gia buộc phải thông qua lệnh shell adb (thử nghiệm cục bộ hoặc tự động).
- Mã quốc gia điện thoại: Mã quốc gia được lấy qua mạng di động. Nếu có nhiều SIM trả về các mã khác nhau thì mã quốc gia được chọn là không xác định.
- Mã quốc gia Wi-Fi: Mã quốc gia được truy xuất qua Wi-Fi (80211.ad).
- Mã quốc gia điện thoại được biết lần cuối: Mã quốc gia được biết lần cuối được truy xuất qua mạng di động. Nếu có nhiều SIM trả về các mã khác nhau thì mã quốc gia được chọn là không xác định.
- Mã quốc gia vị trí: Mã quốc gia được lấy từ nhà cung cấp vị trí hợp nhất
LocationManager. - 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 UWB thì khung UWB sẽ gọi lệnh ANDROID_SET_COUNTRY_CODE UCI với giá trị DEFAULT_COUNTRY_CODE ("00") và thông báo cho ứ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ể xác định mã quốc gia hợp lệ, nó sẽ định cấu hình mã quốc gia mới bằng lệnh ANDROID_SET_COUNTRY_CODE và thông báo cho ứng dụng UWB rằng ngăn xếp UWB đã READY .
Nếu không thể sử dụng UWB do các quy định địa phương ở một quốc gia, bộ điều khiển UWB sẽ trả về mã trạng thái STATUS_CODE_ANDROID_REGULATION_UWB_OFF . Sau đó, khung UWB sẽ 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 đi đến một quốc gia khác, khung UWB sẽ định cấu hình mã quốc gia mới bằng lệnh ANDROID_SET_COUNTRY_CODE UCI. Tùy thuộc vào mã trạng thái được bộ điều khiển UWB trả về (dựa trên các quy định của UWB ở quốc gia mới), điều này có thể dẫn đến thay đổi trạng thái ngăn xếp UWB.
Định dạng lệnh được xác định theo đặc tả FIRA UCI
Để biết định dạng của gói điều khiển UCI, hãy xem phần 4.4.2 của đặc tả UCI .
Phiên bản giao diện
Đặc tả UCI cho phép các nhà cung cấp UWB hiển thị phiên bản của ngăn xếp UCI do thiết bị triển khai bằng cách sử dụng các lệnh 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 CR dự thảo được mô-đun UWB hỗ trợ
Các CR dự thảo sau đây cho FiRa 2.0 được hỗ trợ bởi phiên bản mô-đun UWB #330810000:
Giao diện UCI của Android (phần nhà cung cấp FiRa)
Đặc tả UCI xác định một tập hợp các mã định danh nhóm (GID) và mã định danh opcode (OID) cho tất cả các thông báo được xác định theo đặc tả. Thông số kỹ thuật cũng dành riêng một bộ GID dành riêng cho việc sử dụng của nhà cung cấp. Ngăn xếp AOSP UWB 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 đặc tả. Để biết chi tiết, xem phần 8.4 của đặc tả UCI .
Các thông báo của nhà cung cấp này được Android sử dụng được xác định trong gói HAL android.hardware.uwb.fira_android .
Phiên bản giao diện nhà cung cấp
Nhà cung cấp UWB phải cung cấp phiên bản của gói HAL android.hardware.uwb.fira_android được hỗ trợ trên thiết bị thông qua IUwbChip.getSupportedAndroidUciVersion() . Khung sử dụng thông tin phiên bản này để xử lý khả năng tương thích ngược.
Danh sách Android GID và OID
Bảng sau liệt kê GID và OID cho Android. GID 0xE và 0xF được dành riêng cho các OEM Android sử dụng.
| GID | OID | Sự định nghĩa |
|---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Được sử dụng bởi lệnh và phản hồi để nhận các số liệu thống kê liên quan đến sức mạnh UWB. Chỉ được hỗ trợ nếu UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY được đặt thành 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Được sử 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 được mã hóa cứng bởi OEM). Mã quốc gia được gửi dưới dạng giá trị 2 byte tương ứng với mã quốc gia ISO-3166. Giá trị | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Được sử dụng bởi thông báo để nhận số liệu thống kê chẩn đoán phạm vi UWB. Chỉ được hỗ trợ nếu UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS được đặt thành 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Dành riêng cho việc sử dụng OEM. |
Phần mở rộng của nhà cung cấp đối với các thông báo được xác định bởi đặc tả UCI
Phần này mô tả chi tiết về phần mở rộng của nhà cung cấp đối với các thông báo do đặc tả UCI 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 bởi ngăn xếp AOSP trong phần TLV dành riêng cho nhà cung cấp 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 liệt kê các tham số cho thông báo cấu hình phiên UWB.
| Tên tham số | Chiều dài (octet) | Nhãn (ID) | Phiên bản giao diện nhà cung cấp | Sự miêu tả |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | Tỷ lệ xen kẽ nếu AOA_RESULT_REQ được đặt thành 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 báo cáo chẩn đoán. Chỉ định cấu hình tham số này khi Giá trị:
|
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. Mặt nạ bit này có kích thước 1 byte trong Android 14 trở lên và 4 byte trong Android 13 trở xuống. Chỉ định cấu hình tham số này khi Định nghĩa bit:
|
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 TLV dành riêng cho nhà cung cấp trong CAPS_INFO :
- GID: 0000b (nhóm lõi UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
Bảng sau liệt kê các tham số cho các thông báo khả năng UWB.
| Tên tham số | Chiều dài (octet) | Nhãn (ID) | Phiên bản giao diện nhà cung cấp | Sự miêu tả |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Giá trị 1 byte biểu thị sự hỗ trợ cho truy vấn thống kê nguồn điện. Giá trị:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Giá trị 1 byte biểu thị sự hỗ trợ cho tính năng xen kẽ ăng-ten. Giá trị:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Giá trị 4 byte biểu thị khoảng thời gian tối thiểu được hỗ trợ tính bằng mili giây. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | Mặt nạ bit 4 byte biểu thị các giá trị RANGE_DATA_NTF_CONFIG được hỗ trợ. 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 biểu thị sự hỗ trợ của báo cáo RSSI. Giá trị:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Giá trị 1 byte biểu thị sự hỗ trợ của báo cáo chẩn đoán. Giá trị:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | Giá trị 4 byte cho biết thời lượng khe 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ố phiên phạm vi FiRa tối đa được hỗ trợ. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | Mặt nạ bit 2 byte để biểu thị các kênh hỗ trợ AoA. Mỗi Giá trị:
|
Mã trạng thái
Sau đây là các mã trạng thái trong không gian nhà cung cấp. Chúng được hệ thống con UWB (UWBS) trả về trong các phản hồi UCI (chẳng hạn như SESSION_START_RSP ).
| Mã trạng thái | Giá trị | Sự miêu tả |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Mã trạng thái được trả về khi không thể bắt đầu phiên phạm vi hiện tại do xung đột với các phiên phạm vi CCC hoặc FiRa khác. |
STATUS_REGULATION_UWB_OFF | 0x53 | Mã trạng thái được trả về khi không thể bắt đầu phiên phạm vi hiện tại vì lý do 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 nhà cung cấp cho trường trạng thái được UWBS trả về trong SESSION_STATUS_NTF . Thông báo này được UWBS gửi khi trạng thái của phiên khác nhau thay đổi (ví dụ: từ ACTIVE sang IDLE ).
| Mã lý do thay đổi trạng thái | Giá trị | Sự miêu tả |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | Trạng thái phiên đã thay đổi do kênh được định cấu hình không hỗ trợ phạm vi AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | Trạng thái phiên đã thay đổi do xung đột với các phiên CCC hoặc FiRa khác. |
REASON_REGULATION_UWB_OFF | 0x82 | Trạng thái phiên đã thay đổi do UWB phải bị tắt vì lý do quy định. |