מאפייני הרכב

הממשק Vehicle Hardware Abstraction Layer‏ (VHAL) מגדיר את המאפיינים שספקי ציוד מקורי יכולים להטמיע, ומכיל מטא-נתונים של המאפיינים (לדוגמה, אם המאפיין הוא int ואילו מצבי שינוי מותרים). ממשק VHAL מבוסס על גישה לנכס (קריאה, כתיבה, הרשמה למינוי), שהוא הפשטה של פונקציה ספציפית.

ממשקי HAL

VHAL משתמש בממשקים הבאים:

  • getAllPropConfigs() יוצר את (vec<VehiclePropConfig>propConfigs)
    רשימת ההגדרות של כל המאפיינים שנתמכים על ידי VHAL. ב-CarService נעשה שימוש רק במאפיינים נתמכים.
  • getPropConfigs(vec<int32_t> props) יוצר את (StatusCode status,vec<VehiclePropConfig> propConfigs);
    החזרת ההגדרות של המאפיינים שנבחרו.
  • set(VehiclePropValue propValue) יוצר (StatusCodestatus);
    כתיבת ערך למאפיין. תוצאת הכתיבה מוגדרת לכל נכס.
  • subscribe(IVehicleCallback callback, vec<SubscribeOptions> options) יוצר (StatusCode status);
    מתחילים לעקוב אחרי שינוי בערך של נכס. בנכס מוגדר תחום, הפונקציה unsubscribe(IVehicleCallback callback, int32_t propId) יוצרת את הפונקציה (StatusCode status);

VHAL משתמש בממשקי הקריאה החוזרת הבאים:

  • oneway onPropertyEvent(vec<VehiclePropValue>propValues);
    מודיע על שינוי בערך נכס הרכב. צריך לעשות זאת רק בנכסים שנרשמו למינוי.
  • oneway onPropertySetError(StatusCode errorCode,int32_t propId,int32_tareaId);
    החזרת שגיאה ברמת VHAL גלובלית או שגיאה לכל מאפיין. שגיאה גלובלית גורמת להפעלה מחדש של HAL, מה שעלול להוביל להפעלה מחדש של רכיבים אחרים (כולל אפליקציות).

מאפייני הרכב

המאפיינים יכולים להיות לקריאה בלבד, לכתיבה בלבד (משמשים להעברת מידע לרמת VHAL) או לקריאה ולכתיבה (התמיכה ברוב המאפיינים היא אופציונלית). כל מאפיין מזוהה באופן ייחודי באמצעות מפתח int32, ויש לו סוג מוגדר מראש (value_type):

  • BYTES
  • BOOLEAN
  • EPOCH_TIME
  • FLOAT
  • FLOAT[]
  • INT32
  • INT32[]
  • INT64
  • INT64[]
  • STRING
  • MIXED

לנכס תחום יכול להיות יותר מערך אחד, בהתאם למספר התחומים שנתמך בנכס.

סוגי אזורים

ב-VHAL מוגדרים כמה סוגי אזורים:

סוג האזור תיאור
GLOBAL הנכס הזה הוא נכס יחיד (singleton) ואין לו כמה אזורים.
WINDOW אזור שמבוסס על חלונות, באמצעות VehicleAreaWindow enum.
MIRROR אזור שמבוסס על מראות, נעשה בו שימוש ב-VehicleAreaMirror enum.
SEAT אזור שמבוסס על מושבים, נעשה בו שימוש ב-enum של VehicleAreaSeat.
DOOR אזור שמבוסס על דלתות, באמצעות VehicleAreaDoor enum.
WHEEL שטח שמבוסס על גלגלים, באמצעות VehicleAreaWheel enum.

כל נכס תחום חייב להשתמש בסוג אזור מוגדר מראש. לכל סוג אזור יש קבוצה של דגלים מוגדרים ב-enum של סוג האזור. לדוגמה, האזור SEAT מגדיר את VehicleAreaSeat enums:

  • ROW_1_LEFT = 0x0001
  • ROW_1_CENTER = 0x0002
  • ROW_1_RIGHT = 0x0004
  • ROW_2_LEFT = 0x0010
  • ROW_2_CENTER = 0x0020
  • ROW_2_RIGHT = 0x0040
  • ROW_3_LEFT = 0x0100
  • ...

מזהי אזורים

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

פריט תיאור
ROW_1_LEFT | ROW_1_RIGHT מזהה האזור חל על שני המושבים הקדמיים.
ROW_2_LEFT ההגדרה חלה רק על המושב האחורי השמאלי.
ROW_2_RIGHT ההגדרה חלה רק על המושב הימני האחורי.

סטטוס הנכס

