הגדרות נכס

כל נכס נתמך מוגדר על ידי הגדרת נכס שמוגדרת באמצעות מבנה VehiclePropConfig, ויש לו את השדות הבאים.

שדה תיאור
prop

מזהה הנכס. הערך צריך להיות אחד ממאפייני המערכת המוגדרים מתוך VehicleProperty.aidl או מאפיין של ספק. מזהה הנכס נוצר באמצעות פעולת OR ברמת הביטים של השדות הבאים (מימין לשמאל):

  • ‫(0x00000000) 16 ביטים: מזהה ייחודי בטווח 0x0100 עד 0xffff.
  • ‫(0x00000000) 8 ביטים: סוגי מאפיינים שמגדירים את הסוג של המאפיין.
  • ‫(0x00000000) 4 ביטים: סוגי אזורים.
  • ‫(0x00000000) 4 ביטים: VehiclePropertyGroup הערך הוא SYSTEM (0x10000000) או VENDOR (0x20000000). במאמר מאפייני ספקים מפורטים המאפיינים שאפשר להתאים אישית.

לדוגמה,
INFO_VIN (0x11100100) = UniqueID (0x00000100) | VehiclePropertyType.STRING (0x00100000) | VehicleArea.GLOBAL (0x01000000) | VehiclePropertyGroup.SYSTEM (0x10000000)
access
  • מצב הגישה לנכס. חייב להיות אחד מהערכים הבאים: READ, WRITE או READ_WRITE.
  • למאפייני מערכת, הערך צריך להיות אחד ממצבי הגישה המוגדרים שמתועדים ב-VehicleProperty.aidl.
  • בנכסים עם גישה לפי אזור, זהו קבוצת המשנה המקסימלית של הגישה לפי אזור. לדוגמה, אם בנכסים יש שני אזורים עם גישה READ ו-READ_WRITE, צריך להגדיר את הערך הזה כ-READ.
changeMode
  • שינוי המצב של הנכס. חייב להיות אחד מהערכים הבאים: STATIC, ON_CHANGE או CONTINUOUS. ‫STATIC פירושו שערך המאפיין לא משתנה אף פעם אחרי אתחול המערכת. ‫ON_CHANGE מציין ש-VHAL צריך לדווח כשהערך משתנה. ‫CONTINUOUS פירושו שערך המאפיין משתנה באופן רציף, וממשק VHAL צריך לדווח על סמך קצב הדגימה של המינוי.
  • למאפייני מערכת, הערך הזה צריך להיות שווה למצב השינוי שמתועד ב-VehicleProperty.aidl.
configArray מערך אופציונלי שמכיל הגדרות ספציפיות למאפיין. אפשר להשאיר את השדה ריק. למאפייני מערכת מסוימים, למשל GEAR_SELECTION, למערך ההגדרות יש משמעות מיוחדת והוא חייב להיות מוגדר.
configString מחרוזת אופציונלית שמכילה הגדרה ספציפית למאפיין. אפשר להשאיר את השדה ריק.
minSampleRate וגם maxSampleRate קצב הדגימה המינימלי והמקסימלי הנתמך של מאפיין רציף (בהרץ). לא נעשה שימוש אם הנכס לא רציף. ההטמעה של VHAL צריכה לאפשר את ההשגה של minSampleRate ושל maxSampleRate. לא צריך לתמוך בכל קצב דגימה בין המינימום למקסימום.

סוגי נכסים

מוגדר כסוגי enum ב-VehiclePropertyType.aidl. בטבלה הבאה מפורטים סוגי הנכסים הנתמכים.

סוג הנכס ערך תיאור
STRING 0x00100000 מאפיין מחרוזת, משתמש בשדה stringValue ב-Vehicle property value.
BOOLEAN 0x00200000 Boolean, משתמש ברכיב הראשון בשדה int32Values בערך מאפיין הרכב. ‫0 פירושו false, ‫None 0 פירושו true.
INT32 0x00400000 Integer, משתמש ברכיב הראשון בשדה int32Values בערך מאפיין הרכב.
INT32_VEC 0x00410000 Integer[], משתמש ברכיבים בשדה int32Values ב-Vehicle property value.
INT64 0x00500000 נכס ארוך, משתמש ברכיב הראשון בשדה int64Values בערך מאפיין הרכב.
INT64_VEC 0x00510000 Long[], משתמש ברכיבים בשדה int64Values בVehicle property value.
FLOAT 0x00600000 Float, משתמש ברכיב הראשון בשדה floatValues בערך מאפיין הרכב.
FLOAT_VEC 0x00610000 Float[], משתמש ברכיבים בשדה floatValues בVehicle property value.
BYTES 0x00700000 byte[], משתמש ברכיבים בשדה byteValues בVehicle property value.
MIXED 0x00e00000 נכס מסוג מעורב. כל שילוב של סוגים סקלריים או וקטוריים. הפורמט המדויק צריך להיות מוגדר במערך ההגדרות בהגדרות המאפיין.

