Antarmuka Sensors HAL, yang dideklarasikan dalam sensor.h , mewakili antarmuka antara framework Android dan perangkat lunak khusus perangkat keras. Implementasi HAL harus mendefinisikan setiap fungsi yang dideklarasikan di sensor.h. Fungsi utamanya adalah:
-
get_sensors_list- Mengembalikan daftar semua sensor. -
activate- Memulai atau menghentikan sensor. -
batch- Menetapkan parameter sensor seperti frekuensi pengambilan sampel dan latensi pelaporan maksimum. -
setDelay- Hanya digunakan di HAL versi 1.0. Mengatur frekuensi pengambilan sampel untuk sensor tertentu. -
flush- Membilas FIFO dari sensor yang ditentukan dan melaporkan peristiwa flush yang lengkap ketika hal ini dilakukan. -
poll- Mengembalikan peristiwa sensor yang tersedia.
Implementasinya harus aman untuk thread dan memungkinkan fungsi-fungsi ini dipanggil dari thread yang berbeda.
Antarmuka juga mendefinisikan beberapa tipe yang digunakan oleh fungsi-fungsi tersebut. Jenis utamanya adalah:
-
sensors_module_t -
sensors_poll_device_t -
sensor_t -
sensors_event_t
Selain bagian di bawah ini, lihat sensor.h untuk informasi lebih lanjut tentang jenis tersebut.
get_sensors_list(daftar)
int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list);
Memberikan daftar sensor yang diterapkan oleh HAL. Lihat sensor_t untuk detail tentang cara sensor didefinisikan.
Urutan kemunculan sensor dalam daftar adalah urutan sensor yang akan dilaporkan ke aplikasi. Biasanya sensor dasar muncul terlebih dahulu, diikuti oleh sensor komposit.
Jika beberapa sensor berbagi jenis sensor dan properti pengaktifan yang sama, sensor pertama dalam daftar disebut sensor “default”. Ini yang dikembalikan oleh getDefaultSensor(int sensorType, bool wakeUp) .
Fungsi ini mengembalikan jumlah sensor dalam daftar.
aktifkan (sensor, benar/salah)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Mengaktifkan atau menonaktifkan sensor.
sensor_handle adalah pegangan sensor untuk mengaktifkan/menonaktifkan. Pegangan sensor ditentukan oleh bidang handle struktur sensor_tnya .
enabled diatur ke 1 untuk mengaktifkan atau 0 untuk menonaktifkan sensor.
Sensor sekali pakai menonaktifkan dirinya sendiri secara otomatis setelah menerima suatu peristiwa, dan sensor tersebut masih harus menerima untuk dinonaktifkan melalui panggilan ke activate(..., enabled=0) .
Sensor non-bangun tidak pernah mencegah SoC masuk ke mode penangguhan; yaitu, HAL tidak boleh melakukan penguncian layar sebagian atas nama aplikasi.
Sensor pengaktifan, saat menyampaikan peristiwa secara terus-menerus, dapat mencegah SoC masuk ke mode penangguhan, namun jika tidak ada peristiwa yang perlu dikirimkan, penguncian layar aktif sebagian harus dilepaskan.
Jika enabled adalah 1 dan sensor telah diaktifkan, fungsi ini tidak dapat dijalankan dan berhasil.
Jika enabled adalah 0 dan sensor telah dinonaktifkan, fungsi ini tidak dapat dijalankan dan berhasil.
Fungsi ini mengembalikan 0 jika berhasil dan angka kesalahan negatif jika tidak.
batch(sensor, flag, periode pengambilan sampel, latensi laporan maksimum)
int (*batch)(
struct sensors_poll_device_1* dev,
int sensor_handle,
int flags,
int64_t sampling_period_ns,
int64_t max_report_latency_ns);
Menetapkan parameter sensor, termasuk frekuensi pengambilan sampel dan latensi laporan maksimum . Fungsi ini dapat dipanggil saat sensor diaktifkan, yang mana hal ini tidak boleh menyebabkan pengukuran sensor apa pun hilang: Transisi dari satu laju pengambilan sampel ke laju pengambilan sampel lainnya tidak dapat menyebabkan kejadian hilang, begitu pula peralihan dari latensi laporan maksimum yang tinggi ke latensi laporan maksimum yang rendah. latensi laporan maksimum.
sensor_handle adalah pegangan sensor yang akan dikonfigurasi.
flags saat ini tidak digunakan.
sampling_period_ns adalah periode pengambilan sampel saat sensor harus dijalankan, dalam nanodetik. Lihat sampling_period_ns untuk detail selengkapnya.
max_report_latency_ns adalah waktu maksimum dimana peristiwa dapat ditunda sebelum dilaporkan melalui HAL, dalam nanodetik. Lihat paragraf max_report_latency_ns untuk lebih jelasnya.
Fungsi ini mengembalikan 0 jika berhasil dan angka kesalahan negatif jika tidak.
setDelay(sensor, periode pengambilan sampel)
int (*setDelay)(
struct sensors_poll_device_t *dev,
int sensor_handle,
int64_t sampling_period_ns);
Setelah HAL versi 1.0, fungsi ini tidak digunakan lagi dan tidak pernah dipanggil. Sebaliknya, fungsi batch dipanggil untuk mengatur parameter sampling_period_ns .
Di HAL versi 1.0, setDelay digunakan sebagai pengganti batch untuk menyetel sampling_period_ns .
siram (sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Tambahkan acara flush complete ke akhir FIFO perangkat keras untuk sensor yang ditentukan dan hapus FIFO; peristiwa tersebut disampaikan seperti biasa (yaitu: seolah-olah latensi pelaporan maksimum telah kedaluwarsa) dan dihapus dari FIFO.
Flush terjadi secara asinkron (yaitu: fungsi ini harus segera kembali). Jika implementasi menggunakan FIFO tunggal untuk beberapa sensor, FIFO tersebut akan di-flush dan kejadian flush complete ditambahkan hanya untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada buffering yang memungkinkan), atau jika FIFO kosong pada saat panggilan dilakukan, flush harus tetap berhasil dan mengirimkan peristiwa pembilasan lengkap untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor sekali tembak.
Ketika flush dipanggil, meskipun peristiwa flush sudah ada di FIFO untuk sensor tersebut, peristiwa flush tambahan harus dibuat dan ditambahkan ke akhir FIFO, dan FIFO harus di-flush. Jumlah panggilan flush harus sama dengan jumlah event flush finish yang dibuat.
flush tidak berlaku untuk sensor sekali tembak ; jika sensor_handle mengacu pada sensor sekali pakai, flush harus mengembalikan -EINVAL dan tidak menghasilkan peristiwa metadata lengkap flush.
Fungsi ini mengembalikan 0 jika berhasil, -EINVAL jika sensor yang ditentukan adalah sensor sekali pakai atau tidak diaktifkan, dan angka kesalahan negatif jika tidak.
pemilihan()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count);
Mengembalikan array data sensor dengan mengisi argumen data . Fungsi ini harus diblokir hingga acara tersedia. Ini akan mengembalikan jumlah peristiwa yang dibaca jika berhasil, atau angka kesalahan negatif jika terjadi kesalahan.
Jumlah kejadian yang dikembalikan dalam data harus lebih kecil atau sama dengan argumen count . Fungsi ini tidak akan pernah mengembalikan 0 (tidak ada kejadian).
Urutan panggilan
Saat perangkat melakukan booting, get_sensors_list dipanggil.
Saat sensor diaktifkan, fungsi batch akan dipanggil dengan parameter yang diminta, diikuti dengan activate(..., enable=1) .
Perhatikan bahwa dalam HAL versi 1_0, urutannya adalah sebaliknya: activate dipanggil terlebih dahulu, diikuti oleh set_delay .
Ketika karakteristik yang diminta dari suatu sensor berubah saat diaktifkan, fungsi batch dipanggil.
flush dapat dipanggil kapan saja, bahkan pada sensor yang tidak diaktifkan (dalam hal ini harus mengembalikan -EINVAL )
Ketika sensor dinonaktifkan, activate(..., enable=0) akan dipanggil.
Sejalan dengan panggilan tersebut, fungsi poll akan dipanggil berulang kali untuk meminta data. poll dapat dipanggil bahkan ketika tidak ada sensor yang diaktifkan.
sensor_modul_t
sensors_module_t adalah tipe yang digunakan untuk membuat modul perangkat keras Android untuk sensor. Implementasi HAL harus mendefinisikan objek HAL_MODULE_INFO_SYM jenis ini untuk mengekspos fungsi get_sensors_list . Lihat definisi sensors_module_t di sensor.h dan definisi hw_module_t untuk informasi lebih lanjut.
sensor_poll_device_t / sensor_poll_device_1_t
sensors_poll_device_1_t berisi metode lainnya yang ditentukan di atas: activate , batch , flush dan poll . Bidang common (tipe hw_device_t ) menentukan nomor versi HAL.
sensor_t
sensor_t mewakili sensor Android . Berikut beberapa bidang pentingnya:
nama: String yang terlihat pengguna yang mewakili sensor. String ini sering kali berisi nama bagian dari sensor yang mendasarinya, jenis sensor, dan apakah itu merupakan sensor bangun. Misalnya, “LIS2HH12 Accelerometer”, “MAX21000 Uncalibrated Gyroscope”, “BMP280 Wake-up Barometer”, “MPU6515 Game Rotation Vector”
pegangan: Bilangan bulat yang digunakan untuk merujuk ke sensor saat mendaftar atau menghasilkan peristiwa darinya.
type: Jenis sensor. Lihat penjelasan jenis sensor di Apa itu Sensor Android? untuk lebih jelasnya, dan lihat Jenis sensor untuk jenis sensor resmi. Untuk jenis sensor non-resmi, type harus dimulai dengan SENSOR_TYPE_DEVICE_PRIVATE_BASE
stringType: Jenis sensor sebagai string. Jika sensor memiliki tipe resmi, setel ke SENSOR_STRING_TYPE_* . Jika sensor memiliki tipe spesifik pabrikan, stringType harus dimulai dengan nama domain kebalikan pabrikan. Misalnya, sensor (misalnya detektor unicorn) yang ditentukan oleh tim Cool-product di Fictional-Company dapat menggunakan stringType=”com.fictional_company.cool_product.unicorn_detector” . stringType digunakan untuk mengidentifikasi secara unik jenis sensor non-resmi. Lihat sensor.h untuk informasi lebih lanjut tentang tipe dan tipe string.
diperlukan Izin: Sebuah string yang mewakili izin yang harus dimiliki aplikasi untuk melihat sensor, mendaftar ke sensor tersebut, dan menerima datanya. String kosong berarti aplikasi tidak memerlukan izin apa pun untuk mengakses sensor ini. Beberapa jenis sensor seperti monitor detak jantung memiliki requiredPermission wajib. Semua sensor yang memberikan informasi sensitif kepada pengguna (seperti detak jantung) harus dilindungi dengan izin.
flags: Bendera untuk sensor ini, yang menentukan mode pelaporan sensor dan apakah sensor tersebut merupakan sensor bangun atau bukan. Misalnya, sensor bangun satu kali akan memiliki flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . Bit flag yang tidak digunakan pada versi HAL saat ini harus dibiarkan sama dengan 0.
maxRange: Nilai maksimum yang dapat dilaporkan oleh sensor, dalam satuan yang sama dengan nilai yang dilaporkan. Sensor harus dapat melaporkan nilai tanpa jenuh dalam [-maxRange; maxRange] . Perhatikan bahwa ini berarti jangkauan total sensor dalam pengertian umum adalah 2*maxRange . Ketika sensor melaporkan nilai pada beberapa sumbu, rentang tersebut berlaku untuk setiap sumbu. Misalnya, akselerometer “+/- 2g” akan melaporkan maxRange = 2*9.81 = 2g .
resolusi: Perbedaan nilai terkecil yang dapat diukur oleh sensor. Biasanya dihitung berdasarkan maxRange dan jumlah bit dalam pengukuran.
daya: Biaya daya untuk mengaktifkan sensor, dalam miliAmps. Jumlah ini hampir selalu melebihi konsumsi daya yang dilaporkan dalam lembar data sensor yang mendasarinya. Lihat Sensor dasar!= Sensor fisik untuk detail selengkapnya dan lihat Proses pengukuran daya untuk detail tentang cara mengukur konsumsi daya suatu sensor. Jika konsumsi daya sensor bergantung pada apakah perangkat bergerak, maka konsumsi daya saat bergerak adalah yang dilaporkan dalam bidang power .
minDelay: Untuk sensor kontinu, periode pengambilan sampel, dalam mikrodetik, sesuai dengan laju tercepat yang didukung sensor. Lihat sampling_period_ns untuk mengetahui detail tentang cara nilai ini digunakan. Berhati-hatilah karena minDelay dinyatakan dalam mikrodetik sedangkan sampling_period_ns dalam nanodetik. Untuk sensor mode pelaporan khusus dan perubahan, kecuali ditentukan lain, minDelay harus 0. Untuk sensor satu jepretan, harus -1.
maxDelay: Untuk sensor kontinu dan terus berubah, periode pengambilan sampel, dalam mikrodetik, sesuai dengan laju paling lambat yang didukung sensor. Lihat sampling_period_ns untuk mengetahui detail tentang cara nilai ini digunakan. Berhati-hatilah karena maxDelay dinyatakan dalam mikrodetik sedangkan sampling_period_ns dalam nanodetik. Untuk sensor khusus dan sensor sekali tembak, maxDelay harus 0.
fifoReservedEventCount: Jumlah kejadian yang dicadangkan untuk sensor ini di FIFO perangkat keras. Jika ada FIFO khusus untuk sensor ini, maka fifoReservedEventCount adalah ukuran FIFO khusus ini. Jika FIFO dibagikan dengan sensor lain, fifoReservedEventCount adalah ukuran bagian FIFO yang dicadangkan untuk sensor tersebut. Pada sebagian besar sistem FIFO bersama, dan pada sistem yang tidak memiliki FIFO perangkat keras, nilainya adalah 0.
fifoMaxEventCount: Jumlah maksimum kejadian yang dapat disimpan di FIFO untuk sensor ini. Ini selalu lebih besar atau sama dengan fifoReservedEventCount . Nilai ini digunakan untuk memperkirakan seberapa cepat FIFO akan penuh ketika mendaftar ke sensor pada kecepatan tertentu, seandainya tidak ada sensor lain yang diaktifkan. Pada sistem yang tidak memiliki FIFO perangkat keras, fifoMaxEventCount adalah 0. Lihat Batching untuk detail selengkapnya.
Untuk sensor dengan tipe sensor resmi, beberapa bidang ditimpa oleh kerangka. Misalnya, sensor akselerometer dipaksa untuk memiliki mode pelaporan berkelanjutan, dan monitor detak jantung dipaksa untuk dilindungi oleh izin SENSOR_PERMISSION_BODY_SENSORS .
sensor_event_t
Peristiwa sensor yang dihasilkan oleh sensor Android dan dilaporkan melalui fungsi polling type sensors_event_t . Berikut adalah beberapa bidang penting dari sensors_event_t :
versi: Harus sizeof(struct sensors_event_t)
sensor: Pegangan sensor yang menghasilkan peristiwa, seperti yang ditentukan oleh sensor_t.handle .
type: Jenis sensor dari sensor yang menghasilkan peristiwa, seperti yang ditentukan oleh sensor_t.type .
stempel waktu: Stempel waktu peristiwa dalam nanodetik. Ini adalah waktu terjadinya peristiwa (langkah yang diambil, atau pengukuran akselerometer dilakukan), bukan waktu peristiwa tersebut dilaporkan. timestamp harus disinkronkan dengan jam elapsedRealtimeNano , dan dalam kasus sensor kontinu, jitternya harus kecil. Pemfilteran stempel waktu terkadang diperlukan untuk memenuhi persyaratan CDD, karena hanya menggunakan waktu interupsi SoC untuk menyetel stempel waktu menyebabkan jitter terlalu tinggi, dan hanya menggunakan waktu chip sensor untuk menyetel stempel waktu dapat menyebabkan desinkronisasi dari jam elapsedRealtimeNano , sebagai jam sensor melayang.
data dan bidang yang tumpang tindih: Nilai yang diukur oleh sensor. Arti dan satuan bidang tersebut spesifik untuk setiap jenis sensor. Lihat sensor.h dan definisi berbagai jenis Sensor untuk deskripsi bidang data. Untuk beberapa sensor, keakuratan pembacaan juga dilaporkan sebagai bagian dari data, melalui kolom status . Bidang ini hanya disalurkan untuk jenis sensor tertentu tersebut, dan muncul di lapisan SDK sebagai nilai akurasi. Untuk sensor tersebut, fakta bahwa bidang status harus disetel disebutkan dalam definisi jenis sensornya .
Metadata flush peristiwa selesai
Peristiwa metadata memiliki jenis yang sama dengan peristiwa sensor normal: sensors_event_meta_data_t = sensors_event_t . Mereka dikembalikan bersama dengan peristiwa sensor lainnya melalui polling. Mereka memiliki bidang-bidang berikut:
versi: Harus META_DATA_VERSION
jenis: Harus SENSOR_TYPE_META_DATA
sensor, cadangan, dan stempel waktu : Harus 0
meta_data.what: Berisi tipe metadata untuk acara ini. Saat ini terdapat satu jenis metadata yang valid: META_DATA_FLUSH_COMPLETE .
Peristiwa META_DATA_FLUSH_COMPLETE mewakili penyelesaian flush sensor FIFO. Ketika meta_data.what=META_DATA_FLUSH_COMPLETE , meta_data.sensor harus disetel ke pegangan sensor yang telah di-flush. Mereka dihasilkan ketika dan hanya ketika flush dipanggil pada sensor. Lihat bagian fungsi flush untuk informasi lebih lanjut.