לכל ערך של נכס יש ערך VehiclePropertyStatus. הסטטוס הנוכחי של הנכס:

פריט תיאור
AVAILABLE הנכס זמין והערך תקין.
UNAVAILABLE ערך הנכס לא זמין כרגע. הנתונים משמשים לתכונות מושבתות באופן זמני בנכס נתמך.
ERROR יש בעיה בנכס הזה.

הגדרת נכס

משתמשים ב-VehiclePropConfig כדי לספק את פרטי ההגדרה של כל נכס. המידע כולל:

משתנה תיאור
access r, w rw
changeMode מייצג את אופן המעקב אחר נכס, בשינוי לעומת מתמשך.
areaConfigs הערכים areaId,‏ min ו-max.
configArray פרמטרים נוספים של הגדרה.
configString מידע נוסף שמוענק כמחרוזת.
minSampleRate maxSampleRate
prop מזהה נכס, int

טיפול במאפייני תחום

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

  • הקריאה get לנכס תחום תמיד כוללת את מזהה האזור בבקשה. לכן, המערכת מחזירה רק את הערך הנוכחי של מזהה האזור המבוקש. אם הנכס הוא גלובלי, מזהה האזור הוא 0.
  • קריאה ל-set לנכס מחולק לאזורים תמיד כוללת את מזהה האזור בבקשה. לכן, רק מזהה האזור המבוקש ישתנה.
  • קריאה ל-subscribe יוצרת אירועים לכל מזהי האזורים בנכס.

קבלת שיחות

במהלך האיפוס, יכול להיות שהערך של המאפיין עדיין לא יהיה זמין כי עדיין לא התקבלה ההודעה התואמת מרשת הרכב. במקרים כאלה, קריאה ל-get אמורה להחזיר את הערך -EAGAIN. לחלק מהנכסים (כמו HVAC) יש מאפיין נפרד של הפעלה/כיבוי. קריאה ל-get למאפיין כזה (כשהוא כבוי) אמורה להחזיר סטטוס UNAVAILABLE במקום שגיאה. לדוגמה, אחזור של טמפרטורת בקרת האקלים

דוגמה ל-VHAL get HVAC

איור 1. אחזור הטמפרטורה של בקרת האקלים (CS = CarService, ‏ VHAL = Vehicle HAL)

הגדרת שיחות

בפעולה אופיינית, קריאה ל-set מובילה לשליחת בקשה לשינוי ברשת הרכבים. קריאה ל-set היא אידיאלית כפעולה אסינכרונית שתוחזר בהקדם האפשרי, אבל היא יכולה להיות גם סינכרונית. יכול להיות שבחלק מהקריאות ל-set נדרשים נתונים ראשוניים, אבל במהלך האינטראקציה הראשונית יכול להיות שהנתונים האלה עדיין לא יהיו זמינים. במקרים כאלה, הקריאה ל-set אמורה להחזיר את הערך StatusCode#TRY_AGAIN. בחלק מהנכסים עם מתגים נפרדים להפעלה ולכיבוי, הערך StatusCode#NOT_AVAILABLE או StatusCode#NOT_AVAILABLE_DISABLED אמור להופיע כשהנכס כבוי ולא ניתן לבצע את הפעולה set. עד שהפרמטר set יופעל, לא בטוח שהפונקציה get תחזיר את אותו הערך שהוגדר. לדוגמה: set HVAC Temperature.

דוגמה להפעלת בקרת אקלים מבוססת-VHAL

איור 2. הגדרת טמפרטורת בקרת האקלים (CS = CarService, VHAL = Vehicle HAL)

טיפול במאפיינים מותאמים אישית

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

  • צריך ליצור את מזהה הנכס באמצעות השדות הבאים:
    • VehiclePropertyGroup:VENDOR
      הקבוצה VENDOR משמשת רק לנכסים מותאמים אישית.
    • VehicleArea
      בוחרים את סוג האזור המתאים.
    • VehiclePropertyType
      בוחרים את סוג הנתונים המתאים. הסוג BYTES מאפשר העברה של נתונים גולמיים, וזה מספיק ברוב המקרים. שליחת נתונים גדולים בתדירות גבוהה באמצעות מאפיינים מותאמים אישית יכולה להאט את הגישה של הרכב כולו לרשת – חשוב להיזהר כשמוסיפים עומס נתונים גדול.
    • Property ID
      בוחרים מזהה של ארבעה ביט למאפיין המותאם אישית.
  • כדי למנוע פיצול של הסביבה העסקית, אסור להשתמש במאפיינים מותאמים אישית כדי ליצור רפליקציה של מאפייני רכב שכבר קיימים ב-SDK (VehiclePropertyIds).
  • ממלאים את השדה VehiclePropConfig.configString בתיאור קצר של המאפיין המותאם אישית. כך הכלים לבדיקת תקינות יוכלו לסמן שכפול לא מכוון של מאפייני רכב קיימים. לדוגמה, "מצב של נורית אזהרה".
  • גישה דרך CarPropertyManager (לרכיבי Java) או דרך ממשק ה-API של שירות רשת הרכב (לרכיבי נייטיב). אין לשנות ממשקי API אחרים של רכב, כי הפעולה הזו עלולה לגרום לבעיות תאימות בעתיד.
  • אחרי שמטמיעים מאפייני ספקים, בוחריםרק את רשימת ההרשאות במערך הערכים (enum) VehicleVendorPermission של מאפייני הספקים. מיפוי של הרשאות של ספקים למאפייני מערכת יפגע ב-CTS וב-VTS.

