Protokol perangkat antarmuka manusia (HID) pelacak kepala, tersedia untuk perangkat yang menjalankan Android 13 dan lebih tinggi, memungkinkan perangkat pelacak kepala dihubungkan ke perangkat Android melalui USB atau Bluetooth dan diekspos ke kerangka kerja dan aplikasi Android melalui sensor kerangka. Protokol ini digunakan untuk mengontrol efek virtualizer audio (audio 3D). Halaman ini menggunakan istilah perangkat dan host dalam pengertian Bluetooth, dimana perangkat berarti perangkat pelacak kepala dan host berarti host Android.
Produsen perangkat harus mengonfigurasi perangkat Android mereka untuk mengaktifkan dukungan protokol HID pelacak kepala. Untuk informasi lebih detail tentang konfigurasi, lihat README Sensor Dinamis .
Halaman ini mengasumsikan pemahaman terhadap sumber daya berikut:
Struktur tingkat atas
Kerangka kerja Android mengidentifikasi perangkat pelacak kepala sebagai perangkat HID.
Untuk contoh lengkap deskriptor HID yang valid, lihat Lampiran 1: Contoh Deskriptor HID .
Di tingkat atas, perangkat pelacak kepala adalah kumpulan aplikasi dengan halaman Sensors ( 0x20 ) dan Other: Custom ( 0xE1 ). Di dalam koleksi ini terdapat beberapa bidang data ( input ) dan properti ( fitur ).
Properti dan bidang data
Bagian ini menjelaskan properti dan bidang data dalam kumpulan aplikasi perangkat pelacak kepala.
Properti: Deskripsi Sensor ( 0x0308 )
Properti Sensor Description ( 0x0308 ) adalah properti string ASCII (8-bit) read-only yang harus berisi nilai berikut:
#AndroidHeadTracker#1.0
Diharapkan tidak ada terminator nol, artinya ukuran total properti ini adalah 23 karakter 8-bit.
Properti ini berfungsi sebagai diskriminator untuk menghindari tabrakan dengan sensor khusus lainnya.
Properti: ID Unik Persisten ( 0x0302 )
Properti Persistent Unique ID ( 0x0302 ) adalah array read-only yang terdiri dari 16 elemen, masing-masing 8 bit (total 128 bit). Tidak ada terminator nol yang diharapkan. Properti ini opsional.
Properti ini memungkinkan perangkat pelacakan kepala yang terintegrasi dalam perangkat audio untuk mereferensikan perangkat audio yang terpasang padanya. Skema berikut ini didukung.
Pelacak kepala mandiri
Jika properti Persistent Unique ID ( 0x0302 ) tidak ada atau disetel ke nol semua, berarti perangkat pelacak kepala tidak terpasang secara permanen ke perangkat audio dan dapat digunakan secara terpisah, misalnya dengan membiarkan pengguna secara manual kaitkan perangkat pelacak kepala dengan perangkat audio terpisah.
Referensi menggunakan alamat MAC Bluetooth
| Oktet | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
| Nilai | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | B | T | MAC Bluetooth | |||||
Dalam skema ini, 8 oktet pertama harus 0 , oktet 8 dan 9 masing-masing harus berisi nilai ASCII B dan T , dan 6 oktet berikutnya diinterpretasikan sebagai alamat MAC Bluetooth, dengan asumsi perangkat pelacak kepala berlaku untuk perangkat audio apa pun yang memiliki alamat MAC ini.
Referensi menggunakan UUID
Setiap kali bit paling signifikan (MSB) dari oktet 8 diatur ( ≥0x80 ), bidang tersebut ditafsirkan sebagai UUID, sebagaimana ditentukan dalam RFC-4122 . Perangkat audio yang sesuai menyediakan UUID yang sama, yang terdaftar pada kerangka Android, melalui mekanisme yang tidak ditentukan dan khusus untuk jenis transportasi yang digunakan.
Properti: Status Pelaporan ( 0x0316 )
Properti Status Pelaporan ( 0x0316 ) adalah properti baca/tulis yang memiliki semantik standar seperti yang ditentukan dalam spesifikasi HID. Tuan rumah menggunakan properti ini untuk menunjukkan ke perangkat peristiwa mana yang harus dilaporkan. Hanya nilai No Events ( 0x0840 ) dan All Events ( 0x0841 ) yang digunakan.
Nilai awal untuk bidang ini harus Tidak Ada Peristiwa dan tidak boleh diubah oleh perangkat, hanya oleh host.
Properti: Status Daya ( 0x0319 )
Properti Power State ( 0x0319 ) adalah properti baca/tulis yang memiliki semantik standar seperti yang ditentukan dalam spesifikasi HID. Host menggunakan properti ini untuk menunjukkan pada perangkat status daya mana yang harus digunakan. Hanya nilai Daya Penuh ( 0x0851 ) dan Daya Mati ( 0x0855 ) yang digunakan.
Nilai awal untuk bidang ini ditentukan oleh perangkat dan tidak boleh diubah oleh perangkat, hanya oleh host.
Properti: Interval Laporan ( 0x030E )
Properti Interval Laporan ( 0x030E ) adalah properti baca/tulis yang memiliki semantik standar seperti yang ditentukan dalam spesifikasi HID. Host menggunakan properti ini untuk menunjukkan ke perangkat seberapa sering melaporkan pembacaan datanya. Satuannya adalah detik. Kisaran valid untuk nilai ini ditentukan oleh perangkat dan dijelaskan menggunakan mekanisme Fisik Min/Maks. Setidaknya kecepatan pelaporan 50 Hz harus didukung, dan kecepatan pelaporan maksimum yang disarankan adalah 100 Hz. Oleh karena itu, interval laporan minimum harus kurang dari atau sama dengan 20 ms, dan disarankan lebih besar dari atau sama dengan 10 ms.
Bidang data: Nilai Khusus 1 ( 0x0544 )
Bidang Nilai Khusus 1 ( 0x0544 ) adalah bidang masukan yang digunakan untuk melaporkan informasi pelacakan kepala aktual. Ini adalah array 3 elemen, diinterpretasikan berdasarkan aturan HID normal untuk nilai fisik seperti yang ditentukan di bagian 6.2.2.7 spesifikasi HID. Kisaran valid untuk setiap elemen adalah [-π, π] rad. Satuannya selalu radian.
Elemen-elemen tersebut diinterpretasikan sebagai: [rx, ry, rz] , sehingga [rx, ry, rz] adalah vektor rotasi , yang mewakili transformasi dari kerangka acuan ke kerangka kepala. Besarannya harus berada dalam kisaran [0..π].
Kerangka referensi bersifat arbitrer, namun umumnya tetap dan harus digunakan dengan tangan kanan. Penyimpangan dalam jumlah kecil dapat diterima. Sumbu kepala adalah:
- X dari telinga kiri ke kanan
- Y dari belakang kepala sampai hidung (belakang ke depan)
- Z dari leher hingga puncak kepala
Bidang data: Nilai Khusus 2 ( 0x0545 )
Bidang Nilai Khusus 2 ( 0x0545 ) adalah bidang masukan yang digunakan untuk melaporkan informasi pelacakan kepala aktual. Ini adalah array titik tetap 3 elemen, diinterpretasikan sesuai dengan aturan HID normal untuk nilai fisik. Satuannya selalu radian/detik.
Elemen-elemen tersebut diinterpretasikan sebagai: [vx, vy, vz] , sehingga [vx, vy, vz] adalah vektor rotasi , yang mewakili kecepatan sudut kerangka kepala (relatif terhadap dirinya sendiri).
Bidang data: Nilai Khusus 3 ( 0x0546 )
Bidang Nilai Khusus 3 ( 0x0546 ) adalah bidang masukan yang digunakan untuk melacak diskontinuitas dalam kerangka acuan. Ini adalah bilangan bulat skalar berukuran 8 bit. Nilai tersebut harus bertambah (dengan sampul) oleh perangkat setiap kali kerangka acuan diubah, misalnya, jika algoritme filter orientasi yang digunakan untuk menentukan orientasi telah disetel ulang statusnya. Nilai ini diinterpretasikan menurut aturan HID normal untuk nilai fisik. Namun, nilai fisik dan satuannya tidak menjadi masalah. Satu-satunya informasi yang relevan dengan host adalah nilai yang diubah. Untuk menghindari masalah numerik terkait hilangnya presisi saat mengkonversi dari satuan logis ke satuan fisik, disarankan untuk menetapkan nilai min fisik, maks fisik, dan eksponen satuan ke nol untuk bidang ini.
Struktur laporan
Pengelompokan properti ke dalam laporan (berdasarkan penetapan ID laporan) bersifat fleksibel. Untuk efisiensi, sebaiknya pisahkan properti baca-saja dari properti baca/tulis.
Untuk kolom data, kolom Nilai Khusus 1, 2, dan 3 harus berada dalam laporan yang sama dan hanya ada dalam satu laporan untuk perangkat tertentu (kumpulan aplikasi).
Kirim laporan masukan
Perangkat harus secara berkala dan asinkron (melalui pesan INPUT HID) mengirimkan laporan masukan ketika semua kondisi ini terpenuhi:
- Properti Power State diatur ke Full Power.
- Properti Negara Pelaporan diatur ke Semua Peristiwa.
- Properti Interval Pelaporan bukan nol.
Properti Interval Pelaporan menentukan seberapa sering laporan dikirim. Jika salah satu ketentuan di atas tidak terpenuhi, perangkat tidak boleh mengirimkan laporan apa pun.
Kompatibilitas maju dan mundur
Protokol HID pelacak kepala menggunakan skema versi yang memungkinkan pembaruan, sekaligus memungkinkan interoperabilitas antara host dan perangkat yang menggunakan versi protokol berbeda. Versi protokol diidentifikasi dengan dua angka, mayor dan minor, yang memiliki semantik berbeda seperti yang dijelaskan di bagian berikut.
Versi yang didukung oleh suatu perangkat dapat ditentukan dengan memeriksa properti Sensor Description ( 0x0308 ).
Kompatibilitas versi kecil
Perubahan pada versi minor kompatibel dengan versi minor sebelumnya yang didasarkan pada versi mayor yang sama. Dalam pembaruan ke versi minor, host mengabaikan bidang data dan properti tambahan. Misalnya, perangkat yang menggunakan protokol versi 1.6 kompatibel dengan host yang mendukung protokol versi 1.x, termasuk versi 1.5.
Kompatibilitas versi utama
Perubahan yang tidak kompatibel dengan versi sebelumnya diperbolehkan untuk perubahan pada versi utama. Untuk mendukung beberapa versi utama untuk interoperabilitas dengan host lama dan baru, perangkat dapat menentukan beberapa koleksi aplikasi dalam deskriptor laporannya. Misalnya:
const unsigned char ReportDescriptor[] = {
HID_USAGE_PAGE_SENSOR,
HID_USAGE_SENSOR_TYPE_OTHER_CUSTOM,
HID_COLLECTION(HID_APPLICATION),
// Feature report 2 (read-only).
HID_REPORT_ID(2),
// Magic value: "#AndroidHeadTracker#1.5"
HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION,
HID_LOGICAL_MIN_8(0),
HID_LOGICAL_MAX_8(0xFF),
HID_REPORT_SIZE(8),
HID_REPORT_COUNT(23),
HID_FEATURE(HID_CONST_VAR_ABS),
...
HID_END_COLLECTION,
HID_COLLECTION(HID_APPLICATION),
// Feature report 12 (read-only).
HID_REPORT_ID(12),
// Magic value: "#AndroidHeadTracker#2.4"
HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION,
HID_LOGICAL_MIN_8(0),
HID_LOGICAL_MAX_8(0xFF),
HID_REPORT_SIZE(8),
HID_REPORT_COUNT(23),
HID_FEATURE(HID_CONST_VAR_ABS),
...
HID_END_COLLECTION,
};
Dalam hal ini, host dapat menghitung semua koleksi aplikasi berbeda yang diiklankan oleh perangkat, memeriksa properti Sensor Description untuk menentukan versi protokol yang diterapkan masing-masing, lalu memilih versi protokol terbaru yang didukung host. Saat dipilih, host bekerja dengan protokol tunggal yang dipilih selama masa koneksi perangkat.
Lampiran: Contoh deskriptor HID
Contoh berikut mengilustrasikan deskriptor HID valid yang khas. Ini menggunakan makro C yang umum digunakan, disediakan di Penggunaan Sensor HID (bagian 4.1).
const unsigned char ReportDescriptor[] = {
HID_USAGE_PAGE_SENSOR,
HID_USAGE_SENSOR_TYPE_OTHER_CUSTOM,
HID_COLLECTION(HID_APPLICATION),
// Feature report 2 (read-only).
HID_REPORT_ID(2),
// Magic value: "#AndroidHeadTracker#1.0"
HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION,
HID_LOGICAL_MIN_8(0),
HID_LOGICAL_MAX_8(0xFF),
HID_REPORT_SIZE(8),
HID_REPORT_COUNT(23),
HID_FEATURE(HID_CONST_VAR_ABS),
// UUID.
HID_USAGE_SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID,
HID_LOGICAL_MIN_8(0),
HID_LOGICAL_MAX_8(0xFF),
HID_REPORT_SIZE(8),
HID_REPORT_COUNT(16),
HID_FEATURE(HID_CONST_VAR_ABS),
// Feature report 1 (read/write).
HID_REPORT_ID(1),
// 1-bit on/off reporting state.
HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE,
HID_LOGICAL_MIN_8(0),
HID_LOGICAL_MAX_8(1),
HID_REPORT_SIZE(1),
HID_REPORT_COUNT(1),
HID_COLLECTION(HID_LOGICAL),
HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_NO_EVENTS,
HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_ALL_EVENTS,
HID_FEATURE(HID_DATA_ARR_ABS),
HID_END_COLLECTION,
// 1-bit on/off power state.
HID_USAGE_SENSOR_PROPERTY_POWER_STATE,
HID_LOGICAL_MIN_8(0),
HID_LOGICAL_MAX_8(1),
HID_REPORT_SIZE(1),
HID_REPORT_COUNT(1),
HID_COLLECTION(HID_LOGICAL),
HID_USAGE_SENSOR_PROPERTY_POWER_STATE_D4_POWER_OFF,
HID_USAGE_SENSOR_PROPERTY_POWER_STATE_D0_FULL_POWER,
HID_FEATURE(HID_DATA_ARR_ABS),
HID_END_COLLECTION,
// 6-bit reporting interval, with values [0x00..0x3F] corresponding to [10ms..100ms].
HID_USAGE_SENSOR_PROPERTY_REPORT_INTERVAL,
HID_LOGICAL_MIN_8(0x00),
HID_LOGICAL_MAX_8(0x3F),
HID_PHYSICAL_MIN_8(10),
HID_PHYSICAL_MAX_8(100),
HID_REPORT_SIZE(6),
HID_REPORT_COUNT(1),
HID_USAGE_SENSOR_UNITS_SECOND,
HID_UNIT_EXPONENT(0xD), // 10^-3
HID_FEATURE(HID_DATA_VAR_ABS),
// Input report 1
// Orientation as rotation vector (scaled to [-pi..pi] rad).
HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_1,
HID_LOGICAL_MIN_16(0x01, 0x80), // LOGICAL_MINIMUM (-32767)
HID_LOGICAL_MAX_16(0xFF, 0x7F), // LOGICAL_MAXIMUM (32767)
HID_PHYSICAL_MIN_32(0x60, 0x4F, 0x46, 0xED), // -314159265
HID_PHYSICAL_MAX_32(0xA1, 0xB0, 0xB9, 0x12), // 314159265
HID_UNIT_EXPONENT(0x08), // 10^-8
HID_REPORT_SIZE(16),
HID_REPORT_COUNT(3),
HID_INPUT(HID_DATA_VAR_ABS),
// Angular velocity as rotation vector (scaled to [-32..32] rad/sec).
HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_2,
HID_LOGICAL_MIN_16(0x01, 0x80), // LOGICAL_MINIMUM (-32767)
HID_LOGICAL_MAX_16(0xFF, 0x7F), // LOGICAL_MAXIMUM (32767)
HID_PHYSICAL_MIN_8(0xE0),
HID_PHYSICAL_MAX_8(0x20),
HID_UNIT_EXPONENT(0x00), // 10^0
HID_REPORT_SIZE(16),
HID_REPORT_COUNT(3),
HID_INPUT(HID_DATA_VAR_ABS),
// Reference frame reset counter.
HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_3,
HID_LOGICAL_MIN_16(0x00, 0x00), // LOGICAL_MINIMUM (0)
HID_LOGICAL_MAX_16(0xFF, 0x00), // LOGICAL_MAXIMUM (255)
HID_PHYSICAL_MIN_8(0x00),
HID_PHYSICAL_MAX_8(0x00),
HID_UNIT_EXPONENT(0x00), // 10^0
HID_REPORT_SIZE(8),
HID_REPORT_COUNT(1),
HID_INPUT(HID_DATA_VAR_ABS),
HID_END_COLLECTION,
};