أجهزة استشعار AIDL HAL

طبقة HAL (Sensors Hardware Abstraction Layer) هي الواجهة بين قاعدة برمجة التطبيقات لأجهزة استشعار Android وأدوات استشعار الجهاز، مثل مقياس التسارع أو الجيروسكوب. تحدِّد حزمة HAL الخاصة بالمستشعرات الدوال التي يجب تنفيذها لسماح الإطار الأساسي بالتحكم في هذه المستشعرات.

يتوفّر حِزم HAL لواجهة برمجة التطبيقات Sensors AIDL في الإصدار 13 من نظام التشغيل Android والإصدارات الأحدث للأجهزة الجديدة والأجهزة التي تمت ترقيتها. إنّ حزمة HAL لواجهة برمجة التطبيقات لأجهزة الاستشعار المستندة إلى Sensors HAL 2.1 تستخدم واجهة HAL لواجهة برمجة التطبيقات و تعرِض أنواع أجهزة تتبُّع الرأس وأجهزة استشعار IMU ذات المحاور المحدودة.

واجهة HAL في لغة تعريف واجهة نظام Android ‏(AIDL)

يمكن العثور على المصدر الرئيسي لمستندات HAL لواجهة برمجة التطبيقات Sensors AIDL ضمن تعريف HAL في hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.

تنفيذ حزمة HAL لواجهة برمجة التطبيقات (AIDL) لأجهزة الاستشعار

لتنفيذ حزمة HAL لواجهة برمجة التطبيقات Sensors AIDL، يجب أن ينشئ العنصر واجهة ISensors ويفّر جميع الدوالّ المحدّدة في hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.

بدء HAL

يجب أن يبدأ إطار عمل أجهزة الاستشعار في Android عملية إعداد واجهة برمجة التطبيقات لأجهزة الاستشعار (HAL) قبل أن يمكن استخدامها. يستدعي إطار العمل الدالة initialize() لتقديم ثلاث مَعلمات إلى Sensors HAL: وصفان لفئة FMQ ومؤشر واحد إلى ISensorsCallback.

يستخدم HAL الوصف الأوّل لإنشاء Event FMQ المستخدَم لكتابة أحداث الاستشعار في إطار العمل. يستخدم HAL المعرّف الثاني لإنشاء FMQ لـ Wake Lock المستخدَم للمزامنة عندما يُطلق HAL قفل التنشيط لأحداث WAKE_UP الاستشعار. يجب أن يحفظ HAL مؤشرًا إلى عنصر ISensorsCallback حتى تتمكّن من استدعاء أيّ دوال ردّ اتصال ضرورية.

يجب أن تكون الدالة initialize() هي الدالة الأولى التي يتم استدعاؤها عند بدء استخدام HAL لأجهزة الاستشعار.

عرض أجهزة الاستشعار المتاحة

للحصول على قائمة بجميع أجهزة الاستشعار الثابتة المتاحة في الجهاز، يمكنك استخدام الوظيفة getSensorsList(). تعرض هذه الدالة قائمة بأدوات الاستشعار، التي يتم تمييز كلٍّ منها بشكل فريد من خلال الاسم المعرِّف لها. يجب ألا يتغيّر الاسم المعرِّف لجهاز استشعار معيّن عند إعادة تشغيل العملية التي تستضيف حزمة HAL الخاصة بأجهزة الاستشعار. وقد تتغير الأسماء المعرِّفة على مستوى عمليات إعادة تشغيل الجهاز وإعادة تشغيل خادم النظام.

إذا كانت هناك عدة أجهزة استشعار تشترك في نوع أداة الاستشعار نفسه وخاصية التنشيط، يكون اسم المستشعر الأول في القائمة هو أداة الاستشعار التلقائية ويتم إرجاعها إلى التطبيقات التي تستخدم وظيفة getDefaultSensor(int sensorType, bool wakeUp).

ثبات قائمة أجهزة الاستشعار

