Antarmuka Sensors HAL, dideklarasikan dalam sensor.h , mewakili antarmuka antara kerangka kerja 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- Mengatur parameter sensor seperti frekuensi pengambilan sampel dan latensi pelaporan maksimum. -
setDelay- Hanya digunakan di HAL versi 1.0. Mengatur frekuensi pengambilan sampel untuk sensor yang diberikan. -
flush- Membilas FIFO dari sensor yang ditentukan dan melaporkan peristiwa flush yang lengkap saat ini selesai. -
poll- Mengembalikan peristiwa sensor yang tersedia.
Implementasinya harus thread-safe dan memungkinkan fungsi-fungsi ini dipanggil dari thread yang berbeda.
Antarmuka juga mendefinisikan beberapa jenis 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);
Menyediakan daftar sensor yang diimplementasikan oleh HAL. Lihat sensor_t untuk detail tentang bagaimana 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 bangun yang sama, yang pertama dalam daftar disebut sensor "default". Ini adalah 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 dari struktur sensor_t -nya.
enabled diatur ke 1 untuk mengaktifkan atau 0 untuk menonaktifkan sensor.
Sensor sekali tembak menonaktifkan diri mereka sendiri secara otomatis setelah menerima suatu peristiwa, dan mereka masih harus menerima untuk dinonaktifkan melalui panggilan untuk activate(..., enabled=0) .
Sensor non-bangun tidak pernah mencegah SoC masuk ke mode tunda; yaitu, HAL tidak boleh menahan penguncian sebagian atas nama aplikasi.
Sensor pengaktifan, saat mengirimkan peristiwa secara terus-menerus, dapat mencegah SoC masuk ke mode penangguhan, tetapi jika tidak ada peristiwa yang perlu dikirimkan, penguncian pengaktifan parsial harus dilepaskan.
Jika enabled adalah 1 dan sensor sudah diaktifkan, fungsi ini adalah no-op dan berhasil.
Jika enabled adalah 0 dan sensor sudah dinonaktifkan, fungsi ini adalah no-op dan berhasil.
Fungsi ini mengembalikan 0 pada keberhasilan dan angka kesalahan negatif sebaliknya.
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);
Menyetel parameter sensor, termasuk frekuensi pengambilan sampel dan latensi laporan maksimum . Fungsi ini dapat dipanggil saat sensor diaktifkan, dalam hal ini tidak boleh menyebabkan pengukuran sensor hilang: Transisi dari satu laju pengambilan sampel ke laju pengambilan sampel lainnya tidak dapat menyebabkan peristiwa yang hilang, juga tidak dapat beralih dari latensi laporan maksimum yang tinggi ke latensi laporan 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 di mana sensor harus berjalan, dalam nanodetik. Lihat sampling_period_ns untuk detail selengkapnya.
max_report_latency_ns adalah waktu maksimum di mana peristiwa dapat ditunda sebelum dilaporkan melalui HAL, dalam nanodetik. Lihat paragraf max_report_latency_ns untuk lebih jelasnya.
Fungsi ini mengembalikan 0 pada keberhasilan dan angka kesalahan negatif sebaliknya.
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. Sebagai gantinya, fungsi batch dipanggil untuk menyetel parameter sampling_period_ns .
Dalam HAL versi 1.0, setDelay digunakan sebagai ganti batch untuk mengatur 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 flush FIFO; peristiwa tersebut dikirimkan seperti biasa (yaitu: seolah-olah latensi pelaporan maksimum telah kedaluwarsa) dan dihapus dari FIFO.
Flush terjadi secara tidak sinkron (yaitu: fungsi ini harus segera kembali). Jika implementasi menggunakan FIFO tunggal untuk beberapa sensor, FIFO tersebut akan di-flush dan event flush complete ditambahkan hanya untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada buffering), atau jika FIFO kosong pada saat panggilan, flush harus tetap berhasil dan mengirim acara flush complete untuk sensor tersebut. Ini berlaku untuk semua sensor selain sensor sekali tembak.
Saat flush dipanggil, bahkan jika acara flush sudah ada di FIFO untuk sensor itu, yang tambahan harus dibuat dan ditambahkan ke akhir FIFO, dan FIFO harus di-flush. Jumlah panggilan flush harus sama dengan jumlah event flush complete yang dibuat.
flush tidak berlaku untuk sensor sekali tembak ; jika sensor_handle mengacu pada sensor one-shot, flush harus mengembalikan -EINVAL dan tidak menghasilkan event metadata lengkap flush.
Fungsi ini mengembalikan 0 jika berhasil, -EINVAL jika sensor yang ditentukan adalah sensor sekali tembak atau tidak diaktifkan, dan angka kesalahan negatif sebaliknya.
pemilihan()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count);
Mengembalikan larik data sensor dengan mengisi argumen data . Fungsi ini harus diblokir hingga acara tersedia. Ini akan mengembalikan jumlah peristiwa yang dibaca saat berhasil, atau nomor kesalahan negatif jika terjadi kesalahan.
Jumlah kejadian yang dikembalikan dalam data harus kurang atau sama dengan argumen count . Fungsi ini tidak akan pernah mengembalikan 0 (tidak ada acara).
Urutan panggilan
Saat perangkat melakukan booting, get_sensors_list dipanggil.
Ketika sebuah sensor diaktifkan, fungsi batch akan dipanggil dengan parameter yang diminta, diikuti oleh activate(..., enable=1) .
Perhatikan bahwa di HAL versi 1_0, urutannya adalah kebalikannya: activate dipanggil terlebih dahulu, diikuti oleh set_delay .
Ketika karakteristik sensor yang diminta berubah saat diaktifkan, fungsi batch dipanggil.
flush dapat dipanggil kapan saja, bahkan pada sensor yang tidak diaktifkan (dalam hal ini harus mengembalikan -EINVAL )
Saat sensor dinonaktifkan, activate(..., enable=0) akan dipanggil.
Sejalan dengan panggilan tersebut, fungsi poll akan dipanggil berulang kali untuk meminta data. poll dapat dipanggil meskipun 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 sisa metode yang didefinisikan di atas: activate , batch , flush dan poll . Bidang common (dari tipe hw_device_t ) mendefinisikan nomor versi HAL.
sensor_t
sensor_t mewakili sensor Android . Berikut adalah beberapa bidang pentingnya:
name: String yang terlihat oleh pengguna yang mewakili sensor. String ini sering berisi nama bagian dari sensor yang mendasari, jenis sensor, dan apakah itu sensor bangun. Misalnya, “LIS2HH12 Accelerometer”, “MAX21000 Uncalibrated Gyroscope”, “BMP280 Wake-up Barometer”, “Vektor Rotasi Game MPU6515”
handle: Bilangan bulat yang digunakan untuk merujuk ke sensor saat mendaftar atau menghasilkan peristiwa darinya.
jenis: Jenis sensor. Lihat penjelasan jenis sensor di Apa itu sensor Android? untuk detail selengkapnya, dan lihat Jenis sensor untuk jenis sensor resmi. Untuk jenis sensor tidak resmi, type harus dimulai dengan SENSOR_TYPE_DEVICE_PRIVATE_BASE
stringType: Jenis sensor sebagai string. Saat sensor memiliki tipe resmi, setel ke SENSOR_STRING_TYPE_* . Ketika sensor memiliki tipe khusus pabrikan, stringType harus dimulai dengan nama domain terbalik pabrikan. Misalnya, sebuah sensor (misalnya detektor unicorn) yang ditentukan oleh tim produk Keren di Perusahaan Fiksi dapat menggunakan stringType=”com.fictional_company.cool_product.unicorn_detector” . stringType digunakan untuk mengidentifikasi jenis sensor non-resmi secara unik. Lihat sensor.h untuk informasi lebih lanjut tentang tipe dan tipe string.
diperlukanPermission: String yang mewakili izin yang harus dimiliki aplikasi untuk melihat sensor, mendaftar ke sana, dan menerima datanya. String kosong berarti aplikasi tidak memerlukan izin apa pun untuk mengakses sensor ini. Beberapa jenis sensor seperti monitor detak jantung memiliki Izin wajib yang requiredPermission . Semua sensor yang memberikan informasi sensitif 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 sekali pakai akan memiliki flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . Bit dari flag yang tidak digunakan dalam versi HAL saat ini harus dibiarkan sama dengan 0.
maxRange: Nilai maksimum yang dapat dilaporkan sensor, dalam unit yang sama dengan nilai yang dilaporkan. Sensor harus dapat melaporkan nilai tanpa saturasi dalam [-maxRange; maxRange] . Perhatikan bahwa ini berarti rentang total sensor dalam pengertian umum adalah 2*maxRange . Saat sensor melaporkan nilai pada beberapa sumbu, rentang berlaku untuk setiap sumbu. Misalnya, akselerometer “+/- 2g” akan melaporkan maxRange = 2*9.81 = 2g .
resolusi: Perbedaan terkecil dalam nilai yang dapat diukur oleh sensor. Biasanya dihitung berdasarkan maxRange dan jumlah bit dalam pengukuran.
daya: Biaya daya untuk mengaktifkan sensor, dalam miliAmp. Ini hampir selalu lebih dari konsumsi daya yang dilaporkan dalam lembar data sensor yang mendasarinya. Lihat Sensor dasar != sensor fisik untuk detail lebih lanjut dan lihat Proses pengukuran daya untuk detail tentang cara mengukur konsumsi daya sensor. Jika konsumsi daya sensor bergantung pada apakah perangkat bergerak, konsumsi daya saat bergerak adalah yang dilaporkan di bidang power .
minDelay: Untuk sensor kontinu, periode pengambilan sampel, dalam mikrodetik, sesuai dengan kecepatan tercepat yang didukung sensor. Lihat sampling_period_ns untuk detail tentang bagaimana nilai ini digunakan. Hati-hati bahwa minDelay dinyatakan dalam mikrodetik sedangkan sampling_period_ns dalam nanodetik. Untuk sensor mode perubahan dan pelaporan khusus, kecuali ditentukan lain, minDelay harus 0. Untuk sensor sekali tembak, harus -1.
maxDelay: Untuk sensor yang terus menerus dan berubah, periode pengambilan sampel, dalam mikrodetik, sesuai dengan kecepatan paling lambat yang didukung sensor. Lihat sampling_period_ns untuk detail tentang bagaimana nilai ini digunakan. Hati-hati bahwa maxDelay dinyatakan dalam mikrodetik sedangkan sampling_period_ns dalam nanodetik. Untuk sensor khusus dan sekali tembak, maxDelay harus 0.
fifoReservedEventCount: Jumlah peristiwa yang dicadangkan untuk sensor ini di perangkat keras FIFO. 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, nilai ini adalah 0.
fifoMaxEventCount: Jumlah maksimum peristiwa yang dapat disimpan dalam 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 tingkat tertentu, seandainya tidak ada sensor lain yang diaktifkan. Pada sistem yang tidak memiliki FIFO perangkat keras, fifoMaxEventCount adalah 0. Lihat Batching untuk lebih jelasnya.
Untuk sensor dengan tipe sensor resmi, beberapa bidang ditimpa oleh kerangka kerja. 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 didefinisikan oleh sensor_t.handle .
type: Jenis sensor dari sensor yang menghasilkan peristiwa, seperti yang didefinisikan oleh sensor_t.type .
timestamp: Stempel waktu acara dalam nanodetik. Ini adalah waktu peristiwa itu terjadi (langkah diambil, atau pengukuran akselerometer dilakukan), bukan waktu peristiwa itu dilaporkan. timestamp harus disinkronkan dengan jam elapsedRealtimeNano , dan dalam kasus sensor kontinu, jitter harus kecil. Pemfilteran stempel waktu terkadang diperlukan untuk memenuhi persyaratan CDD, karena hanya menggunakan waktu interupsi SoC untuk menyetel stempel waktu menyebabkan jitter yang terlalu tinggi, dan hanya menggunakan waktu chip sensor untuk menyetel stempel waktu dapat menyebabkan elapsedRealtimeNano dari jam RealtimeNano yang telah berlalu, karena sensor jam melayang.
bidang data dan tumpang tindih: Nilai yang diukur oleh sensor. Arti dan unit dari bidang tersebut khusus 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 bidang status . Bidang ini hanya disalurkan untuk jenis sensor tertentu, yang muncul di lapisan SDK sebagai nilai akurasi. Untuk sensor tersebut, fakta bahwa bidang status harus disetel disebutkan dalam definisi jenis sensornya .
Metadata flush acara 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, reserved, dan stempel waktu : Harus 0
meta_data.what: Berisi jenis metadata untuk acara ini. Saat ini ada satu jenis metadata yang valid: META_DATA_FLUSH_COMPLETE .
Peristiwa META_DATA_FLUSH_COMPLETE mewakili penyelesaian flush dari sensor FIFO. Ketika meta_data.what=META_DATA_FLUSH_COMPLETE , meta_data.sensor harus diatur 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.