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 audio virtualizer (audio 3D). Halaman ini menggunakan istilah perangkat dan host dalam pengertian Bluetooth, di mana 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 Dynamic Sensors README .
Halaman ini mengasumsikan keakraban dengan sumber daya berikut:
Struktur tingkat atas
Kerangka kerja Android mengidentifikasi perangkat pelacak kepala sebagai perangkat HID.
Untuk contoh lengkap dari deskriptor HID yang valid, lihat Lampiran 1: Contoh Descriptor HID .
Di tingkat atas, perangkat pelacak kepala adalah kumpulan aplikasi dengan halaman Sensors ( 0x20 ) dan Other: Custom ( 0xE1 ). Di dalam kumpulan 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
Tidak ada terminator nol yang diharapkan, artinya ukuran total properti ini adalah 23 karakter 8-bit.
Properti ini berfungsi sebagai pembeda untuk menghindari tabrakan dengan sensor kustom lainnya.
Properti: ID Unik Persisten ( 0x0302 )
Properti Persistent Unique ID ( 0x0302 ) adalah array read-only 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 merujuk ke perangkat audio yang terpasang. Skema berikut didukung.
Pelacak kepala mandiri
Jika properti Persistent Unique ID ( 0x0302 ) tidak ada atau disetel ke semua nol, berarti perangkat head tracker tidak terpasang secara permanen ke perangkat audio dan dapat digunakan secara terpisah, misalnya, dengan membiarkan pengguna secara manual mengaitkan 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 | Bluetooth MAC | |||||
Dalam skema ini, 8 oktet pertama harus 0 , oktet 8 dan 9 masing-masing harus berisi nilai ASCII B dan T , dan 6 oktet berikut diinterpretasikan sebagai alamat MAC Bluetooth, dengan asumsi perangkat head tracker 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 kerja Android, melalui mekanisme yang tidak ditentukan yang khusus untuk jenis transportasi yang digunakan.
Properti: Negara Pelapor ( 0x0316 )
Properti Reporting State ( 0x0316 ) adalah properti baca/tulis yang memiliki semantik standar seperti yang didefinisikan dalam spesifikasi HID. Tuan rumah menggunakan properti ini untuk menunjukkan ke perangkat peristiwa mana yang akan dilaporkan. Hanya nilai Tidak Ada Peristiwa ( 0x0840 ) dan Semua Peristiwa ( 0x0841 ) yang digunakan.
Nilai awal untuk bidang ini harus No Events 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 didefinisikan dalam spesifikasi HID. Tuan rumah menggunakan properti ini untuk menunjukkan ke perangkat di mana status dayanya. 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 Report Interval ( 0x030E ) adalah properti baca/tulis yang memiliki semantik standar seperti yang didefinisikan dalam spesifikasi HID. Tuan rumah menggunakan properti ini untuk menunjukkan ke perangkat seberapa sering melaporkan pembacaan datanya. Satuan adalah detik. Rentang yang valid untuk nilai ini ditentukan oleh perangkat dan dijelaskan menggunakan mekanisme Fisik Min/Maks. Setidaknya 50 Hz tingkat pelaporan harus didukung, dan tingkat pelaporan maksimum yang disarankan adalah 100 Hz. Oleh karena itu, interval laporan minimum harus kurang dari atau sama dengan 20 md, dan disarankan lebih besar dari atau sama dengan 10 md.
Bidang data: Nilai Khusus 1 ( 0x0544 )
Bidang Nilai Khusus 1 ( 0x0544 ) adalah bidang masukan yang digunakan untuk melaporkan informasi pelacakan kepala yang sebenarnya. Ini adalah larik 3-elemen, yang ditafsirkan menurut aturan HID normal untuk nilai fisik seperti yang ditentukan dalam bagian 6.2.2.7 dari spesifikasi HID. Rentang yang valid untuk setiap elemen adalah [-π, ] rad. Satuan selalu radian.
Elemen diinterpretasikan sebagai: [rx, ry, rz] , sehingga [rx, ry, rz] adalah vektor rotasi , yang mewakili transformasi dari kerangka acuan ke kerangka kepala. Magnitudo harus dalam kisaran [0..π].
Kerangka acuan bersifat arbitrer, tetapi umumnya tetap dan harus menggunakan tangan kanan. Sejumlah kecil penyimpangan dapat diterima. Sumbu kepala adalah:
- X dari telinga kiri ke kanan
- Y dari belakang kepala ke hidung (belakang ke depan)
- Z dari leher ke atas kepala
Bidang data: Nilai Khusus 2 ( 0x0545 )
Bidang Nilai Kustom 2 ( 0x0545 ) adalah bidang masukan yang digunakan untuk melaporkan informasi pelacakan kepala yang sebenarnya. Ini adalah array titik tetap 3-elemen, yang ditafsirkan menurut aturan HID normal untuk nilai fisik. Satuan selalu radian/detik.
Elemen-elemen tersebut ditafsirkan sebagai: [vx, vy, vz] , sehingga [vx, vy, vz] adalah vektor rotasi , yang mewakili kecepatan sudut rangka kepala (relatif terhadap dirinya sendiri).
Bidang data: Nilai Khusus 3 ( 0x0546 )
Bidang Nilai Kustom 3 ( 0x0546 ) adalah bidang masukan yang digunakan untuk melacak diskontinuitas dalam bingkai referensi. Ini adalah bilangan bulat skalar berukuran 8 bit. Itu harus ditambah (dengan sampul) oleh perangkat setiap kali kerangka acuan diubah, misalnya, jika algoritma filter orientasi yang digunakan untuk menentukan orientasi telah disetel ulang statusnya. Nilai ini ditafsirkan menurut aturan HID normal untuk nilai fisik. Namun, nilai fisik dan unit tidak masalah. Satu-satunya informasi yang relevan dengan tuan rumah adalah nilai yang diubah. Untuk menghindari masalah numerik yang terkait dengan hilangnya presisi saat mengonversi dari unit logis ke fisik, sebaiknya setel nilai untuk min fisik, maks fisik, dan eksponen unit 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 bidang data, bidang Nilai Khusus 1, 2, dan 3 harus berada dalam laporan yang sama dan hanya ada dalam satu laporan untuk perangkat tertentu (kumpulan aplikasi).
Mengirim masukan laporan
Perangkat harus secara berkala dan asinkron (melalui pesan HID INPUT) mengirim laporan input ketika semua kondisi di bawah ini terpenuhi:
- Properti Power State diatur ke Full Power.
- Properti Reporting State diatur ke All Events.
- Properti Interval Pelaporan bukan nol.
Properti Interval Pelaporan menentukan seberapa sering laporan dikirim. Jika salah satu kondisi di atas tidak terpenuhi, perangkat tidak boleh mengirim laporan apa pun.
Kompatibilitas maju dan mundur
Protokol HID pelacak kepala menggunakan skema versi yang memungkinkan pembaruan, sementara memungkinkan interoperabilitas antara host dan perangkat yang menggunakan versi protokol yang berbeda. Versi untuk protokol diidentifikasi dengan dua angka, mayor dan minor, yang memiliki semantik berbeda seperti yang dijelaskan di bagian berikut.
Versi yang didukung oleh perangkat dapat ditentukan dengan memeriksa properti Deskripsi Sensor ( 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 ke belakang diperbolehkan untuk perubahan pada versi utama. Untuk mendukung beberapa versi utama untuk interoperabilitas dengan host lama dan baru, perangkat dapat menentukan beberapa koleksi aplikasi di deskriptor laporannya. Sebagai contoh:
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, tuan rumah dapat menghitung semua koleksi aplikasi berbeda yang diiklankan oleh perangkat, memeriksa properti Deskripsi Sensor mereka untuk menentukan versi protokol yang mereka terapkan masing-masing, lalu memilih versi protokol terbaru yang didukung tuan rumah. Saat dipilih, host bekerja dengan protokol tunggal yang dipilih untuk masa pakai koneksi perangkat.
Lampiran 1: Contoh deskriptor HID
Contoh berikut mengilustrasikan deskriptor HID valid yang khas. Ini menggunakan makro C yang umum digunakan, disediakan dalam 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,
};