بعد إعادة تشغيل المستشعرات HAL، إذا أشارت البيانات التي تم عرضها من خلال getSensorsList() إلى حدوث تغيير كبير مقارنةً بقائمة أدوات الاستشعار التي تم استردادها قبل إعادة التشغيل، يؤدي إطار العمل إلى إعادة تشغيل بيئة تشغيل Android. تشمل التغييرات الكبيرة في قائمة أجهزة الاستشعار الحالات التي لا يتوفّر فيها جهاز استشعار يحمل اسمًا معيّنًا أو تم تغيير سمات جهاز استشعار أو تم إدخال أجهزة استشعار جديدة. على الرغم من أنّ إعادة تشغيل نظام التشغيل Android Runtime يتسبب في تعطيل المستخدم، إلا أنّه إجراء مطلوب لأنّ إطار عمل Android لم يعُد يستوفي عقد Android API الذي ينص على عدم تغيير أدوات الاستشعار الثابتة (غير الديناميكية) أثناء مدة استخدام التطبيق. وقد يمنع ذلك أيضًا إطار العمل من إعادة تأسيس طلبات أدوات الاستشعار النشطة التي تقدّمها التطبيقات. لذلك، ننصح مورّدي HAL بمحاولة تجنُّب تغييرات قائمة أجهزة الاستشعار التي يمكن تجنُّبها.

لضمان ثبات أسماء أجهزة الاستشعار، يجب أن يربط HAL بشكلٍ حاسم جهاز استشعار ما في الجهاز باسمه. على الرغم من عدم فرض واجهة أجهزة الاستشعار HAL تنفيذًا محدّدًا، فإنّ المطوّرين لديهم عدد من الخيارات المتاحة لتلبية هذا الشرط.

على سبيل المثال، يمكن ترتيب قائمة أجهزة الاستشعار باستخدام مجموعة من سمات كل جهاز استشعار الثابتة، مثل المورّد والطراز ونوع جهاز الاستشعار. يعتمد خيار آخر على حقيقة أنّ مجموعة أجهزة الاستشعار الثابتة في الجهاز ثابتة في الأجهزة، لذا يحتاج HAL إلى معرفة وقت اكتمال عملية إعداد جميع أجهزة الاستشعار المتوقّعة قبل الرجوع من getSensorsList(). يمكن تجميع قائمة الأجهزة الاستشعار المتوقّعة في ملف HAL ثنائي أو تخزينها فيملف إعدادات في نظام الملفات، ويمكن استخدام ترتيب الظهور لإنشاء أسماء معرِّفات ثابتة. ورغم أنّ أفضل حل يعتمد على تفاصيل التنفيذ المحددة لدالة HAL، فإن الشرط الرئيسي هو ألا تتغير مؤشرات أداة الاستشعار عند إعادة تشغيل طبقة تجريد الأجهزة (HAL).

ضبط أجهزة الاستشعار

قبل تفعيل أداة الاستشعار، يجب ضبطها باستخدام فترة قياس كثافة العينة ومدة الاستجابة القصوى لإعداد التقارير باستخدام الدالة batch().

يجب أن يكون بالإمكان إعادة ضبط جهاز الاستشعار في أي وقت باستخدام batch() بدون فقدان بياناته.

فترة أخذ العيّنات

يكون لمرحلة أخذ العينات معنى مختلفًا استنادًا إلى نوع أداة الاستشعار التي يتم إعدادها:

• متواصلة: يتم إنشاء أحداث أدوات الاستشعار بمعدّل متواصل.
• عند حدوث تغيير: لا يتمّ إنشاء الأحداث بسرعة أكبر من فترة أخذ العينات، وقد يتمّ إنشاؤها بمعدّل أبطأ من فترة أخذ العينات إذا لم تتغيّر القيمة المقاسة.
• قياس لمرة واحدة: يتم تجاهل فترة أخذ العينات.
• خاص: لمزيد من التفاصيل، يُرجى الاطّلاع على أنواع أجهزة الاستشعار.

للتعرّف على التفاعل بين فترة أخذ العينات وmodi reporting لجهاز الاستشعار، اطّلِع على وضعَي إعداد التقارير.

الحد الأقصى لوقت استجابة إعداد التقارير

