Sensors HAL 1.0

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

• ‫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).

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

activate(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).

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

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

إذا كانت قيمة 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 بدلاً من batch لضبط sampling_period_ns.

flush(sensor)

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

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

يتم تنفيذ عملية المسح بشكل غير متزامن (أي يجب أن تعرض هذه الدالة القيمة على الفور). إذا كان التنفيذ يستخدم قائمة انتظار واحدة بنظام الوارد أولاً الصادر أولاً (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 للحصول على مزيد من المعلومات.

sensors_poll_device_t / sensors_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"

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

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. يجب أن تظل أجزاء العلامة غير المستخدَمة في إصدار HAL الحالي مساوية للصفر.

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 لهذا المستشعر، فإنّ fifoReservedEventCount هو حجم هذا المخزن المؤقت المخصّص. إذا كانت المخزن المؤقت FIFO مشتركًا مع أجهزة استشعار أخرى، يمثّل fifoReservedEventCount حجم الجزء من المخزن المؤقت FIFO المحجوز لجهاز الاستشعار هذا. في معظم أنظمة FIFO المشتركة، وفي الأنظمة التي لا تتضمّن FIFO للأجهزة، تكون هذه القيمة 0.

fifoMaxEventCount: الحد الأقصى لعدد الأحداث التي يمكن تخزينها في المخازن المؤقتة ذات الأولوية الأولى في الدخول والأولى في الخروج (FIFO) لهذا المستشعر تكون هذه القيمة دائمًا أكبر من أو تساوي fifoReservedEventCount. تُستخدَم هذه القيمة لتقدير سرعة امتلاء المخزن المؤقت FIFO عند التسجيل في أداة الاستشعار بمعدل معيّن، على افتراض عدم تفعيل أي أدوات استشعار أخرى. في الأنظمة التي لا تتضمّن ذاكرة FIFO مدمجة، تكون قيمة 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، لأنّ استخدام وقت مقاطعة نظام على شريحة (SoC) فقط لضبط الطوابع الزمنية يؤدي إلى حدوث تفاوت كبير جدًا، كما أنّ استخدام وقت شريحة المستشعر فقط لضبط الطوابع الزمنية يمكن أن يؤدي إلى عدم المزامنة مع ساعة elapsedRealtimeNano، لأنّ ساعة المستشعر تنحرف.

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

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

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

version: يجب أن تكون القيمة META_DATA_VERSION

النوع: يجب أن يكون 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 على أحد المستشعرات. راجِع القسم الخاص بوظيفة محو البيانات للحصول على مزيد من المعلومات.