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

تمثّل واجهة Sensors HAL، التي تم تحديدها في sensors.h، الواجهة بين إطار عمل Android والبرامج الخاصة بالأجهزة. يجب أن يحدد تطبيق HAL كل دالة المبينة في أجهزة الاستشعار. الوظائف الرئيسية هي:

• get_sensors_list - لعرض قائمة بجميع أجهزة الاستشعار
• activate - بدء أداة استشعار أو إيقافها
• batch - لضبط مَعلمات أداة الاستشعار، مثل معدّل أخذ العينات والحد الأقصى لمُدد الاستجابة في الإبلاغ
• ‫setDelay - لا يتم استخدام هذا العنصر إلا في الإصدار 1.0 من HAL. لضبط معدّل أخذ العينات لجهاز استشعار معيّن.
• flush - مسح FIFO لجهاز الاستشعار المحدّد والإبلاغ عن اكتمال تدفّق البيانات الحدث عند الانتهاء من ذلك.
• poll - لعرض أحداث أداة الاستشعار المتوفرة

يجب أن يكون التنفيذ متوافقًا مع سلسلة المحادثات وأن يسمح باستدعاء هذه الدوال. من سلاسل محادثات مختلفة.

وتحدِّد الواجهة أيضًا عدة أنواع تستخدمها هذه الدوال. المصدر الرئيسي أنواعها هي:

• sensors_module_t
• sensors_poll_device_t
• sensor_t
• sensors_event_t

بالإضافة إلى الأقسام الواردة أدناه، يُرجى الاطّلاع على sensors.h للحصول على مزيد من المعلومات عن هذه الأنواع.

get_sensors_list(list)

int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t
  const** list);

توفر قائمة أجهزة الاستشعار التي تنفذها طبقة تجريد الأجهزة (HAL). اطّلِع على sensor_t للحصول على تفاصيل عن كيفية تعريف أدوات الاستشعار.

إنّ الترتيب الذي تظهر به أدوات الاستشعار في القائمة هو الترتيب الذي سيتم به إبلاغ التطبيقات بأدوات الاستشعار. عادةً ما تظهر أجهزة الاستشعار الأساسية أولاً، تليها أدوات الاستشعار المركّبة.

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

تعرض هذه الدالة عدد أجهزة الاستشعار في القائمة.

تفعيل(أداة استشعار، صواب/خطأ)

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

تفعيل أداة استشعار أو إيقافها

sensor_handle هو اسم أداة الاستشعار لتفعيلها أو إيقافها. يتم تحديد اسم جهاز الاستشعار من خلال حقل handle في بنية sensor_t.

يتم ضبط enabled على 1 لتفعيل أداة الاستشعار أو 0 لإيقافها.

يتم إيقاف أدوات الاستشعار لمرة واحدة تلقائيًا عند تلقّي حدث، ويجب أن تقبل هذه الأدوات إيقافها من خلال طلب إلى activate(..., enabled=0).

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

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

إذا كانت قيمة enabled هي 1 وكان جهاز الاستشعار مفعَّلاً حاليًا، لن تعمل هذه الوظيفة. وتنجح.

إذا كانت قيمة enabled هي 0 وتم إيقاف أداة الاستشعار، لن يتم تنفيذ هذه الوظيفة. وتنجح.

تعرض هذه الدالة القيمة 0 في حال نجاح العملية ورقم خطأ سلبي في الحالات الأخرى.

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);

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

sensor_handle هو مقبض أداة الاستشعار المطلوب ضبطه.

إنّ flags غير مستخدَم حاليًا.

‫sampling_period_ns هي فترة أخذ العينات التي يجب أن يعمل فيها المستشعر ، بالكيلونانوثانية. راجِع sampling_period_ns لمعرفة المزيد من التفاصيل.

max_report_latency_ns هو الحد الأقصى للوقت الذي يمكن خلاله بدء الأحداث قبل أن يتم الإبلاغ عنه من خلال HAL، في غضون نانو ثانية. اطّلِع على الفقرة max_report_latency_ns لمعرفة مزيد من التفاصيل.

تعرض هذه الدالة القيمة 0 في حال نجاح العملية ورقم خطأ سلبي في الحالات الأخرى.