טיפול במאפייני HVAC

אפשר להשתמש ב-VHAL כדי לשלוט ב-HVAC על ידי הגדרת מאפיינים שקשורים ל-HVAC. רוב נכסי ה-HVAC הם נכסים מחולקים לאזורים, אבל יש כמה נכסים לא מחולקים לאזורים (גלובליים). דוגמאות למאפיינים שהוגדרו:

נכס המטרה
VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET מגדירים טמפרטורה לכל אזור.
VEHICLE_PROPERTY_HVAC_RECIRC_ON בקרה על המחזוריות לכל תחום.

כדי לראות רשימה מלאה של מאפייני בקרת אקלים, מחפשים את VEHICLE_PROPERTY_HVAC_* ב-types.hal. כשבנכס בקרת האקלים נעשה שימוש ב-VehicleAreaSeat, חלים כללים נוספים למיפוי נכס בקרת אקלים מחולק לאזורים למזהי אזורים. כל מושב זמין ברכב חייב להיות חלק ממזהה אזור במערך מזהי האזורים.

דוגמה ראשונה. ברכב יש שני מושבים קדמיים (ROW_1_LEFT, ROW_1_RIGHT) ושלושה מושבים אחוריים (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). ברכב יש שתי יחידות בקרת טמפרטורה: בצד הנהג ובצד הנוסע.

  • קבוצת מיפוי תקינה של מזהי אזורים עבור HVAC_TEMPERATURE SET היא:
    • ROW_1_LEFT | ROW_2_LEFT
    • ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT
  • מיפוי חלופי לאותה הגדרת חומרה הוא:
    • ROW_1_LEFT | ROW_2_LEFT | ROW_2_CENTER
    • ROW_1_RIGHT | ROW_2_RIGHT

דוגמה שנייה. במכונית יש 3 מושבים בשורה הראשונה (ROW_1_LEFT, ROW_1_RIGHT), 3 מושבים בשורה השנייה (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT) ושלוש שורות בשלישית (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). במכונית יש שלוש יחידות בקרת טמפרטורה: צד הנהג, צד הנוסע ואחור. דרך סבירה למיפוי HVAC_TEMPERATURE_SET למזהי אזורים היא כמערך של שלושה רכיבים:

  • ROW_1_LEFT
  • ROW_1_RIGHT
  • ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT

טיפול במאפייני חיישנים

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

ראו את מאפייני החיישנים הנתמכים (ב-types.hal).

שירות מפות לרכב

שירות מפות לרכב (VMS) מספק מנגנון להעברת נתוני מפה בין לקוחות באמצעות ממשק pub/sub, כדי לתמוך בתכונות נפוצות ברכב, כמו מערכות מתקדמות לעזרה לנהג (ADAS). לקוחות יכולים לכלול מערכות רכב שמתקשרות דרך נכס ה-VMS ב-VHAL או באפליקציות Android בעלות הרשאות. הנתונים ששותפו ב-VMS אמורים להיות מוגבלים לנתוני מפה לשימוש במערכות הרכב ובאפליקציות התומכות.

מכונות VMS מיועדת לשימוש רק בהטמעות של Android Automotive. AOSP לא כולל לקוחות שמוגדרים כברירת מחדל שמפרסמים מכונות וירטואליות או נרשמים אליהן. במאפיין VMS ב-VHAL, סוגי ההודעות ומבנה הנתונים מתוארים ב-VHAL 2.0 ב-enum‏ VmsMessageType, שבו מפורטים סוגי ההודעות הנתמכות של VMS. טיפוס ה-enum הזה משמש כמספר השלם הראשון במערך המספרים השלמים של מאפיין הרכב, והוא קובע איך הקוד של שאר ההודעה מפוענח.