Sensors HAL 1.0

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تمثل واجهة 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 في حال نجاح العملية ورقم خطأ سلبي في الحالات الأخرى.

دفعة(أداة استشعار، علامات، فترة أخذ العينات، الحد الأقصى لوقت استجابة التقرير)

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 ولذلك)

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 إذا كان جهاز الاستشعار المحدّد عبارة عن أو أداة استشعار بلقطة واحدة أو لم يتم تفعيلها، ورقم خطأ سلبي في الحالات الأخرى.

الاستطلاع()

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 Un معايرة جيروسكوب"، "BMP280 Wake-up Barometer"، "MPU6515 Game Rotation Vector"

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

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

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

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

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

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

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

sensors_event_t

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

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

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

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

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

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

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

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

الإصدار: يجب أن يكون 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 للحصول على مزيد من المعلومات.