Sensors HAL 1.0

تمثّل واجهة Sensors HAL، التي تم تعريفها في sensors.h، الواجهة بين إطار عمل Android framework والبرامج الخاصة بالأجهزة. يجب أن يحدّد تنفيذ واجهة 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 complete event في نهاية قائمة FIFO للأجهزة لجهاز الاستشعار المحدّد وتُفرِغ قائمة FIFO؛ ويتم إرسال هذه الأحداث كالمعتاد (أي كما لو كان الحد الأقصى لوقت تأخير إرسال التقارير قد انتهى) وتتم إزالتها من قائمة FIFO.

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

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

name: سلسلة مرئية للمستخدم تمثّل جهاز الاستشعار. غالبًا ما تحتوي هذه السلسلة على اسم جزء جهاز الاستشعار الأساسي ونوع جهاز الاستشعار وما إذا كان جهاز استشعار منبّهًا. على سبيل المثال، "مقياس التسارع LIS2HH12"، "جيروسكوب MAX21000 غير المعاير"، "مقياس الضغط الجوي BMP280 المنبّه"، "متجه دوران الألعاب MPU6515"

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

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 الحالي مساويةً للصفر.

maxRange: الحد الأقصى للقيمة التي يمكن أن يُرسلها جهاز الاستشعار، بنفس الوحدة التي يتم بها إرسال القيم. يجب أن يكون جهاز الاستشعار قادرًا على إرسال القيم بدون تشبع ضمن [-maxRange; maxRange]. يُرجى العِلم أنّ هذا يعني أنّ النطاق الإجمالي لـ جهاز الاستشعار بالمعنى العام هو 2*maxRange. عندما يُرسِل جهاز الاستشعار قيمًا على عدة محاور، ينطبق النطاق على كل محور. على سبيل المثال، سيُرسِل مقياس التسارع "+/- 2g" تقريرًا maxRange = 2*9.81 = 2g.

resolution: أصغر فرق في القيمة يمكن أن يقيسه جهاز الاستشعار. يتم حسابه عادةً استنادًا إلى maxRange وعدد وحدات البت في القياس.

power: تكلفة الطاقة لتفعيل جهاز الاستشعار، بالمللي أمبير. يكون هذا الرقم دائمًا أكبر من استهلاك الطاقة المُرسَل في الـ ورقة بيانات جهاز الاستشعار الأساسي. يُرجى الاطّلاع على أجهزة الاستشعار الأساسية لا تساوي أجهزة الاستشعار الفعلية لمزيد من التفاصيل، وعلى عملية قياس الطاقة للحصول على تفاصيل حول كيفية قياس استهلاك الطاقة لجهاز استشعار. إذا كان استهلاك الطاقة لجهاز الاستشعار يعتمد على ما إذا كان الجهاز يتحرك، فإنّ استهلاك الطاقة أثناء الحركة هو ما يتم إرساله في الحقل power.

minDelay: بالنسبة إلى أجهزة الاستشعار المستمرة، تكون فترة أخذ العيّنات، بـ الميكرو ثانية، والتي تتوافق مع أسرع معدّل يتيحه جهاز الاستشعار. يُرجى الاطّلاع على sampling_period_ns للحصول على تفاصيل حول كيفية استخدام هذه القيمة. يُرجى العِلم أنّ minDelay يتم التعبير عنه بالميكرو ثانية بينما يتم التعبير عن sampling_period_ns بالنانو ثانية. بالنسبة إلى أجهزة الاستشعار التي تُرسِل التقارير عند تغيير البيانات وأجهزة الاستشعار التي تُرسِل التقارير في وضع خاص، ما لم يُنص على خلاف ذلك، يجب أن تكون minDelay مساويةً للصفر. بالنسبة إلى أجهزة الاستشعار التي تعمل لمرة واحدة، يجب أن تكون القيمة -1.

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

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

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

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

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

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

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

version: يجب أن تكون META_DATA_VERSION

type: يجب أن تكون SENSOR_TYPE_META_DATA

sensor, reserved, and 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 لمزيد من المعلومات.