API של אשכול מכשירים

השתמש ב-API של Cluster Instrument (API של אנדרואיד) כדי להציג אפליקציות ניווט, כולל מפות Google, בתצוגה משנית במכונית, כגון מאחורי גלגל ההגה בלוח המכשירים. דף זה מתאר כיצד ליצור שירות כדי לשלוט באותה תצוגה משנית ולאחר מכן לשלב את השירות עם CarService כך שאפליקציות ניווט יוכלו להציג ממשק משתמש.

טרמינולוגיה

המונחים הבאים משמשים בדף זה:

דרישות מוקדמות

כדי לפתח את האינטגרציה, הקפידו על האלמנטים הבאים:

• סביבת פיתוח אנדרואיד. כדי להגדיר את סביבת הפיתוח של Android, ראה דרישות בנייה .
• הורד את קוד המקור של אנדרואיד. קבל את הגרסה העדכנית ביותר של קוד המקור של אנדרואיד מסניף pi-car-release (או מאוחר יותר) בכתובת https://android.googlesource.com .
• יחידת ראש (HU). מכשיר אנדרואיד המסוגל להריץ אנדרואיד 9 (או מאוחר יותר). מכשיר זה חייב להיות בעל תצוגה משלו ולהיות מסוגל להבהב את התצוגה עם גרסאות חדשות של אנדרואיד.
• אשכול מכשירים הוא אחד מהבאים:
  • תצוגה משנית פיזית מחוברת ל-HU. אם חומרת המכשיר והקרנל תומכים בניהול של מספר תצוגות.
  • יחידה עצמאית. כל יחידה חישובית המחוברת ל-HU באמצעות חיבור רשת, המסוגלת לקלוט ולהציג זרם וידאו בתצוגה משלה.
  • תצוגה מדומה. במהלך הפיתוח, אתה יכול להשתמש באחת מהסביבות המחקות הבאות:
    • תצוגות משניות מדומה. כדי לאפשר תצוגה משנית מדומה בכל הפצת אנדרואיד של AOSP, עבור אל הגדרות אפשרויות המפתח באפליקציית מערכת ההגדרות ולאחר מכן בחר סימולציה של תצוגות משניות. תצורה זו מקבילה לחיבור צג משני פיזי, עם המגבלה שתצוגה זו מונחת על הצג הראשי.
    • אשכול מכשירים מדומה. אמולטור אנדרואיד הכלול ב-Android Automotive מספק אפשרות להציג אשכול מכשירים עם שירות ClusterRenderingService מחובר לתצוגה המשנית.
    אמולטור _qemu-pipes . שירות ClusterRenderingService מחובר לתצוגה המשנית. יישומו של אשכול מכשירים כדי להתחבר לתצוגה החיצונית המדומה הזו.

ארכיטקטורת אינטגרציה

רכיבי אינטגרציה

כל שילוב של ה-API של אשכול מכשירים מורכב משלושת הרכיבים הבאים:

• CarService
• אפליקציות ניווט
• שירות אשכול מכשירים OEM

שירות מכוניות

CarService מתווך בין אפליקציות ניווט לרכב, ומבטיח שרק אפליקציית ניווט אחת פעילה בכל זמן נתון ורק אפליקציות עם הרשאת android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL יכולות לשלוח נתונים לרכב.

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

לצורך הטמעת אשכול מכשירים, יצרני OEM לרכב חייבים ליצור הטמעה מותאמת אישית של InstrumentClusterRendererService ולעדכן את שירות ClusterRenderingService מחובר לתצוגה המשנית.

בעת רינדור של אשכול מכשירים, במהלך תהליך האתחול CarService קורא את מפתח InstrumentClusterRendererService של שירות ClusterRenderingService מחובר לתצוגה המשנית. כדי לאתר יישום של InstrumentClusterService . ב-AOSP, ערך זה מצביע על שירות העיבוד של יישום אשכולות לדוגמה של Navigation State API:

<string name="instrumentClusterRendererService">
android.car.cluster/.ClusterRenderingService
</string>

השירות הנזכר בערך זה מאותחל ומחויב ל- CarService . כאשר אפליקציות ניווט, כמו מפות Google, מבקשות CarInstrumentClusterManager , CarService מספקת מנהל שמעדכן את מצב Cluster Instrument מ- InstrumentClusterRenderingService המחובר. (במקרה זה, מחויב מתייחס לשירותי אנדרואיד .)

