Antarmuka UWB HAL

Stack ultra-wideband (UWB) AOSP menggunakan antarmuka UCI yang ditentukan FiRa sebagai platform HAL. Antarmuka HAL menggunakan pipe 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 dengan versi sebelumnya dan berfungsi dengan versi UCI apa pun yang diterapkan oleh vendor UWB di perangkat. Karena framework UWB AOSP adalah modul, framework ini juga dapat secara selektif menambahkan dukungan untuk permintaan perubahan (CR) yang disetujui dari spesifikasi UCI draf yang ditargetkan untuk rilis standar FiRa utama. Semua draf CR tersebut 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, dan proses mulai dan berhenti sesi UWB.

Inisialisasi stack UWB

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

Deinisialisasi stack UWB

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

Memulai dan menghentikan sesi UWB

Gambar 3. Alur awal/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 (tercantum dalam urutan prioritas). Framework UWB berhenti di sumber pertama tempat kode negara ditentukan.

  1. Ganti kode negara: Kode negara 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 telephony terakhir yang diketahui: Kode negara terakhir yang diketahui diambil melalui seluler. Jika ada beberapa SIM yang menampilkan kode berbeda, kode negara yang dipilih tidak dapat ditentukan.
  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. Kemudian, jika dapat menentukan kode negara yang valid, framework UWB akan 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 lokal 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 akan 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 status stack UWB.

Format perintah yang ditentukan spesifikasi FIRA UCI

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

Pembuatan versi antarmuka

Spesifikasi UCI memungkinkan vendor UWB menampilkan versi stack UCI yang diimplementasikan oleh perangkat menggunakan perintah UCI_GET_DEVICE_INFO_RSP dan UCI_GET_CAPS_INFO_RSP. Framework ini menggunakan perintah ini untuk mengambil versi UCI perangkat dan mengubah perilakunya sebagaimana mestinya.

Daftar draf CR yang didukung oleh modul UWB

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

Antarmuka UCI Android (bagian vendor FiRa)

Spesifikasi UCI menentukan kumpulan ID grup (GID) dan ID opcode (OID) untuk semua pesan yang ditentukan spesifikasi. Spesifikasi ini juga mencadangkan kumpulan 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 tentang spesifikasi UCI.

Pesan vendor ini yang digunakan oleh Android 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 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 disediakan untuk digunakan OEM Android.

GID 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 ditetapkan ke 1.
ANDROID_SET_COUNTRY_CODE = 0x1

Digunakan untuk menetapkan kode negara peraturan 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. 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 ditetapkan ke 1.
OEM = 0xE,0xF 0x00 - 0x3F Disimpan untuk penggunaan OEM.

Ekstensi vendor ke pesan yang ditentukan spesifikasi UCI

Bagian ini menjelaskan detail ekstensi vendor ke pesan yang ditentukan oleh 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 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
(octet)		 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. Konfigurasikan parameter ini hanya jika CORE_GET_CAPS_INFO_RSP menampilkan SUPPORTED_DIAGNOSTICS dengan nilai 1 yang menunjukkan bahwa fitur pelaporan diagnostik 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. Bitmask ini berukuran 1 byte di Android 14 atau yang lebih tinggi dan 4 byte di Android 13 atau yang lebih rendah.

Konfigurasikan parameter ini hanya jika CORE_GET_CAPS_INFO_RSP menampilkan 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

CORE_GET_CAPS_INFO_RSP

Berikut adalah TLV yang ditentukan oleh stack AOSP di bagian TLV yang direservasi 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
(octet)		 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 fitur yang berinterleaving antena.

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 milidetik.
SUPPORTED_RANGE_DATA_NTF_CONFIG 4 0xE5 2 Bitmask 4 byte yang menunjukkan nilai RANGE_DATA_NTF_CONFIG yang didukung. Bitmask dengan setiap bit sesuai dengan nilai yang digunakan di RANGE_DATA_NTF_CONFIG di 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 maksimum sesi rentang FiRa yang didukung.
SUPPORTED_CHANNELS_AOA 2 0xEA 2

Bitmask 2 byte untuk menunjukkan saluran yang mendukung AoA. Setiap 1 dalam bitmask sesuai dengan saluran UWB tertentu.

Nilai:

  • 0x01: Mendukung Saluran 5
  • 0x02: Saluran 6 didukung
  • 0x04: Saluran 8 didukung
  • 0x08: Mendukung Channel 9
  • 0x10: Channel 10 didukung
  • 0x20: Channel 12 didukung
  • 0x40: Saluran 13 didukung
  • 0x80: Mendukung Channel 14

Kode status

Berikut adalah kode status di ruang vendor. Informasi 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 pengukuran rentang saat ini tidak dapat dimulai karena konflik dengan sesi pengukuran rentang CCC atau FiRa lainnya.
STATUS_REGULATION_UWB_OFF 0x53

Kode status yang ditampilkan saat sesi pengukuran 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 saat status sesi pengukuran rentang berubah (misalnya, dari ACTIVE menjadi 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 sesi rentang CCC atau FiRa lainnya.
REASON_REGULATION_UWB_OFF 0x82

Status sesi berubah karena UWB harus dinonaktifkan karena alasan peraturan.