Tumpukan ultra-wideband (UWB) AOSP menggunakan antarmuka UCI yang ditentukan FiRa sebagai permukaan HAL. Antarmuka HAL menggunakan pipa buram ( IUwbChip::sendUciMessage()
dan IUwbClientCallback::onUciMessage()
) untuk mengirim dan menerima perintah, respons, dan pemberitahuan antarmuka perintah UWB (UCI). Semua vendor Android UWB harus mendukung semua pesan yang ditentukan spesifikasi FiRa. Kerangka kerja UWB kompatibel dan berfungsi dengan versi UCI apa pun yang diterapkan oleh vendor UWB pada perangkat. Karena kerangka kerja AOSP UWB adalah sebuah modul , ia juga dapat secara selektif menambahkan dukungan untuk permintaan perubahan (CR) yang disetujui dari rancangan spesifikasi UCI yang ditargetkan untuk rilis standar FiRa utama. Draf CR apa pun yang diterapkan dapat berubah sewaktu-waktu.
Definisi antarmuka
Antarmuka UWB HAL didefinisikan menggunakan AIDL yang stabil . Antarmuka utama menggunakan paket android.hardware.uwb
.
Berikut ini adalah dua antarmuka utama dalam paket 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);
}
Alur panggilan HAL dari kerangka UWB
Gambar berikut mengilustrasikan alur panggilan dari kerangka UWB untuk inisialisasi tumpukan UWB, deinisialisasi tumpukan UWB, dan proses memulai dan menghentikan sesi UWB.
Gambar 1. Alur panggilan inisialisasi tumpukan UWB (pengalihan UWB aktif)
Gambar 2. Alur panggilan deinisialisasi tumpukan UWB (pengalihan UWB nonaktif)
Gambar 3. Alur mulai/berhenti sesi UWB
Konfigurasi kode negara UWB
Seperti yang ditunjukkan pada Gambar 1, kerangka kerja UWB mengonfigurasi kode negara UWB selama inisialisasi tumpukan UWB menggunakan perintah UCI ruang vendor ANDROID_SET_COUNTRY_CODE
(GID= 0xC
, OID= 0x1
). Kerangka kerja UWB berupaya menentukan kode negara UWB menggunakan sumber-sumber berikut (tercantum dalam urutan prioritas). Kerangka UWB berhenti pada sumber pertama dimana kode negara ditentukan.
- Ganti kode negara: Kode negara dipaksa melalui perintah adb shell (pengujian lokal atau otomatis).
- Kode negara telepon: Kode negara diambil melalui seluler. Jika ada beberapa SIM yang memberikan kode berbeda, kode negara yang dipilih tidak dapat ditentukan.
- Kode negara Wi-Fi: Kode negara diambil melalui Wi-Fi (80211.ad).
- Kode negara telepon terakhir yang diketahui: Kode negara terakhir yang diketahui diambil melalui seluler. Jika ada beberapa SIM yang memberikan kode berbeda, kode negara yang dipilih tidak dapat ditentukan.
- Kode negara lokasi: Kode negara diambil dari penyedia lokasi gabungan
LocationManager
. - Kode negara default OEM: Kode negara yang ditetapkan oleh produsen perangkat.
Jika kerangka UWB tidak dapat menentukan kode negara UWB, kerangka tersebut akan memanggil perintah UCI ANDROID_SET_COUNTRY_CODE
dengan nilai DEFAULT_COUNTRY_CODE ("00")
dan memberi tahu aplikasi UWB bahwa status tumpukan UWB adalah DISABLED
. Nantinya, ketika kerangka UWB dapat menentukan kode negara yang valid, kerangka tersebut akan mengonfigurasi kode negara baru menggunakan perintah ANDROID_SET_COUNTRY_CODE
dan memberi tahu aplikasi UWB bahwa tumpukan UWB sudah READY
.
Jika UWB tidak dapat digunakan karena peraturan lokal di suatu negara, pengontrol UWB mengembalikan kode status STATUS_CODE_ANDROID_REGULATION_UWB_OFF
. Kerangka kerja UWB kemudian memberi tahu aplikasi UWB bahwa status tumpukan UWB adalah DISABLED
.
Saat pengguna bepergian ke negara lain, kerangka UWB mengonfigurasi kode negara baru menggunakan perintah UCI ANDROID_SET_COUNTRY_CODE
. Bergantung pada kode status yang dikembalikan oleh pengontrol UWB (berdasarkan peraturan UWB di negara baru), hal ini mungkin menyebabkan perubahan pada status tumpukan UWB.
Format perintah yang ditentukan spesifikasi FIRA UCI
Untuk format paket kontrol UCI, lihat bagian 4.4.2 spesifikasi UCI .
Versi antarmuka
Spesifikasi UCI memungkinkan vendor UWB mengekspos versi tumpukan UCI yang diterapkan oleh perangkat menggunakan perintah UCI_GET_DEVICE_INFO_RSP
dan UCI_GET_CAPS_INFO_RSP
. Kerangka kerja ini menggunakan perintah ini untuk mengambil versi UCI perangkat dan mengubah perilakunya.
Daftar draft CR yang didukung oleh modul UWB
Draf CR berikut untuk FiRa 2.0 didukung oleh modul UWB versi #330810000:
Antarmuka Android UCI (bagian vendor FiRa)
Spesifikasi UCI mendefinisikan sekumpulan pengidentifikasi grup (GID) dan pengidentifikasi opcode (OID) untuk semua pesan yang ditentukan spesifikasi. Spesifikasi ini juga mencadangkan satu set GID yang dicadangkan secara eksklusif untuk penggunaan vendor. Tumpukan AOSP UWB menggunakan beberapa GID dan OID vendor ini untuk perintah khusus Android yang tidak ditentukan dalam spesifikasi. Untuk detailnya, lihat bagian 8.4 dari spesifikasi UCI .
Pesan vendor yang digunakan oleh Android ini ditentukan dalam paket HAL android.hardware.uwb.fira_android
.
Versi antarmuka vendor
Vendor UWB harus mengekspos versi paket HAL android.hardware.uwb.fira_android
yang didukung pada perangkat melalui IUwbChip.getSupportedAndroidUciVersion()
. Kerangka kerja ini menggunakan informasi pembuatan versi ini untuk menangani kompatibilitas mundur.
Daftar GID dan OID Android
Tabel berikut mencantumkan GID dan OID untuk Android. GID 0xE
dan 0xF
dicadangkan untuk digunakan oleh OEM Android.
GID | OID | Definisi |
---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Digunakan oleh perintah dan respons untuk mendapatkan statistik terkait kekuatan UWB. Hanya didukung jika UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY diatur ke 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Digunakan untuk mengatur kode negara peraturan saat ini (ditentukan menggunakan SIM atau Wi-Fi, atau dikodekan secara hardcode oleh OEM). Kode negara dikirim sebagai nilai 2 byte yang sesuai dengan kode negara ISO-3166. Nilai | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Digunakan oleh notifikasi untuk mendapatkan statistik diagnostik rentang UWB. Hanya didukung jika UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS diatur ke 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Dicadangkan untuk penggunaan OEM. |
Ekstensi vendor ke pesan yang ditentukan spesifikasi UCI
Bagian ini menjelaskan detail ekstensi vendor ke pesan yang ditentukan spesifikasi UCI.
SESSION_SET_APP_CONFIG_[CMD|RSP] dan SESSION_GET_APP_CONFIG_[CMD|RSP]
Berikut ini adalah nilai panjang tipe (TLV) yang ditentukan oleh tumpukan AOSP di bagian TLV yang dicadangkan vendor di APP_CONFIG
:
- GID: 0001b (grup konfigurasi sesi UWB)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD
) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD
)
Tabel berikut mencantumkan parameter untuk pesan konfigurasi sesi UWB.
Nama parameter | Panjang (oktet) | Menandai (ID) | Versi antarmuka vendor | Keterangan |
---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | Rasio interleaving jika AOA_RESULT_REQ diatur ke 0xF0 . Hanya didukung jika UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING disetel ke 1 . |
NB_OF_AZIMUTH_MEASUREMENTS | 1 | 0xE4 | 1 | |
NB_OF_ELEVATION_MEASUREMENTS | 1 | 0xE5 | 1 | |
ENABLE_DIAGNOSTICS | 1 | 0xE8 | 2 | Nilai 1 byte untuk mengaktifkan atau menonaktifkan pelaporan diagnostik. Konfigurasikan parameter ini hanya ketika Nilai:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 atau 4 | 0xE9 | 2 | Bitmask 1-byte atau 4-byte untuk mengonfigurasi pelaporan diagnostik. Bitmask ini berukuran 1 byte di Android 14 atau lebih tinggi dan 4 byte di Android 13 atau lebih rendah. Konfigurasikan parameter ini hanya ketika Definisi bit:
|
CORE_GET_CAPS_INFO_RSP
Berikut ini adalah TLV yang ditentukan oleh tumpukan AOSP di bagian TLV yang dicadangkan vendor di CAPS_INFO
:
- GID: 0000b (grup inti UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP
)
Tabel berikut mencantumkan parameter untuk pesan kemampuan UWB.
Nama parameter | Panjang (oktet) | Menandai (ID) | Versi antarmuka vendor | Keterangan |
---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Nilai 1 byte menunjukkan dukungan untuk kueri statistik daya. Nilai:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Nilai 1 byte menunjukkan dukungan untuk fitur interleaving antena. Nilai:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Nilai 4 byte menunjukkan interval rentang minimum yang didukung dalam milidetik. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | Bitmask 4 byte menunjukkan nilai RANGE_DATA_NTF_CONFIG yang didukung. Bitmask yang setiap bitnya sesuai dengan nilai yang digunakan dalam RANGE_DATA_NTF_CONFIG di SET_APP_CFG_CMD . |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | Nilai 1 byte menunjukkan dukungan pelaporan RSSI. Nilai:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Nilai 1 byte menunjukkan dukungan pelaporan diagnostik. Nilai:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | Nilai 4 byte menunjukkan durasi slot minimum yang didukung di RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | Nilai 4 byte menunjukkan jumlah maksimum sesi rentang FiRa yang didukung. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | Bitmask 2 byte untuk menunjukkan saluran yang mendukung AoA. Setiap Nilai:
|
Kode status
Berikut ini adalah kode status di ruang vendor. Ini dikembalikan dalam respons UCI (seperti SESSION_START_RSP
) oleh subsistem UWB (UWBS).
Kode status | Nilai | Keterangan |
---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Kode status dikembalikan ketika sesi rentang saat ini tidak dapat dimulai karena konflik dengan sesi rentang CCC atau FiRa lainnya. |
STATUS_REGULATION_UWB_OFF | 0x53 | Kode status dikembalikan ketika sesi rentang saat ini tidak dapat dimulai karena alasan peraturan UWB. |
Nyatakan kode alasan perubahan di SESSION_STATUS_NTF
Berikut ini adalah kode alasan perubahan status yang ditentukan di ruang vendor untuk bidang status yang dikembalikan oleh UWBS di SESSION_STATUS_NTF
. Pemberitahuan ini dikirim oleh UWBS ketika keadaan sesi mulai berubah (misalnya, dari ACTIVE
ke IDLE
).
Sebutkan kode alasan perubahan | Nilai | Keterangan |
---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | Status sesi berubah karena saluran yang dikonfigurasi tidak mendukung rentang AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | Status sesi berubah karena konflik dengan sesi rentang CCC atau FiRa lainnya. |
REASON_REGULATION_UWB_OFF | 0x82 | Status sesi berubah karena UWB harus dinonaktifkan karena alasan peraturan. |