Antarmuka UWB HAL

Catatan: Keanggotaan diperlukan untuk mengakses link ke UCI yang ditetapkan oleh FiRa spesifikasi antarmuka.

AOSP stack ultra-wideband (UWB) menggunakan Antarmuka UCI yang ditentukan FiRa sebagai permukaan HAL. Antarmuka HAL menggunakan pipa buram (IUwbChip::sendUciMessage() dan IUwbClientCallback::onUciMessage()) yang akan dikirim dan menerima perintah, respons, dan notifikasi antarmuka perintah UWB. Semua vendor UWB Android harus mendukung semua spesifikasi FiRa yang ditentukan membuat pesan teks. Framework UWB kompatibel dengan versi lama dan berfungsi dengan UCI apa pun yang diimplementasikan oleh vendor UWB pada perangkat. Karena UWB AOSP ini adalah modul, secara selektif menambahkan dukungan untuk permintaan perubahan yang disetujui (CR) dari draf spesifikasi UCI yang ditargetkan untuk rilis standar FiRa utama. Seperti apa pun draf CR yang diterapkan dapat berubah sewaktu-waktu.

Definisi antarmuka

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

Berikut adalah dua antarmuka utama di android.hardware.uwb paket.

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 ini mengilustrasikan alur panggilan dari kerangka kerja UWB untuk Inisialisasi stack UWB, deinisialisasi stack UWB, serta awal dan awal sesi UWB menghentikan proses.

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

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

Gambar 3. Alur awal/berhenti sesi UWB

Konfigurasi kode negara UWB

Seperti yang terlihat di 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). Kerangka kerja UWB mencoba menentukan kode negara UWB menggunakan sumber berikut (tercantum dalam prioritas lainnya). Framework UWB berhenti di sumber pertama tempat kode negara berada ditentukan.

1. Mengganti kode negara: Kode negara yang dipaksa melalui perintah shell adb (pengujian lokal atau otomatis).
2. Kode negara telepon: Kode negara yang diambil melalui jaringan seluler. Jika ada beberapa SIM yang menampilkan kode berbeda, kode negara yang dipilih bersifat nondeterministik.
3. Kode negara Wi-Fi: Kode negara yang 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 menampilkan hasil berbeda kode negara, kode negara yang dipilih bersifat nondeterministik.
5. Kode negara lokasi: Kode negara yang diambil dari LocationManager penyedia lokasi fusi.
6. Kode negara default OEM: Kode negara yang ditetapkan oleh produsen perangkat.

Jika kerangka kerja UWB tidak dapat menentukan kode negara UWB, UWB 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. Nantinya, ketika kerangka kerja UWB mampu tentukan yang valid, hal ini mengonfigurasi kode negara baru menggunakan Perintah ANDROID_SET_COUNTRY_CODE dan memberi tahu aplikasi UWB bahwa stack UWB adalah READY.

Jika UWB tidak dapat digunakan karena peraturan setempat di suatu negara, pengontrol UWB mengembalikan Kode status STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Kerangka kerja UWB kemudian memberi tahu aplikasi UWB bahwa status stack UWB adalah DISABLED.

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

Format perintah yang ditetapkan berdasarkan spesifikasi FIRA UCI

Untuk mengetahui format paket kontrol UCI, lihat pasal 4.4.2 UCI spesifikasi.

Pembuatan versi antarmuka

Spesifikasi UCI memungkinkan vendor UWB mengekspos versi stack UCI yang diimplementasikan oleh perangkat menggunakan UCI_GET_DEVICE_INFO_RSP dan perintah UCI_GET_CAPS_INFO_RSP. Framework ini menggunakan perintah ini untuk mengambil Versi UCI perangkat dan ubah perilakunya.

Daftar draf CR yang didukung oleh modul UWB

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

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

Antarmuka UCI Android (bagian vendor FiRa)

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

Pesan vendor yang digunakan oleh Android ini didefinisikan di bagian Paket HAL android.hardware.uwb.fira_android.

Pembuatan versi antarmuka vendor

Vendor UWB harus mengekspos versi android.hardware.uwb.fira_android Paket HAL didukung pada perangkat melalui IUwbChip.getSupportedAndroidUciVersion(). Kerangka kerja ini menggunakan informasi pembuatan versi untuk menangani kompatibilitas mundur.

Daftar GID dan OID Android

Tabel berikut mencantumkan GID dan OID untuk Android. GID 0xE dan 0xF disediakan untuk digunakan oleh OEM Android.

GID	OID (OID)	Definisi
ANDROID = 0xC	ANDROID_GET_POWER_STATS = 0x0	Digunakan oleh perintah dan respons untuk mendapatkan statistik terkait daya UWB. Hanya didukung jika UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY disetel ke 1.
	ANDROID_SET_COUNTRY_CODE = 0x1	Digunakan untuk mengatur kode negara regulasi saat ini (ditentukan menggunakan SIM atau Wi-Fi, atau di-hardcode oleh OEM). Kode negara dikirim sebagai nilai 2 byte yang sesuai dengan kode negara ISO-3166. J nilai 00 digunakan untuk menunjukkan bahwa kode negara tidak diketahui.
	ANDROID_RANGE_DIAGNOSTICS = 0x2	Digunakan oleh notifikasi untuk mendapatkan statistik diagnostik rentang UWB. Hanya didukung jika UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS disetel ke 1.
OEM = 0xE,0xF	0x00 - 0x3F	Ditujukan untuk penggunaan OEM.

Pesan yang ditentukan ekstensi vendor ke spesifikasi UCI

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

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

Berikut ini adalah nilai panjang tipe (TLV) yang didefinisikan oleh tumpukan AOSP dalam bagian yang dicadangkan vendor dari TLV 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.