setDelay(sensor, sampling period)

int (*setDelay)(
     struct sensors_poll_device_t *dev,
     int sensor_handle,
     int64_t sampling_period_ns);

بعد الإصدار 1.0 من HAL، تم إيقاف هذه الدالة نهائيًا ولا يتم استدعاؤها مطلقًا. بدلاً من ذلك، يتمّ استدعاء الدالة batch لضبط المَعلمة sampling_period_ns.

في الإصدار 1.0 من HAL، تم استخدام setDelay بدلاً من ضبط sampling_period_ns.

مسح(أداة استشعار)

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

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

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

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

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

لا ينطبق الإجراء flush على أجهزة الاستشعار التي تعمل لمرة واحدة. إذا كان sensor_handle يشير إلى جهاز استشعار يعمل لمرة واحدة، يجب أن يعرض flush القيمة -EINVAL وألا يُنشئ أي حدث لتفريغ البيانات الوصفية الكاملة.

تعرض هذه الدالة القيمة 0 في حال نجاح العملية، وتعرض القيمة -EINVAL إذا كان أداة الاستشعار المحدّدة أداة استشعار لمرة واحدة أو لم تكن مفعّلة، وتعرض رقم خطأ سالبًا في الحالات الأخرى.

poll()

int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
  count);

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

يجب أن يكون عدد الأحداث التي يتم عرضها في data أقل من أو يساوي الوسيطة count. يجب ألا تُرجع هذه الدالة أبدًا القيمة 0 (بدون حدث).

تسلسل المكالمات

عند بدء تشغيل الجهاز، يتم استدعاء get_sensors_list.

عند تفعيل أحد أجهزة الاستشعار، سيتم استدعاء الدالة batch باستخدام المَعلمات المطلوبة، متبوعة بـ activate(..., enable=1).

يُرجى العلم أنّه في الإصدار 1_0 من HAL، كان الترتيب معاكسًا: تمّ استدعاء activate أولاً، ثم set_delay.

عندما تتغيّر الخصائص المطلوبة لأحد المستشعرات أثناء نشطة، تُسمى الدالة batch.

يمكن استدعاء flush في أي وقت، حتى على أجهزة الاستشعار غير المفعّلة (وفي هذه الحالة، يجب أن يعرض الرمز -EINVAL).

عند إيقاف جهاز الاستشعار، سيتم الاتصال بـ "activate(..., enable=0)".

بالتوازي مع هذه الاستدعاءات، سيتم استدعاء الدالة poll بشكل متكرر بيانات الطلب. يمكن الاتصال بـ "poll" حتى في حال عدم تفعيل أي أجهزة استشعار.

sensors_module_t

sensors_module_t هو النوع المستخدَم لإنشاء أجهزة Android لأجهزة الاستشعار. يجب أن يحدِّد تنفيذ HAL عنصرًا HAL_MODULE_INFO_SYM من هذا النوع لعرض الدالة get_sensors_list. يمكنك الاطّلاع على تعريف sensors_module_t في sensors.h وتعريف hw_module_t لمزيد من المعلومات.

أجهزة الاستشعار_poll_device_t / مستشعرات_poll_device_1_t

يحتوي العنصر sensors_poll_device_1_t على بقية الطرق المحدّدة أعلاه: activate وbatch وflush و poll. حقل common (من النوع hw_device_t) تحدد رقم إصدار HAL.

sensor_t

يمثّل الرمز sensor_t جهاز استشعار Android. في ما يلي بعض الحقول المهمة:

name: سلسلة تظهر للمستخدم وتمثل أداة الاستشعار. تظهر هذه السلسلة غالبًا يحتوي على اسم قطعة أداة الاستشعار الأساسية ونوع المستشعر وسواء كانت أداة استشعار للاستيقاظ. على سبيل المثال، "مقياس التسارع LIS2HH12"، "الجيروسكوب غير المحكَّم MAX21000"، "مقياس الضغط BMP280 لتنشيط الجهاز"، "مقياس التسارع والدوران في الألعاب MPU6515"

الاسم المعرِّف: العدد الصحيح المستخدَم للإشارة إلى أداة الاستشعار عند التسجيل لإنشاء الأحداث منه.

