Mulai tahun 2026, untuk menyelaraskan dengan model pengembangan stabil trunk kami dan memastikan stabilitas platform untuk ekosistem, kami akan memublikasikan kode sumber ke AOSP pada Kuartal 2 dan Kuartal 4. Untuk membangun dan berkontribusi ke AOSP, sebaiknya gunakan android-latest-release, bukan aosp-main. Cabang manifes android-latest-release akan selalu merujuk pada rilis terbaru yang di-push ke AOSP. Untuk mengetahui informasi selengkapnya, lihat Perubahan pada AOSP.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Sensors HAL 1.0

Antarmuka Sensors HAL, 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 a sensor tertentu.
flush - Melakukan flush FIFO sensor yang ditentukan dan melaporkan peristiwa flush selesai 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 ini juga menentukan beberapa jenis yang digunakan oleh fungsi tersebut. Jenis utamanya 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);

Menyediakan daftar sensor yang diterapkan oleh HAL. Lihat sensor_t untuk mengetahui detail tentang cara sensor ditentukan.

Urutan sensor muncul dalam daftar adalah urutan sensor akan dilaporkan ke aplikasi. Biasanya, sensor dasar muncul terlebih dahulu, diikuti oleh sensor gabungan.

Jika beberapa sensor memiliki jenis sensor dan properti bangun yang sama, sensor pertama dalam daftar disebut sensor “default”. Sensor ini adalah sensor 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 pengendali sensor yang akan diaktifkan/dinonaktifkan. Pengendali sensor ditentukan oleh kolom handle dari struktur sensor_t.

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

Sensor sekali pakai akan otomatis dinonaktifkan setelah menerima peristiwa, dan sensor tersebut harus tetap menerima untuk dinonaktifkan melalui panggilan ke activate(..., enabled=0).

Sensor non-bangun tidak pernah mencegah SoC masuk ke mode penangguhan; artinya, HAL tidak boleh menahan wake-lock sebagian atas nama aplikasi.

Sensor bangun, saat mengirim peristiwa secara terus-menerus, dapat mencegah SoC masuk ke mode penangguhan, tetapi jika tidak ada peristiwa yang perlu dikirim, wake-lock sebagian harus dilepaskan.

Jika enabled adalah 1 dan sensor sudah diaktifkan, fungsi ini tidak melakukan apa pun dan berhasil.

Jika enabled adalah 0 dan sensor sudah dinonaktifkan, fungsi ini tidak melakukan apa pun dan berhasil.

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

batch(sensor, flags, 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, dan dalam hal ini, fungsi tersebut tidak boleh menyebabkan pengukuran sensor hilang: Transisi dari satu frekuensi sampling ke frekuensi sampling lainnya tidak dapat menyebabkan peristiwa hilang, dan transisi dari latensi laporan maksimum yang tinggi ke latensi laporan maksimum yang rendah juga tidak dapat menyebabkan peristiwa hilang.

sensor_handle adalah pengendali 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 detail selengkapnya.

max_report_latency_ns adalah waktu maksimum peristiwa dapat ditunda 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, 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 pengosongan selesai ke akhir FIFO hardware untuk sensor yang ditentukan dan mengosongkan 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 implementasi menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut akan dikosongkan dan peristiwa pengosongan selesai hanya ditambahkan untuk sensor yang ditentukan.

Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada buffering yang mungkin), atau jika FIFO, kosong pada saat panggilan, flush harus tetap berhasil dan mengirim peristiwa pengosongan selesai untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor sekali pakai.

Saat flush dipanggil, meskipun peristiwa pengosongan sudah ada di FIFO untuk sensor tersebut, peristiwa pengosongan tambahan harus dibuat dan ditambahkan ke akhir FIFO, dan FIFO harus dikosongkan. Jumlah panggilan flush harus sama dengan jumlah peristiwa pengosongan selesai yang dibuat.

flush tidak berlaku untuk sekali pakai sensor; jika sensor_handle merujuk ke sensor sekali pakai, flush harus menampilkan -EINVAL dan tidak membuat peristiwa metadata pengosongan selesai.

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

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

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

