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

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

  • get_sensors_list - إرجاع قائمة بجميع أجهزة الاستشعار.
  • activate - لبدء أو إيقاف جهاز الاستشعار.
  • batch - يضبط معلمات المستشعر مثل تردد أخذ العينات والحد الأقصى لوقت استجابة التقارير.
  • setDelay - يُستخدم فقط في HAL الإصدار 1.0. يضبط تردد أخذ العينات لجهاز استشعار معين.
  • flush - يتدفق ما يرد أولاً يصرف أولاً (FIFO) لجهاز الاستشعار المحدد ويبلغ عن حدث تدفق كامل عند القيام بذلك.
  • poll - إرجاع أحداث المستشعر المتاحة.

يجب أن يكون التنفيذ موضوعًا آمنًا ويسمح باستدعاء هذه الوظائف من مؤشرات ترابط مختلفة.

تحدد الواجهة أيضًا عدة أنواع تستخدمها تلك الوظائف. الأنواع الرئيسية هي:

  • sensors_module_t
  • sensors_poll_device_t
  • sensor_t
  • sensors_event_t

بالإضافة إلى الأقسام أدناه ، راجع sensors.h لمزيد من المعلومات حول هذه الأنواع.

get_sensors_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 إيقاف التنبيه الجزئي نيابة عن التطبيقات.

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

إذا تم enabled هو 1 وكان المستشعر نشطًا بالفعل ، فإن هذه الوظيفة هي no-op وتنجح.

إذا تم enabled هو 0 وكان المستشعر معطلاً بالفعل ، فإن هذه الوظيفة هي no-op وتنجح.

ترجع هذه الدالة 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 (المستشعر ، فترة أخذ العينات)

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 فارغًا في وقت المكالمة ، فلا يزال يجب أن ينجح 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) .

لاحظ أنه في إصدار HAL 1_0 ، كان الترتيب معكوسًا: تم استدعاء 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 في المستشعرات. h وتعريف hw_module_t لمزيد من المعلومات.

sensors_poll_device_t / sensors_poll_device_1_t

يحتوي sensors_poll_device_1_t على باقي الطرق المحددة أعلاه: activate batch poll flush . يحدد حقله common (من النوع hw_device_t ) رقم إصدار HAL.

sensor_t

يمثل sensor_t مستشعر Android . فيما يلي بعض مجالاته المهمة:

الاسم: سلسلة مرئية للمستخدم تمثل المستشعر. غالبًا ما تحتوي هذه السلسلة على اسم جزء من المستشعر الأساسي ونوع المستشعر وما إذا كان مستشعر تنبيه. على سبيل المثال ، "LIS2HH12 Accelerometer" ، "MAX21000 Uncalibrated Gyroscope" ، "BMP280 Wake-up Barometer" ، "MPU6515 Game Rotation Vector"

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

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

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

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

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

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

sensors_event_t

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

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

المستشعر: مقبض المستشعر الذي أنشأ الحدث ، كما هو محدد بواسطة sensor_t.handle .

النوع: نوع المستشعر الذي أنشأ الحدث ، كما هو محدد بواسطة نوع sensor_t.type .

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

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

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

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

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