Sensörler HAL 1.0

sensors.h içinde tanımlanan Sensors HAL arayüzü, Android framework ile donanıma özgü yazılım arasındaki arayüzü temsil eder. Bir 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: 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ün örnekleme sıklığını ayarlar.
• flush: Belirtilen sensörün FIFO'sunu temizler ve bu işlem tamamlandığında temizleme tamamlandı etkinliğini bildirir.
• poll - Kullanılabilir 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üz, bu işlevler tarafından kullanılan çeşitli türleri de tanımlar. Başlıca türler şunlardır:

• sensors_module_t
• sensors_poll_device_t
• sensor_t
• sensors_event_t

Aşağıdaki bölümlere ek olarak, bu türler hakkında daha fazla bilgi için 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ünme sırası, sensörlerin uygulamalara raporlanma sırasıdır. Genellikle önce temel sensörler, ardından bileşik sensörler gösterilir.

Aynı sensör türünü ve uyandırma özelliğini paylaşan birden fazla sensör varsa listedeki ilk sensöre "varsayılan" sensör denir. Bu, 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(sensor, true/false)

int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int
  enabled);

Sensörü etkinleştirir veya devre dışı bırakır.

sensor_handle, etkinleştirilecek/devre dışı bırakılacak sensörün tutma yeridir. Bir sensörün işlevi, sensor_t yapısının handle alanı tarafından tanımlanır.

Sensörü etkinleştirmek için enabled değeri 1'e, devre dışı bırakmak için 0'a ayarlanır.

Tek seferlik sensörler, bir etkinlik aldığında kendilerini otomatik olarak devre dışı bırakır ve activate(..., enabled=0) çağrısı aracılığıyla devre dışı bırakılmayı kabul etmeye devam etmelidir.

Uyandırma sensörleri olmayanlar, hiçbir zaman SoC'nin askıya alma moduna girmesini engellemez. Yani HAL, uygulamalar adına kısmi uyandırma kilidi tutmaz.

Etkinlikleri sürekli olarak iletirken uyandırma sensörleri, SoC'nin askıya alma moduna girmesini engelleyebilir. Ancak herhangi bir etkinliğin iletilmesi gerekmiyorsa kısmi uyandırma kilidi serbest bırakılmalıdır.

enabled 1 ise ve sensör zaten etkinleştirilmişse bu işlev işlem yapmaz ve başarılı olur.

enabled değeri 0 ise ve sensör zaten devre dışı bırakılmışsa 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 sayısı 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 etkinleştirilmişken çağrılabilir. Bu durumda, herhangi bir sensör ölçümünün kaybolmasına neden olmamalıdır: Bir örnekleme hızından diğerine geçiş, olayların kaybolmasına neden olamaz. Ayrıca, yüksek bir maksimum rapor gecikmesinden düşük bir maksimum rapor gecikmesine geçiş de olayların kaybolmasına neden olamaz.

sensor_handle, yapılandırılacak sensörün tutma yeridir.

flags şu anda kullanılmamaktadır.

sampling_period_ns, sensörün çalışması gereken örnekleme süresidir (nanosaniye cinsinden). Daha fazla bilgi için sampling_period_ns sayfasına bakın.

max_report_latency_ns, etkinliklerin HAL üzerinden raporlanmadan önce geciktirilebileceğ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 sayısı 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 sürümü 1.0'dan sonra bu işlev kullanımdan kaldırıldı ve hiçbir zaman çağrılmıyor. Bunun yerine, batch işlevi çağrılarak sampling_period_ns parametresi ayarlanır.

HAL 1.0 sürümünde, sampling_period_ns değerini ayarlamak için toplu işlem yerine setDelay kullanılıyordu.

flush(sensor)

int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

Belirtilen sensör için donanım FIFO'sunun sonuna bir flush complete event ekler ve FIFO'yu temizler; bu etkinlikler her zamanki gibi (ör. maksimum raporlama gecikmesi süresi dolmuş gibi) teslim edilir ve FIFO'dan kaldırılır.

Temizleme 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 boşaltılır ve boşaltma 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 bu sensör için 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, bir boşaltma etkinliği söz konusu sensör için FIFO'da olsa bile ek bir etkinlik oluşturulup FIFO'nun sonuna eklenmeli ve FIFO boşaltılmalıdır. flush çağrılarının 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 değerini döndürmeli ve herhangi bir temizleme tamamlandı meta veri etkinliği oluşturmamalıdır.