במאפיינים מסוג MIXED של ספקים, צריך להגדיר את configArray בפורמט הבא:

  • ‫configArray[0], הערך 1 מציין שהמאפיין הוא String
  • ‫configArray[1], הערך 1 מציין שהמאפיין הוא Boolean
  • ‫configArray[2], הערך 1 מציין שלמאפיין יש ערך Integer
  • configArray[3], המספר מציין את הגודל של Integer[] בנכס
  • ‫configArray[4], הערך 1 מציין שהמאפיין הוא Long
  • configArray[5], המספר מציין את הגודל של Long[] בנכס
  • ‫configArray[6], הערך 1 מציין שהמאפיין הוא Float
  • configArray[7], המספר מציין את הגודל של Float[] בנכס
  • ‫configArray[8], המספר מציין את הגודל של byte[] בנכס.

לדוגמה, configArray = {1, 1, 1, 3, 0, 0, 0, 0, 0} מציין שלמאפיין יש ערך String, ערך Boolean, ערך Integer ומערך עם שלושה מספרים שלמים.

הגדרת מזהה אזור

בנוסף, כל הגדרת נכס יכולה להכיל רשימה של הגדרות מזהי אזורים. הרשימה הזו היא אופציונלית בנכסים גלובליים ונדרשת בנכסים אזוריים (נכסים עם כמה אזורים נתמכים). לכל הגדרה של מזהה אזור יש את השדות הבאים.

שדה תיאור
areaId המזהה של האזור הזה. איך מוצאים מזהי אזורים
minInt32Value וגם maxInt32Value
  • ערך מינימלי ומקסימלי אופציונלי למאפיינים מסוג INT32 בזמן האתחול. חובה להזין 0 לכל שאר הסוגים. המערכת מתעלמת מהמאפיין אם שני הערכים הם 0.
  • בנכס גלובלי, אם צריך להגדיר ערך מינימלי ומקסימלי, צריך להשתמש בהגדרת אזור אחת עם מזהה האזור 0.
  • הערך הזה הוא סטטי ולא ישתנה גם אם ערך המינימום או המקסימום ישתנה בזמן הריצה. מטמיעים את IVehicle#getMinMaxSupportedValue לערך דינמי מינימלי או מקסימלי.
minInt64Value וגם maxInt64Value
  • ערך מינימלי ומקסימלי אופציונלי למאפיינים מסוג INT64 בזמן האתחול. חובה להזין 0 לכל שאר הסוגים. המערכת מתעלמת מהמאפיין אם שני הערכים הם 0.
  • בנכס גלובלי, אם צריך להגדיר ערך מינימלי ומקסימלי, צריך להשתמש בהגדרת אזור אחת עם מזהה האזור 0.
  • הערך הזה הוא סטטי ולא ישתנה גם אם ערך המינימום או המקסימום ישתנה בזמן הריצה. מטמיעים את IVehicle#getMinMaxSupportedValue לערך דינמי מינימלי או מקסימלי.
minFloatValue וגם maxFloatValue
  • ערך מינימלי ומקסימלי אופציונלי למאפיינים מסוג Float בזמן האתחול. חובה להזין 0 לכל שאר הסוגים. המערכת תתעלם מהמאפיין אם שני הערכים הם 0.0.
  • בנכס גלובלי, אם צריך להגדיר ערך מינימלי ומקסימלי, צריך להשתמש בהגדרת אזור אחת עם מזהה האזור 0.
  • הערך הזה הוא סטטי ולא ישתנה גם אם ערך המינימום או המקסימום ישתנה בזמן הריצה. מטמיעים את IVehicle#getMinMaxSupportedValue לערך דינמי מינימלי או מקסימלי.