يحدِّد الحد الأقصى لمُدد الاستجابة في إعداد التقارير الحد الأقصى للوقت الذي يمكن فيه تأخير الأحداث وتخزينها في ذاكرة التخزين المؤقت للأجهزة أولاً قبل كتابتها في ذاكرة التخزين المؤقت للأحداث من خلال HAL عندما تكون وحدة المعالجة المركزية (SoC) مفعَّلة.

تشير القيمة صفر إلى أنّه يجب الإبلاغ عن الأحداث فور قياسها، إما عن طريق تخطّي "قائمة الانتظار بأولوية عكسية" بالكامل أو إفراغ "قائمة الانتظار بأولوية عكسية" فور توفّر حدث واحد من أداة الاستشعار في "قائمة الانتظار بأولوية عكسية".

على سبيل المثال، يُشغّل مقياس التسارع الذي يتم تفعيله بمعدّل 50 هرتز مع الحد الأقصى لوقت المعالجة الذي يساوي صفرًا عمليات المقاطعة 50 مرة في الثانية عندما يكون المعالج المتكامل للنظام قيد التشغيل.

عندما يكون الحد الأقصى لوقت استجابة إعداد التقارير أكبر من الصفر، لا يلزم الإبلاغ عن أحداث أداة الاستشعار فور رصدها. يمكن تخزين الأحداث مؤقتًا في ذاكرة الأجهزة للوصول أولاً إلى العناصر الأقدم والإبلاغ عنها بشكل مجمّع، ما دام لا يتم تأخير أي حدث بأكثر من الحد الأقصى لمُدد الاستجابة للإبلاغ. يتم تسجيل جميع الأحداث منذ الدُفعة السابقة وإرجاعها مرة واحدة. وهذا يقلل من عدد المقاطعات المرسلة إلى المنظومة على الرقاقة (SoC) ويسمح للمنظومة على الرقاقة بالتبديل إلى وضع طاقة أقل أثناء التقاط أداة الاستشعار للبيانات وتجميعها.

يرتبط كل حدث بطابع زمني. يجب ألا يؤثّر تأخير وقت تسجيل الحدث في الطابع الزمني للحدث. يجب أن يكون الطابع الزمني دقيقًا وأن يتوافق مع الوقت الذي وقع فيه الحدث فعليًا، وليس وقت الإبلاغ عنه.

للاطّلاع على معلومات ومتطلبات إضافية بشأن إعداد التقارير عن أحداث أدوات الاستشعار عندما يكون وقت استجابة إعداد التقارير بحد أقصى غير صفري، يُرجى الاطّلاع على التجميع.

تفعيل أدوات الاستشعار

يفعّل إطار العمل أدوات الاستشعار ويوقفها باستخدام الدالة activate(). قبل تشغيل أي جهاز استشعار، يجب أولاً أن تضبط إطار العمل إعدادات المستشعر باستخدام batch().

بعد إيقاف جهاز استشعار، يجب عدم تسجيل أحداث إضافية من هذا الجهاز في "قائمة الانتظار للطلبات الفورية للأحداث".

أجهزة استشعار التنظيف

إذا تم ضبط جهاز استشعار لتجميع بيانات أجهزة الاستشعار، يمكن للإطار العمل فرض محو فوري لأحداث أجهزة الاستشعار المجمّعة من خلال استدعاء flush(). يؤدي ذلك إلى تسجيل أحداث أداة الاستشعار المجمّعة الخاصة بمعرّف أداة الاستشعار المحدّد على الفور في "قائمة الانتظار للطلبات الفورية للأحداث". يجب أن تُلحق طبقة تجريد الأجهزة (HAL) بأجهزة الاستشعار حدث تدفّق كامل بنهاية أحداث أداة الاستشعار التي تتم كتابتها نتيجةً لاستدعاء flush().

يتم تنفيذ عملية التنظيف بشكل غير متزامن (أي أنّ هذه الدالة يجب أن تُرجع على الفور). إذا كان التنفيذ يستخدم قائمة انتظار أولوية تصاعدية واحدة لعدة أجهزة استشعار، تتم تنظيف قائمة الانتظار هذه ويتم إضافة حدث اكتمال التنظيف لجهاز الاستشعار المحدّد فقط.