שירות אשכול מכשירים

יצרני OEM חייבים ליצור חבילת אנדרואיד (APK) המכילה תת-סיווג של שירות ClusterRenderingService המחובר לתצוגה המשנית. שירות ClusterRenderingService מחובר לתצוגה המשנית. לדוגמא.

שיעור זה משרת שתי מטרות:

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

למטרה הראשונה, יישומי OEM של InstrumentClusterRendererService חייבות לאתחל את התצוגה המשנית המשמשת להצגת מידע על מסכים בתא המכונית ולהעביר מידע זה ל- CarService על ידי קריאה לשיטות InstrumentClusterRendererService.setClusterActivityOptions() ו- InstrumentClusterRendererService.setClusterActivityState() .

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

רצף אינטגרציה

התרשים הבא ממחיש את היישום של מצב ניווט שמציג עדכונים:

באיור זה, צבעים מציינים את הדברים הבאים:

• צהוב. CarService ו- CarNavigationStatusManager מסופקים על ידי פלטפורמת אנדרואיד. למידע נוסף, ראה רכב ו- CAR_NAVIGATION_SERVICE .
• טורקיז. InstrumentClusterRendererService מיושם על ידי ה-OEM.
• סָגוֹל. אפליקציית הניווט המיושמת על ידי גוגל ומפתחי צד שלישי.
• ירוק. CarAppFocusManager . למידע נוסף, ראה שימוש בממשק ה-API של CarAppFocusManager להלן וב- CarAppFocusManager .

זרימת המידע על מצב הניווט עוקבת אחר הרצף הזה:

