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

تمثل واجهة 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).

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

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

وحدة_استشعار_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.

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

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

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

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