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. Sensörler HAL 2.1, HINGE_ANGLE sensör türünü kullanıma sunan ve çeşitli yöntemleri HINGE_ANGLE türünü kabul edecek şekilde güncelleyen Sensörler HAL 2.0'ın bir yinelemesidir.
HAL 2.1 arayüzü
Sensors HAL 2.1 ile ilgili temel doküman 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 ana doküman 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, Sensors HAL'e üç parametre sağlamak için HAL 2.0'da initialize() işlevini, HAL 2.1'de ise initialize_2_1() işlevini çağırır: 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 uyanık kalma 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 nesnesine yönelik bir işaretçi 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'ını 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 yapılan önemli değişiklikler arasında, belirli bir tutamağa sahip bir sensörün eksik olduğu veya özelliklerinin değiştiği ya da yeni sensörlerin kullanıma sunulduğu durumlar yer alır. Android çalışma zamanının yeniden başlatılması kullanıcı için rahatsız edici olsa da Android çerçevesi, statik (dinamik olmayan) sensörlerin bir uygulamanın kullanım ömrü boyunca değişmemesiyle ilgili Android API sözleşmesini artık karşılayamadığı için bu işlem gereklidir. 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 tutamaçları sağlamak için HAL, cihazdaki belirli bir fiziksel sensörü tutamacına deterministik olarak eşlemelidir. Sensors HAL arayüzü tarafından belirli bir uygulama zorunlu kılınmasa da geliştiriciler bu koşulu karşılamak için çeşitli seçeneklere sahiptir.
Ö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()'den 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. Görünme sırası, kararlı tutaçlar 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, sensör verileri kaybolmadan batch() kullanılarak istediği zaman 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 oranda 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 geciktirilebileceğ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 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. Sensors 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 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.
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 daha 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, Event FMQ'nun EventQueueFlagBits::READ_AND_PROCESS işlevine EventFlag::wake bitini yazarak etkinliklerin hazır olduğunu çerçeveye 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'ın bir uyanık kalma kilidi alması gerekir. Çerçeve, WAKE_UP etkinliğini aldığında kendi uyanık kalma kilidini güvenceye alır ve Sensors HAL'ın uyanık kalma kilidini serbest bırakmasına olanak tanır. Sensors HAL, uyanık kalma kilidini bıraktığında senkronize etmek için Wake Lock FMQ'yu kullanın.
Sensörler HAL'si, framework'ün 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 olarak işaretlenen etkinliklerin sayısını hesaplar 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 ve sensör etkinliklerinin 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, 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 raporlama 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 Sensors HAL'ye 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'nizi uyguladığını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 mevcuttur.
Otomatik testler cts/tests/sensor/src/android/hardware/cts konumunda bulunur. Bu testler, sensörlerin etkinleştirilmesi, gruplandırılması ve sensör etkinlik oranları gibi standart işlevlerini doğrular.
CTS Verifier 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 kritik öneme sahiptir.
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
2.0'dan Sensors HAL 2.1'e yükseltirken HAL uygulamanızda initialize_2_1(), getSensorsList_2_1() ve injectSensorsData_2_1() yöntemleri ile HAL 2.1 türleri yer almalıdır. Bu yöntemler, yukarıda HAL 2.0 için belirtilen gereksinimleri karşılamalıdır.
Alt sürüm HAL'leri önceki HAL'lerdeki tüm fonksiyonları desteklemek zorunda olduğundan 2.1 HAL'leri, 2.0 HAL'leri olarak ilk kullanıma hazırlanmayı desteklemelidir. Her iki HAL sürümünü de desteklemenin karmaşıklığından kaçınmak için Multi-HAL 2.1'i kullanmanız önemle önerilir.
Kendi Sensors 2.1 HAL'nizi nasıl uygulayacağınıza dair bir örnek için Sensors.h sayfasına bakın.
Sensörler HAL 1.0'dan 2.0'a yükseltme
1.0 sürümünden Sensors HAL 2.0 sürümüne 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() işlevinin ç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()'ye gönderildikten sonra poll()'ye yapılan sonraki tüm çağrılarda herhangi bir WAKE_UP etkinliği için uyanık kalma kilidini serbest bırakabiliyordu. Bunun nedeni, çerçevenin tüm sensör etkinliklerini işlediğini ve gerekirse uyanık kalma 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 uyanık kalma 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 işlevlerinin ç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örleri, Sensors HAL
2.0'da desteklenmelidir.
Çoklu HAL desteği
Sensors HAL 2.0 ve 2.1, Sensors 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.