sensors.h içinde tanımlanan Sensörler 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_tsensors_poll_device_tsensor_tsensors_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 da bileşik sensörler görünür.
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. 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 tanıtıcısı, 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, etkinlik aldıklarında kendilerini otomatik olarak devre dışı bırakır.
Ayrıca, activate(...,
enabled=0) çağrısı yapılarak devre dışı bırakılmayı kabul etmeleri gerekir.
Uyandırma dışı sensörler, SoC'nin askıya alma moduna girmesini hiçbir zaman 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 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, sensör ölçümlerinin kaybolmasına neden olmamalıdır: Bir örnekleme hızından diğerine geçiş, etkinliklerin kaybolmasına neden olamaz. Ayrıca, yüksek bir maksimum rapor gecikmesinden düşük bir maksimum rapor gecikmesine geçiş de etkinliklerin 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 gecikme 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 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 bu 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, ilgili sensör için FIFO'da bir boşaltma etkinliği 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 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 sensör verileri dizisini döndürür. Bu işlev, etkinlikler kullanılabilir olana kadar engellemelidir. İşlem başarılı olursa okunan etkinlik 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.
Çağrı 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 özgü 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 bir 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ünün flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP değeri olur. 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 etkinlik 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ı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 kılınır ve nabız ölçerlerin SENSOR_PERMISSION_BODY_SENSORS
izniyle korunması zorunlu kılınır.
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 zamandır (bir adım atıldı veya ivmeölçer ölçümü yapıldı). timestamp, elapsedRealtimeNano saatiyle senkronize edilmelidir ve sürekli sensörler söz konusu olduğunda titreşim az olmalıdır. Zaman damgalarını ayarlamak için yalnızca SoC kesme süresinin kullanılması çok yüksek titreşime neden olduğundan ve zaman damgalarını ayarlamak için yalnızca sensör çipi süresinin kullanılması, 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 iletilir 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 temizleme tamamlandı etkinlikleri
Meta veri etkinlikleri, normal sensör etkinlikleriyle aynı türe sahiptir:
sensors_event_meta_data_t = sensors_event_t. Yoklama yoluyla diğer sensör etkinlikleriyle birlikte 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.