Sensors Hardware Abstraction Layer (HAL) adalah antarmuka antara framework sensor Android dan sensor perangkat, seperti akselerometer atau giroskop. Sensors HAL menentukan fungsi yang harus diterapkan untuk memungkinkan framework mengontrol sensor.
Sensors HAL 2.0 tersedia di Android 10 dan yang lebih tinggi untuk perangkat baru dan yang diupgrade. Sensor HAL 2.0 didasarkan pada Sensors HAL 1.0, tetapi memiliki beberapa perbedaan utama, yang mencegahnya kompatibel dengan versi sebelumnya. Sensor HAL 2.0 menggunakan Fast Message Queues (FMQs) untuk mengirim peristiwa sensor dari HAL ke dalam framework sensor Android.
Sensors HAL 2.1 tersedia di Android 11 dan yang lebih tinggi
untuk perangkat baru dan yang diupgrade. Sensor HAL 2.1 adalah iterasi dari Sensor HAL 2.0
yang mengekspos
jenis sensor
HINGE_ANGLE
dan mengupdate berbagai metode untuk menerima jenis HINGE_ANGLE.
Antarmuka HAL 2.1
Sumber utama dokumentasi untuk Sensors HAL 2.1 berada dalam definisi HAL
di
hardware/interfaces/sensors/2.1/ISensors.hal.
Jika ada konflik persyaratan antara halaman ini dan ISensors.hal,
gunakan persyaratan di ISensors.hal.
Antarmuka HAL 2.0
Sumber utama dokumentasi untuk Sensors HAL 2.0 berada dalam definisi HAL
di
hardware/interfaces/sensors/2.0/ISensors.hal.
Jika ada konflik persyaratan antara halaman ini dan ISensors.hal,
gunakan persyaratan tersebut di ISensors.hal.
Mengimplementasikan Sensor HAL 2.0 dan HAL 2.1
Untuk mengimplementasikan Sensors HAL 2.0 atau 2.1, objek harus memperluas antarmuka ISensors
dan mengimplementasikan semua fungsi yang ditentukan dalam
2.0/ISensors.hal
atau
2.1/ISensors.hal.
Melakukan inisialisasi HAL
Sensor HAL harus diinisialisasi oleh framework sensor Android sebelum
dapat digunakan. Framework memanggil fungsi initialize() untuk HAL 2.0 dan
fungsi initialize_2_1() untuk HAL 2.1 guna menyediakan tiga parameter ke
HAL Sensor: dua deskripsi FMQ dan satu pointer ke objek
ISensorsCallback.
HAL menggunakan deskriptor pertama untuk membuat Peristiwa FMQ yang digunakan untuk menulis peristiwa
sensor ke framework. HAL menggunakan deskripsi kedua untuk membuat FMQ Wake Lock yang digunakan untuk menyinkronkan saat HAL melepaskan wake lock untuk peristiwa sensor WAKE_UP. HAL harus menyimpan pointer ke objek ISensorsCallback sehingga
fungsi callback yang diperlukan dapat dipanggil.
Fungsi initialize() atau initialize_2_1() harus menjadi fungsi pertama
yang dipanggil saat melakukan inisialisasi Sensors HAL.
Ekspos sensor yang tersedia
Untuk mendapatkan daftar semua sensor statis yang tersedia di perangkat, gunakan
fungsi getSensorsList() di HAL 2.0 dan fungsi getSensorsList_2_1() di
HAL 2.1. Fungsi ini menampilkan daftar sensor, yang masing-masing diidentifikasi secara unik oleh
handlernya. Handle untuk sensor tertentu tidak boleh berubah saat proses
yang menghosting Sensors HAL dimulai ulang. Nama sebutan channel dapat berubah saat perangkat dimulai ulang, dan
saat server sistem dimulai ulang.
Jika beberapa sensor memiliki jenis sensor dan properti pengaktifan yang sama, sensor pertama dalam daftar akan disebut sensor default dan ditampilkan ke
aplikasi yang menggunakan fungsi
getDefaultSensor(int sensorType, bool wakeUp).
Stabilitas daftar sensor
Setelah Sensors HAL dimulai ulang, jika data yang ditampilkan oleh getSensorsList() atau
getSensorsList_2_1() menunjukkan perubahan yang signifikan dibandingkan dengan daftar
sensor yang diambil sebelum dimulai ulang, framework akan memicu dimulai ulangnya
runtime Android. Perubahan signifikan pada daftar sensor mencakup kasus saat
sensor dengan nama sebutan tertentu tidak ada atau telah mengubah atribut, atau saat sensor
baru diperkenalkan. Meskipun memulai ulang runtime Android mengganggu
pengguna, hal ini diperlukan karena framework Android tidak dapat lagi memenuhi
kontrak Android API bahwa sensor statis (non-dinamis) tidak berubah selama
masa aktif aplikasi. Hal ini juga dapat mencegah framework membuat ulang
permintaan sensor aktif yang dibuat oleh aplikasi. Oleh karena itu, vendor HAL disarankan untuk
mencegah perubahan daftar sensor yang dapat dihindari.
Untuk memastikan handle sensor yang stabil, HAL harus memetakan sensor fisik tertentu di perangkat secara deterministik ke handle-nya. Meskipun tidak ada implementasi khusus yang diwajibkan oleh antarmuka HAL Sensor, developer memiliki sejumlah opsi yang tersedia untuk memenuhi persyaratan ini.
Misalnya, daftar sensor dapat diurutkan menggunakan kombinasi atribut tetap
setiap sensor, seperti vendor, model, dan jenis sensor. Opsi lainnya bergantung
pada fakta bahwa kumpulan sensor statis perangkat diperbaiki di hardware, sehingga
HAL perlu mengetahui kapan semua sensor yang diharapkan telah selesai diinisialisasi sebelum
kembali dari getSensorsList() atau getSensorsList_2_1(). Daftar
sensor yang diharapkan ini dapat dikompilasi ke dalam biner HAL atau disimpan dalam
file konfigurasi di sistem file, dan urutan kemunculan dapat digunakan
untuk mendapatkan handle yang stabil. Meskipun solusi terbaik bergantung pada detail
implementasi khusus HAL Anda, persyaratan utamanya adalah bahwa pengendali sensor
tidak berubah di seluruh HAL yang dimulai ulang.
Konfigurasi sensor
Sebelum diaktifkan, sensor harus dikonfigurasi dengan periode sampling
dan latensi pelaporan maksimum menggunakan fungsi batch().
Sensor harus dapat dikonfigurasi ulang kapan saja menggunakan batch() tanpa
kehilangan data sensor.
Periode sampling
Periode sampling memiliki arti yang berbeda berdasarkan jenis sensor yang dikonfigurasi:
- Berkelanjutan: Peristiwa sensor dihasilkan pada kecepatan berkelanjutan.
- Saat berubah: Peristiwa dibuat tidak lebih cepat dari periode sampling dan dapat dibuat dengan kecepatan yang lebih lambat dari periode sampling jika nilai yang diukur tidak berubah.
- Satu kali: Periode pengambilan sampel diabaikan.
- Khusus: Untuk mengetahui detail selengkapnya, lihat Jenis sensor.
Untuk mempelajari interaksi antara periode pengambilan sampel dan mode pelaporan sensor, lihat Mode Pelaporan.
Latensi pelaporan maksimum
Latensi pelaporan maksimum menetapkan waktu maksimum dalam nanodetik sehingga peristiwa dapat ditunda dan disimpan dalam FIFO hardware sebelum ditulis ke Event FMQ melalui HAL saat SoC aktif.
Nilai nol menandakan bahwa peristiwa harus dilaporkan segera setelah diukur, baik melewati FIFO sama sekali, atau mengosongkan FIFO segera setelah satu peristiwa dari sensor ada di FIFO.
Misalnya, akselerometer yang diaktifkan pada 50 Hz dengan latensi pelaporan maksimum nol akan memicu gangguan 50 kali per detik saat SoC aktif.
Jika latensi pelaporan maksimum lebih besar dari nol, peristiwa sensor tidak perlu dilaporkan segera setelah terdeteksi. Peristiwa dapat disimpan sementara di FIFO hardware dan dilaporkan dalam batch, selama tidak ada peristiwa yang tertunda lebih dari latensi pelaporan maksimum. Semua peristiwa sejak batch sebelumnya dicatat dan ditampilkan sekaligus. Hal ini mengurangi jumlah gangguan yang dikirim ke SoC dan memungkinkan SoC beralih ke mode daya yang lebih rendah saat sensor merekam dan mengelompokkan data.
Setiap peristiwa memiliki stempel waktu yang terkait dengannya. Menunda waktu saat peristiwa dilaporkan tidak boleh memengaruhi stempel waktu peristiwa. Stempel waktu harus akurat dan sesuai dengan waktu terjadinya peristiwa secara fisik, bukan waktu peristiwa dilaporkan.
Untuk informasi dan persyaratan tambahan tentang pelaporan peristiwa sensor dengan latensi pelaporan maksimum yang bukan nol, lihat Penggabungan.
Mengaktifkan sensor
Framework mengaktifkan dan menonaktifkan sensor menggunakan fungsi activate().
Sebelum mengaktifkan sensor, framework harus mengonfigurasi sensor terlebih dahulu menggunakan batch().
Setelah sensor dinonaktifkan, peristiwa sensor tambahan dari sensor tersebut tidak boleh ditulis ke Peristiwa FMQ.
Flush sensor
Jika sensor dikonfigurasi untuk mengelompokkan data sensor, framework dapat memaksa
pengosongan langsung peristiwa sensor yang dikelompokkan dengan memanggil flush(). Hal ini menyebabkan
peristiwa sensor batch untuk handle sensor yang ditentukan segera
ditulis ke FMQ Peristiwa. HAL Sensor harus menambahkan peristiwa flush complete
ke akhir peristiwa sensor yang ditulis sebagai hasil dari panggilan ke
flush().
Pengosongan terjadi secara asinkron (yaitu, fungsi ini harus segera ditampilkan). Jika implementasi menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut akan dihapus dan peristiwa flush complete hanya ditambahkan untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada kemungkinan buffering), atau jika FIFO
kosong pada saat panggilan, flush() harus tetap berhasil dan mengirimkan peristiwa
flush lengkap untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor
sekali pakai.
Jika flush() dipanggil untuk sensor one-shot, flush() harus menampilkan
BAD_VALUE dan tidak menghasilkan peristiwa flush complete.
Menulis peristiwa sensor ke FMQ
FMQ Peristiwa digunakan oleh Sensors HAL untuk mendorong peristiwa sensor ke framework sensor Android.
FMQ Peristiwa adalah FMQ yang disinkronkan, yang berarti bahwa setiap upaya untuk menulis lebih banyak peristiwa ke FMQ daripada ruang yang tersedia akan menyebabkan operasi tulis gagal. Dalam hal ini, HAL harus menentukan apakah akan menulis kumpulan peristiwa saat ini sebagai dua grup peristiwa yang lebih kecil atau menulis semua peristiwa bersama-sama jika ruang yang tersedia cukup.
Saat Sensor HAL telah menulis jumlah peristiwa sensor yang diinginkan ke Peristiwa FMQ, Sensor HAL harus memberi tahu framework bahwa peristiwa sudah siap dengan menulis bit EventQueueFlagBits::READ_AND_PROCESS ke fungsi EventFlag::wake Peristiwa FMQ. EventFlag dapat dibuat dari Event FMQ
menggunakan EventFlag::createEventFlag dan fungsi getEventFlagWord()
Event FMQ.
Sensors HAL 2.0/2.1 mendukung write dan writeBlocking di FMQ Peristiwa.
Implementasi default memberikan referensi untuk menggunakan write. Jika fungsi writeBlocking digunakan, flag readNotification harus ditetapkan ke EventQueueFlagBits::EVENTS_READ, yang ditetapkan oleh framework saat membaca peristiwa dari FMQ Peristiwa. Flag notifikasi tulis harus disetel ke
EventQueueFlagBits::READ_AND_PROCESS, yang memberi tahu framework bahwa peristiwa
telah ditulis ke FMQ Peristiwa.
Acara WAKE_UP
Peristiwa WAKE_UP adalah peristiwa sensor yang menyebabkan prosesor aplikasi (AP)
mengaktifkan dan menangani peristiwa dengan segera. Setiap kali peristiwa WAKE_UP ditulis
ke FMQ Peristiwa, HAL Sensor harus mengamankan kunci layar aktif untuk memastikan bahwa
sistem tetap aktif hingga framework dapat menangani peristiwa. Setelah menerima
peristiwa WAKE_UP, framework mengamankan kunci layar saat aktifnya sendiri, sehingga
Sensor HAL dapat melepaskan kunci layar saat aktifnya. Untuk menyinkronkan saat Sensors HAL
melepaskan wake lock-nya, gunakan Wake Lock FMQ.
Sensors HAL harus membaca Wake Lock FMQ untuk menentukan jumlah peristiwa WAKE_UP
yang telah ditangani framework. HAL hanya boleh melepaskan kunci layar aktifnya
untuk peristiwa WAKE_UP jika jumlah total peristiwa WAKE_UP yang tidak ditangani adalah nol.
Setelah menangani peristiwa sensor, framework akan menghitung jumlah peristiwa yang
ditandai sebagai peristiwa WAKE_UP dan menulis angka ini kembali ke Wake Lock FMQ.
Framework menetapkan notifikasi tulis WakeLockQueueFlagBits::DATA_WRITTEN di Wake Lock FMQ setiap kali menulis data ke Wake Lock FMQ.
Sensor dinamis
Sensor dinamis adalah sensor yang secara fisik bukan bagian dari perangkat, tetapi dapat digunakan sebagai input ke perangkat, seperti gamepad dengan akselerometer.
Saat sensor dinamis terhubung, fungsi onDynamicSensorConnected dalam
ISensorsCallback harus dipanggil dari Sensor HAL. Hal ini memberi tahu
framework sensor dinamis baru dan memungkinkan sensor untuk dikontrol
melalui framework dan membuat peristiwa sensor digunakan oleh klien.
Demikian pula, saat sensor dinamis terputus, fungsi onDynamicSensorDisconnected di ISensorsCallback harus dipanggil agar
framework dapat menghapus sensor yang tidak lagi tersedia.
Saluran langsung
Direct channel adalah metode operasi saat peristiwa sensor ditulis ke
memori tertentu, bukan ke FMQ Peristiwa yang mengabaikan Framework
Sensor Android. Klien yang mendaftarkan saluran langsung harus membaca peristiwa sensor
langsung dari memori yang digunakan untuk membuat saluran langsung dan tidak akan
menerima peristiwa sensor melalui framework. Fungsi configDirectReport()
mirip dengan batch() untuk operasi normal dan mengonfigurasi saluran laporan
langsung.
Fungsi registerDirectChannel() dan unregisterDirectChannel() membuat
atau menghancurkan saluran langsung baru.
Mode operasi
Fungsi setOperationMode() memungkinkan framework mengonfigurasi sensor
sehingga framework dapat memasukkan data sensor ke sensor. Hal ini berguna untuk
pengujian, terutama untuk algoritma yang ada di bawah framework.
Fungsi injectSensorData() di HAL 2.0 dan fungsi injectSensorsData_2_1()
di HAL 2.0 biasanya digunakan untuk mendorong parameter operasional ke
HAL Sensor. Fungsi ini juga dapat digunakan untuk memasukkan peristiwa sensor ke dalam
sensor tertentu.
Validasi
Untuk memvalidasi penerapan Sensors HAL, jalankan pengujian CTS dan VTS sensor.
Pengujian CTS
Pengujian CTS sensor ada dalam pengujian CTS otomatis dan aplikasi CTS Verifier manual.
Pengujian otomatis terletak di cts/tests/sensor/src/android/hardware/cts. Pengujian ini memverifikasi fungsi standar sensor, seperti mengaktifkan sensor, pengelompokan, dan kecepatan peristiwa sensor.
Pengujian CTS Verifier terletak di cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors. Pengujian ini memerlukan input manual dari operator pengujian dan memastikan bahwa sensor melaporkan nilai yang akurat.
Lulus uji CTS sangat penting untuk memastikan bahwa perangkat yang sedang diuji memenuhi semua persyaratan CDD.
Pengujian VTS
Pengujian VTS untuk Sensor HAL 2.0 terletak di
hardware/interfaces/sensors/2.0/vts.
Pengujian VTS untuk Sensors HAL 2.1 terletak di
hardware/interfaces/sensors/2.1/vts.
Pengujian ini memastikan bahwa Sensors HAL diimplementasikan dengan benar dan semua
persyaratan dalam ISensors.hal dan ISensorsCallback.hal terpenuhi dengan benar.
Mengupgrade ke Sensors HAL 2.1 dari 2.0
Saat mengupgrade ke Sensors HAL 2.1 dari 2.0, implementasi HAL Anda harus menyertakan
metode initialize_2_1(), getSensorsList_2_1(), dan injectSensorsData_2_1(), bersama dengan jenis HAL 2.1. Metode ini harus memenuhi persyaratan
yang sama yang diuraikan untuk HAL 2.0 di atas.
Karena HAL versi minor harus mendukung semua fungsi dari HAL sebelumnya, HAL 2.1 harus mendukung inisialisasi sebagai HAL 2.0. Untuk menghindari kompleksitas dalam mendukung kedua versi HAL, sebaiknya gunakan Multi-HAL 2.1.
Untuk contoh cara menerapkan Sensor 2.1 HAL Anda sendiri, lihat Sensors.h.
Mengupgrade ke Sensors HAL 2.0 dari 1.0
Saat mengupgrade ke Sensors HAL 2.0 dari 1.0, pastikan penerapan HAL Anda memenuhi persyaratan berikut.
Melakukan inisialisasi HAL
Fungsi initialize() harus didukung untuk membuat FMQ antara
framework dan HAL.
Mengekspos sensor yang tersedia
Di Sensors HAL 2.0, fungsi getSensorsList() harus menampilkan nilai yang sama
selama booting perangkat tunggal, bahkan di seluruh Sensors HAL yang dimulai ulang. Persyaratan baru
fungsi getSensorsList() adalah fungsi tersebut harus menampilkan nilai yang sama selama
satu booting perangkat, bahkan setelah Sensor HAL dimulai ulang. Hal ini memungkinkan
framework mencoba membangun kembali koneksi sensor jika server sistem
dimulai ulang. Nilai yang ditampilkan oleh getSensorsList() dapat berubah setelah perangkat
melakukan mulai ulang.
Menulis peristiwa sensor ke FMQ
Daripada menunggu poll() dipanggil, di Sensors HAL 2.0, Sensors HAL
harus secara proaktif menulis peristiwa sensor ke FMQ Peristiwa setiap kali peristiwa sensor
tersedia. HAL juga bertanggung jawab untuk menulis bit yang benar ke
EventFlag untuk menyebabkan pembacaan FMQ dalam framework.
Peristiwa WAKE_UP
Di Sensors HAL 1.0, HAL dapat melepaskan kunci layar aktifnya untuk peristiwa WAKE_UP
pada panggilan berikutnya ke poll() setelah WAKE_UP diposting ke
poll() karena hal ini menunjukkan bahwa framework telah memproses semua peristiwa
sensor dan telah mendapatkan kunci layar aktif, jika diperlukan. Karena, di Sensors HAL 2.0,
HAL tidak lagi mengetahui kapan framework telah memproses peristiwa yang ditulis ke
FMQ, Wake Lock FMQ memungkinkan framework berkomunikasi dengan HAL saat
telah menangani peristiwa WAKE_UP.
Di Sensors HAL 2.0, kunci layar yang diamankan oleh Sensors HAL untuk peristiwa WAKE_UP
harus dimulai dengan SensorsHAL_WAKEUP.
Sensor dinamis
Sensor dinamis ditampilkan menggunakan fungsi poll() di Sensor HAL 1.0.
Sensors HAL 2.0 mengharuskan onDynamicSensorsConnected dan
onDynamicSensorsDisconnected di ISensorsCallback dipanggil setiap kali koneksi
sensor dinamis berubah. Callback ini tersedia sebagai bagian dari
pointer ISensorsCallback yang disediakan melalui fungsi initialize().
Mode operasi
Mode DATA_INJECTION untuk sensor WAKE_UP harus didukung di Sensor HAL
2.0.
Dukungan multi-HAL
Sensors HAL 2.0 dan 2.1 mendukung multi-HAL menggunakan framework Multi-HAL Sensor. Untuk mengetahui detail penerapan, lihat Mentransfer dari Sensors HAL 1.0.