Antarmuka HAL Sensor, yang dideklarasikan di 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- Mengosongkan FIFO sensor yang ditentukan dan melaporkan peristiwa selesai pengosongan saat hal ini dilakukan.poll- Menampilkan peristiwa sensor yang tersedia.
Implementasi harus aman untuk thread dan memungkinkan fungsi ini dipanggil dari thread yang berbeda.
Antarmuka juga menentukan beberapa jenis yang digunakan oleh fungsi tersebut. Jenis utamanya adalah:
sensors_module_tsensors_poll_device_tsensor_tsensors_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);
Menyediakan daftar sensor yang diimplementasikan oleh HAL. Lihat sensor_t untuk mengetahui detail tentang cara sensor ditentukan.
Urutan sensor dalam daftar adalah urutan sensor yang akan dilaporkan ke aplikasi. Biasanya, sensor dasar muncul terlebih dahulu, diikuti dengan sensor gabungan.
Jika beberapa sensor memiliki jenis sensor dan properti aktif 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, benar/salah)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Mengaktifkan atau menonaktifkan sensor.
sensor_handle adalah tuas sensor untuk mengaktifkan/menonaktifkan. Handle sensor
ditentukan oleh kolom handle dari struktur sensor_t.
enabled disetel ke 1 untuk mengaktifkan atau 0 untuk menonaktifkan sensor.
Sensor sekali baca menonaktifkan dirinya secara otomatis setelah menerima peristiwa,
dan sensor tersebut harus tetap menerima untuk dinonaktifkan melalui panggilan ke activate(...,
enabled=0).
Sensor non-wake-up tidak pernah mencegah SoC masuk ke mode suspend; artinya, HAL tidak boleh menahan penguncian layar saat aktif parsial atas nama aplikasi.
Sensor aktif, saat mengirimkan peristiwa secara terus-menerus, dapat mencegah SoC masuk ke mode ditangguhkan, tetapi jika tidak ada peristiwa yang perlu dikirimkan, wake-lock parsial harus dilepaskan.
Jika enabled adalah 1 dan sensor sudah diaktifkan, fungsi ini tidak akan melakukan apa pun
dan berhasil.
Jika enabled adalah 0 dan sensor sudah dinonaktifkan, fungsi ini tidak akan melakukan apa pun dan berhasil.
Fungsi ini menampilkan 0 jika berhasil dan angka error negatif jika tidak.
batch(sensor, tanda, periode pengambilan sampel, latensi pelaporan 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, dan dalam hal ini, tidak boleh menyebabkan pengukuran sensor hilang: Transisi dari satu frekuensi pengambilan sampel ke frekuensi pengambilan sampel lainnya tidak boleh menyebabkan peristiwa hilang, begitu juga transisi dari latensi pelaporan maksimum yang tinggi ke latensi pelaporan maksimum yang rendah.
sensor_handle adalah handle sensor yang akan dikonfigurasi.
flags saat ini tidak digunakan.
sampling_period_ns adalah periode pengambilan sampel saat sensor
harus berjalan, dalam nanodetik. Lihat sampling_period_ns untuk
detail selengkapnya.
max_report_latency_ns adalah waktu maksimum penundaan peristiwa sebelum dilaporkan melalui HAL, dalam nanodetik. Lihat paragraf max_report_latency_ns
untuk mengetahui detail selengkapnya.
Fungsi ini menampilkan 0 jika berhasil dan angka error 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.
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);
Tambahkan peristiwa selesai flush ke akhir FIFO hardware untuk sensor yang ditentukan dan flush FIFO; peristiwa tersebut dikirim seperti biasa (yaitu: seolah-olah latensi pelaporan maksimum telah berakhir) dan dihapus dari FIFO.
Pengosongan terjadi secara asinkron (yaitu: fungsi ini harus segera ditampilkan). Jika penerapan menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut akan dikosongkan dan peristiwa selesai pengosongan hanya ditambahkan untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada kemungkinan buffering), atau jika FIFO kosong pada saat panggilan, flush harus tetap berhasil dan mengirim peristiwa selesai penghapusan untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor sekali pemicu.
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 di-flush. Jumlah panggilan flush
harus sama dengan jumlah peristiwa selesai flush yang dibuat.
flush tidak berlaku untuk sensor sekaligus; jika sensor_handle merujuk ke sensor sekali baca, flush harus menampilkan -EINVAL dan tidak menghasilkan peristiwa metadata selesai penghapusan.
Fungsi ini menampilkan 0 jika berhasil, -EINVAL jika sensor yang ditentukan adalah
sensor sekali baca atau tidak diaktifkan, dan angka error negatif jika sebaliknya.
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. Metode ini akan menampilkan jumlah peristiwa yang dibaca
jika 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 akan pernah menampilkan 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 pada HAL versi 1_0, urutannya berlawanan: activate dipanggil
terlebih dahulu, diikuti dengan set_delay.
Saat karakteristik sensor yang diminta berubah saat diaktifkan, fungsi batch dipanggil.
flush dapat dipanggil kapan saja, bahkan pada sensor yang tidak diaktifkan (dalam hal ini, sensor 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.
sensors_module_t
sensors_module_t adalah jenis yang digunakan untuk membuat modul hardware Android
untuk sensor. Penerapan HAL harus menentukan objek
HAL_MODULE_INFO_SYM 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.
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 (berjenis hw_device_t)
menentukan nomor versi HAL.
sensor_t
sensor_t merepresentasikan sensor Android. Berikut beberapa kolom pentingnya:
name: String yang dapat dilihat pengguna yang mewakili sensor. String ini sering kali berisi nama komponen sensor yang mendasarinya, jenis sensor, dan apakah itu sensor aktif. Misalnya, “LIS2HH12 Accelerometer”, “MAX21000 Uncalibrated Gyroscope”, “BMP280 Wake-up Barometer”, “MPU6515 Game Rotation Vector”
handle: Bilangan bulat yang digunakan untuk merujuk ke sensor saat mendaftar ke sensor atau membuat 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 tidak resmi, type harus dimulai dengan SENSOR_TYPE_DEVICE_PRIVATE_BASE
stringType: Jenis sensor sebagai string. Jika
sensor memiliki jenis resmi, setel ke SENSOR_STRING_TYPE_*. Jika
sensor memiliki jenis khusus produsen, stringType harus
dimulai 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 tidak resmi secara unik. Lihat sensors.h untuk mengetahui informasi selengkapnya tentang jenis dan jenis string.
requiredPermission: String yang merepresentasikan 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 dengan izin.
flags: Flag untuk sensor ini, yang menentukan mode pelaporan sensor dan apakah sensor merupakan sensor aktif atau tidak. Misalnya, sensor aktif sekali
akan memiliki flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP. Bit 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 mengalami saturasi
dalam [-maxRange; maxRange]. Perhatikan bahwa ini berarti rentang total sensor
dalam arti generik adalah 2*maxRange. Jika sensor melaporkan nilai di beberapa sumbu, rentang 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 milliAmpere.
Hal ini hampir selalu lebih besar daripada konsumsi daya yang dilaporkan dalam
lembar data sensor yang mendasarinya. Lihat Sensor dasar != sensor fisik untuk mengetahui detail selengkapnya dan lihat Proses pengukuran daya untuk mengetahui detail tentang cara mengukur konsumsi daya sensor.
Jika konsumsi daya sensor bergantung pada apakah perangkat bergerak, konsumsi daya saat bergerak adalah yang dilaporkan di kolom power.
minDelay: Untuk sensor berkelanjutan, periode pengambilan sampel, dalam
mikrodetik, sesuai dengan frekuensi tercepat yang didukung sensor. Lihat sampling_period_ns untuk mengetahui detail tentang cara nilai ini digunakan. Perhatikan bahwa minDelay dinyatakan dalam mikrodetik, sedangkan sampling_period_ns dalam nanodetik. Untuk sensor mode pelaporan khusus dan saat perubahan, kecuali
dinyatakan lain, minDelay harus 0. Untuk sensor sekali pakai, nilainya harus -1.
maxDelay: Untuk sensor berkelanjutan dan saat berubah, periode
sampling, dalam mikrodetik, yang sesuai dengan kecepatan paling lambat yang didukung sensor. Lihat sampling_period_ns untuk mengetahui detail tentang cara nilai ini digunakan. Perhatikan bahwa maxDelay dinyatakan dalam mikrodetik, sedangkan sampling_period_ns dalam nanodetik. Untuk sensor khusus dan sekali pakai, maxDelay harus
0.
fifoReservedEventCount: Jumlah peristiwa yang dicadangkan untuk sensor ini di
FIFO hardware. 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 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 pada kecepatan tertentu, dengan asumsi tidak ada sensor lain yang diaktifkan. Pada sistem yang tidak memiliki FIFO hardware, fifoMaxEventCount adalah 0. Lihat Batching untuk mengetahui detail selengkapnya.
Untuk sensor dengan jenis sensor resmi, beberapa kolom akan diganti
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 polling adalah type sensors_event_t. Berikut beberapa kolom penting sensors_event_t:
version: Harus sizeof(struct sensors_event_t)
sensor: Handle sensor yang menghasilkan peristiwa, seperti yang ditentukan oleh
sensor_t.handle.
type: Jenis sensor yang menghasilkan peristiwa, sebagaimana ditentukan oleh
sensor_t.type.
timestamp: Stempel waktu peristiwa dalam nanodetik. Ini adalah waktu
peristiwa terjadi (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 menyetel stempel waktu menyebabkan jitter yang terlalu tinggi, dan hanya menggunakan waktu chip sensor untuk menyetel stempel waktu dapat menyebabkan desinkronisasi dari clock elapsedRealtimeNano, karena clock sensor mengalami penyimpangan.
data dan kolom yang tumpang-tindih: Nilai yang diukur oleh
sensor. Arti dan satuan kolom tersebut 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 selesai penghapusan metadata
Peristiwa metadata memiliki jenis yang sama dengan peristiwa sensor normal:
sensors_event_meta_data_t = sensors_event_t. Peristiwa ini dikembalikan bersama dengan
peristiwa sensor lainnya melalui polling. Objek ini memiliki kolom berikut:
version: Harus META_DATA_VERSION
type: Harus SENSOR_TYPE_META_DATA
sensor, dicadangkan, dan stempel waktu: 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 menunjukkan penyelesaian flush FIFO sensor. Saat meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor
harus ditetapkan ke handle sensor yang telah dibersihkan. Nilai ini dibuat
saat dan hanya saat flush dipanggil pada sensor. Lihat bagian tentang
fungsi flush untuk mengetahui informasi selengkapnya.