إذا لم يكن لدى أداة الاستشعار المحدّدة قائمة انتظار أولوية (FIFO) (لا يمكن تخزين البيانات مؤقتًا)، أو إذا كانت قائمة الانتظار خالية في وقت المكالمة، يجب أن تنجح flush() وتُرسِل حدثًا يشير إلى اكتمال تنظيف ذاكرة التخزين المؤقت لتلك أداة الاستشعار. ينطبق ذلك على جميع أدوات الاستشعار بخلاف أدوات الاستشعار التي تعمل لمرة واحدة.

إذا تمّ استدعاء flush() لجهاز استشعار لمرة واحدة، يجب أن يعرض flush()BAD_VALUE بدون إنشاء حدث اكتمال تنظيف.

كتابة بيانات أحداث المستشعر إلى FMQ

يتم استخدام إطار FMQ بواسطة أجهزة الاستشعار HAL لتوجيه أحداث أداة الاستشعار إلى إطار عمل أجهزة الاستشعار في Android.

إنّ "قائمة انتظار الرسائل الفورية للأحداث" هي قائمة انتظار متزامنة للرسائل الفورية، ما يعني أنّ أي محاولة لكتابة عدد أحداث أكبر من المساحة المتاحة في قائمة الانتظار للرسائل الفورية تؤدي إلى تعذُّر الكتابة. في هذه الحالة، يجب أن يحدّد HAL ما إذا كان سيتم كتابة المجموعة الحالية من الأحداث كجماعتَين أصغر من الأحداث أو كتابة جميع الأحداث معًا عندما تتوفّر مساحة كافية.

عندما يكتب المستشعر HAL العدد المطلوب من أحداث أجهزة الاستشعار إلى Event FMQ، يجب أن يعلم هذا HAL إطار العمل بأنّ الأحداث جاهزة من خلال كتابة وحدة بت EventQueueFlagBits::READ_AND_PROCESS في دالة EventFlag::wake في فعالية FMQ. يمكن إنشاء EventFlag من Event FMQ باستخدام EventFlag::createEventFlag ودالة getEventFlagWord() في Event FMQ.

تتوافق أجهزة الاستشعار AIDL HAL مع كلّ من write وwriteBlocking في فعالية FMQ. توفّر عملية التنفيذ التلقائية مرجعًا لاستخدام write. في حال استخدام الدالة writeBlocking، يجب ضبط علامة readNotification على EventQueueFlagBits::EVENTS_READ، والذي يتم ضبطه من خلال إطار العمل عند قراءة الأحداث من Event FMQ. يجب ضبط علامة إشعار الكتابة على EventQueueFlagBits::READ_AND_PROCESS، ما يُعلم إطار العمل بأنّه تمت كتابة الأحداث في Event FMQ.

أحداث WAKE_UP

أحداث WAKE_UP هي أحداث من أجهزة الاستشعار تؤدي إلى تنشيط معالج التطبيقات (AP) والتعامل مع الحدث على الفور. عند كتابة حدث WAKE_UP في Event FMQ، يجب أن يحصل Sensors HAL على قفل تنبيه لضمان بقاء النظام في وضع التشغيل إلى أن يتمكّن إطار العمل من معالجة الحدث. عند تلقّي حدث WAKE_UP، يُحصّن إطار العمل قفل التنشيط الخاص به، ما يسمح لواجهة برمجة التطبيقات (HAL) لأجهزة الاستشعار بإزالة قفل التنشيط. لمزامنة البيانات عندما يُبطل Sensors HAL قفل التنشيط، استخدِم Wake Lock FMQ.

يجب أن يقرأ Sensors HAL ملف Wake Lock FMQ لتحديد عدد WAKE_UP الأحداث التي تعامل معها إطار العمل. يجب ألا يُطلق HAL قفل التنشيط لأحداث WAKE_UP إلا إذا كان إجمالي عدد أحداث WAKE_UP غير المُعالجة يساوي صفرًا. بعد معالجة أحداث أداة الاستشعار، يحتسب إطار العمل عدد الأحداث التي يتم وضع علامة عليها كأحداث WAKE_UP ويُعيد كتابة هذا العدد في "قائمة الانتظار للطلبات الفورية" الخاصة بميزة "قفل التنشيط".

