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

لا تمنع أجهزة الاستشعار غير المخصّصة للتنشيط وحدة المعالجة المركزية (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 بدلاً من batch لضبط 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 لمعرفة المزيد من المعلومات.

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. في ما يلي بعض الحقول المهمة:

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

‫fifoMaxEventCount: الحد الأقصى لعدد الأحداث التي يمكن تخزينها في قوائم "الأول بالدخول أولاً بالخروج" لهذا المستشعر تكون هذه القيمة أكبر من أو تساوي 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

‫sensor وreserved وtimestamp: يجب أن تكون القيمة 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 للحصول على مزيد من المعلومات.