sensors.h dosyasında tanımlanan Sensörler 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: Bir sensörün parametrelerini (ör. örnekleme sıklığı ve maksimum raporlama gecikmesi) belirler.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 karma 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.
activate(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 herkese açık adı, sensor_t yapısının handle alanı tarafından 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 olmayan 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 1 ise ve sensör zaten etkinse bu işlev hiç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.
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);Ö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 kaybolmasına neden olmamalıdır: Bir örnekleme hızından diğerine geçiş, etkinliklerin kaybolmasına 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 bakı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(sensör, örnekleme dönemi)
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.
flush(sensör)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Belirtilen sensör için donanım FIFO'sunun sonuna bir flush complete etkinliği ekleyin ve FIFO'yu temizleyin; bu etkinlikler her zamanki gibi (ör. maksimum raporlama gecikmesi sona ermiş gibi) yayınlanır 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örün FIFO'su yoksa (arabelleğe alma yapılamaz) veya FIFO, çağrı sırasında boşsa flush yine de başarılı olmalı ve söz konusu sensör için bir temizleme tamamlandı 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ı veya hata durumunda 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 açıldığında get_sensors_list çağrılır.
Bir sensör etkinleştirildiğinde, batch işlevi istenen parametrelerle çağrılır ve ardından activate(..., enable=1) çağrılır.
HAL 1_0 sürümünde sıranın tam tersini olduğunu unutmayın: Önce activate, ardından set_delay çağrılır.
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, veri isteğinde bulunmak için poll işlevi tekrar tekrar çağrılır. poll, hiçbir sensör etkinleştirilmemiş olsa bile çağrılabilir.
sensors_module_t
sensors_module_t, sensörler için Android donanım modülünü oluşturmak 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ü), HAL'ın sürüm numarasını tanımlar.
sensor_t
sensor_t, Android sensörünü temsil eder. Ö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ünün açıklamasını, resmi sensör türleri için de Sensör türleri başlıklı makaleyi inceleyin. 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 bir uyanma sensöründe flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP bulunur. İşaretin geçerli HAL sürümünde kullanılmayan bitleri 0 değerine ayarlanmalıdır.
maxRange: Sensörün bildirebileceği maksimum değer (bildirilen değerlerle aynı birimde). Sensör, [-maxRange; maxRange] içinde doygunluk olmadan değerleri bildirebilmelidir. 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.
resolution: 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.
power: Sensörün etkinleştirilmesinin güç maliyeti (miliamper cinsinden).
Bu değer, temel sensörün veri sayfasında bildirilen güç tüketiminden neredeyse her zaman 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şiklik ve özel raporlama modu sensörleri için aksi belirtilmedikçe minDelay 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'ün mikrosaniye cinsinden, sampling_period_ns'ün ise nanosaniye cinsinden ifade edildiğine dikkat edin. Ö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 ilgili 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 sensör etkinleştirilmediği varsayılarak, FIFO'nun sensöre belirli bir hızda kaydedildiğinde ne kadar hızlı dolacağını tahmin etmek için kullanılır. Donanım FIFO'su olmayan sistemlerde fifoMaxEventCount 0 değerini alı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ı ve nabız monitörlerinin SENSOR_PERMISSION_BODY_SENSORS iznine sahip olması zorunludur.
sensors_event_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'teki bazı önemli alanları aşağıda bulabilirsiniz:
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 bildirildiği saat değil, etkinliğin gerçekleştiği saattir (bir adım atıldı veya bir ivmeölçer ölçümü yapıldı). timestamp, elapsedRealtimeNano saatiyle senkronize
edilmelidir ve sürekli sensörler söz konusu olduğunda jitter
küçü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, CDD şartlarını karşılamak için zaman damgası filtreleme bazen 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 aktarımı 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 tutamacına 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üne bakın.