Bu işlev, başarılı olursa 0, belirtilen sensör tek seferlik bir sensörse veya etkinleştirilmemişse -EINVAL, aksi takdirde negatif bir hata sayısı 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 sensör verileri dizisini döndürür. Bu işlev, etkinlikler kullanılabilir olana kadar engellemelidir. İşlem başarılı olursa okunan etkinliklerin sayısını, hata durumunda ise negatif bir hata numarası döndürür.

data içinde döndürülen etkinlik sayısı, count bağımsız değişkeninden küçük veya bu değere eşit olmalıdır. Bu işlev hiçbir zaman 0 (etkinlik yok) değerini döndürmez.

Aramaların sırası

Cihaz başlatıldığında get_sensors_list çağrılır.

Bir sensör etkinleştirildiğinde, istenen parametrelerle batch işlevi çağrılır ve ardından activate(..., enable=1) işlevi çağrılır.

HAL sürüm 1_0'da sıranın ters olduğunu unutmayın: activate önce, ardından set_delay çağrılıyordu.

Bir sensör etkin durumdayken istenen özellikleri değiştiğinde batch işlevi çağrılır.

flush, etkinleştirilmemiş sensörlerde bile (bu durumda -EINVAL döndürmesi gerekir) herhangi bir zamanda çağrılabilir.

Bir sensör devre dışı bırakıldığında activate(..., enable=0) çağrılır.

Bu çağrılarla paralel olarak, veri istemek için poll işlevi tekrar tekrar çağrılır. poll, hiçbir sensör etkin olmasa bile aranabilir.

sensors_module_t

sensors_module_t, sensörler için Android donanım modülünü oluşturmak üzere kullanılan türdür. HAL'nin uygulanması, get_sensors_list işlevini kullanıma sunmak için bu türde bir nesne HAL_MODULE_INFO_SYM tanımlamalıdır. Daha fazla bilgi için sensors.h dosyasındaki sensors_module_t tanımına 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. Önemli alanlarından bazıları şunlardır:

name: 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 Accelerometer", "MAX21000 Uncalibrated Gyroscope", "BMP280 Wake-up Barometer", "MPU6515 Game Rotation Vector"

handle: Sensöre kaydolurken veya sensörden etkinlik oluştururken sensörü ifade etmek için kullanılan tam sayı.

type: Sensörün türü. Daha fazla bilgi için Android sensörleri nelerdir? başlıklı makalede sensör türüyle ilgili açıklamayı, resmi sensör türleri için ise 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 türü dize olarak. Sensörün resmi bir türü olduğunda SENSOR_STRING_TYPE_* olarak ayarlayın. Sensörün üreticiye özel bir türü olduğunda stringType, üreticinin ters alan adıyla başlamalıdır. Örneğin, Fictional-Company'deki Cool-product ekibi tarafından tanımlanan bir sensör (örneğin, tek boynuzlu at dedektörü) 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ına bakın.

requiredPermission: Uygulamaların sensörü görebilmesi, sensöre kaydolabilmesi ve sensör verilerini alabilmesi için sahip olması gereken izni temsil eden bir dize. Boş bir dize, uygulamaların bu sensöre erişmek için herhangi bir izin gerektirmediği anlamına gelir. Nabız takip cihazı gibi bazı sensör türlerinde zorunlu requiredPermission bulunur. Hassas kullanıcı bilgileri (ör. kalp atış hızı) sağlayan tüm sensörler izinle korunmalıdır.

flags: Bu sensörün raporlama modunu ve sensörün uyandırma sensörü olup olmadığını tanımlayan sensör işaretleri. Örneğin, tek seferlik uyandırma sensöründe flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP bulunur. Mevcut HAL sürümünde kullanılmayan işaret bitleri 0'a eşit bırakılmalıdır.

maxRange: Sensörün bildirebileceği maksimum değer. Bildirilen değerlerle aynı birimdedir. Sensör, [-maxRange; maxRange] içinde doygunluğa ulaşmadan değerleri bildirebilmelidir. Bu, sensörün genel anlamdaki toplam aralığının 2*maxRange olduğu anlamına gelir. Sensörün birkaç eksende değer bildirmesi durumunda aralık her eksen için geçerlidir. Ö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.

power: Sensörün etkinleştirilmesinin güç maliyeti (miliamper cinsinden). Bu değer, neredeyse her zaman temel 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ünü, sensörün güç tüketimini ölçme hakkında bilgi için Güç ölçümü süreci bölümünü inceleyin. Sensörün güç tüketimi cihazın hareket edip etmemesine bağlıysa hareket halindeyken güç tüketimi power alanında bildirilir.

