منسوخ شدن نسخه HAL

در نسخه L از Android، پشتیبانی از برخی نسخه‌های HAL حسگر را متوقف می‌کنیم. تنها نسخه‌های پشتیبانی‌شده SENSORS_DEVICE_API_VERSION_1_0 و SENSORS_DEVICE_API_VERSION_1_3 هستند.

در نسخه‌های بعدی، احتمالاً پشتیبانی از 1_0 را نیز متوقف خواهیم کرد.

‫1_0 مفهومی از دسته‌بندی ندارد. درصورت امکان، همه دستگاه‌هایی که از 1_0 استفاده می‌کنند باید به 1_3 ارتقا یابند.

‫1_1 و 1_2 از تعریف ضعیف مفهوم دسته‌بندی رنج می‌برند و دیگر پشتیبانی نمی‌شوند

همه دستگاه‌هایی که درحال‌حاضر از 1_1 یا 1_2 استفاده می‌کنند باید به 1_3 ارتقا دهند.

در نسخه ۱.۳، مفهوم دسته‌بندی را ساده کردیم و حسگرهای بیدارباش را معرفی کردیم.

برای ارتقا به نسخه 1_3، تغییرات فهرست‌شده در زیر را دنبال کنید.

پیاده‌سازی تابع دسته‌ای

حتی اگر دسته‌بندی را پیاده‌سازی نکنید (سخت‌افزار شما FIFO ندارد)، باید تابع batch را پیاده‌سازی کنید. batch برای تنظیم دوره نمونه‌برداری و حداکثر تأخیر گزارش‌دهی برای حسگر داده‌شده استفاده می‌شود. جایگزین setDelay می‌شود. دیگر با setDelay تماس گرفته نخواهد شد.

اگر دسته‌ای‌سازی را پیاده‌سازی نمی‌کنید، می‌توانید batch را با فراخوانی کردن تابع setDelay موجودتان با پارامتر sampling_period_ns ارائه‌شده پیاده‌سازی کنید.

پیاده‌سازی تابع پاک‌سازی

حتی اگر دسته‌بندی را پیاده‌سازی نمی‌کنید، باید تابع flush را پیاده‌سازی کنید.

اگر دسته‌ای‌سازی را پیاده‌سازی نکنید، flush باید یک رویداد META_DATA_FLUSH_COMPLETE تولید کند و ۰ (موفقیت) را برگرداند.

تغییر sensors_poll_device_t.common.version

your_poll_device.common.version = SENSORS_DEVICE_API_VERSION_1_3

فیلدهای جدید را به تعریف حسگرهایتان اضافه کنید

هنگام تعریف هر حسگر، علاوه‌بر فیلدهای معمول sensor_t:

.name =       "My magnetic field Sensor",
.vendor =     "My company",
.version
=    1,
.handle =     mag_handle,
.type =       SENSOR_TYPE_MAGNETIC_FIELD,
.maxRange =   200.0f,
.resolution = CONVERT_M,
.power =      5.0f,
.minDelay =
 16667,

همچنین باید فیلدهای جدید را که بین نسخه ۱_۰ و ۱_۳ تعریف شده‌اند تنظیم کنید:

.fifoReservedEventCount = 0,
.fifoMaxEventCount =   0,
.stringType =         0,
.requiredPermission = 0,
.maxDelay =      200000
.flags =
SENSOR_FLAG_CONTINUOUS_MODE,

fifoReservedEventCount: اگر دسته‌ای‌سازی را پیاده‌سازی نمی‌کنید، این مورد را روی ۰ تنظیم کنید.

fifoMaxEventCount: اگر دسته‌ای‌سازی را پیاده‌سازی نمی‌کنید، این مورد را روی ۰ تنظیم کنید

stringType: برای همه حسگرهای رسمی Android (حسگرهایی که در sensors.h تعریف شده‌اند)، روی ۰ تنظیم کنید، زیرا این مقدار توسط چارچوب بازنویسی خواهد شد. برای حسگرهای غیررسمی، برای جزئیات نحوه تنظیم آن، sensor_t را ببینید.