(חדש ב-Android 14)
supportedEnumValues
  • רשימה אופציונלית של ערכים נתמכים בזמן האתחול, אם המאפיין מוגדר כמאפיין מסוג enum. אם לא מציינים ערך (ריק) או אם הגרסה של Android היא לפני גרסה 14, המערכת מניחה שכל ערכי ה-enum נתמכים.
  • בנכס גלובלי, אם צריך להגדיר ערכי enum נתמכים, צריך להשתמש בהגדרת אזור אחת עם מזהה האזור 0.
  • הערך הזה הוא סטטי ולא ישתנה גם אם הערכים הנתמכים ישתנו בזמן הריצה. מטמיעים את IVehicle#getSupportedValuesLists לערכים דינמיים נתמכים.
  • ההגדרה הזו רלוונטית רק למאפיינים מסוג enum. בשאר הסוגים, השדה הזה צריך להיות ריק. כדי להציג ערכים נתמכים לסוגים אחרים שאינם enum, משתמשים בפונקציה IVehicle#getSupportedValuesLists.
(חדש ב-Android 15)
supportVariableUpdateRate
  • האם יש תמיכה בקצב עדכון משתנים. ההגדרה הזו רלוונטית רק לנכסים רציפים.
  • אם הערך הוא true, האפליקציה יכולה להפעיל קצב עדכון משתנה למינוי כדי לקבל אירועי עדכון של מאפיינים רק כשערך המאפיין משתנה (כלומר, מאפיינים רציפים מטופלים כמאפיינים שמשתנים).
  • אם כל המנויים של נכס מסוים מפעילים קצב עדכון משתנה, בקשת המינוי ל-VHAL מפעילה קצב עדכון משתנה עבור הנכס, ו-VHAL צריך לשלוח אירועי עדכון של הנכס רק כשערך הנכס משתנה.
  • אם מנוי כלשהו מבקש קצב עדכון קבוע, בקשת המינוי ל-VHAL משביתה את קצב העדכון המשתנה של המאפיין, ו-AAOS מסנן את האירועים הכפולים עבור הלקוחות שמבקשים קצב עדכון משתנה.
  • מומלץ מאוד לתמוך בקצב עדכון משתנה לכל המאפיינים הרציפים שאינם פעימות לב, כדי לשפר את הביצועים, אלא אם נתוני המאפיינים גדולים (לדוגמה, מערך בייטים בגודל 1k) ועשויים לתפוס כמות גדולה של זיכרון לצורך שמירה במטמון.
(חדש ב-Android 16)
hasSupportedValueInfo
  • אם הערך הוא לא null, המאפיין הזה מציין ערכים מינימליים או מקסימליים נתמכים, או רשימה של ערכים נתמכים.
  • השדה הזה קובע אם ממשקי ה-API הדינמיים של הערכים הנתמכים: getMinMaxSupportedValue, ‏ getSupportedValuesLists, subscribeSupportedValueChange, ‏ unsubscribeSupportedValueChange נתמכים עבור מזהה המאפיין ומזהה האזור הזה.
  • אם לא null, צריך להטמיע את ממשקי ה-API האלה ב-VHAL עבור מזהה הנכס ומזהה האזור האלה.
  • אם null או ב-Android בגרסה 15 ומטה, אין תמיכה בערכים דינמיים של מזהה הנכס ומזהה האזור. הלקוח חייב להשתמש במידע הסטטי על הערכים הנתמכים שמופיע בהגדרת מאפייני הרכב.

סוגי אזורים

מוגדר כסוגי enum ב-VehicleArea.aidl. בהמשך מפורטים סוגי האזורים הנתמכים.

סוג האזור ערך תיאור
GLOBAL 0x01000000 הנכס הזה הוא נכס גלובלי ואין לו אזורים מרובים.
חלון 0x03000000 אזור שמבוסס על חלונות, נעשה בו שימוש ב-VehicleAreaWindow enum.
MIRROR 0x04000000 אזור שמבוסס על שיקופים, נעשה שימוש ב-VehicleAreaMirror enum.
סיאט 0x05000000 השטח מבוסס על מושבים, ומשתמש ב-enum‏ VehicleAreaSeat.
DOOR 0x06000000 השטח מבוסס על דלתות, נעשה שימוש ב-enum‏ VehicleAreaDoor.
גלגל 0x07000000 השטח מבוסס על גלגלים, ומשתמש ב-enum‏ VehicleAreaWheel.

בכל נכס עם אזורים צריך להשתמש בסוג אזור שהוגדר מראש. לכל סוג אזור יש קבוצה של דגלים בינאריים (bit flags) שמוגדרים בספירה (enum) של סוג האזור. לדוגמה, אזור המושב מגדיר את הערכים הבאים של enum:‏ VehicleAreaSeat:

  • 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 ההגדרה חלה רק על המושב האחורי הימני.

מידע נוסף זמין במאמר בנושא מיזוג אוויר.