Sensors HAL 1.0

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Antarmuka HAL Sensor, yang dideklarasikan di sensors.h, mewakili antarmuka antara framework Android dan software khusus hardware. Implementasi HAL harus menentukan setiap fungsi yang dideklarasikan di sensors.h. Fungsi utamanya adalah:

• get_sensors_list - Menampilkan daftar semua sensor.
• activate - Memulai atau menghentikan sensor.
• batch - Menetapkan parameter sensor seperti frekuensi sampling dan latensi pelaporan maksimum.
• setDelay - Hanya digunakan di HAL versi 1.0. Menetapkan frekuensi sampling untuk sensor tertentu.
• flush - Menghapus FIFO sensor yang ditentukan dan melaporkan peristiwa penghapusan lengkap saat 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. Jenis 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);

Memberikan daftar sensor yang diimplementasikan oleh HAL. Lihat sensor_t untuk mengetahui detail tentang cara sensor ditentukan.

Urutan kemunculan sensor dalam daftar adalah urutan 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 yang ditampilkan 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. ID sensor ditentukan oleh kolom handle dari struktur sensor_t-nya.

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

Sensor one-shot menonaktifkan dirinya secara otomatis setelah menerima peristiwa, dan sensor tersebut masih harus menerima 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 wake-up, saat terus mengirimkan peristiwa, dapat mencegah SoC beralih ke mode penangguhan, tetapi jika tidak ada peristiwa yang perlu dikirim, kunci layar sebagian 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 akan melakukan operasi dan berhasil.

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

batch(sensor, flag, sampling period, maximum report latency)

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 sampling dan latensi laporan maksimum. Fungsi ini dapat dipanggil saat sensor diaktifkan, dalam hal ini tidak boleh menyebabkan pengukuran sensor hilang: Transisi dari satu frekuensi sampling ke frekuensi sampling lainnya tidak dapat menyebabkan peristiwa hilang, begitu pula transisi dari latensi laporan maksimum tinggi ke latensi laporan maksimum rendah.

sensor_handle adalah nama sebutan sensor yang akan dikonfigurasi.

flags saat ini tidak digunakan.

sampling_period_ns adalah periode sampling saat sensor harus berjalan, dalam nanodetik. Lihat sampling_period_ns untuk secara lebih mendetail.

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

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

setDelay(sensor, sampling period)

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 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 {i>buffer<i}), atau jika FIFO, kosong saat panggilan berlangsung, flush harus tetap berhasil dan mengirimkan kejadian {i>flush complete<i} untuk sensor itu. Hal ini berlaku untuk semua sensor selain sensor one-shot.

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 sensor sekaligus; jika sensor_handle merujuk ke sensor sekaligus, flush harus menampilkan -EINVAL dan tidak menghasilkan peristiwa metadata lengkap penghapusan.

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. Fungsi ini akan menampilkan jumlah peristiwa yang dibaca saat berhasil, atau angka error negatif jika terjadi error.

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

Urutan panggilan

Saat perangkat melakukan booting, get_sensors_list akan 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, harus menampilkan -EINVAL)

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

Secara paralel 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 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 di sensors.h dan definisi hw_module_t untuk mengetahui informasi selengkapnya.

sensors_poll_device_t / sensors_poll_device_1_t

sensors_poll_device_1_t berisi metode lainnya yang ditentukan di atas: activate, batch, flush, dan poll. Kolom common-nya (berjenis hw_device_t) menentukan nomor versi HAL.

sensor_t

sensor_t mewakili Android sensor. Berikut ini beberapa kolom pentingnya:

name: String yang terlihat pengguna yang mewakili sensor. String ini sering kali berisi nama bagian sensor yang mendasarinya, jenis sensor, dan apakah sensor tersebut merupakan sensor pengaktifan. 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 mengetahui 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 jenis resmi, yang disetel ke SENSOR_STRING_TYPE_*. Kapan sensor memiliki jenis khusus produsen, stringType harus mulailah dengan nama domain terbalik produsen. 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 sensor tidak resmi secara unik jenis datanya. Lihat sensors.h untuk mengetahui informasi selengkapnya tentang jenis dan string jenis datanya.

requiredPermission: String yang mewakili izin yang harus dimiliki aplikasi untuk melihat sensor, mendaftar ke sensor, 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 wake-up one-shot 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 rentang total sensor dalam arti umum adalah 2*maxRange. Saat sensor melaporkan nilai di beberapa sumbu, rentang berlaku untuk setiap sumbu. Misalnya, “+/- 2g” akselerometer akan melaporkan maxRange = 2*9.81 = 2g.

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

daya: Biaya daya untuk mengaktifkan sensor, dalam milliAmps. Nilai ini hampir selalu lebih besar dari 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 cara mengukur konsumsi daya sensor. Jika konsumsi daya sensor bergantung pada apakah perangkat bergerak, konsumsi daya saat bergerak adalah konsumsi daya yang dilaporkan di kolom power.

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. Perhatikan bahwa minDelay dinyatakan dalam mikrodetik, sedangkan sampling_period_ns dalam nanodetik. Untuk sensor saat diubah dan mode pelaporan khusus, kecuali jika tidak ditentukan, minDelay harus 0. Untuk sensor one-shot, nilainya 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 mengetahui detail tentang cara penggunaan nilai ini. 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 pada sistem yang tidak memiliki FIFO hardware, nilai ini adalah 0.

fifoMaxEventCount: Jumlah maksimum peristiwa yang dapat disimpan dalam FIFO untuk sensor ini. Nilai ini selalu lebih besar dari 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 monitor detak jantung dipaksa untuk dilindungi oleh izin SENSOR_PERMISSION_BODY_SENSORS.

sensors_event_t

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

versi: Harus sizeof(struct sensors_event_t)

sensor: Nama sebutan 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.

timestamp: Stempel waktu peristiwa dalam nanodetik. Ini adalah waktu terjadinya peristiwa (langkah diambil, atau pengukuran akselerometer dilakukan), bukan waktu peristiwa dilaporkan. timestamp harus disinkronkan dengan jam elapsedRealtimeNano, dan dalam kasus 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.

data dan kolom 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 penyelesaian 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. Kolom tersebut memiliki kolom berikut:

versi: Harus META_DATA_VERSION

type: Harus SENSOR_TYPE_META_DATA

sensor, reserved, dan timestamp: 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. Jika meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor harus ditetapkan ke handle sensor yang telah dihapus. Mereka adalah dihasilkan saat dan hanya saat flush dipanggil pada sensor. Lihat bagian tentang fungsi flush untuk informasi selengkapnya.