‫type: يشير إلى نوع جهاز الاستشعار. اطّلِع على شرح نوع الاستشعار في مقالة ما هي أدوات استشعار Android؟ لمعرفة المزيد من التفاصيل، وراجِع أنواع أدوات الاستشعار لمعرفة أنواع أدوات الاستشعار الرسمية. بالنسبة أنواع أدوات استشعار غير رسمية، يجب أن يبدأ type بالبادئة SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType: نوع المستشعر كسلسلة. عندما يكون لجهاز الاستشعار نوع رسمي، اضبطه على SENSOR_STRING_TYPE_*. عندما يكون لدى أداة الاستشعار نوع خاص بالشركة المصنّعة، يجب أن يبدأ stringType باسم النطاق العكسي للشركة المصنّعة. على سبيل المثال، يمكن أن يستخدم جهاز الاستشعار (مثل جهاز رصد الوحوش الخرافية) الذي حدّده فريق Cool-product في شركة Fictional-Company معرّف stringType=”com.fictional_company.cool_product.unicorn_detector”. تُستخدَم stringType لتحديد أدوات الاستشعار غير الرسمية بشكل فريد. الأنواع. اطّلِع على sensors.h للحصول على مزيد من المعلومات عن الأنواع وأنواع سلاسل الرسائل.

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

flags: علامات لهذا المستشعر، تحدّد وضع إعداد تقارير المستشعر وما إذا كان المستشعر مستشعرًا لتنبيه الجهاز أم لا. على سبيل المثال، سيكون لدى flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP يجب ترك الوحدات الثنائيّة للعلامة التي لا يتم استخدامها في إصدار HAL الحالي مساوية لـ 0.

‫maxRange: الحد الأقصى للقيمة التي يمكن أن يبلِغ عنها المستشعر، بالوحدة نفسها المستخدَمة في القيم التي يتم الإبلاغ عنها يجب أن يكون أداة الاستشعار قادرة على تسجيل القيم بدون تشويش خلال [-maxRange; maxRange]. لاحظ أن هذا يعني أن النطاق الإجمالي أداة الاستشعار بشكل عام هي 2*maxRange. عندما تبلغ أداة الاستشعار عن القيم التي تزيد عن عدة محاور، فإن النطاق ينطبق على كل محور. على سبيل المثال، "+/- 2g" سيبلغ مقياس التسارع maxRange = 2*9.81 = 2g.

درجة الدقة: أصغر اختلاف في القيمة يمكن أن يقيسها أداة الاستشعار. يتم حسابها عادةً استنادًا إلى maxRange وعدد وحدات البت في القياس.

الطاقة: تكلفة الطاقة لتفعيل أداة الاستشعار، بالمللي أمبير ويكون هذا الرقم دائمًا تقريبًا أعلى من استهلاك الطاقة الذي تم الإبلاغ عنه في ورقة بيانات أداة الاستشعار الأساسية. راجِع القسم أجهزة استشعار الأساس != مادية أدوات الاستشعار للحصول على مزيد من التفاصيل، والاطّلاع على مقالة قياس الطاقة للاطّلاع على تفاصيل حول طريقة قياس استهلاك الطاقة لجهاز الاستشعار. إذا كان استهلاك الطاقة في أداة الاستشعار يعتمد على ما إذا كان الجهاز يتحرك، فإنّ استهلاك الطاقة أثناء الحركة هو الاستهلاك الذي يتم تسجيله في حقل power .

minDelay: بالنسبة إلى أدوات الاستشعار المستمرة، تكون فترة أخذ العيّنات في بالميكرو ثانية، وهي تتجاوب مع أسرع معدل تدعمه أداة الاستشعار. راجِع sampling_period_ns لمعرفة تفاصيل حول كيفية استخدام هذه القيمة. يجب الانتباه إلى أنّ minDelay يتم التعبير عنه بالميكرو ثانية بينما تكون السمة sampling_period_ns في نانو ثانية. بالنسبة إلى أجهزة الاستشعار التي تعمل عند حدوث تغيير وأجهزة الاستشعار الخاصة بوضع إعداد التقارير، يجب أن يكونminDelay يساوي 0 ما لم يتم تحديد غير ذلك. بالنسبة إلى أدوات الاستشعار التي تعمل بنقرة واحدة، يجب أن يكون القيمة -1.

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