1. CarService מאתחל את InstrumentClusterRenderingService .
2. במהלך האתחול, InstrumentClusterRenderingService מעדכן CarService עם:
   1. מאפייני תצוגה של אשכול מכשירים, כגון גבולות לא ברורים (ראה פרטים נוספים על גבולות לא ברורים מאוחר יותר).
   2. אפשרויות פעילות הדרושות להפעלת פעילויות בתוך תצוגת אשכול המכשירים (ראה פרטים נוספים ב- ActivityOptions .
3. אפליקציית ניווט (כגון מפות Google עבור Android Automotive או כל אפליקציית מפות עם ההרשאות הנדרשות):
   1. מקבל CarAppFocusManager באמצעות מחלקת Car מ-car-lib.
   2. לפני שמתחילים הנחיות מפורטות, קריאות ל- CarAppFocusManager.requestFocus() כדי להעביר את CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION כפרמטר appType .
4. CarAppFocusManager מעביר בקשה זו ל- CarService . אם יאושר, CarService בודק את חבילת אפליקציית הניווט ומאתר פעילות המסומנת בקטגוריה android.car.cluster.NAVIGATION .
5. אם נמצא, אפליקציית הניווט משתמשת ב- ActivityOptions שדווחו על ידי InstrumentClusterRenderingService כדי להפעיל את הפעילות וכוללת את מאפייני התצוגה של אשכול מכשירים כתוספות בכוונה.

שלב את ה-API

הטמעת InstrumentClusterRenderingService חייבת:

• הגדר כשירות יחיד על ידי הוספת הערך הבא ל-AndroidManifest.xml. זה הכרחי כדי להבטיח שעתק יחיד של שירות אשכול המכשירים פועל, אפילו במהלך אתחול ומעבר משתמש:
  android:singleUser="true"
• החזק את הרשאת המערכת BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE . זה מבטיח שרק שירות העיבוד של אשכול המכשירים הכלול כחלק מתמונת מערכת אנדרואיד יהיה תמיד כבול על ידי CarService :

  <uses-permission android:name="android.car.permission.BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE"/>
  

הטמעת InstrumentClusterRenderingService

כדי לבנות את השירות:

1. כתוב מחלקה המשתרעת משירות ClusterRenderingService מחובר לתצוגה המשנית.
ולאחר מכן הוסף ערך מתאים לקובץ AndroidManifest.xml שלך. מחלקה זו שולטת בתצוגת אשכול המכשירים ויכולה ( אופציונלית ) להציג נתוני Navigation State API.
2. במהלך onCreate() , השתמש בשירות זה כדי לאתחל את התקשורת עם חומרת העיבוד. האפשרויות כוללות:
   • קבע את התצוגה המשנית שתשמש עבור אשכול המכשירים.
   • צור תצוגה וירטואלית כך שאפליקציית אשכול הכלים תעבד ותשדר את התמונה המעובדת ליחידה חיצונית (באמצעות פורמט הזרמת וידאו, כגון H.264).
3. כאשר התצוגה המצוינת למעלה מוכנה, שירות זה חייב לקרוא ל- InstrumentClusterRenderingService#setClusterActivityLaunchOptions() כדי להגדיר את ה- ActivityOptions המדויק שיש להשתמש בהם כדי להציג פעילות באשכול הכלים. השתמש בפרמטרים הבאים:
   • קטגוריה. שירות ClusterRenderingService מחובר לתצוגה המשנית.
   • ActivityOptions. מופע ActivityOptions שניתן להשתמש בו כדי להפעיל פעילות באשכול המכשירים. לדוגמה, מתוך היישום לדוגמה Instrument Cluster ב-AOSP:

     getService().setClusterActivityLaunchOptions(
        CATEGORY_NAVIGATION,
        ActivityOptions.makeBasic()
           .setLaunchDisplayId(displayId));
     

4. כאשר Cluster Instrument מוכן להצגת פעילויות, שירות זה חייב להפעיל את InstrumentClusterRenderingService#setClusterActivityState() . השתמש בפרמטרים הבאים:
   • שירות ClusterRenderingService category מחובר לתצוגה המשנית.
   • חבילת state שנוצר עם שירות ClusterRenderingService מחובר לתצוגה המשנית.
   הקפד לספק את הנתונים הבאים:
   • visible מציין את אשכול המכשירים כגלוי ומוכן להצגת תוכן.
   • unobscuredBounds מלבן המגדיר את האזור בתוך תצוגת אשכול המכשירים שבו בטוח להציג תוכן. לדוגמה, אזורים המכוסים על ידי חוגים ומדדים.
5. עוקף את שיטת Service#dump() ודווח על מידע סטטוס שימושי לניפוי באגים (ראה dumpsys למידע נוסף).

יישום InstrumentClusterRenderingService לדוגמה

הדוגמה הבאה מתארת ​​יישום InstrumentClusterRenderingService , שיוצר תצוגה VirtualDisplay להצגת תוכן אשכול הכלים על צג פיזי מרוחק.

לחלופין, קוד זה יכול להעביר את displayId של צג משני פיזי המחובר ל-HU, אם ידוע שאחד כזה זמין.

/**
* Sample {@link InstrumentClusterRenderingService} implementation
*/
public class SampleClusterServiceImpl extends InstrumentClusterRenderingService {
   // Used to retrieve or create displays
   private final DisplayManager mDisplayManager;
   // Unique identifier for the display to be used for instrument
   // cluster
   private final String mUniqueId = UUID.randomUUID().toString();
   // Format of the instrument cluster display
   private static final int DISPLAY_WIDTH = 1280;
   private static final int DISPLAY_HEIGHT = 720;
   private static final int DISPLAY_DPI = 320;
   // Area not covered by instruments
   private static final int DISPLAY_UNOBSCURED_LEFT = 40;
   private static final int DISPLAY_UNOBSCURED_TOP = 0;
   private static final int DISPLAY_UNOBSCURED_RIGHT = 1200;
   private static final int DISPLAY_UNOBSCURED_BOTTOM = 680;
   @Override
   public void onCreate() {
      super.onCreate();
      // Create a virtual display to render instrument cluster activities on
      mDisplayManager = getSystemService(DisplayManager.class);
      VirtualDisplay display = mDisplayManager.createVirtualDisplay(
          mUniqueId, DISPLAY_WIDTH, DISPLAY_HEIGHT, DISPLAY_DPI, null,
          0 /* flags */, null, null);
      // Do any additional initialization (e.g.: start a video stream
      // based on this virtual display to present activities on a remote
      // display).
      onDisplayReady(display.getDisplay());
}
private void onDisplayReady(Display display) {
    // Report activity options that should be used to launch activities on
    // the instrument cluster.
    String category = CarInstrumentClusterManager.CATEGORY_NAVIGATION;
    ActionOptions options = ActivityOptions.makeBasic()
        .setLaunchDisplayId(display.getDisplayId());
    setClusterActivityOptions(category, options);
    // Report instrument cluster state.
    Rect unobscuredBounds = new Rect(DISPLAY_UNOBSCURED_LEFT,
        DISPLAY_UNOBSCURED_TOP, DISPLAY_UNOBSCURED_RIGHT,
        DISPLAY_UNOBSCURED_BOTTOM);
    boolean visible = true;
    ClusterActivityState state = ClusterActivityState.create(visible,
       unobscuredBounds);
    setClusterActivityState(category, options);
  }
}

השתמש בממשק ה-API של CarAppFocusManager

ה-API של CarAppFocusManager מספק שיטה בשם getAppTypeOwner() , המאפשרת לשירות האשכולות שנכתבו על ידי יצרני OEM לדעת לאיזו אפליקציית ניווט יש מיקוד ניווט בכל זמן נתון. יצרני OEM יכולים להשתמש בשיטה הקיימת CarAppFocusManager#addFocusListener() ולאחר מכן להשתמש ב- getAppTypeOwner() כדי ללמוד לאיזו אפליקציה יש מיקוד. עם מידע זה, יצרני OEM יכולים:

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

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

השתמש בשיטת CarAppFocusManager#addFocusListener(..) כדי להאזין לשינויים במיקוד האפליקציה:

import android.car.CarAppFocusManager;

...

Car car = Car.createCar(this);
mAppFocusManager = (CarAppFocusManager)car.getCarManager(Car.APP_FOCUS_SERVICE);
mAppFocusManager.addFocusListener(this, CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION);

...

public void onAppFocusChanged(int appType, boolean active) {
    // Use the CarAppFocusManager#getAppTypeOwner(appType) method call
    // to retrieve a list of active package names
}

השתמש בשיטת CarAppFocusManager#getAppTypeOwner(..) כדי לאחזר את שמות החבילות של הבעלים הנוכחי של סוג אפליקציה נתון שנמצא בפוקוס. שיטה זו עשויה להחזיר יותר משם חבילה אחד אם הבעלים הנוכחי משתמש בתכונה android:sharedUserId .

import android.car.CarAppFocusManager;

...

Car car = Car.createCar(this);
mAppFocusManager = (CarAppFocusManager)car.getCarManager(Car.APP_FOCUS_SERVICE);
List<String> focusOwnerPackageNames = mAppFocusManager.getAppTypeOwner(
              CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION);

if (focusOwnerPackageNames == null || focusOwnerPackageNames.isEmpty()) {
        // No Navigation app has focus
        // OEM may choose to show their default cluster view
} else {
       // focusOwnerPackageNames
       // Use the PackageManager to retrieve the cluster activity for the package(s)
       // returned in focusOwnerPackageNames
}

...

נספח: השתמש באפליקציה לדוגמה

AOSP מספקת אפליקציה לדוגמה המיישמת את ממשק ה-API של Navigation State.

כדי להפעיל את האפליקציה לדוגמה הזו:

1. בנה והבזק את Android Auto ב-HU נתמך. השתמש בבניין אנדרואיד ובהוראות המהבהבות הספציפיות למכשיר שלך. להנחיות, ראה שימוש בלוחות עזר .
2. חבר צג משני פיזי ל-HU (אם נתמך) או הפעל את ה-HU המשני הווירטואלי:
   1. בחר מצב מפתח באפליקציית ההגדרות.
   2. עבור אל הגדרות > מערכת > מתקדם > אפשרויות מפתחים > הדמיית תצוגות משניות .
3. הפעל מחדש את ה-HU. שירות ClusterRenderingService מחובר לתצוגה המשנית.
4. כדי להפעיל את אפליקציית KitchenSink:
   1. פתח את המגירה.
   2. עבור אל Inst. אשכול .
   3. לחץ על התחל METADATA .

KitchenSink מבקש NAVIGATION focus, אשר מורה לשירות DirectRenderingCluster להציג ממשק משתמש מדומה באשכול המכשיר.