sensors.h dosyasında tanımlanan Sensors HAL arayüzü, Android çerçevesi ile donanıma özgü yazılım arasındaki arayüzü temsil eder. HAL uygulaması, sensors.h dosyasında tanımlanan her işlevi tanımlamalıdır. Ana işlevler şunlardır:
get_sensors_list- Tüm sensörlerin listesini döndürür.activate: Bir sensörü başlatır veya durdurur.batch- Örnekleme sıklığı ve maksimum raporlama gecikmesi gibi bir sensörün parametrelerini ayarlar.setDelay: Yalnızca HAL 1.0 sürümünde kullanılır. Belirli bir sensör için örnekleme sıklığını belirler.flush: Belirtilen sensörün FIFO'sunu temizler ve bu işlem tamamlandığında temizleme tamamlandı etkinliğini bildirir.poll: Mevcut sensör etkinliklerini döndürür.
Uygulama, iş parçacığı açısından güvenli olmalı ve bu işlevlerin farklı iş parçacıklarından çağrılmasına izin vermelidir.
Arayüzde, bu işlevler tarafından kullanılan çeşitli türler de tanımlanır. Ana türler şunlardır:
sensors_module_tsensors_poll_device_tsensor_tsensors_event_t
Bu türlerle ilgili daha fazla bilgi için aşağıdaki bölümlere ve sensors.h dosyasına bakın.
get_sensors_list(list)
int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list);
HAL tarafından uygulanan sensörlerin listesini sağlar. Sensörlerin nasıl tanımlandığıyla ilgili ayrıntılar için sensor_t bölümüne bakın.
Sensörlerin listede göründüğü sıra, sensörlerin uygulamalara bildirileceği sıradır. Genellikle önce temel sensörler, ardından birleşik sensörler görünür.
Birkaç sensör aynı sensör türünü ve uyandırma özelliğini paylaşıyorsa listedeki ilk sensör "varsayılan" sensör olarak adlandırılır. getDefaultSensor(int sensorType, bool wakeUp) tarafından döndürülen değerdir.
Bu işlev, listedeki sensör sayısını döndürür.
etkinleştir(sensör, doğru/yanlış)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Bir sensörü etkinleştirir veya devre dışı bırakır.
sensor_handle, etkinleştirilecek/devre dışı bırakılacak sensörün adı. Bir sensörün tutamaç adı, sensor_t yapısının handle alanıyla tanımlanır.
enabled, sensörü etkinleştirmek için 1'e veya devre dışı bırakmak için 0'a ayarlanır.
Tek seferlik sensörler, bir etkinlik aldıktan sonra kendilerini otomatik olarak devre dışı bırakır ve activate(...,
enabled=0) çağrısı üzerinden devre dışı bırakılmayı kabul etmeleri gerekir.
Uyandırma dışı sensörler, SoC'nin askıya alma moduna geçmesini hiçbir zaman engellemez. Yani HAL, uygulamalar adına kısmi uyanma kilidi tutmaz.
Uyandırma sensörleri, sürekli olarak etkinlik yayınlarken SoC'nin askıya alma moduna girmesini önleyebilir ancak etkinlik gönderilmesi gerekmiyorsa kısmi uyandırma kilidi kaldırılmalıdır.
enabled değeri 1 ise ve sensör zaten etkinleştirilmişse bu işlev herhangi bir işlem yapmaz ve başarılı olur.
enabled 0 ise ve sensör zaten devre dışıysa bu işlev hiçbir işlem yapmaz ve başarılı olur.
Bu işlev, başarılı olduğunda 0, aksi takdirde negatif bir hata numarası döndürür.
toplu işlemler(sensör, işaretler, örnekleme süresi, maksimum rapor gecikmesi)
int (*batch)(
struct sensors_poll_device_1* dev,
int sensor_handle,
int flags,
int64_t sampling_period_ns,
int64_t max_report_latency_ns);
Örnekleme sıklığı ve maksimum rapor gecikmesi dahil olmak üzere bir sensörün parametrelerini ayarlar. Bu işlev, sensör etkinken çağrılabilir. Bu durumda, sensör ölçümlerinin kaybedilmesine neden olmamalıdır: Bir örnekleme hızından diğerine geçiş, etkinliklerin kaybedilmesine neden olamaz. Yüksek maksimum rapor gecikmesinden düşük maksimum rapor gecikmesine geçiş de bu durumu etkilemez.
sensor_handle, yapılandırılacak sensörün adı.
flags şu anda kullanılmamaktadır.
sampling_period_ns, sensörün nanosaniye cinsinden çalışması gereken örnekleme dönemidir. Daha fazla bilgi için sampling_period_ns metriğine göz atın.
max_report_latency_ns, etkinliklerin HAL üzerinden bildirilmeden önce geciktirebileceği maksimum süredir (nanosaniye cinsinden). Daha fazla bilgi için max_report_latency_ns paragrafına bakın.
Bu işlev, başarılı olduğunda 0, aksi takdirde negatif bir hata numarası döndürür.
setDelay(sensor, sampling period)
int (*setDelay)(
struct sensors_poll_device_t *dev,
int sensor_handle,
int64_t sampling_period_ns);
HAL 1.0 sürümünden sonra bu işlevin desteği sonlandırıldı ve işlev hiçbir zaman çağrılmadı.
Bunun yerine, sampling_period_ns parametresini ayarlamak için batch işlevi çağrılır.
HAL 1.0 sürümünde, sampling_period_ns değerini ayarlamak için batch yerine setDelay kullanılıyordu.
sifon(sensör)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Belirtilen sensör için donanım FIFO'nun sonuna bir tamamen boşaltma etkinliği ekler ve FIFO'yu boşaltır.Bu etkinlikler her zamanki gibi sunulur (ör. maksimum raporlama gecikmesinin süresi dolmuş gibi) ve FIFO'dan kaldırılır.
Boşaltma işlemi eşzamansız olarak gerçekleşir (yani bu işlev hemen döndürülmelidir). Uygulamada birkaç sensör için tek bir FIFO kullanılıyorsa bu FIFO temizlenir ve temizleme tamamlandı etkinliği yalnızca belirtilen sensör için eklenir.
Belirtilen sensörde FIFO yoksa (arabelleğe alma mümkün değilse) veya çağrı sırasında FIFO boşsa
flush yine de başarılı olmalı ve söz konusu sensör için
tam temizlik etkinliği göndermelidir. Bu, tek seferlik sensörler dışındaki tüm sensörler için geçerlidir.
flush çağrıldığında, söz konusu sensör için FIFO'da zaten bir temizleme etkinliği olsa bile ek bir etkinlik oluşturulup FIFO'nun sonuna eklenmeli ve FIFO temizlenmelidir. flush çağrısı sayısı, oluşturulan temizleme tamamlandı etkinliklerinin sayısına eşit olmalıdır.
flush, tek seferlik sensörler için geçerli değildir; sensor_handle tek seferlik bir sensörü ifade ediyorsa flush, -EINVAL döndürmeli ve eksiksiz meta verileri temizleme etkinliği oluşturmamalıdır.
Bu işlev, başarılı olduğunda 0, belirtilen sensör tek seferlik bir sensörse veya etkinleştirilmediyse -EINVAL, aksi takdirde negatif bir hata numarası döndürür.
poll()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count);
data bağımsız değişkenini doldurarak bir sensör verisi dizisi döndürür. Bu işlev, etkinlikler kullanıma sunulana kadar engellemelidir. Başarılı bir işlemde okunan etkinliklerin sayısını, hata durumunda ise negatif bir hata numarasını döndürür.
data içinde döndürülen etkinlik sayısı, count bağımsız değişkeninden az veya bu değere eşit olmalıdır. Bu işlev hiçbir zaman 0 (etkinlik yok) değerini döndürmez.
Arama sırası
Cihaz başlatıldığında get_sensors_list çağrılır.
Bir sensör etkinleştirildiğinde batch işlevi, istenen parametrelerle ve ardından activate(..., enable=1) ile çağrılır.
HAL sürüm 1_0'da sıranın tam tersi olduğunu unutmayın: Önce activate, ardından set_delay çağrıldı.
Bir sensör etkinken istenen özellikleri değiştiğinde batch işlevi çağrılır.
flush, etkinleştirilmemiş sensörlerde bile (bu durumda -EINVAL döndürmelidir) dilediğiniz zaman çağrılabilir.
Bir sensör devre dışı bırakıldığında activate(..., enable=0) çağrılır.
Bu çağrılara paralel olarak poll işlevi, veri istemek için tekrar tekrar çağrılır. poll, hiçbir sensör etkin olmadığında bile çağrılabilir.
sensors_module_t
sensors_module_t, sensörler için Android donanım modülünü oluşturmak için kullanılan türdür. HAL'ın uygulanması, get_sensors_list işlevini göstermek için bu türde bir HAL_MODULE_INFO_SYM nesnesi tanımlamalıdır. Daha fazla bilgi için sensors.h dosyasında sensors_module_t ve hw_module_t tanımına bakın.
sensors_poll_device_t / sensors_poll_device_1_t
sensors_poll_device_1_t, yukarıda tanımlanan yöntemlerin geri kalanını içerir:
activate, batch, flush ve
poll. common alanı (hw_device_t türünde) HAL'nin sürüm numarasını tanımlar.
sensor_t
sensor_t, Android sensörünü temsil eder. Bunun önemli alanlarından bazıları şunlardır:
ad: Sensörü temsil eden, kullanıcı tarafından görülebilen bir dize. Bu dize genellikle temel sensörün parça adını, sensörün türünü ve uyandırma sensörü olup olmadığını içerir. Örneğin, "LIS2HH12 İvme Ölçer", "MAX21000 Kalibre Edilmemiş Jiroskop", "BMP280 Uyandırma Barometresi", "MPU6515 Oyun Dönme Vektörü"
handle: Sensöre kaydolurken veya sensörden etkinlik oluştururken sensörü belirtmek için kullanılan tam sayı.
type: Sensörün türü. Daha fazla bilgi için Android sensörleri nedir? başlıklı makalede sensör türüne dair açıklamaya, resmi sensör türleri için de Sensör türleri bölümüne bakın. Resmi olmayan sensör türleri için type, SENSOR_TYPE_DEVICE_PRIVATE_BASE ile başlamalıdır
stringType: Sensörün dize olarak türü. Sensörün resmi bir türü varsa SENSOR_STRING_TYPE_* olarak ayarlayın. Sensör üreticiye özgü bir türe sahipse stringType, üreticinin ters alan adıyla başlamalıdır. Örneğin, Hayali Şirket'teki Cool-product ekibi tarafından tanımlanan bir sensör (ör. tek boynuzlu at algılayıcı) stringType=”com.fictional_company.cool_product.unicorn_detector” kullanabilir.
stringType, resmi olmayan sensör türlerini benzersiz şekilde tanımlamak için kullanılır. Türler ve dize türleri hakkında daha fazla bilgi için sensors.h dosyasını inceleyin.
requiredPermission: Uygulamaların sensörü görmek, kaydetmek ve verilerini almak için sahip olması gereken izni temsil eden bir dize. Boş bir dize, uygulamaların bu sensöre erişmek için herhangi bir izne ihtiyaç duymadığı anlamına gelir. Nabız monitörü gibi bazı sensör türlerinde zorunlu bir requiredPermission bulunur. Hassas kullanıcı bilgileri (ör. nabız) sağlayan tüm sensörler bir izinle korunmalıdır.
flags: Bu sensörün işaretleri. Sensörün raporlama modunu ve sensörün uyanma sensörü olup olmadığını tanımlar. Örneğin, tek seferlik uyandırma sensöründe flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP bulunur. Geçerli HAL sürümünde kullanılmayan işaretin bit değerleri 0'a eşit olmalıdır.
maxRange: Sensörün bildirebileceği maksimum değer (bildirilen değerlerle aynı birimde). Sensör, [-maxRange; maxRange] içinde eşleşmeden değerleri raporlayabilmelidir. Bu, genel anlamda sensörün toplam aralığının 2*maxRange olduğunu gösterir. Sensör birkaç eksen üzerinde değer bildirdiğinde aralık her eksen için geçerli olur. Örneğin, "+/- 2g" ivme ölçer maxRange = 2*9.81 = 2g değerini bildirir.
Çözünürlük: Sensörün ölçebileceği en küçük değer farkı.
Genellikle maxRange ve ölçümdeki bit sayısına göre hesaplanır.
güç: Sensörü etkinleştirmenin güç maliyeti (milisaniye cinsinden).
Bu değer, neredeyse her zaman altta yatan sensörün veri sayfasında bildirilen güç tüketiminden daha fazladır. Daha fazla bilgi için Temel sensörler != fiziksel sensörler bölümüne, bir sensörün güç tüketiminin nasıl ölçüleceği hakkında ayrıntılı bilgi için de Güç ölçüm süreci bölümüne göz atın.
Sensörün güç tüketimi, cihazın hareket edip etmediğine bağlıysa power alanında hareket halindeyken güç tüketimi raporlanır.
minDelay: Sürekli sensörler için, sensörün desteklediği en hızlı hıza karşılık gelen mikrosaniye cinsinden örnekleme dönemi. Bu değerin nasıl kullanıldığıyla ilgili ayrıntılar için sampling_period_ns bölümüne bakın. minDelay'ün mikrosaniye cinsinden, sampling_period_ns'ün ise nanosaniye cinsinden ifade edildiğine dikkat edin. Değişim sırasında ve özel raporlama modu sensörleri için aksi belirtilmedikçe minDelay değeri 0 olmalıdır. Tek seferlik sensörler için bu değer -1 olmalıdır.
maxDelay: Sürekli ve değişiklikte olan sensörler için, sensörün desteklediği en yavaş hıza karşılık gelen mikrosaniye cinsinden örnekleme dönemi. Bu değerin nasıl kullanıldığıyla ilgili ayrıntılar için sampling_period_ns bölümüne bakın. maxDelay metriğinin mikrosaniye cinsinden, sampling_period_ns değerinin ise nanosaniye cinsinden ifade edildiğini unutmayın. Özel ve tek seferlik sensörler için maxDelay 0 olmalıdır.
fifoReservedEventCount: Donanım FIFO'sunda bu sensör için ayrılan etkinliklerin sayısı. Bu sensör için özel bir FIFO varsa fifoReservedEventCount, bu özel FIFO'nun boyutudur. FIFO diğer sensörlerle paylaşılıyorsa fifoReservedEventCount, FIFO'nun söz konusu sensör için ayrılmış kısmının boyutudur. Çoğu paylaşılan FIFO sisteminde ve donanım FIFO'su olmayan sistemlerde bu değer 0'dır.
fifoMaxEventCount: Bu sensör için FIFO'larda depolanabilecek maksimum etkinlik sayısı. Bu değer, her zaman fifoReservedEventCount değerinden büyük veya eşit olmalıdır. Bu değer, başka hiçbir sensörün etkinleştirilmediğini varsayarsak bu değer, sensöre belirli bir hızda kaydolurken FIFO'nun ne kadar hızlı dolacağını tahmin etmek için kullanılır. Donanım FIFO'su olmayan sistemlerde fifoMaxEventCount 0'dır. Daha fazla bilgi için Gruplandırma bölümüne bakın.
Resmi bir sensör türüne sahip sensörlerde, bazı alanların üzerine çerçeve tarafından yazılır. Örneğin, ivme ölçer sensörlerinin sürekli raporlama moduna sahip olması, nabız monitörlerinin ise SENSOR_PERMISSION_BODY_SENSORS iznine sahip olması zorunludur.
sensörler_etkinlik_t
Android sensörleri tarafından oluşturulan ve poll işlevi aracılığıyla raporlanan sensör etkinlikleri type sensors_event_t türündedir. sensors_event_t ile ilgili bazı önemli alanlar şunlardır:
version: sizeof(struct sensors_event_t) olmalıdır
sensor: sensor_t.handle tarafından tanımlandığı üzere, etkinliği oluşturan sensörün herkese açık kullanıcı adı.
type: Etkinliği oluşturan sensörün sensor_t.type tarafından tanımlanan sensör türü.
zaman damgası: Etkinliğin nanosaniye cinsinden zaman damgası. Bu, etkinliğin raporlandığı zamanı değil, etkinliğin gerçekleştiği zamandır (bir adım atıldı veya ivme ölçer ölçümü yapıldı). timestamp, elapsedRealtimeNano saatiyle senkronize edilmelidir. Sürekli sensörler söz konusu olduğunda ise titreşim seviyesi düşük olmalıdır. Zaman damgaları ayarlamak için yalnızca SoC kesinti süresinin kullanılması çok yüksek titreşime neden olduğundan ve zaman damgaları ayarlamak için yalnızca sensör çipi süresinin kullanılması, sensör saati kaydığı için elapsedRealtimeNano saatiyle senkronizasyonun bozulmasına neden olabileceğinden, zaman damgası filtreleme bazen CDD şartlarını karşılamak için gereklidir.
veriler ve örtüşen alanlar: Sensör tarafından ölçülen değerler. Bu alanların anlamları ve birimleri her sensör türüne özeldir. Veri alanlarının açıklaması için sensors.h dosyasını ve farklı sensör türlerinin tanımını inceleyin. Bazı sensörlerde, ölçümlerin doğruluğu da status alanı aracılığıyla verilerin bir parçası olarak raporlanır. Bu alan yalnızca belirli sensör türleri için aktarılır ve SDK katmanında doğruluk değeri olarak görünür. Bu sensörler için durum alanının ayarlanması gerektiği, sensör türü tanımında belirtilir.
Meta veri temizleme tamamlandı etkinlikleri
Meta veri etkinlikleri, normal sensör etkinlikleriyle aynı türdedir:
sensors_event_meta_data_t = sensors_event_t. Bu etkinlikler, anket aracılığıyla diğer sensör etkinlikleriyle birlikte döndürülür. Bu alanlar aşağıdakileri içerir:
version: META_DATA_VERSION olmalıdır
type: SENSOR_TYPE_META_DATA olmalıdır
sensor, reserved ve timestamp: 0 olmalıdır.
meta_data.what: Bu etkinliğin meta veri türünü içerir. Şu anda tek geçerli meta veri türü META_DATA_FLUSH_COMPLETE'tür.
META_DATA_FLUSH_COMPLETE etkinlikleri, bir sensör FIFO'sunun temizlenmesinin tamamlandığını temsil eder. meta_data.what=META_DATA_FLUSH_COMPLETE olduğunda meta_data.sensor, temizlenen sensörün tutma yerine ayarlanmalıdır. Yalnızca bir sensörde flush çağrıldığında oluşturulurlar. Daha fazla bilgi için flush işlevi bölümünü inceleyin.