‫fifoReservedEventCount: عدد الأحداث المحجوزة لهذا المستشعر في ملف FIFO للأجهزة إذا كان هناك نظام FIFO مخصص لجهاز الاستشعار هذا، حجم ملفات FIFO المخصّصة هذه هو fifoReservedEventCount. إذا كان أمر FIFO التي تتم مشاركتها مع أجهزة استشعار أخرى، فإن fifoReservedEventCount هو حجم جزء عنصر FIFO الخاص بهذا المستشعر. في معظم أنظمة "الذاكرة المؤقتة للأولوية" المشتركة، وعلى الأنظمة التي لا تتضمّن ذاكرة مؤقتة للأولوية في الأجهزة، تكون هذه القيمة 0.

fifoMaxEventCount: الحد الأقصى لعدد الأحداث التي يمكن بتخزينها في عناصر FIFO الخاصة بهذا المستشعر. تكون هذه القيمة أكبر من أو تساوي fifoReservedEventCount دائمًا. ويتم استخدام هذه القيمة لتقدير مدى بسرعة امتلأ جهاز FIFO عند التسجيل في أداة الاستشعار في مع افتراض عدم تنشيط أي أجهزة استشعار أخرى. في الأنظمة التي لا تتضمّن ملفًا دوارًا للقراءة والكتابة في الأجهزة، تكون قيمة fifoMaxEventCount هي 0. يمكنك الاطّلاع على التجميع لمزيد من التفاصيل.

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

sensors_event_t

أحداث أدوات الاستشعار التي تنشئها أدوات استشعار Android ويتم الإبلاغ عنها من خلال وظيفة الاستطلاع هي type sensors_event_t. إليك بعض الأمثلة الحقول المهمة في sensors_event_t:

الإصدار: يجب أن يكون sizeof(struct sensors_event_t).

أداة الاستشعار: هي مقبض أداة الاستشعار التي تسبّب الحدث، كما هو محدَّد من خلال sensor_t.handle

type: نوع أداة الاستشعار التي أدت إلى الحدث، على النحو المحدّد في sensor_t.type

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

البيانات والحقول المتداخلة: القيم التي يتم قياسها بواسطة أداة الاستشعار. يختلف معنى هذه الحقول ووحداتها حسب نوع كل جهاز استشعار. اطّلِع على sensors.h وتعريف أنواع الحساسات المختلفة للحصول على وصف لسمات data . بالنسبة إلى بعض أجهزة الاستشعار، يتم أيضًا الإبلاغ عن دقة القراءات كجزء من البيانات، من خلال حقل status. هذا الحقل مخصص فقط أنواع أدوات الاستشعار المحددة هذه، والتي تظهر في طبقة SDK محددة بدقة. وبالنسبة إلى أجهزة الاستشعار هذه، يجب تعيين حقل الحالة مذكورة في نوع أداة الاستشعار التعريف.

أحداث اكتمال تفريغ البيانات الوصفية

إنّ أحداث البيانات الوصفية من النوع نفسه أحداث أدوات الاستشعار العادية: sensors_event_meta_data_t = sensors_event_t ويتم إرجاعها مع أحداث الاستشعار الأخرى من خلال الاستطلاع. يمتلك الحقول التالية:

version: يجب أن يكون META_DATA_VERSION

type: يجب أن يكون SENSOR_TYPE_META_DATA

أداة الاستشعار المحجوزة والطابع الزمني: يجب أن تكون 0.

‫meta_data.what: يحتوي على نوع البيانات الوصفية لهذا الحدث. يتوفّر حاليًا نوع واحد فقط من البيانات الوصفية الصالحة: META_DATA_FLUSH_COMPLETE.

تمثّل أحداث META_DATA_FLUSH_COMPLETE اكتمال تفريغ ملف FIFO لجهاز قياس . الموعد meta_data.what=META_DATA_FLUSH_COMPLETE، meta_data.sensor يجب ضبطه على مقبض أداة الاستشعار التي تم تدفقها. وهي يتم إنشاؤه عند استدعاء flush في أداة استشعار فقط. راجع القسم الذي يتناول الدالة flush للحصول على مزيد من المعلومات.