Sensor HAL 1.0

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

Antarmuka Sensors HAL, yang dideklarasikan dalam sensors.h, merepresentasikan 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.

Implementasi harus thread-safe 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, lihat sensors.h untuk mengetahui informasi selengkapnya tentang jenis tersebut.

get_sensors_list(list)

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 sensor yang muncul dalam daftar adalah urutan pelaporan sensor ke aplikasi. Biasanya, sensor dasar muncul terlebih dahulu, diikuti dengan sensor komposit.

Jika beberapa sensor memiliki jenis sensor dan properti pengaktifan yang sama, sensor pertama dalam daftar disebut sensor "default". Ini adalah yang ditampilkan oleh getDefaultSensor(int sensorType, bool wakeUp).

Fungsi ini menampilkan jumlah sensor dalam daftar.

activate(sensor, true/false)

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.

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

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

Sensor non-wake-up tidak pernah mencegah SoC masuk ke mode penangguhan; yaitu, HAL tidak akan menahan wake-lock 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 akan melakukan tindakan apa pun dan berhasil.

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

Fungsi ini menampilkan 0 jika berhasil dan 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, yang 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 tuas 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 mengetahui detail selengkapnya.

max_report_latency_ns adalah waktu maksimum yang dapat digunakan untuk menunda peristiwa sebelum dilaporkan melalui HAL, dalam nanodetik. Lihat paragraf max_report_latency_ns untuk mengetahui 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, setDelay 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 ditayangkan seperti biasa (yaitu, seolah-olah latensi pelaporan maksimum telah habis masa berlakunya) dan dihapus dari FIFO.

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 dapat melakukan buffering), atau jika FIFO, kosong pada saat panggilan, flush harus tetap berhasil dan mengirim peristiwa flush complete untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor one-shot.

Saat flush dipanggil, meskipun peristiwa flush sudah ada di FIFO untuk sensor tersebut, peristiwa tambahan harus dibuat dan ditambahkan ke akhir FIFO, dan FIFO harus dihapus. Jumlah panggilan flush harus sama dengan jumlah peristiwa flush lengkap 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 jika tidak diaktifkan.

poll()

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

Jumlah peristiwa yang ditampilkan dalam data harus lebih kecil atau sama dengan argumen count. Fungsi ini tidak akan pernah menampilkan 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 sebaliknya: activate dipanggil terlebih dahulu, diikuti dengan set_delay.

Saat karakteristik sensor yang diminta berubah saat diaktifkan, fungsi batch akan 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.

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 jenis yang digunakan untuk membuat modul hardware Android untuk sensor. Implementasi HAL harus menentukan HAL_MODULE_INFO_SYM objek dari 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.

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. Kolom common-nya (berjenis hw_device_t) menentukan nomor versi HAL.

sensor_t

sensor_t mewakili sensor Android. Berikut 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”, “Vektor Rotasi Game MPU6515”

handle: Integer yang digunakan untuk merujuk pada sensor saat mendaftar atau menghasilkan peristiwa dari sensor.

type: Jenis sensor. Lihat penjelasan jenis sensor di Apa yang dimaksud dengan 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, tetapkan ke SENSOR_STRING_TYPE_*. Jika sensor memiliki jenis khusus produsen, stringType harus diawali 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 jenis sensor non-resmi secara unik. Lihat sensors.h untuk informasi selengkapnya tentang jenis dan jenis string.

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 monitor detak jantung memiliki requiredPermission wajib. Semua sensor yang memberikan informasi pengguna sensitif (seperti detak jantung) harus dilindungi oleh izin.

flags: Flag untuk sensor ini, yang menentukan mode pelaporan sensor dan apakah sensor tersebut merupakan sensor bangun atau tidak. Misalnya, sensor bangun tidur satu kali akan memiliki flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP. Bit tanda 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, akselerometer “+/- 2g” akan melaporkan maxRange = 2*9.81 = 2g.

resolution: Perbedaan nilai terkecil yang dapat diukur sensor. Biasanya dihitung 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 != sensor fisik untuk detail selengkapnya, 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 konsumsi daya yang dilaporkan di kolom power.

minDelay: Untuk sensor kontinu, periode sampling, dalam mikrodetik, sesuai dengan kecepatan tercepat yang didukung sensor. Lihat sampling_period_ns untuk mengetahui detail tentang cara penggunaan nilai ini. Perhatikan bahwa minDelay dinyatakan dalam mikrodetik, sedangkan sampling_period_ns dalam nanodetik. Untuk sensor mode pelaporan khusus dan saat berubah, kecuali jika ditentukan sebaliknya, minDelay harus 0. Untuk sensor one-shot, nilainya harus -1.

maxDelay: Untuk sensor berkelanjutan dan saat berubah, periode sampling, dalam mikrodetik, sesuai dengan kecepatan paling lambat yang didukung sensor. Lihat sampling_period_ns untuk mengetahui detail tentang cara penggunaan nilai ini. Perhatikan bahwa maxDelay dinyatakan dalam mikrodetik, sedangkan sampling_period_ns dalam nanodetik. Untuk sensor khusus dan one-shot, maxDelay harus 0.

fifoReservedEventCount: Jumlah peristiwa yang dicadangkan untuk sensor ini dalam FIFO hardware. Jika ada FIFO khusus untuk sensor ini, 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 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 cepat FIFO akan penuh saat mendaftar ke sensor dengan kecepatan tertentu, 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 framework. 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 pol adalah type sensors_event_t. Berikut beberapa kolom penting sensors_event_t:

version: 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 persyaratan CDD, karena hanya menggunakan waktu interupsi SoC untuk menetapkan stempel waktu menyebabkan jitter yang terlalu tinggi, dan hanya menggunakan waktu chip sensor untuk menetapkan stempel waktu dapat menyebabkan desinkronisasi dari clock elapsedRealtimeNano, karena clock sensor mengalami drift.

data dan kolom tumpang-tindih: Nilai yang diukur oleh sensor. Arti dan unit kolom tersebut bersifat khusus untuk setiap jenis sensor. Lihat sensors.h dan definisi berbagai Jenis sensor untuk deskripsi kolom data. Untuk beberapa sensor, akurasi pembacaan juga dilaporkan sebagai bagian dari data, melalui kolom status. Kolom ini hanya disalurkan untuk jenis sensor tertentu, yang muncul di lapisan SDK sebagai nilai akurasi. Untuk sensor tersebut, fakta bahwa kolom status harus ditetapkan disebutkan dalam definisi jenis sensor mereka.

Peristiwa penyelesaian penghapusan metadata

Peristiwa metadata memiliki jenis yang sama dengan peristiwa sensor normal: sensors_event_meta_data_t = sensors_event_t. Peristiwa ini ditampilkan bersama dengan peristiwa sensor lainnya melalui polling. Kolom tersebut memiliki kolom berikut:

version: Harus META_DATA_VERSION

type: Harus berupa SENSOR_TYPE_META_DATA

sensor, reserved, dan timestamp: Harus 0

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

Peristiwa META_DATA_FLUSH_COMPLETE mewakili penyelesaian proses flush FIFO sensor. Jika meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor harus ditetapkan ke handle sensor yang telah dihapus. Fungsi ini dihasilkan saat dan hanya saat flush dipanggil di sensor. Lihat bagian tentang fungsi flush untuk mengetahui informasi selengkapnya.