سنسور HAL 1.0

توجه: در این صفحه سنسورهای HAL 1.0 توضیح داده شده است. برای کسب اطلاعات در مورد اجرای Sensors HAL 2.0 در دستگاه‌های دارای Android 10 و بالاتر، به Sensors HAL 2.0 مراجعه کنید.

رابط Sensors HAL که در sensors.h اعلام شده است، رابط بین چارچوب Android و نرم افزار مخصوص سخت افزار را نشان می دهد. یک پیاده سازی HAL باید هر تابع اعلام شده در sensors.h را تعریف کند. توابع اصلی عبارتند از:

• get_sensors_list - لیست تمام حسگرها را برمی‌گرداند.
• activate - یک سنسور را شروع یا متوقف می کند.
• batch - پارامترهای سنسور مانند فرکانس نمونه برداری و حداکثر تأخیر گزارش را تنظیم می کند.
• setDelay - فقط در نسخه HAL 1.0 استفاده می شود. فرکانس نمونه برداری را برای یک سنسور مشخص تنظیم می کند.
• flush - FIFO سنسور مشخص شده را شستشو می دهد و پس از انجام این کار، یک رویداد کامل فلاش را گزارش می دهد.
• poll - رویدادهای حسگر موجود را برمی‌گرداند.

پیاده سازی باید به صورت Thread ایمن باشد و اجازه دهد که این توابع از رشته های مختلف فراخوانی شوند.

رابط همچنین چندین نوع مورد استفاده توسط آن توابع را تعریف می کند. انواع اصلی عبارتند از:

• 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) .

حسگرهای غیر بیدار هرگز از رفتن SoC به حالت تعلیق جلوگیری نمی کنند. یعنی HAL نباید از طرف برنامه‌های کاربردی، قفل قفل جزئی داشته باشد.

سنسورهای بیدار شدن، هنگام ارائه رویدادها به طور مداوم، می توانند از رفتن SoC به حالت تعلیق جلوگیری کنند، اما اگر نیازی به ارائه هیچ رویدادی نباشد، قفل بیدار شدن جزئی باید آزاد شود.

اگر enabled 1 باشد و سنسور قبلاً فعال شده باشد، این عملکرد غیرفعال است و موفق می شود.

اگر 0 enabled باشد و سنسور قبلاً غیرفعال شده باشد، این عملکرد غیرفعال است و موفق می شود.

این تابع در صورت موفقیت 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 و در غیر این صورت یک عدد خطای منفی را برمی گرداند.

تأخیر تنظیم (حسگر، دوره نمونه برداری)

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);

یک رویداد flush full به انتهای سخت افزار FIFO برای سنسور مشخص شده اضافه کنید و FIFO را شستشو دهید. آن رویدادها طبق معمول تحویل داده می شوند (به عنوان مثال: گویی حداکثر تأخیر گزارش منقضی شده است) و از FIFO حذف می شوند.

فلاش به صورت ناهمزمان اتفاق می افتد (یعنی: این تابع باید فوراً برگردد). اگر پیاده سازی از یک FIFO برای چندین سنسور استفاده کند، آن FIFO فلاش می شود و رویداد flush full فقط برای سنسور مشخص شده اضافه می شود.

اگر حسگر مشخص شده فاقد FIFO باشد (بدون بافر امکان پذیر نیست)، یا اگر FIFO در زمان تماس خالی بود، flush همچنان باید موفق باشد و یک رویداد flush کامل برای آن سنسور ارسال کند. این برای همه سنسورها غیر از سنسورهای تک شات صدق می کند.

هنگامی که flush فراخوانی می شود، حتی اگر یک رویداد flush از قبل برای آن سنسور در FIFO وجود داشته باشد، باید یک رویداد اضافی ایجاد شود و به انتهای FIFO اضافه شود و FIFO باید فلاش شود. تعداد تماس‌های flush باید برابر با تعداد رویدادهای flush full ایجاد شده باشد.

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 نوعی است که برای ایجاد ماژول سخت افزار اندروید برای سنسورها استفاده می شود. پیاده سازی 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 نشان دهنده یک سنسور اندروید است. در اینجا به برخی از زمینه های مهم آن اشاره می شود:

