Antarmuka UWB HAL

Stack ultra-wideband (UWB) AOSP menggunakan antarmuka UCI yang ditentukan FiRa sebagai permukaan HAL. Antarmuka HAL menggunakan saluran buram (IUwbChip::sendUciMessage() dan IUwbClientCallback::onUciMessage()) untuk mengirim dan menerima perintah, respons, dan notifikasi antarmuka perintah UWB (UCI). Semua vendor UWB Android harus mendukung semua pesan yang ditentukan spesifikasi FiRa. Framework UWB kompatibel mundur dan berfungsi dengan versi UCI apa pun yang diterapkan oleh vendor UWB di perangkat. Karena framework UWB AOSP adalah modul, framework ini juga dapat menambahkan dukungan secara selektif untuk permintaan perubahan (CR) yang disetujui dari draf spesifikasi UCI yang ditujukan untuk rilis standar FiRa utama. Setiap draf CR yang diterapkan dapat berubah sewaktu-waktu.

Definisi antarmuka

Antarmuka HAL UWB ditentukan menggunakan AIDL stabil. Antarmuka utama menggunakan paket android.hardware.uwb.

Berikut 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 framework UWB

Gambar berikut mengilustrasikan alur panggilan dari framework UWB untuk inisialisasi stack UWB, deinisialisasi stack UWB, serta proses mulai dan berhenti sesi UWB.

Gambar 1. Alur panggilan inisialisasi stack UWB (tombol UWB diaktifkan)

Gambar 2. Alur panggilan deinisialisasi stack UWB (tombol UWB dinonaktifkan)

Gambar 3. Alur mulai/berhenti sesi UWB

Konfigurasi kode negara UWB

Seperti yang ditunjukkan pada Gambar 1, framework UWB mengonfigurasi kode negara UWB selama inisialisasi stack UWB menggunakan perintah UCI ruang vendor ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). Framework UWB mencoba menentukan kode negara UWB menggunakan sumber berikut (yang tercantum dalam urutan prioritas). Framework UWB berhenti di sumber pertama tempat kode negara ditentukan.

1. Ganti kode negara: Kode negara yang dipaksakan melalui perintah shell adb (pengujian lokal atau otomatis).
2. Kode negara telepon: Kode negara yang diambil melalui seluler. Jika ada beberapa SIM yang menampilkan kode berbeda, kode negara yang dipilih tidak dapat ditentukan.
3. Kode negara Wi-Fi: Kode negara yang diambil melalui Wi-Fi (80211.ad).
4. Kode negara telephony terakhir yang diketahui: Kode negara terakhir yang diketahui dan diambil melalui jaringan seluler. Jika ada beberapa SIM yang menampilkan kode yang berbeda, kode negara yang dipilih tidak deterministik.
5. Kode negara lokasi: Kode negara yang diambil dari penyedia lokasi gabungan LocationManager.
6. Kode negara default OEM: Kode negara yang ditetapkan oleh produsen perangkat.

Jika framework UWB tidak dapat menentukan kode negara UWB, framework akan memanggil perintah UCI ANDROID_SET_COUNTRY_CODE dengan nilai DEFAULT_COUNTRY_CODE ("00") dan memberi tahu aplikasi UWB bahwa status stack UWB adalah DISABLED. Selanjutnya, saat framework UWB dapat menentukan kode negara yang valid, framework tersebut akan mengonfigurasi kode negara baru menggunakan perintah ANDROID_SET_COUNTRY_CODE dan memberi tahu aplikasi UWB bahwa stack UWB READY.

Jika UWB tidak dapat digunakan karena peraturan setempat di suatu negara, pengontrol UWB akan menampilkan kode status STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Framework UWB kemudian memberi tahu aplikasi UWB bahwa status stack UWB adalah DISABLED.

Saat pengguna bepergian ke negara lain, framework UWB mengonfigurasi kode negara baru menggunakan perintah UCI ANDROID_SET_COUNTRY_CODE. Bergantung pada kode status yang ditampilkan oleh pengontrol UWB (berdasarkan peraturan UWB di negara baru), hal ini dapat menyebabkan perubahan pada status stack UWB.

Format perintah yang ditentukan spesifikasi UCI FIRA

Untuk format paket kontrol UCI, lihat bagian 4.4.2 spesifikasi UCI.

Pembuatan versi antarmuka

Spesifikasi UCI memungkinkan vendor UWB mengekspos versi stack UCI yang diterapkan oleh perangkat menggunakan perintah UCI_GET_DEVICE_INFO_RSP dan UCI_GET_CAPS_INFO_RSP. Framework menggunakan perintah ini untuk mengambil versi UCI perangkat dan mengubah perilakunya sesuai dengan versi tersebut.

Daftar draf CR yang didukung oleh modul UWB

Draf CR berikut untuk FiRa 2.0 didukung oleh modul UWB versi #330810000:

• CR 287
• Dukungan SUS API dan Spesifikasi UCI untuk Persyaratan Antarmuka Kunci Digital CCC

Antarmuka UCI Android (bagian vendor FiRa)

Spesifikasi UCI menentukan serangkaian ID grup (GID) dan ID opcode (OID) untuk semua pesan yang ditentukan spesifikasi. Spesifikasi juga mencadangkan serangkaian GID yang dicadangkan secara eksklusif untuk penggunaan vendor. Stack UWB AOSP menggunakan beberapa GID dan OID vendor ini untuk perintah khusus Android yang tidak ditentukan dalam spesifikasi. Untuk mengetahui detailnya, lihat bagian 8.4 spesifikasi UCI.

Pesan vendor yang digunakan oleh Android ini ditentukan dalam paket HAL android.hardware.uwb.fira_android.

Pembuatan versi antarmuka vendor

Vendor UWB harus mengekspos versi paket HAL android.hardware.uwb.fira_android yang didukung di perangkat melalui IUwbChip.getSupportedAndroidUciVersion(). Framework menggunakan informasi 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.

Ekstensi vendor untuk pesan yang ditentukan spesifikasi UCI

Bagian ini menjelaskan detail ekstensi vendor untuk pesan yang ditentukan spesifikasi UCI.

SESSION_SET_APP_CONFIG_[CMD|RSP] dan SESSION_GET_APP_CONFIG_[CMD|RSP]

Berikut adalah nilai panjang jenis (TLV) yang ditentukan oleh stack AOSP di bagian TLV yang dicadangkan vendor dalam 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.

CORE_GET_CAPS_INFO_RSP

Berikut adalah TLV yang ditentukan oleh stack 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.

Kode status

Berikut adalah kode status di ruang vendor. Nilai ini ditampilkan dalam respons UCI (seperti SESSION_START_RSP) oleh subsistem UWB (UWBS).

Kode alasan perubahan status di SESSION_STATUS_NTF

Berikut adalah kode alasan perubahan status yang ditentukan di ruang vendor untuk kolom status yang ditampilkan oleh UWBS dalam SESSION_STATUS_NTF. Notifikasi ini dikirim oleh UWBS saat status sesi pengukuran jarak berubah (misalnya, dari ACTIVE ke IDLE).