Urutan panggilan

Saat perangkat di-booting, get_sensors_list akan dipanggil.

Saat sensor diaktifkan, fungsi batch akan dipanggil dengan parameter yang diminta, diikuti oleh activate(..., enable=1).

Perhatikan bahwa di HAL versi 1_0, urutannya terbalik: activate dipanggil terlebih dahulu, diikuti oleh set_delay.

Saat karakteristik sensor yang diminta berubah saat sensor diaktifkan, fungsi batch akan dipanggil.

flush dapat dipanggil kapan saja, bahkan pada sensor yang tidak diaktifkan (dalam hal ini fungsi tersebut 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. Implementasi 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 mewakili sensor Android. Berikut beberapa kolom pentingnya:

name: String yang terlihat oleh pengguna yang mewakili sensor. String ini sering kali berisi nama bagian sensor yang mendasarinya, jenis sensor, dan apakah sensor tersebut adalah sensor bangun. 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 tersebut atau membuat peristiwa dari sensor tersebut.

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, tetapkan 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”. The stringType digunakan untuk mengidentifikasi jenis sensor tidak resmi secara unik. Lihat sensors.h untuk mengetahui informasi selengkapnya tentang jenis dan jenis string types.

requiredPermission: String yang mewakili izin yang harus dimiliki aplikasi untuk melihat sensor, mendaftar ke sensor tersebut, 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 adalah sensor bangun atau bukan. Misalnya, sensor bangun sekali pakai 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 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.

power: Biaya daya untuk mengaktifkan sensor, dalam milliAmp. Biaya ini hampir selalu lebih besar daripada konsumsi daya yang dilaporkan dalam datasheet 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 atau tidak, konsumsi daya saat bergerak adalah konsumsi daya yang dilaporkan di kolom power.

minDelay: Untuk sensor berkelanjutan, periode sampling, dalam mikrodetik, yang sesuai dengan kecepatan 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 sesuai perubahan, kecuali jika ditentukan lain, minDelay harus 0. Untuk sensor sekali pakai, nilai ini harus -1.

maxDelay: Untuk sensor berkelanjutan dan sesuai perubahan, 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 hardware 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. Di sebagian besar sistem FIFO bersama, dan pada sistem yang tidak memiliki FIFO hardware, nilai ini adalah 0.

fifoMaxEventCount: Jumlah maksimum peristiwa yang dapat disimpan di FIFO untuk sensor ini. Nilai ini selalu lebih besar 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 Pengelompokan untuk mengetahui detail selengkapnya.

Untuk sensor dengan jenis sensor resmi, beberapa kolom akan 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 dibuat oleh sensor Android dan dilaporkan melalui fungsi polling berjenis type sensors_event_t. Berikut beberapa kolom penting sensors_event_t:

version: Harus sizeof(struct sensors_event_t)

sensor: Pengendali sensor yang membuat peristiwa, seperti yang ditentukan oleh sensor_t.handle.

type: Jenis sensor dari sensor yang membuat 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 akan menyebabkan jitter yang terlalu tinggi, dan hanya menggunakan waktu chip sensor untuk menetapkan stempel waktu dapat menyebabkan desinkronisasi dari elapsedRealtimeNano jam, karena jam sensor mengalami drift.

data and overlapping fields: Nilai yang diukur oleh sensor. Arti dan unit kolom tersebut khusus untuk setiap jenis sensor jenis. Lihat sensors.h dan definisi berbagai Jenis sensor untuk mengetahui 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 sensornya.

Peristiwa pengosongan selesai 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. Peristiwa ini memiliki kolom berikut:

version: Harus META_DATA_VERSION

type: Harus SENSOR_TYPE_META_DATA

sensor, reserved, and timestamp: Harus 0

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

META_DATA_FLUSH_COMPLETE peristiwa mewakili penyelesaian pengosongan FIFO sensor. Jika meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor harus ditetapkan ke pengendali sensor yang telah dikosongkan. Peristiwa ini dibuat saat dan hanya saat flush dipanggil pada sensor. Lihat bagian tentang fungsi pengosongan untuk mengetahui informasi selengkapnya.