חיישנים HAL 1.0

ממשק HAL של החיישנים, שמוצהר ב-sensors.h, מייצג את הממשק בין ה-framework של Android תוכנה ספציפית לחומרה. חובה להגדיר כל פונקציה של הטמעת HAL שהוצהר בחיישנים. הפונקציות העיקריות הן:

• get_sensors_list - מחזירה את הרשימה של כל החיישנים.
• activate – הפעלה או עצירה של החיישן.
• batch – הגדרת הפרמטרים של החיישן, כמו תדירות דגימה ומקסימום זמן אחזור של הדיווח.
• setDelay – בשימוש רק בגרסה 1.0 של HAL. מגדיר את תדירות הדגימה של לחיישן מסוים.
• 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)

הפונקציה הזו מחזירה את מספר החיישנים ברשימה.

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 במספר הצלחה, ואם לא, מחזירה מספר שגיאה שלילי.

אצווה(חיישן, דגלים, תקופת דגימה, זמן אחזור מקסימלי של דוח)

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.

Flush(sensor)

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

הוספת אירוע flushcomplete לסוף ה-FIFO של החומרה עבור החיישן שצוין וניקוי ה-FIFO; האירועים האלה נשלחים כרגיל (כלומר, כאילו זמן האחזור המקסימלי לדיווח) שהתוקף שלו פג) והוסר מה-FIFO.

הניקוי מתבצע באופן אסינכרוני (כלומר, הפונקציה הזו חייבת לחזור מיד). אם בהטמעה נעשה שימוש ב-FIFO אחד לכמה חיישנים, ה-FIFO ואירוע 'הניקוי' יתווסף רק לחיישן שצוין.

אם בחיישן שצוין אין FIFO (אין אפשרות אגירת נתונים), או אם יש FIFO, היה ריק בזמן השיחה, flush עדיין צריך להצליח ו לשלוח אירוע ריקון מלא עבור החיישן. הכלל הזה חל על כל החיישנים האחרים מחיישנים חד-פעמיים.

כשמתבצעת קריאה אל flush, גם אם כבר מתקיים אירוע Flash FIFO לחיישן הזה. צריך ליצור חיישן נוסף ולהוסיף אותו לסוף החיישן של ה-FIFO, וצריך לנקות את ה-FIFO. מספר הflush הקריאות חייבות להיות שווה למספר האירועים של השלמה אוטומטית שנוצרו.

flush לא רלוונטי לתמונה אחת חיישנים, אם sensor_handle מתייחס לחיישן חד-פעמי, flush חייב להחזיר -EINVAL ולא ליצור ניקוי אירוע של מטא-נתונים מלאים.

הפונקציה הזו מחזירה 0 בהצלחה, -EINVAL אם החיישן שצוין או לא הופעל, ומספר שגיאה שלילי.

segment()

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 גם אם לא הופעלו חיישנים.

חיישנים_Module_t

sensors_module_t הוא הסוג שמשמש ליצירת החומרה של Android של החיישנים. כשמטמיעים את ה-HAL, חייבים להגדיר אובייקט HAL_MODULE_INFO_SYM מהסוג הזה כדי לחשוף את הפונקציה get_sensors_list. לצפייה הגדרה של sensors_module_t ב-sensors.h וההגדרה של hw_module_t אפשר לקבל מידע נוסף.

חיישנים_poll_device_t / חיישנים_poll_device_1_t

sensors_poll_device_1_t מכיל את שאר השיטות שהוגדרו למעלה: activate, batch, flush וגם poll שדה common שלו (מסוג hw_device_t) מגדיר את מספר הגרסה של HAL.

חיישן_t

sensor_t מייצג Android חיישן. הנה כמה מהשדות החשובים בו:

name: מחרוזת גלויה למשתמש שמייצגת את החיישן. המחרוזת הזו לעיתים קרובות כולל את שם החלק של החיישן הבסיסי, סוג החיישן בין אם זהו חיישן התעוררות. לדוגמה, "מד תאוצה LIS2HH12", "MAX21000 Uncalibrated Gyroscope", "BMP280 Wake-up Barometer", "MPU6515 Game וקטור סבב"

כינוי: המספר השלם המשמש להתייחס לחיישן כשנרשמים אליו, או וליצור ממנה אירועים.

type: סוג החיישן. הצגת הסבר על החיישן מקלידים מהם חיישני Android? לקבלת פרטים נוספים, וקוראים את המאמר סוגי חיישנים עבור סוגי חיישנים רשמיים. עבור סוגי חיישנים לא רשמיים, type חייב להתחיל ב-SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType: סוג החיישן כמחרוזת. כאשר סוג החיישן הרשמי שמוגדר לSENSOR_STRING_TYPE_*. מתי סוג החיישן ספציפי ליצרן, stringType חייב מתחיל בשם הדומיין ההפוך של היצרן. לדוגמה, חיישן מזהה חד-קרן) שהוגדר על ידי צוות מוצר מגניב חברה בדיונית יכולה להשתמש stringType=”com.fictional_company.cool_product.unicorn_detector”. stringType משמש לזיהוי ייחודי של חיישנים לא רשמיים שונים. מידע נוסף על סוגים ומחרוזות זמין בכתובת sensors.h שונים.