requiredPermission: این اجازه‌ای است که برنامه‌ها برای دسترسی به حسگر شما باید داشته باشند. معمولاً می‌توانید این مقدار را برای همه حسگرهایتان روی ۰ تنظیم کنید، اما حسگرهای نوع HEART_RATE باید این مقدار را روی SENSOR_PERMISSION_BODY_SENSORS. تنظیم کنند

maxDelay: این مقدار مهم است و باید آن را براساس قابلیت‌های حسگر و درایور آن تنظیم کنید.

این مقدار فقط برای حسگرهای پیوسته و تغییر تعریف می‌شود. این مقدار برابر با تأخیر بین دو رویداد حسگر متناظر با کمترین بسامدی است که این حسگر پشتیبانی می‌کند. وقتی بسامدهای پایین‌تر ازطریق تابع batch درخواست می‌شود، رویدادها در این بسامد تولید می‌شوند. چارچوب یا برنامه‌ها می‌توانند از آن برای تخمین زمان پر شدن FIFO دسته‌ای استفاده کنند. اگر این مقدار به‌درستی تنظیم نشود، CTS ناموفق خواهد بود. برای حسگرهای حالت گزارش ویژه و یک‌باره، maxDelay را روی ۰ تنظیم کنید.

برای حسگرهای پیوسته، آن را روی حداکثر دوره نمونه‌برداری مجاز در میکروثانیه تنظیم کنید.

موارد زیر برای period_ns،‏ maxDelay، و minDelay قابل‌اجرا است:

  • period_ns به نانوثانیه است درحالی‌که maxDelay/minDelay به میکروثانیه است.
  • ‫maxDelay همیشه باید در یک عدد صحیح علامت‌دار ۳۲ بیتی جا شود. این فقط در معماری‌های ۶۴ بیتی به‌دلیل سازگاری باینری به‌عنوان ۶۴ بیتی اعلام می‌شود.

پرچم‌ها: این فیلد حالت گزارش‌دهی حسگر و اینکه حسگر حسگر بیدارباش است یا نه را تعریف می‌کند.

اگر دسته‌بندی را پیاده‌سازی نمی‌کنید و فقط از نسخه ۱.۰ به ۱.۳ می‌روید، این مقدار را روی این تنظیم کنید:

‫SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ONE_SHOT_MODE برای حسگرهای تک‌ضرب

SENSOR_FLAG_CONTINUOUS_MODE برای حسگرهای پیوسته SENSOR_FLAG_ON_CHANGE_MODE برای حسگرهای تغییر-روشن به‌جز حسگر مجاورت SENSOR_FLAG_SPECIAL_REPORTING_MODE برای حسگرهای دارای حالت گزارش‌دهی ویژه به‌جز حسگر شیب.

SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ON_CHANGE_MODE برای حسگر مجاورت و حسگر رسمی تشخیص کجی Android.

نکته‌هایی درباره ارتقا از نسخه 1_1 یا 1_2

  • اکنون تابع batch تقریباً همیشه موفق است، حتی برای حسگرهایی که از دسته‌ای کردن پشتیبانی نمی‌کنند، صرف‌نظر از مقدار آرگومان مهلت زمانی. تنها مواردی که ممکن است تابع batch با خطا مواجه شود خطاهای داخلی، یا sensor_handle, بد یا sampling_period_ns منفی یا max_report_latency_ns منفی است.
  • اینکه حسگر از دسته‌بندی پشتیبانی می‌کند یا نه براساس این تعریف می‌شود که fifoMaxEventCount بزرگ‌تر از ۰ باشد. (در نسخه‌های قبلی، براساس مقدار برگشتی batch() بود.)
  • حسگرهایی که از دسته‌بندی پشتیبانی می‌کنند همیشه در چیزی هستند که در نسخه‌های قبلی «حالت دسته‌ای» می‌نامیدیم: حتی اگر پارامتر max_report_latency_ns برابر با ۰ باشد، حسگر همچنان باید دسته‌بندی شود، یعنی وقتی SoC به حالت تعلیق می‌رود، رویدادها باید در FIFO ذخیره شوند.
  • پارامتر flags تابع batch دیگر استفاده نمی‌شود. ‫DRY_RUN و WAKE_UPON_FIFO_FULL هر دو منسوخ شده‌اند و هرگز به تابع batch منتقل نخواهند شد.
  • اکنون به آرگومان مهلت دسته‌ای، آرگومان max_report_latency گفته می‌شود.