Antarmuka UWB HAL

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.

1. Ganti kode negara: Kode negara dipaksa melalui perintah adb shell (pengujian lokal atau otomatis).
2. Kode negara telepon: Kode negara diambil melalui seluler. Jika ada beberapa SIM yang memberikan kode berbeda, kode negara yang dipilih tidak dapat ditentukan.
3. Kode negara Wi-Fi: Kode negara diambil melalui Wi-Fi (80211.ad).
4. 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.
5. Kode negara lokasi: Kode negara diambil dari penyedia lokasi gabungan LocationManager .
6. 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:

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

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.

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.

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.

Kode status

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

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 ).