minDelay: Sürekli sensörler için, sensörün desteklediği en hızlı hıza karşılık gelen örnekleme süresi (mikrosaniye cinsinden). Bu değerin nasıl kullanıldığıyla ilgili ayrıntılar için sampling_period_ns etkinliğine bakın. minDelay değerinin mikrosaniye, sampling_period_ns değerinin ise nanosaniye cinsinden ifade edildiğini unutmayın. Değişiklik üzerine ve özel raporlama modu sensörleri için aksi belirtilmedikçe minDelay 0 olmalıdır. Tek seferlik sensörler için -1 olmalıdır.

maxDelay: Sürekli ve değişiklik üzerine çalışan sensörler için, sensörün desteklediği en yavaş hıza karşılık gelen örnekleme süresi (mikrosaniye cinsinden). Bu değerin nasıl kullanıldığıyla ilgili ayrıntılar için sampling_period_ns etkinliğine bakın. maxDelay değerinin mikrosaniye, sampling_period_ns değerinin ise nanosaniye cinsinden ifade edildiğini unutmayın. Özel ve tek seferlik sensörler için maxDelay değeri 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ılan 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ün FIFO'larında depolanabilecek maksimum etkinlik sayısı. Bu değer her zaman fifoReservedEventCount değerinden büyük veya bu değere eşittir. Bu değer, başka sensörlerin etkinleştirilmediği varsayılarak belirli bir hızda sensöre kaydolurken FIFO'nun ne kadar hızlı dolacağını tahmin etmek için kullanılır. Donanım FIFO'sunun olmadığı sistemlerde fifoMaxEventCount değeri 0'dır. Daha fazla bilgi için Toplu işleme bölümüne bakın.

Resmi 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ı zorunlu tutulur ve nabız ölçerlerin SENSOR_PERMISSION_BODY_SENSORS izniyle korunması zorunlu tutulur.

sensors_event_t

Android sensörleri tarafından oluşturulan ve poll işlevi aracılığıyla bildirilen sensör etkinlikleri type sensors_event_t türündedir. sensors_event_t'in bazı önemli alanları şunlardır:

version: sizeof(struct sensors_event_t) olmalıdır.

sensor: Etkinliği oluşturan sensörün, sensor_t.handle tarafından tanımlanan tutma yeri.

type: Etkinliği oluşturan sensörün, sensor_t.type tarafından tanımlanan sensör türü.

timestamp: Etkinliğin nanosaniye cinsinden zaman damgası. Bu, etkinliğin bildirildiği zaman değil, etkinliğin gerçekleştiği (bir adım atıldığı veya ivmeölçer ölçümü yapıldığı) zamandır. timestamp, elapsedRealtimeNano saatiyle senkronize edilmelidir ve sürekli sensörler söz konusu olduğunda titreşim az olmalıdır. Yalnızca SoC kesme süresini kullanarak zaman damgalarını ayarlamak çok yüksek titreşime neden olduğundan ve yalnızca sensör çip süresini kullanarak zaman damgalarını ayarlamak, sensör saati kaydığından elapsedRealtimeNano saatinden senkronizasyonun bozulmasına neden olabileceğinden, bazen CDD şartlarını karşılamak için zaman damgası filtreleme gerekir.

Veriler ve çakışan alanlar: Sensör tarafından ölçülen değerler. Bu alanların anlamı ve birimleri her sensör türüne özeldir. Veri alanlarının açıklaması için sensors.h ve farklı Sensör türlerinin tanımına bakın. Bazı sensörler için okumaların doğruluğu da status alanı aracılığıyla verilerin bir parçası olarak bildirilir. Bu alan yalnızca belirli sensör türleri için kanalize edilir ve SDK katmanında bir 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 boşaltma tamamlandı etkinlikleri

Meta veri etkinlikleri, normal sensör etkinlikleriyle aynı türe sahiptir: sensors_event_meta_data_t = sensors_event_t. Bu etkinlikler, diğer sensör etkinlikleriyle birlikte yoklama yoluyla döndürülür. Bu alanlar şunlardır:

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 bir geçerli meta veri türü vardır: META_DATA_FLUSH_COMPLETE.

META_DATA_FLUSH_COMPLETE etkinlikleri, sensör FIFO'sunun temizlenmesinin tamamlanmasını temsil eder. meta_data.what=META_DATA_FLUSH_COMPLETE olduğunda meta_data.sensor, temizlenmiş sensörün tutma yerine ayarlanmalıdır. Yalnızca bir sensörde flush çağrıldığında oluşturulur. Daha fazla bilgi için flush işleviyle ilgili bölüme bakın.