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

ملاحظة: توضِّح هذه الصفحة حزمة HAL 1.0 لأجهزة الاستشعار. للحصول على معلومات عن تنفيذ Sensors HAL 2.0 على الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android والإصدارات الأحدث، يُرجى الاطّلاع على Sensors HAL 2.0.

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

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

تعرِض هذه الدالة عدد الحساسات في القائمة.

Enable(sensor, true/false)

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.

flush(sensor)

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

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

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

إذا لم يكن لدى أداة الاستشعار المحدّدة قائمة انتظار أولوية (لا يمكن تخزين البيانات مؤقتًا)، أو إذا كانت قائمة الانتظار خالية في وقت المكالمة، يجب أن تنجح 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 Wake-up Barometer" و"MPU6515 Game Rotation Vector"

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

‫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 = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP يجب ترك الوحدات الثنائيّة للعلامة التي لا يتم استخدامها في إصدار HAL الحالي مساوية لـ 0.

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

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

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

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

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

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

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

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

sensors_event_t

أحداث أجهزة الاستشعار التي يتم إنشاؤها بواسطة أجهزة استشعار Android وتسجيلها من خلال الدالة poll هي من النوع type sensors_event_t. في ما يلي بعض الحقول المهمة في sensors_event_t:

‫version: يجب أن يكون sizeof(struct sensors_event_t)

sensor: الاسم المعرِّف لأداة الاستشعار التي أدّت إلى إنشاء الحدث، كما هو محدّد في sensor_t.handle.

‫type: نوع جهاز الاستشعار الذي أدّى إلى إنشاء الحدث، كما هو محدّد في sensor_t.type.

‫الطابع_الزمني: الطابع الزمني للحدث بالنانوسثانية هذا هو الوقت الذي وقعت فيه الفعالية (تم اتخاذ خطوة أو تم إجراء قياس لمقياس التسارع)، وليس الوقت الذي تم فيه الإبلاغ عن الحدث. يجب أن تكون timestamp متزامنة مع ساعة elapsedRealtimeNano، وفي حال استخدام أدوات الاستشعار المستمرة، يجب أن يكون الاضطراب صغيرًا. يكون فلترة الطوابع الزمنية ضروريًا في بعض الأحيان لاستيفاء متطلبات CDD ، لأنّ استخدام وقت المقاطعة في وحدة المعالجة المركزية فقط لضبط الطوابع الزمنية يؤدي إلى حدوث تداخل كبير جدًا، كما أنّ استخدام وقت شريحة الاستشعار فقط لضبط الطوابع الزمنية يمكن أن يؤدي إلى إيقاف المزامنة مع 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 للحصول على مزيد من المعلومات.