Sensörler Donanım Soyutlama Katmanı (HAL), Android sensör çerçevesi ile cihazın sensörleri (ör. ivme ölçer veya jiroskop) arasındaki arayüzdür. Sensörler HAL, çerçevenin sensörleri kontrol etmesine izin vermek için uygulanması gereken işlevleri tanımlar.
Sensors HAL 2.0, yeni ve yükseltilmiş cihazlarda Android 10 ve sonraki sürümlerde kullanılabilir. Sensors HAL 2.0, Sensors HAL 1.0'ı temel alır ancak geriye dönük uyumluluğu engelleyen birkaç önemli farkı vardır. Sensörler HAL 2.0, sensör etkinliklerini HAL'den Android sensör çerçevesine göndermek için Hızlı Mesaj Kuyrukları'nı (FMQ) kullanır.
Sensörler HAL 2.1, yeni ve yükseltilmiş cihazlarda Android 11 ve sonraki sürümlerde kullanılabilir. Sensors HAL 2.1, Sensors HAL 2.0'ın bir yinelemesidir. Bu yineleme, HINGE_ANGLE sensör türünü kullanıma sunar ve çeşitli yöntemleri HINGE_ANGLE türünü kabul edecek şekilde günceller.
HAL 2.1 arayüzü
Sensors HAL 2.1 ile ilgili dokümanların ana kaynağı, hardware/interfaces/sensors/2.1/ISensors.hal adresindeki HAL tanımıdır.
Bu sayfa ile ISensors.hal arasında şartlarla ilgili bir çelişki varsa ISensors.hal'daki şartı kullanın.
HAL 2.0 arayüzü
Sensors HAL 2.0 ile ilgili belgelerin ana kaynağı, hardware/interfaces/sensors/2.0/ISensors.hal adresindeki HAL tanımıdır.
Bu sayfa ile ISensors.hal arasında şartlarla ilgili bir çelişki varsa ISensors.hal'daki şartı kullanın.
Sensörler HAL 2.0 ve HAL 2.1'i uygulama
Sensors HAL 2.0 veya 2.1'i uygulamak için bir nesne, ISensors
arayüzünü genişletmeli ve 2.0/ISensors.hal
veya
2.1/ISensors.hal içinde tanımlanan tüm işlevleri uygulamalıdır.
HAL'yi başlatma
Sensörler HAL'inin kullanılabilmesi için önce Android sensör çerçevesi tarafından başlatılması gerekir. Çerçeve, HAL 2.0 için initialize() işlevini, HAL 2.1 için ise initialize_2_1() işlevini çağırarak Sensors HAL'e üç parametre sağlar: iki FMQ tanımlayıcısı ve bir ISensorsCallback nesnesine yönelik işaretçi.
HAL, sensör etkinliklerini çerçeveye yazmak için kullanılan Event FMQ'yu oluşturmak üzere ilk tanımlayıcıyı kullanır. HAL, WAKE_UP sensör etkinlikleri için uyandırma kilidini bıraktığında senkronizasyon için kullanılan Wake
Lock FMQ'yu oluşturmak üzere ikinci tanımlayıcıyı kullanır. HAL, gerekli geri çağırma işlevlerinin çağrılabilmesi için ISensorsCallback nesnesinin işaretçisini kaydetmelidir.
Sensors HAL başlatılırken ilk çağrılan işlev initialize() veya initialize_2_1() işlevi olmalıdır.
Kullanılabilir sensörleri kullanıma sunma
Cihazdaki tüm statik sensörlerin listesini almak için HAL 2.0'da getSensorsList() işlevini, HAL 2.1'de ise getSensorsList_2_1() işlevini kullanın. Bu işlev, her biri tutma yeriyle benzersiz şekilde tanımlanan bir sensör listesi döndürür. Belirli bir sensörün tutma yeri, Sensörler HAL'ı barındıran işlem yeniden başlatıldığında değişmemelidir. Herkese açık kullanıcı adları, cihaz yeniden başlatıldığında ve sistem sunucusu yeniden başlatıldığında değişebilir.
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 ve getDefaultSensor(int sensorType, bool wakeUp) işlevini kullanan uygulamalara döndürülür.
Sensör listesinin kararlılığı
Sensors HAL yeniden başlatıldıktan sonra, getSensorsList() veya getSensorsList_2_1() tarafından döndürülen veriler, yeniden başlatmadan önce alınan sensör listesine kıyasla önemli bir değişikliği gösteriyorsa çerçeve, Android çalışma zamanının yeniden başlatılmasını tetikler. Sensör listesinde önemli değişiklikler arasında belirli bir tutamağa sahip sensörün eksik olması veya özelliklerinin değişmesi ya da yeni sensörlerin kullanıma sunulması yer alır. Android çalışma zamanını yeniden başlatmak kullanıcı deneyimini olumsuz etkilese de bu işlem gereklidir. Bunun nedeni, Android çerçevesinin artık Android API sözleşmesini karşılayamamasıdır. Bu sözleşmeye göre statik (dinamik olmayan) sensörler, bir uygulamanın kullanım ömrü boyunca değişmez. Bu durum, çerçevenin uygulamalar tarafından yapılan etkin sensör isteklerini yeniden oluşturmasını da engelleyebilir. Bu nedenle, HAL tedarikçilerinin gereksiz sensör listesi değişikliklerini önlemesi önerilir.
Kararlı sensör tutma yerleri sağlamak için HAL, cihazdaki belirli bir fiziksel sensörü tutma yerine deterministik olarak eşlemelidir. Sensors HAL arayüzü tarafından belirli bir uygulama zorunlu kılınmasa da geliştiriciler bu şartı karşılamak için çeşitli seçeneklerden yararlanabilir.
Örneğin, sensör listesi her sensörün sabit özelliklerinin (ör. satıcı, model ve sensör türü) bir kombinasyonu kullanılarak sıralanabilir. Başka bir seçenek ise cihazın statik sensör setinin donanımda sabit olmasından yararlanır. Bu nedenle, HAL'ın getSensorsList() veya getSensorsList_2_1()'dan dönmeden önce beklenen tüm sensörlerin başlatma işlemini tamamladığını bilmesi gerekir. Beklenen sensörlerin bu listesi, HAL ikili dosyasına derlenebilir veya dosya sistemindeki bir yapılandırma dosyasında saklanabilir. Ayrıca, görünme sırası, kararlı tutma yerleri elde etmek için kullanılabilir. En iyi çözüm, HAL'nizin belirli uygulama ayrıntılarına bağlı olsa da temel şart, sensör tutamaçlarının HAL yeniden başlatıldığında değişmemesidir.
Sensörleri yapılandırma
Bir sensör etkinleştirilmeden önce batch() işlevi kullanılarak örnekleme dönemi ve maksimum raporlama gecikmesiyle yapılandırılmalıdır.
Bir sensör, batch() kullanılarak sensör verileri kaybolmadan herhangi bir zamanda yeniden yapılandırılabilmelidir.
Örnekleme dönemi
Örnekleme dönemi, yapılandırılan sensör türüne bağlı olarak farklı bir anlam ifade eder:
- Sürekli: Sensör etkinlikleri sürekli bir hızda oluşturulur.
- Değişiklik üzerine: Etkinlikler, örnekleme döneminden daha hızlı oluşturulmaz ve ölçülen değer değişmezse örnekleme döneminden daha yavaş bir hızda oluşturulabilir.
- Tek görevli: Örnekleme dönemi yoksayılır.
- Özel: Daha fazla bilgi için Sensör türleri başlıklı makaleyi inceleyin.
Örnekleme dönemi ile sensörün raporlama modları arasındaki etkileşim hakkında bilgi edinmek için Raporlama Modları başlıklı makaleyi inceleyin.
Maksimum raporlama gecikmesi
Maksimum raporlama gecikmesi, SoC uyanıkken HAL aracılığıyla Event FMQ'ya yazılmadan önce etkinliklerin gecikebileceği ve donanım FIFO'sunda depolanabileceği maksimum süreyi nanosaniye cinsinden belirler.
Sıfır değeri, etkinliklerin ölçülür ölçülmez raporlanması gerektiğini belirtir. Bu durumda, FIFO tamamen atlanır veya sensörden bir etkinlik FIFO'da yer alır almaz FIFO boşaltılır.
Örneğin, maksimum raporlama gecikmesi sıfır olan ve 50 Hz'de etkinleştirilen bir ivmeölçer, SoC uyanıkken saniyede 50 kez kesintiyi tetikler.
Maksimum raporlama gecikmesi sıfırdan büyük olduğunda, sensör etkinliklerinin algılanır algılanmaz raporlanması gerekmez. Etkinlikler, maksimum raporlama gecikmesinden daha fazla gecikmemek koşuluyla geçici olarak donanım FIFO'sunda depolanabilir ve toplu olarak raporlanabilir. Önceki toplu işlemden bu yana tüm etkinlikler kaydedilir ve tek seferde döndürülür. Bu, SoC'ye gönderilen kesme sayısını azaltır ve sensör veri yakalayıp toplarken SoC'nin daha düşük güç moduna geçmesine olanak tanır.
Her etkinliğin kendisiyle ilişkilendirilmiş bir zaman damgası vardır. Bir etkinliğin raporlandığı zamanın geciktirilmesi, etkinliğin zaman damgasını etkilememelidir. Zaman damgası doğru olmalı ve etkinliğin bildirildiği zamana değil, fiziksel olarak gerçekleştiği zamana karşılık gelmelidir.
Maksimum raporlama gecikmesi sıfır olmayan sensör etkinliklerinin raporlanmasıyla ilgili ek bilgi ve koşullar için Toplu İşleme bölümüne bakın.
Sensörleri etkinleştirme
Çerçeve, activate() işlevini kullanarak sensörleri etkinleştirir ve devre dışı bırakır.
Çerçeve, bir sensörü etkinleştirmeden önce batch() kullanarak sensörü yapılandırmalıdır.
Bir sensör devre dışı bırakıldıktan sonra bu sensörden gelen ek sensör etkinlikleri, etkinlik FMQ'suna yazılmamalıdır.
Sifon sensörleri
Bir sensör, sensör verilerini toplu olarak gönderecek şekilde yapılandırılmışsa çerçeve, flush() çağrılarak toplu sensör etkinliklerinin anında boşaltılmasını zorlayabilir. Bu, belirtilen sensör tutacına ait toplu sensör etkinliklerinin hemen Event FMQ'ya yazılmasına neden olur. Sensörler HAL'ı, flush() çağrısı sonucunda yazılan sensör etkinliklerinin sonuna bir temizleme tamamlandı etkinliği eklemelidir.
Temizleme işlemi eşzamansız olarak gerçekleşir (yani bu işlev hemen geri dönmelidir). Uygulamada birden fazla 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 bir temizleme tamamlandı etkinliği göndermelidir. Bu, tek seferlik sensörler dışındaki tüm sensörler için geçerlidir.
Tek seferlik bir sensör için flush() çağrılırsa flush(), BAD_VALUE değerini döndürmeli ve temizleme tamamlandı etkinliği oluşturmamalıdır.
Sensör etkinliklerini FMQ'ya yazma
Event FMQ, sensör etkinliklerini Android sensör çerçevesine göndermek için Sensors HAL tarafından kullanılır.
Olay FMQ'su senkronize bir FMQ'dur. Bu nedenle, kullanılabilir alanın izin verdiğinden daha fazla olay yazma girişimi başarısız yazma işlemiyle sonuçlanır. Bu durumda HAL, yeterli alan olduğunda mevcut etkinlik grubunu iki küçük etkinlik grubu olarak mı yazacağını yoksa tüm etkinlikleri birlikte mi yazacağını belirlemelidir.
Sensors HAL, istenen sayıda sensör etkinliğini Event FMQ'ya yazdığında, EventQueueFlagBits::READ_AND_PROCESS bitini Event FMQ'nun EventFlag::wake işlevine yazarak çerçeveye etkinliklerin hazır olduğunu bildirmelidir. EventFlag, EventFlag::createEventFlag kullanılarak Event FMQ'dan ve Event FMQ'nun getEventFlagWord() işlevinden oluşturulabilir.
Sensors HAL 2.0/2.1, Event FMQ'da hem write hem de writeBlocking'yi destekler.
Varsayılan uygulama, write kullanımına ilişkin bir referans sağlar. writeBlocking işlevi kullanılıyorsa readNotification işareti EventQueueFlagBits::EVENTS_READ olarak ayarlanmalıdır. Bu işaret, çerçeve tarafından Event FMQ'dan etkinlikler okunurken ayarlanır. Yazma bildirimi işareti, çerçeveye etkinliklerin Event FMQ'ya yazıldığını bildiren EventQueueFlagBits::READ_AND_PROCESS olarak ayarlanmalıdır.
WAKE_UP etkinlikleri
WAKE_UP etkinlikleri, uygulama işlemcisinin (AP) uyanmasına ve etkinliği hemen işlemesine neden olan sensör etkinlikleridir. Event FMQ'ya bir WAKE_UP etkinliği her yazıldığında, sistemin çerçeve etkinliği işleyene kadar uyanık kalmasını sağlamak için Sensors HAL, uyandırma kilidi almalıdır. Çerçeve, WAKE_UP etkinliğini aldığında kendi uyandırma kilidini güvenceye alır ve Sensörler HAL'ının uyandırma kilidini serbest bırakmasına olanak tanır. Sensors HAL
uyandırma kilidini bıraktığında senkronizasyon yapmak için uyandırma kilidi FMQ'sunu kullanın.
Sensörler HAL'si, çerçevenin işlediği WAKE_UP
etkinlik sayısını belirlemek için Wake Lock FMQ'yu okumalıdır. HAL, yalnızca toplam işlenmemiş WAKE_UP olay sayısı sıfırsa WAKE_UP olayları için uyandırma kilidini serbest bırakmalıdır.
Çerçeve, sensör etkinliklerini işledikten sonra WAKE_UP etkinlikleri olarak işaretlenen etkinliklerin sayısını sayar ve bu sayıyı Wake Lock FMQ'ya geri yazar.
Çerçeve, Wake Lock FMQ'ya veri yazdığında Wake Lock FMQ'da WakeLockQueueFlagBits::DATA_WRITTEN write
notification ayarını yapar.
Dinamik sensörler
Dinamik sensörler, fiziksel olarak cihazın bir parçası olmayan ancak cihaza giriş olarak kullanılabilen sensörlerdir (ör. ivme ölçerli bir oyun kumandası).
Dinamik bir sensör bağlandığında, ISensorsCallback içindeki onDynamicSensorConnected işlevi Sensors HAL'den çağrılmalıdır. Bu, yeni dinamik sensörü çerçeveye bildirir ve sensörün çerçeve aracılığıyla kontrol edilmesine, sensör etkinliklerinin de istemciler tarafından tüketilmesine olanak tanır.
Benzer şekilde, dinamik bir sensörün bağlantısı kesildiğinde, ISensorsCallback içindeki onDynamicSensorDisconnected işlevi çağrılmalıdır. Böylece çerçeve, artık kullanılamayan sensörleri kaldırabilir.
Doğrudan kanal
Doğrudan kanal, sensör etkinliklerinin Android Sensors Framework'ü atlayarak Event FMQ yerine belirli bir belleğe yazıldığı bir işlem yöntemidir. Doğrudan kanal kaydeden bir istemci, sensör etkinliklerini doğrudan kanalı oluşturmak için kullanılan bellekten okumalıdır ve sensör etkinliklerini çerçeve üzerinden almaz. configDirectReport() işlevi, normal çalışma için batch() işlevine benzer ve doğrudan rapor kanalını yapılandırır.
registerDirectChannel() ve unregisterDirectChannel() işlevleri yeni bir doğrudan kanal oluşturur veya yok eder.
Çalışma modları
setOperationMode() işlevi, çerçeveye sensör verilerini sensöre yerleştirebilmesi için çerçeveye bir sensörü yapılandırma olanağı tanır. Bu, özellikle çerçeve altında bulunan algoritmalar için test yaparken yararlıdır.
HAL 2.0'daki injectSensorData() işlevi ve HAL 2.0'daki injectSensorsData_2_1() işlevi, normalde operasyonel parametreleri Sensörler HAL'ına aktarmak için kullanılır. Bu işlev, belirli bir sensöre sensör etkinlikleri yerleştirmek için de kullanılabilir.
Doğrulama
Sensörler HAL uygulamanızı doğrulamak için sensör CTS ve VTS testlerini çalıştırın.
CTS testleri
Sensör CTS testleri hem otomatik CTS testlerinde hem de manuel CTS Verifier uygulamasında bulunur.
Otomatik testler cts/tests/sensor/src/android/hardware/cts konumunda bulunur. Bu testler, sensörlerin etkinleştirilmesi, toplu işleme ve sensör etkinlik oranları gibi sensörlerin standart işlevlerini doğrular.
CTS Doğrulayıcı testleri cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors konumunda bulunur. Bu testler, test operatörünün manuel girişini gerektirir ve sensörlerin doğru değerler bildirmesini sağlar.
CTS testlerini geçmek, test edilen cihazın tüm CDD koşullarını karşıladığından emin olmak için çok önemlidir.
VTS testleri
Sensors HAL 2.0 için VTS testleri hardware/interfaces/sensors/2.0/vts konumunda bulunur.
Sensörler HAL 2.1 için VTS testleri hardware/interfaces/sensors/2.1/vts konumunda bulunur.
Bu testler, Sensörler HAL'ının düzgün şekilde uygulandığını ve ISensors.hal ile ISensorsCallback.hal içindeki tüm şartların uygun şekilde karşılandığını doğrular.
Sensörler HAL 2.0'dan 2.1'e yükseltme
Sensors HAL 2.0'dan 2.1'e yükseltirken HAL uygulamanızda HAL 2.1 türleriyle birlikte initialize_2_1(), getSensorsList_2_1() ve injectSensorsData_2_1() yöntemleri yer almalıdır. Bu yöntemler, yukarıda HAL 2.0 için belirtilen gereksinimleri karşılamalıdır.
Küçük sürüm HAL'leri önceki HAL'lerdeki tüm işlevleri desteklemek zorunda olduğundan 2.1 HAL'leri, 2.0 HAL'leri olarak başlatılmayı desteklemelidir. Her iki HAL sürümünü desteklemenin karmaşıklığından kaçınmak için Multi-HAL 2.1'i kullanmanız önemle tavsiye edilir.
Kendi Sensors 2.1 HAL'nizi nasıl uygulayacağınızla ilgili bir örnek için Sensors.h sayfasına bakın.
Sensors HAL 1.0'dan 2.0'a yükseltme
1.0'dan Sensors HAL 2.0'a yükseltirken HAL uygulamanızın aşağıdaki koşulları karşıladığından emin olun.
HAL'yi başlatma
Çerçeve ile HAL arasında FMQ'lar oluşturmak için initialize() işlevi desteklenmelidir.
Kullanılabilir sensörleri kullanıma sunma
Sensors HAL 2.0'da getSensorsList() işlevi, tek bir cihaz başlatma işlemi sırasında Sensors HAL yeniden başlatılsa bile aynı değeri döndürmelidir. getSensorsList() işlevinin yeni bir şartı, tek bir cihaz başlatma sırasında, Sensors HAL yeniden başlatmaları arasında bile aynı değeri döndürmesi gerektiğidir. Bu, sistem sunucusu yeniden başlatılırsa çerçevenin sensör bağlantılarını yeniden kurmayı denemesine olanak tanır. getSensorsList() tarafından döndürülen değer, cihaz yeniden başlatıldıktan sonra değişebilir.
Sensör etkinliklerini FMQ'ya yazma
Sensors HAL 2.0'da poll() çağrılmasını beklemek yerine, sensör etkinlikleri kullanılabilir olduğunda Sensors HAL'ın sensör etkinliklerini Event FMQ'ya proaktif olarak yazması gerekir. HAL, çerçeve içinde FMQ okuması yapılması için EventFlag'ya doğru bitleri yazmaktan da sorumludur.
WAKE_UP etkinlikleri
Sensors HAL 1.0'da, HAL, WAKE_UP, poll()'a gönderildikten sonra poll()'a yapılan sonraki tüm çağrılarda herhangi bir WAKE_UP etkinliği için uyandırma kilidini serbest bırakabiliyordu. Bunun nedeni, çerçevenin tüm sensör etkinliklerini işlediğini ve gerekirse uyandırma kilidi aldığını belirtmesiydi. Sensors HAL 2.0'da HAL, artık çerçeve FMQ'ya yazılan etkinlikleri ne zaman işlediğini bilmediğinden Wake Lock FMQ, çerçeveye WAKE_UP etkinliklerini işlediğinde HAL ile iletişim kurma olanağı tanır.
Sensors HAL 2.0'da, WAKE_UP etkinlikleri için Sensors HAL tarafından güvenli hale getirilen uyandırma kilidi SensorsHAL_WAKEUP ile başlamalıdır.
Dinamik sensörler
Dinamik sensörler, Sensors HAL 1.0'da poll() işlevi kullanılarak döndürülür.
Sensors HAL 2.0, dinamik sensör bağlantıları değiştiğinde ISensorsCallback içindeki onDynamicSensorsConnected ve onDynamicSensorsDisconnected öğelerinin çağrılmasını gerektirir. Bu geri çağırmalar, initialize() işlevi aracılığıyla sağlanan ISensorsCallback işaretçisinin bir parçası olarak kullanılabilir.
Çalışma modları
DATA_INJECTION modundaki WAKE_UP sensörler, Sensors HAL 2.0'da desteklenmelidir.
Çoklu HAL desteği
Sensörler HAL 2.0 ve 2.1, Sensörler Multi-HAL çerçevesi kullanılarak çoklu HAL'yi destekler. Uygulama ayrıntıları için Sensors HAL 1.0'dan taşıma başlıklı makaleyi inceleyin.