requiredPermissions: מחרוזת שמייצגת את ההרשאה. שאפליקציות צריכות להחזיק כדי לראות את החיישן, להירשם אליו ולקבל של הנתונים. אם מופיעה מחרוזת ריקה, פירוש הדבר הוא שאפליקציות לא דורשות הרשאות כדי לגשת לחיישן הזה. לחלק מסוגי החיישנים, כמו מוניטור קצב הלב, יש חובה 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 השדה הזה.

minDelay: בחיישנים רציפים, תקופת הדגימה מיקרו-שניות, בהתאם לקצב המהיר ביותר שנתמך בחיישן. ראו sampling_period_ns פרטים על אופן השימוש בערך הזה. שימו לב ש-minDelay הוא מבוטאת במיליוניות השנייה, בעוד ש-sampling_period_ns ננו-שניות. לחיישנים במצב דיווח או דיווח מיוחד, אלא אם אחרת, הערך minDelay חייב להיות 0. בחיישנים של צילום אחד, חייב להיות 1-.

maxDelay: עבור חיישנים רציפים או חיישנים חדשים, מצב הדגימה במיליוניות השנייה, בהתאם לקצב האיטי ביותר של החיישן נתמך. ראו sampling_period_ns פרטים על אופן השימוש בערך הזה. שימו לב ש-maxDelay הוא מבוטאת במיליוניות השנייה, בעוד ש-sampling_period_ns ננו-שניות. לחיישנים מיוחדים ולחיישנים חד-פעמיים, maxDelay חייב להיות 0.

fifoReserveEventCount: מספר האירועים ששמורים לחיישן הזה FIFO לחומרה. אם יש FIFO ייעודי לחיישן הזה, fifoReservedEventCount הוא הגודל של ה-FIFO הייעודי הזה. אם ה-FIFO הוא משותף עם חיישנים אחרים, fifoReservedEventCount הוא הגודל של החלק ה-FIFO ששמור לאותו חיישן. ברוב מערכות FIFO המשותפות, ובמצב למערכות שאין להן FIFO לחומרה, הערך הזה הוא 0.

fifoMaxEventCount: המספר המקסימלי של אירועים שיכולים להיות מאוחסנים ביחידות ה-FIFO של החיישן הזה. הערך הזה תמיד גדול מ- או שווה ל- fifoReservedEventCount הערך הזה משמש להערכה של האופן שבו מהירות ה-FIFO תתמלא במהירות במהלך הרישום לחיישן בתנאי שלא הופעלו חיישנים אחרים. במערכות שאין להן FIFO של החומרה, fifoMaxEventCount הוא 0. לפרטים נוספים, ראו אצווה.

עבור חיישנים עם סוג חיישן רשמי, חלק מהשדות מוחלפים על ידי המסגרת. לדוגמה, חיישני מד תאוצה הם מאולצים מצב דיווח רציף, ומוניטורי קצב לב אוכף להיות מוגן על ידי SENSOR_PERMISSION_BODY_SENSORS הרשאה.

חיישנים_event_t

אירועי חיישנים שנוצרים על ידי חיישני Android ומדווחים באמצעות פונקציית הסקר הם מתוך type sensors_event_t. הנה כמה דוגמאות שדות חשובים של sensors_event_t:

גרסה: חייבת להיות sizeof(struct sensors_event_t)

sensor: נקודת האחיזה של החיישן שיצר את האירוע, לפי ההגדרה של sensor_t.handle.

type: סוג החיישן של החיישן שיצר את האירוע, כפי שמוגדר על ידי sensor_t.type.

timestamp: חותמת הזמן של האירוע בננו-שניות. זו השעה שבה התרחש אירוע (בוצע שלב, או שבוצעה מדידה של מד תאוצה), לא השעה שבה דווח על האירוע. חובה לסנכרן את timestamp עם בשעון elapsedRealtimeNano, ובמקרה של חיישנים רציפים, הרעידות חייב להיות קטן. לפעמים צריך לסנן חותמות זמן כדי לעמוד ב-CDD כי שימוש רק בזמן הפסקה של SoC להגדרת חותמות זמן גורמים לרעידות גבוהות מדי, ומשתמשים רק בזמן שבב החיישן עשויות לגרום לביטול סנכרון השעון של elapsedRealtimeNano, כששעון החיישן זז.

data ושדות חופפים: הערכים שנמדדים באמצעות באמצעות חיישן. המשמעות והיחידות של השדות האלה הן ספציפיות לכל חיישן מהסוג הזה. למידע על סוגי החיישנים השונים, אפשר לעיין בקטע sensors.h שדות נתונים. עבור חיישנים מסוימים, יש דיווח גם על רמת הדיוק של התוצאות כחלק מהנתונים, באמצעות שדה status. בשדה הזה בלבד של סוגי החיישנים שנבחרו, ומופיעים בשכבת ה-SDK ערך הדיוק. עבור החיישנים האלה, צריך להגדיר את שדה הסטטוס מוזכר בסוג החיישן שלהם להגדרה.

אירועים שהושלמו של מטא-נתונים

הסוג של אירועי מטא-נתונים זהה לזה של אירועי חיישנים רגילים: sensors_event_meta_data_t = sensors_event_t הם מוחזרים יחד עם אירועי חיישנים אחרים באמצעות סקר. הם כוללים את השדות הבאים:

גרסה: חייבת להיות META_DATA_VERSION

type: חייב להיות SENSOR_TYPE_META_DATA

sensor, Reserve, חותמת זמן: חייבת להיות 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.