Sensor HAL 1.0

Catatan: Halaman ini menjelaskan Sensors HAL 1.0. Untuk mengetahui informasi tentang cara menerapkan Sensor HAL 2.0 di perangkat yang menjalankan Android 10 dan yang lebih tinggi, lihat Sensor HAL 2.0.

Antarmuka Sensors HAL, yang dideklarasikan dalam sensors.h, merepresentasikan antarmuka antara framework Android dan perangkat lunak khusus perangkat keras. Implementasi HAL harus menentukan setiap fungsi yang dideklarasikan dalam sensors.h. Fungsi utamanya adalah:

• get_sensors_list - Menampilkan daftar semua sensor.
• activate - Memulai atau menghentikan sensor.
• batch - Menetapkan parameter sensor seperti frekuensi pengambilan sampel dan maksimum latensi pelaporan.
• setDelay - Hanya digunakan di HAL versi 1.0. Menetapkan frekuensi pengambilan sampel untuk sensor tertentu.
• flush - Menghapus FIFO sensor yang ditentukan dan melaporkan pengosongan selesai ketika hal ini dilakukan.
• poll - Menampilkan peristiwa sensor yang tersedia.

Implementasinya harus aman untuk thread dan memungkinkan fungsi ini dipanggil dari thread yang berbeda.

Antarmuka juga menentukan beberapa jenis yang digunakan oleh fungsi tersebut. Utama adalah:

• sensors_module_t
• sensors_poll_device_t
• sensor_t
• sensors_event_t

Selain bagian di bawah ini, lihat sensors.h untuk mengetahui informasi selengkapnya 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 diterapkan oleh HAL. Lihat sensor_t untuk mengetahui detail tentang cara sensor ditentukan.

Urutan munculnya sensor di daftar adalah urutan dari sensor akan dilaporkan ke aplikasi. Biasanya, sensor dasar muncul pertama, diikuti oleh sensor komposit.

Jika beberapa sensor memiliki jenis sensor dan properti bangun yang sama, satu dalam daftar disebut sensor “default”. Ini adalah nilai yang dikembalikan oleh getDefaultSensor(int sensorType, bool wakeUp).

Fungsi ini menampilkan 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 tuas sensor yang akan diaktifkan/dinonaktifkan. Sebuah sensor handle ditentukan oleh kolom handle dalam struktur sensor_t-nya.

enabled disetel ke 1 untuk mengaktifkan atau 0 untuk menonaktifkan sensor.

Sensor satu kali menonaktifkan dirinya sendiri secara otomatis setelah menerima suatu peristiwa, dan mereka tetap harus menyetujui permintaan untuk dinonaktifkan melalui panggilan ke activate(..., enabled=0).

Sensor yang tidak diaktifkan tidak pernah mencegah SoC masuk ke mode ditangguhkan; sehingga adalah, HAL tidak boleh menahan penguncian layar saat aktif parsial atas nama aplikasi.

Sensor bangun, saat mengirim peristiwa secara terus-menerus, dapat mencegah SoC masuk ke mode ditangguhkan, tetapi jika tidak ada peristiwa yang perlu dikirimkan, komponen penguncian layar saat aktif harus dilepaskan.

Jika enabled adalah 1 dan sensor sudah diaktifkan, fungsi ini tidak dioperasikan dan berhasil.

Jika enabled adalah 0 dan sensor sudah dinonaktifkan, fungsi ini tidak dioperasikan dan berhasil.

Fungsi ini menampilkan 0 jika berhasil dan angka error negatif jika tidak.