يضبط إطار العمل إشعار WakeLockQueueFlagBits::DATA_WRITTEN write في "قائمة الانتظار للرسائل الفورية" لميزة "قفل التنشيط" كلما كتب البيانات في "قائمة الانتظار للرسائل الفورية" لميزة "قفل التنشيط".

أجهزة الاستشعار الديناميكية

أجهزة الاستشعار الديناميكية هي أجهزة استشعار ليست جزءًا من الجهاز جسديًا ولكن يمكن استخدامها كمدخلات للجهاز، مثل جهاز تحكم ألعاب مزوّد بمقياس تسارع.

عند توصيل جهاز استشعار ديناميكي، يجب استدعاء الدالة onDynamicSensorConnected في ISensorsCallback من Sensors HAL. يؤدي ذلك إلى إرسال إشعار إلى الإطار العملي بشأن أداة الاستشعار الديناميكية الجديدة والسماح بالتحكم في أداة الاستشعار من خلال الإطار العملي واستخدام العملاء لأحداث أداة الاستشعار.

وبالمثل، عند انقطاع الاتصال بجهاز استشعار ديناميكي، يجب استدعاء onDynamicSensorDisconnected في ISensorsCallback ليكون بإمكان الإطار الأساسي إزالة أي جهاز استشعار لم يعُد متاحًا.

قناة مباشرة

القناة المباشرة هي طريقة تتم من خلالها كتابة أحداث أداة الاستشعار في ذاكرة معيّنة بدلاً من إرسالها إلى أداة FMQ التي تجتاز إطار عمل أجهزة استشعار Android. على العميل الذي يسجّل قناة مباشرة قراءة أحداث أجهزة الاستشعار مباشرةً من الذاكرة التي تم استخدامها لإنشاء القناة المباشرة ولن يتم تلقّي أحداث أجهزة الاستشعار من خلال الإطار. تشبه الدالة configDirectReport() الدالة batch() للتشغيل العادي، وتضبط قناة التقرير المباشر.

تنشئ الدالتان registerDirectChannel() وunregisterDirectChannel() قناة مباشرة جديدة أو تُزيلانها.

أوضاع التشغيل

تسمح دالة setOperationMode() للإطار بضبط أداة استشعار كي يتمكّن الإطار من إدخال بيانات أداة الاستشعار في أداة الاستشعار. ويُعدّ ذلك مفيدًا في الاختبار، خاصةً بالنسبة إلى الخوارزميات التي تقع أسفل إطار العمل.

تُستخدَم الدالة injectSensorData() عادةً لدفع المَعلمات التشغيلية إلى حزمة HAL الخاصة بأجهزة الاستشعار. يمكن أيضًا استخدام الدالة لإدخال أحداث الأجهزة الاستشعارية في جهاز استشعار معيّن.

التحقُّق

للتحقّق من صحة تنفيذك لواجهة HAL الخاصة بأجهزة الاستشعار، عليك إجراء اختبارَي CTS وVTS لأجهزة الاستشعار.

اختبارات CTS

تتوفّر اختبارات CTS الخاصة بأجهزة الاستشعار في كلّ من اختبارات CTS المبرمَجة وتطبيق "أداة التحقّق من CTS" يدوية الاستخدام.

يمكنك العثور على الاختبارات المبرمَجة في cts/tests/sensor/src/android/hardware/cts. تتحقّق هذه الاختبارات من الوظائف العادية لأدوات الاستشعار، مثل تفعيل أدوات الاستشعار وتجميعها ومعدّلات أحداث أدوات الاستشعار.

يمكنك العثور على اختبارات CTS Verifier من خلال الرابط cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors. تتطلّب هذه الاختبارات إدخالًا يدويًا من مشغّل الاختبار، وتؤكّد أنّ أجهزة الاستشعار تُسجّل قيمًا دقيقة.

إنّ اجتياز اختبارات CTS أمر مهم لضمان استيفاء الجهاز الخاضع للاختبار لجميع متطلبات CDD.

اختبارات VTS