Catatan: Lihat Tabel 34 tentang spesifikasi UCI untuk mengetahui parameter lain yang diharapkan.

Nama parameter	Panjang (oktet)	Tag (ID)	Versi antarmuka vendor	Deskripsi
NB_OF_RANGE_MEASUREMENTS	1	0xE3	1	Rasio interleaving jika AOA_RESULT_REQ ditetapkan ke 0xF0. Hanya didukung jika UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING ditetapkan 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. Konfigurasi parameter ini hanya saat CORE_GET_CAPS_INFO_RSP menampilkan SUPPORTED_DIAGNOSTICS dengan nilai 1 yang menunjukkan bahwa fitur pelaporan diagnostik adalah didukung. Nilai: 1: Fitur diaktifkan 0: Fitur dinonaktifkan
DIAGRAMS_FRAME_REPORTS_FIELDS	1 atau 4	0xE9	2	Bitmask 1 byte atau 4 byte untuk mengonfigurasi pelaporan diagnostik. Ini bitmask adalah 1 byte di Android 14 atau lebih tinggi dan 4 byte di Android 13 atau yang lebih rendah. Konfigurasikan parameter ini hanya bila Pengembalian dengan biaya CORE_GET_CAPS_INFO_RSP SUPPORTED_DIAGNOSTICS dengan nilai 1 yang menunjukkan bahwa fitur pelaporan diagnostik didukung. Definisi bit: b0 (0x01): Mengaktifkan kolom RSSI b1 (0x02): Mengaktifkan kolom AoA b2 (0x04): Mengaktifkan kolom CIR

INTI_CAPS_INFO_RSP

Berikut ini adalah TLV yang didefinisikan oleh tumpukan AOSP di vendor yang disediakan bagian dari TLV di CAPS_INFO:

• GID: 0000b (grup inti UWB)
• OID: 000011b (CORE_GET_CAPS_INFO_RSP)

Tabel berikut mencantumkan parameter untuk pesan kemampuan UWB.

Catatan: Lihat Tabel 34 tentang spesifikasi UCI untuk mengetahui parameter lain yang diharapkan.

Nama parameter	Panjang (oktet)	Tag (ID)	Versi antarmuka vendor	Deskripsi
SUPPORTED_POWER_STATS_QUERY	1	0xC0	1	Nilai 1 byte yang menunjukkan dukungan untuk kueri statistik daya. Nilai: 1: Fitur didukung 0: Fitur tidak didukung
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING	1	0xE3	1	Nilai 1 byte yang menunjukkan dukungan untuk antena yang berinterleaving aplikasi baru. Nilai: 1: Fitur didukung 0: Fitur tidak didukung
SUPPORTED_MIN_RANGING_INTERVAL_MS	4	0xE4	2	Nilai 4 byte yang menunjukkan interval rentang minimum yang didukung dalam dalam milidetik.
SUPPORTED_RANGE_DATA_NTF_CONFIG	4	0xE5	2	4 byte bitmask yang menunjukkan RANGE_DATA_NTF_CONFIG nilai. {i>Bitmask<i} di mana setiap bit sesuai dengan nilai yang digunakan dalam RANGE_DATA_NTF_CONFIG dalam SET_APP_CFG_CMD.
SUPPORTED_RSSI_REPORTING	1	0xE6	2	Nilai 1 byte yang menunjukkan dukungan pelaporan RSSI. Nilai: 1: Fitur didukung 0: Fitur tidak didukung
SUPPORTED_DIAGNOSTICS	1	0xE7	2	Nilai 1 byte yang menunjukkan dukungan pelaporan diagnostik. Nilai: 1: Fitur didukung 0: Fitur tidak didukung
SUPPORTED_MIN_SLOT_DURATION_RSTU	4	0xE8	2	Nilai 4 byte yang menunjukkan durasi slot minimum yang didukung di RSTU.
SUPPORTED_MAX_RANGING_SESSION_NUMBER	4	0xE9	2	Nilai 4 byte yang menunjukkan jumlah rentang FiRa maksimum yang didukung sesi.
SUPPORTED_CHANNELS_AOA	2	0xEA	2	2 byte bitmask untuk menunjukkan saluran yang mendukung AoA. Masing-masing 1 dalam bitmask sesuai dengan saluran UWB tertentu. Nilai: 0x01: Mendukung Saluran 5 0x02: Mendukung Saluran 6 0x04: Mendukung Channel 8 0x08: Mendukung Channel 9 0x10: Mendukung Channel 10 0x20: Mendukung Channel 12 0x40: Mendukung Channel 13 0x80: Mendukung Channel 14

Kode status

Berikut adalah kode status di ruang vendor. Ini ditampilkan dalam Respons UCI (seperti SESSION_START_RSP) oleh subsistem UWB (UWBS).

Kode status	Nilai	Deskripsi
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT	0x52	Kode status yang ditampilkan saat sesi rentang saat ini tidak dapat dimulai karena konflik dengan sesi rentang CCC atau FiRa lainnya.
STATUS_REGULATION_UWB_OFF	0x53	Kode status yang ditampilkan saat sesi rentang saat ini tidak dapat dimulai karena alasan peraturan UWB.

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 di SESSION_STATUS_NTF. Notifikasi ini dikirim oleh UWBS ketika status sesi rentang berubah (misalnya, dari ACTIVE hingga IDLE).

Kode alasan perubahan status	Nilai	Deskripsi
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 CCC atau FiRa lain sesi rentang.
REASON_REGULATION_UWB_OFF	0x82	Status sesi diubah karena UWB harus dinonaktifkan karena alasan peraturan.