batch(sensor, tanda, 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 laporan maksimum latensi yang tinggi. Fungsi ini dapat dipanggil saat sensor diaktifkan, di dalam hal ini tidak boleh menyebabkan pengukuran sensor hilang: Transisi dari satu frekuensi pengambilan sampel ke frekuensi lainnya tidak dapat menyebabkan peristiwa hilang, juga tidak dapat beralih dari latensi laporan maksimum yang tinggi ke laporan maksimum yang rendah latensi yang rendah.

sensor_handle adalah tuas sensor yang akan dikonfigurasi.

flags saat ini tidak digunakan.

sampling_period_ns adalah periode pengambilan sampel saat sensor akan berjalan, dalam nanodetik. Lihat sampling_period_ns untuk secara lebih mendetail.

max_report_latency_ns adalah waktu maksimum peristiwa dapat tertunda sebelum dilaporkan melalui HAL, dalam nanodetik. Lihat class max_report_Latency_ns untuk detail selengkapnya.

Fungsi ini menampilkan 0 jika berhasil dan angka error negatif jika tidak.

setPenundaan(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 menetapkan Parameter sampling_period_ns.

Di HAL versi 1.0, setPenundaan digunakan, bukan batch, untuk menetapkan sampling_period_ns.

flush(sensor)

int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

Menambahkan peristiwa flush complete ke akhir FIFO hardware untuk sensor yang ditentukan dan menghapus FIFO; peristiwa tersebut dikirim seperti biasa (yaitu, seolah-olah latensi pelaporan maksimum telah kedaluwarsa) dan dihapus dari FIFO.

Flush terjadi secara asinkron (yaitu: fungsi ini harus langsung ditampilkan). Jika implementasinya menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut di-flush dan kejadian flush complete ditambahkan hanya untuk sensor yang ditentukan.

Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada kemungkinan {i>buffer<i}), atau jika FIFO, kosong saat panggilan berlangsung, flush harus tetap berhasil dan mengirimkan kejadian {i>flush complete<i} untuk sensor itu. Ini berlaku untuk semua sensor lainnya daripada sensor sekali pakai.

Saat flush dipanggil, meskipun peristiwa flush sudah ada dalam FIFO untuk sensor tersebut, sensor tambahan harus dibuat dan ditambahkan ke bagian akhir dari FIFO, dan FIFO harus dibersihkan. Jumlah flush harus sama dengan jumlah peristiwa flush complete yang dibuat.

flush tidak berlaku untuk satu kali sensor; jika sensor_handle mengacu pada sensor satu kali, flush harus menampilkan -EINVAL dan tidak menghasilkan apa pun menghapus peristiwa metadata lengkap.

Fungsi ini menampilkan 0 jika berhasil, -EINVAL jika sensor yang ditentukan adalah sensor satu kali atau tidak diaktifkan, dan angka error negatif sebaliknya.

polling()

int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
  count);

Menampilkan array data sensor dengan mengisi argumen data. Fungsi ini harus diblokir hingga peristiwa tersedia. Ini akan mengembalikan jumlah peristiwa yang dibaca pada keberhasilan, atau jumlah kesalahan negatif jika terjadi kesalahan.

Jumlah peristiwa yang ditampilkan dalam data harus kurang atau sama dengan argumen count. Fungsi ini tidak boleh mengembalikan 0 (tidak ada peristiwa).

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 di HAL versi 1_0, urutannya adalah kebalikannya: activate dipanggil pertama, lalu set_delay.

Ketika karakteristik sensor yang diminta berubah saat sedang diaktifkan, fungsi batch dipanggil.

flush dapat dipanggil kapan saja, bahkan pada sensor yang tidak diaktifkan (dalam hal ini ID tersebut harus menampilkan -EINVAL)

Saat sensor dinonaktifkan, activate(..., enable=0) akan dipanggil.

Sejalan dengan panggilan tersebut, fungsi poll akan dipanggil berulang kali untuk data permintaan. poll dapat dipanggil meskipun tidak ada sensor yang diaktifkan.

sensor_modul_t

sensors_module_t adalah jenis yang digunakan untuk membuat hardware Android untuk sensor-sensor tersebut. Implementasi HAL harus mendefinisikan objek HAL_MODULE_INFO_SYM jenis ini untuk mengekspos fungsi get_sensors_list. Lihat definisi sensors_module_t dalam sensors.h dan definisi hw_module_t untuk informasi selengkapnya.

flavors_poll_device_t / sensor_poll_device_1_t

sensors_poll_device_1_t berisi metode lain yang ditentukan di atas: activate, batch, flush, dan poll. Kolom common (dengan jenis hw_device_t) mendefinisikan nomor versi HAL.

sensor_t

sensor_t mewakili Android sensor. Berikut ini beberapa kolom pentingnya:

