Ngăn xếp băng tần siêu rộng (UWB) của AOSP sử dụng giao diện UCI do FiRa xác định làm giao diện HAL. Giao diện HAL sử dụng một dấu gạch đứ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 UWB (UCI).
Tất cả nhà cung cấp Android UWB đều phải hỗ trợ tất cả thông báo được xác định theo quy cách FiRa. Khung UWB tương thích ngược và hoạt động với mọi phiên bản UCI mà nhà cung cấp UWB triển khai trên thiết bị. Vì khung UWB AOSP là một mô-đun, nên khung này cũng có thể thêm tính năng hỗ trợ có chọn lọc cho các yêu cầu thay đổi (CR) đã phê duyệt từ bản dự thảo quy cách UCI nhắm đến các bản phát hành tiêu chuẩn FiRa chính. Mọi bản dự thảo CR như vậy được triển khai đề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 lệnh gọi HAL từ khung UWB
Các hình ảnh sau đây minh hoạ luồng lệnh gọi từ khung UWB để khởi chạy ngăn xếp UWB, huỷ khởi chạy ngăn xếp UWB và các quy trình bắt đầu và dừng phiên UWB.
Hình 1. Quy trình gọi khởi chạy ngăn xếp UWB (bật nút bật/tắt UWB)
Hình 2. Quy trình gọi huỷ khởi chạy ngăn xếp UWB (tắt nút bật/tắt 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ư minh hoạ 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 (liệt kê theo thứ tự ưu tiên). Khung UWB sẽ dừng ở nguồn đầu tiên nơi mã quốc gia được xác định.
- Ghi đè mã quốc gia: Mã quốc gia được buộc thông qua lệnh shell adb (kiểm thử cục bộ hoặc tự động).
- Mã quốc gia điện thoại: Mã quốc gia được truy xuất qua điện thoại di động. Nếu có nhiều SIM trả về các mã khác nhau, thì mã quốc gia đã chọn là không xác định.
- Mã quốc gia Wi-Fi: Mã quốc gia được truy xuất thông qua Wi-Fi (80211.ad).
- Mã quốc gia điện thoại đã biết 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 mã khác nhau, thì mã quốc gia được chọn là không xác định.
- Mã quốc gia của vị trí: Mã quốc gia được truy xuất từ nhà cung cấp vị trí kết hợp
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 không thể xác định mã quốc gia UWB, 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 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ể xác định mã quốc gia hợp lệ, khung này 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 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 các quy định địa phương tại một quốc gia, thì trình đ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 di chuyển đế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 UCI ANDROID_SET_COUNTRY_CODE. Tuỳ thuộc vào mã trạng thái do bộ điều khiển UWB trả về (dựa trên quy định về 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 quy cách 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 thông số kỹ thuật UCI.
Tạo phiên bản giao diện
Quy cách 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 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 câu trả lời soạn trước dự thảo mà mô-đun UWB hỗ trợ
Các bản nháp CR sau đây cho FiRa 2.0 được hỗ trợ bởi mô-đun UWB phiên bản #330810000:
Giao diện UCI của Android (phần nhà cung cấp FiRa)
Thông số kỹ thuật UCI xác định một tập hợp giá trị nhận dạng nhóm (GID) và giá trị nhận dạng mã opcode (OID) cho tất cả thông báo được xác định theo thông số kỹ thuật. Quy cách này cũng dành riêng một nhóm GID cho nhà cung cấp sử dụng. Ngăn xếp UWB AOSP 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 quy cách. Để biết thông tin chi tiết, hãy xem phần 8.4 của thông số kỹ thuật UCI.
Các 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.
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 gói HAL android.hardware.uwb.fira_android được hỗ trợ trên thiết bị thông qua IUwbChip.getSupportedAndroidUciVersion(). Khung này 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 GID và OID của Android
Bảng sau đây liệt kê các GID và OID cho Android. GID 0xE và 0xF được dành riêng cho các nhà sản xuất thiết bị gốc (OEM) Android sử dụng.
| GID | OID | Định nghĩa |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Được lệnh và phản hồi sử dụng để nhận số liệu thống kê liên quan đến nguồn UWB.
Chỉ được hỗ trợ nếu bạn đặt UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY thành 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Dùng để đặt mã quốc gia hiện hành theo quy định (được xác định bằng SIM hoặc Wi-Fi hoặc do nhà sản xuất thiết bị gốc (OEM) mã hoá cứng). 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 thông báo sử dụng để nhận số liệu thống kê chẩn đoán phạm vi UWB.
Chỉ được hỗ trợ nếu bạn đặt UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS thành 1.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Dành riêng cho OEM sử dụng. |
Tiện ích của nhà cung cấp cho các thông báo được xác định theo quy cách UCI
Phần này mô tả thông tin chi tiết về phần mở rộng của nhà cung cấp cho các thông báo do quy cách 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) do ngăn xếp AOSP xác định trong phần dành riêng cho nhà cung cấp của 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ã nhận dạng) |
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 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 tính năng 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 là 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 về bit:
|
CORE_GET_CAPS_INFO_RSP
Sau đây là các TLV do ngăn xếp AOSP xác định trong phần dành riêng cho 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ã nhận dạng) |
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 khả năng hỗ trợ truy vấn số liệu thống kê về nguồn điện. Giá trị:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | Giá trị 1 byte cho biết có hỗ trợ tính năng xen kẽ ăng-ten. Giá trị:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Giá trị 4 byte cho biết khoảng thời gian đo khoảng cách 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 cho biết 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ị 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 khả năng hỗ trợ báo cáo RSSI. Giá trị:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | Giá trị 1 byte cho biết khả năng hỗ trợ 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 tối thiểu của khung được hỗ trợ trong RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | Giá trị 4 byte cho biết số phiên hoạt động trong phạm vi FiRa tối đa được hỗ trợ. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | Mặt nạ bit 2 byte để chỉ ra 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 của nhà cung cấp. Các thông tin 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 không thể bắt đầu phiên đo khoảng cách hiện tại do xung đột với các phiên đo khoảng cách 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 khoảng thời gian hiện tại vì các lý do theo 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 do UWBS gửi khi trạng thái của một phiên đo khoảng cách thay đổi (ví dụ: từ ACTIVE thành 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ợ tính năng đo khoảng cách theo góc tới. |
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 đo phạm vi CCC hoặc FiRa khác. |
REASON_REGULATION_UWB_OFF |
0x82 |
Trạng thái phiên bị thay đổi vì UWB phải bị tắt vì lý do theo quy định. |