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

تمثل واجهة Sensors HAL، المعلنة في Sensors.h ، الواجهة بين إطار عمل Android والبرامج الخاصة بالأجهزة. يجب أن يحدد تطبيق HAL كل وظيفة معلنة في أجهزة الاستشعار.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(قائمة)

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

int (*setDelay)(
     struct sensors_poll_device_t *dev,
     int sensor_handle,
     int64_t sampling_period_ns);

بعد إصدار HAL 1.0، تم إهمال هذه الوظيفة ولم يتم استدعاؤها مطلقًا. وبدلاً من ذلك، يتم استدعاء الدالة batch لتعيين معلمة sampling_period_ns .

في HAL الإصدار 1.0، تم استخدام setDelay بدلاً من الدُفعة لتعيين sampling_period_ns .

تدفق (الاستشعار)

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

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

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