חיישנים HAL 1.0

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

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

חיישנים שאינם מתעוררים לעולם אינם מונעים מה-SoC לעבור למצב השעיה; כלומר, ה-HAL לא יקיים Wake-lock חלקי מטעם בקשות.

חיישני התעוררות, בעת מסירת אירועים ברציפות, יכולים למנוע מה-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 בודד עבור מספר חיישנים, ה-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 הוא הסוג המשמש ליצירת מודול החומרה של אנדרואיד עבור החיישנים. היישום של ה-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 and poll . השדה common שלו (מהסוג hw_device_t ) מגדיר את מספר הגרסה של ה-HAL.

sensor_t

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

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

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 למידע נוסף על סוגים וסוגי מחרוזות.

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

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

חיישנים_אירוע_t

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

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

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

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