name: String yang terlihat oleh pengguna yang mewakili sensor. String ini sering berisi nama bagian sensor yang mendasarinya, jenis sensor, dan apakah itu sensor bangun tidur. Misalnya, “Akselerometer LIS2HH12”, "MAX21000 Giroskop yang Tidak Dikalibrasi", "Barometer Bangunkan BMP280", "Game MPU6515 Vektor Rotasi”

handle: Bilangan bulat yang digunakan untuk merujuk pada sensor saat mendaftar atau yang menghasilkan peristiwa darinya.

type: Jenis sensor. Lihat penjelasan sensor Ketik Apa itu sensor Android? untuk mengetahui detail selengkapnya, dan lihat Jenis sensor untuk jenis sensor resmi. Sebagai jenis sensor tidak resmi, type harus diawali dengan SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType: Jenis sensor sebagai string. Jika sensor memiliki jenis resmi, yang disetel ke SENSOR_STRING_TYPE_*. Kapan sensor memiliki jenis khusus produsen, stringType harus mulailah dengan nama domain terbalik produsen. Misalnya, sebuah sensor (misalnya pendeteksi unicorn) yang ditentukan oleh tim Cool-product di Fiksi-Perusahaan bisa menggunakan stringType=”com.fictional_company.cool_product.unicorn_detector”. stringType digunakan untuk mengidentifikasi sensor tidak resmi secara unik jenis. Lihat sensors.h untuk mengetahui informasi selengkapnya tentang jenis dan string jenis.

requiredPermission: String yang mewakili izin yang harus dimiliki aplikasi untuk melihat sensor, mendaftar, dan menerima datanya. String kosong berarti aplikasi tidak memerlukan izin apa pun untuk mengakses sensor ini. Beberapa jenis sensor seperti pemantau detak jantung memiliki requiredPermission wajib. Semua sensor yang menyediakan informasi pengguna (seperti detak jantung) harus dilindungi oleh izin akses.

flag: Tanda untuk sensor ini, yang menentukan mode pelaporan sensor, dan apakah sensornya adalah sensor bangun tidur atau bukan. Misalnya, sensor membangunkan satu kali akan memiliki flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP. Bagian dari penanda 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 total rentang dari sensor dalam arti umum adalah 2*maxRange. Ketika sensor melaporkan nilai beberapa sumbu, rentang berlaku untuk setiap sumbu. Misalnya, “+/- 2g” akselerometer akan melaporkan maxRange = 2*9.81 = 2g.

resolusi: Perbedaan nilai terkecil yang dapat diukur sensor. Biasanya dikomputasi berdasarkan maxRange dan jumlah bit dalam pengukuran.

daya: Biaya daya untuk mengaktifkan sensor, dalam milliAmps. Jumlah ini hampir selalu lebih tinggi dibandingkan konsumsi daya yang dilaporkan dalam lembar data sensor yang mendasarinya. Lihat Sensor dasar != fisik sensor untuk mengetahui detail selengkapnya dan lihat Pengukuran daya untuk mengetahui detail tentang cara mengukur konsumsi daya sensor. Jika pemakaian daya sensor bergantung pada apakah perangkat bergerak, konsumsi daya saat bergerak adalah yang dilaporkan dalam power kolom tersebut.

minPenundaan: Untuk sensor berkelanjutan, periode pengambilan sampel, dalam mikrodetik, yang sesuai dengan kecepatan tercepat yang didukung sensor. Lihat sampling_period_ns untuk detail tentang bagaimana nilai ini digunakan. Ketahuilah bahwa minDelay adalah yang diekspresikan dalam mikrodetik saat sampling_period_ns dalam dalam nanodetik. Untuk sensor saat diubah dan mode pelaporan khusus, kecuali jika tidak ditentukan, minDelay harus 0. Untuk sensor satu kali, harus -1.

maxPenundaan: Untuk sensor berkelanjutan dan saat perubahan, pengambilan sampel titik, dalam mikrodetik, yang sesuai dengan laju paling lambat sensor didukung. Lihat sampling_period_ns untuk detail tentang bagaimana nilai ini digunakan. Ketahuilah bahwa maxDelay adalah yang diekspresikan dalam mikrodetik saat sampling_period_ns dalam dalam nanodetik. Untuk sensor khusus dan satu kali foto, maxDelay harus 0.