يمكن العثور على اختبارات VTS لحزمة HAL لواجهة برمجة التطبيقات Sensors AIDL في ملف برمجي في المسار: hardware/interfaces/sensors/aidl/vts/. تضمن هذه الاختبارات تنفيذ حزمة HAL الخاصة بأجهزة الاستشعار بشكل صحيح واستيفاء جميع المتطلبات الواردة في ISensors.aidl وISensorsCallback.aidl بشكل صحيح.

بدء HAL

يجب أن تكون الدالة initialize() متوافقة لإنشاء قوائم انتظار الطلبات الفورية بين الإطار وHAL.

إتاحة أجهزة الاستشعار المتاحة

في مجموعة أدوات الاستشعار AIDL HAL، يجب أن تعرض الدالة getSensorsList() القيمة نفسها أثناء تشغيل جهاز واحد، حتى في عمليات إعادة تشغيل طبقة تجريد الأجهزة (HAL) لأجهزة الاستشعار. من المتطلبات الجديدة للدالة getSensorsList() أن تعرِض القيمة نفسها أثناء التمهيد لجهاز واحد، حتى في عمليات إعادة تشغيل HAL لأجهزة الاستشعار. يتيح ذلك لإطار العمل محاولة إعادة إنشاء اتصالات أجهزة الاستشعار في حال إعادة تشغيل خادم النظام. يمكن أن تتغيّر القيمة التي يعرضها getSensorsList() بعد أن يُعيد الجهاز تشغيله.

كتابة أحداث أجهزة الاستشعار في "الملفّ الموحّد للطلبات"

بدلاً من انتظار استدعاء poll()، يجب أن يكتب واجهة HAL لأجهزة الاستشعار HAL لأجهزة الاستشعار بشكل استباقي أحداث أجهزة الاستشعار في Event FMQ كلما كانت أحداث أجهزة الاستشعار متوفّرة. تتحمّل HAL أيضًا مسؤولية كتابة الوحدات الصحيحة في ملف ‎ EventFlag لقراءة FMQ ضمن الإطار.

أحداث WAKE_UP

في أجهزة الاستشعار HAL 1.0، تمكّن HAL من فتح قفل التنشيط لأي حدث WAKE_UP في أي طلب لاحق لـ poll() بعد نشر WAKE_UP على poll() لأنّ ذلك يشير إلى أنّ إطار العمل قد عالج جميع أحداث أداة الاستشعار وحصل على قفل تنشيط، إذا لزم الأمر. في حزمة Sensors AIDL HAL، لم يعُد يتم إشعار HAL عندما يعالج إطار العمل الأحداث المكتوبة في FMQ، لذلك يسمح إطار العمل لحزمة Wake Lock FMQ بالتواصل مع HAL عند معالجته لأحداث WAKE_UP.

في حزمة HAL لواجهة برمجة التطبيقات لأجهزة الاستشعار الذكية (AIDL)، يجب أن يبدأ قفل التنشيط الذي توفّره حزمة HAL لأجهزة الاستشعار لأحداث WAKE_UP بـ SensorsHAL_WAKEUP.

أجهزة الاستشعار الديناميكية

تم عرض أجهزة الاستشعار الديناميكية باستخدام الدالة poll() في Sensors HAL 1.0. تتطلب أجهزة الاستشعار AIDL HAL استدعاء onDynamicSensorsConnected وonDynamicSensorsDisconnected في ISensorsCallback عند تغيير اتصالات أدوات الاستشعار الديناميكية. تتوفّر عمليات الاستدعاء هذه كجزء من مؤشر ISensorsCallback الذي يتم توفيره من خلال الدالة initialize().

أوضاع التشغيل

يجب أن يكون وضع DATA_INJECTION متوافقًا مع أدوات استشعار WAKE_UP.

دعم واجهات HAL المتعددة

تتوافق أجهزة الاستشعار AIDL HAL مع طبقة تجريد الأجهزة (HAL) المتعددة باستخدام إطار عمل أجهزة الاستشعار المتعددة HAL. للاطّلاع على تفاصيل التنفيذ، يُرجى الاطّلاع على نقل البيانات من Sensors HAL 2.1.