name: یک رشته قابل مشاهده برای کاربر که نشان دهنده حسگر است. این رشته اغلب شامل نام قطعه حسگر زیرین، نوع سنسور و اینکه آیا حسگر بیدار است یا خیر می باشد. به عنوان مثال، «شتاب‌سنج LIS2HH12»، «ژیروسکوپ بدون کالیبره MAX21000»، «بارومتر بیدار شدن BMP280»، «بردار چرخش بازی MPU6515»

handle: عدد صحیحی که برای رجوع به حسگر در هنگام ثبت روی آن یا ایجاد رویدادها از آن استفاده می شود.

نوع: نوع سنسور. توضیح نوع سنسور را در سنسورهای اندروید چیست ببینید؟ برای جزئیات بیشتر، و انواع سنسور برای انواع سنسور رسمی را ببینید. برای انواع حسگرهای غیر رسمی، 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 مراجعه کنید.

requirePermission: رشته ای نشان دهنده مجوزی است که برنامه ها باید برای دیدن حسگر، ثبت نام در آن و دریافت داده های آن داشته باشند. یک رشته خالی به این معنی است که برنامه ها برای دسترسی به این حسگر نیازی به مجوز ندارند. برخی از انواع حسگرها مانند نمایشگر ضربان قلب دارای requiredPermission اجباری هستند. همه حسگرهایی که اطلاعات حساس کاربر را ارائه می دهند (مانند ضربان قلب) باید با مجوز محافظت شوند.

flags: پرچم هایی برای این سنسور، مشخص کننده حالت گزارش سنسور و اینکه آیا سنسور یک حسگر بیداری است یا نه. به عنوان مثال، یک سنسور بیدار شدن یک شات دارای 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 اختصاصی برای این سنسور وجود دارد، پس fifoReservedEventCount اندازه این FIFO اختصاصی است. اگر FIFO با سنسورهای دیگر به اشتراک گذاشته شود، fifoReservedEventCount اندازه بخشی از FIFO است که برای آن سنسور رزرو شده است. در اکثر سیستم‌های FIFO مشترک، و در سیستم‌هایی که FIFO سخت‌افزاری ندارند، این مقدار ۰ است.

fifoMaxEventCount: حداکثر تعداد رویدادهایی که می توان در FIFO برای این سنسور ذخیره کرد. این همیشه بزرگتر یا برابر با fifoReservedEventCount است. این مقدار برای تخمین سرعت پر شدن FIFO هنگام ثبت نام در سنسور با نرخ مشخصی استفاده می شود، فرض کنید هیچ سنسور دیگری فعال نشده باشد. در سیستم هایی که FIFO سخت افزاری ندارند، fifoMaxEventCount 0 است. برای جزئیات بیشتر به Batching مراجعه کنید.

برای حسگرهایی با نوع سنسور رسمی، برخی از فیلدها توسط چارچوب بازنویسی می شوند. به عنوان مثال، حسگرهای شتاب سنج مجبور هستند حالت گزارش دهی پیوسته داشته باشند، و مانیتورهای ضربان قلب مجبور هستند با مجوز SENSOR_PERMISSION_BODY_SENSORS محافظت شوند.

sensors_event_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 RealtimeNano شود. ساعت سنسور حرکت می کند

داده ها و فیلدهای همپوشانی: مقادیر اندازه گیری شده توسط سنسور. معنی و واحدهای آن فیلدها برای هر نوع حسگر مشخص است. برای توضیح فیلدهای داده به 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 روی سنسور فراخوانی می شود، تولید می شوند. برای اطلاعات بیشتر به بخش عملکرد فلاش مراجعه کنید.