fifoReservedEventCount: Jumlah peristiwa yang dicadangkan untuk sensor ini dalam FIFO perangkat keras. Jika ada FIFO khusus untuk sensor ini, maka fifoReservedEventCount adalah ukuran FIFO khusus ini. Jika FIFO adalah dibagikan ke sensor lain, fifoReservedEventCount merupakan ukuran bagian dari FIFO yang disediakan untuk sensor tersebut. Pada sebagian besar sistem FIFO bersama, dan di sistem yang tidak memiliki FIFO perangkat keras, nilainya 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 dengan cepat FIFO akan penuh saat mendaftar ke sensor pada dengan asumsi tidak ada sensor lain yang diaktifkan. Pada sistem yang tidak memiliki FIFO hardware, fifoMaxEventCount adalah 0. Lihat Pengelompokan untuk mengetahui detail selengkapnya.

Untuk sensor dengan jenis sensor resmi, beberapa kolom ditimpa oleh kerangka kerja. Misalnya, sensor akselerometer dipaksa untuk memiliki mode pelaporan berkelanjutan, dan pemantauan detak jantung dipaksa untuk dilindungi oleh SENSOR_PERMISSION_BODY_SENSORS izin akses.

sensor_event_t (sensor_event_t)

Peristiwa sensor yang dihasilkan oleh sensor Android dan dilaporkan melalui fungsi pol adalah type sensors_event_t. Berikut beberapa kolom penting sensors_event_t:

versi: Harus sizeof(struct sensors_event_t)

sensor: Gagang sensor yang menghasilkan peristiwa, seperti yang didefinisikan oleh sensor_t.handle.

type: Jenis sensor sensor yang menghasilkan peristiwa, seperti yang ditetapkan oleh sensor_t.type.

timestamp: Stempel waktu peristiwa dalam nanodetik. Ini adalah saat terjadi (langkah atau pengukuran akselerometer dibuat), bukan waktu saat peristiwa itu dilaporkan. timestamp harus disinkronkan dengan clock elapsedRealtimeNano, dan untuk sensor berkelanjutan, jitter harus kecil. Pemfilteran stempel waktu terkadang diperlukan untuk memenuhi CDD persyaratan, karena hanya menggunakan waktu interupsi SoC untuk menyetel stempel waktu menyebabkan jitter yang terlalu tinggi, dan hanya menggunakan waktu chip sensor untuk menyetel dapat menyebabkan de-sinkronisasi dari Jam elapsedRealtimeNano, saat jam sensor bergerak.

kolom data dan kolom yang tumpang-tindih: Nilai yang diukur oleh sensor. Arti dan satuan bidang tersebut spesifik untuk setiap sensor . Lihat sensors.h dan definisi berbagai Jenis sensor untuk mengetahui deskripsi {i>field<i} data. Untuk beberapa sensor, akurasi pembacaan juga dilaporkan sebagai bagian dari data, melalui kolom status. Bidang ini hanya yang disalurkan untuk jenis sensor tertentu tersebut, muncul di lapisan SDK sebagai nilai akurasi. Untuk sensor tersebut, fakta bahwa isian status harus ditetapkan disebutkan dalam jenis sensor definisi.

Peristiwa lengkap penghapusan metadata

Peristiwa metadata memiliki jenis yang sama dengan peristiwa sensor normal: sensors_event_meta_data_t = sensors_event_t. Keduanya dikembalikan bersama dengan kejadian sensor lain melalui polling. Aset tersebut memiliki kolom berikut:

versi: Harus META_DATA_VERSION

type: Harus SENSOR_TYPE_META_DATA

sensor, cadangan, dan stempel waktu: Harus 0

meta_data.what: Berisi jenis metadata untuk peristiwa ini. Saat ini terdapat satu jenis metadata yang valid: META_DATA_FLUSH_COMPLETE.

Peristiwa META_DATA_FLUSH_COMPLETE merepresentasikan penyelesaian proses flush sensor FIFO. Saat meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor harus disetel ke tuas sensor yang telah di-flush. Mereka adalah dihasilkan saat dan hanya saat flush dipanggil pada sensor. Lihat bagian tentang fungsi flush untuk informasi selengkapnya.