Kombi-Instrumenten-API

Verwenden Sie die Instrument Cluster API (Android API), um Navigations-Apps, einschließlich Google Maps, auf einem zweiten Display in einem Auto, wie etwa hinter dem am Lenkrad an der Instrumentenkonsole. Auf dieser Seite wird beschrieben, wie Sie ein um diese sekundäre Anzeige zu steuern und den Dienst mit CarService, damit Navigations-Apps eine Benutzeroberfläche.

Terminologie

Auf dieser Seite werden die folgenden Begriffe verwendet.

AutoInstrumentClusterManager
Eine CarManager-Instanz, die es externen Apps ermöglicht, eine Aktivität auf dem Gerät zu starten an das Kombi-Instrument an. Sie erhalten Callbacks, wenn das Kombi-Instrument angezeigt wird. Aktivitäten.
Automanager
Basisklasse aller Administratoren, die von externen Apps für die Interaktion mit autospezifischen Apps verwendet werden die von CarService implementiert wurden.
CarService
Android-Plattformdienst für die Kommunikation zwischen externen Apps (einschließlich Google Maps) und fahrzeugspezifische Funktionen wie der Zugriff auf das Kombi-Instrument.
Ziel
Das endgültige Ziel, zu dem das Fahrzeug fahren soll.
Voraussichtliche Ankunftszeit
Die voraussichtliche Ankunftszeit an einem Ziel.
Haupteinheit (HU)
Primäre Recheneinheit, die in einem Auto eingebettet ist. Die HU führt den gesamten Android-Code aus und ist mit dem zentralen Display im Auto verbunden.
Kombi-Instrument
Sekundäres Display hinter dem Lenkrad und zwischen dem Auto Instrumente. Dies kann eine unabhängige Recheneinheit sein, HU über das interne Netzwerk des Autos (CAN-Bus) oder einen sekundären Bildschirm an die HU gebunden.
InstrumentClusterRenderingService
Basisklasse für den Dienst, der für die Schnittstelle mit dem Kombi-Instrument verwendet wird Display. OEMs müssen eine Erweiterung dieser Klasse bereitstellen, die mit der OEM-spezifischen Hardware.
KitchenSink App
In Android Automotive enthaltene Test-App.
Route
Ein bestimmter Pfad, auf dem ein Fahrzeug zu einem Ziel fährt.
Singleton
Ein Android-Dienst mit dem Attribut android:singleUser. Bei Höchstens eine Instanz des Dienstes wird auf dem Android-System ausgeführt.

Voraussetzungen

Stellen Sie sicher, dass Sie diese Elemente haben, bevor Sie fortfahren:

  • Android-Entwicklungsumgebung So richten Sie das Android-Gerät ein: Entwicklungsumgebung, siehe Build-Anforderungen
  • Laden Sie den Android-Quellcode herunter. Aktuelle Version von den Android-Quellcode aus dem Zweig „pi-car-release“ (oder höher) unter https://android.googlesource.com verwenden.
  • Haupteinheit (HU): Ein Android-Gerät, auf dem Android 9 oder höher. Dieses Gerät muss ein eigenes Display haben und das Display mit neuen Android-Builds blinken lässt.
  • Kombi-Instrument ist eines der folgenden: <ph type="x-smartling-placeholder">
      </ph>
    • Physisches sekundäres Display an der HU. Wenn die Gerätehardware und der Kernel unterstützen die Verwaltung mehrerer Bildschirme.
    • Unabhängige Einheit. Recheneinheiten, die mit der HU über eine Netzwerkverbindung, die einen Videostream empfangen und wiedergeben kann auf ihrem eigenen Display.
    • Emuliertes Display Während der Entwicklung können Sie diesen emulierten Umgebungen: <ph type="x-smartling-placeholder">
        </ph>
      • Simulierte sekundäre Displays. Um ein simuliertes sekundären Bildschirm in einer beliebigen AOSP-Android-Distribution öffnen, rufen Sie die Entwickleroptionen auf. in der System-App Einstellungen und wählen Sie dann Simulieren Sie sekundäre Bildschirme Diese Konfiguration entspricht dem Anhängen einer physischen sekundären mit der Einschränkung, dass diese Anzeige Display.
      • Emuliertes Kombi-Instrument Inklusive Android Emulator mit AAOS bietet eine Option zum Anzeigen eines Kombi-Instruments mit ClusterRenderingService zurückgegeben wird.

Integrationsarchitektur

Integrationskomponenten

Jede Integration der Instrument Cluster API umfasst die folgenden drei Komponenten:

  • CarService
  • Navigations-Apps
  • OEM-Kombi-Instrumentendienst

Integrationskomponenten

CarService

CarService vermittelt zwischen Navigations-Apps und dem Auto und sorgt dafür, dass eine Navigations-App zu einem bestimmten Zeitpunkt aktiv ist und nur Apps mit der Mit der Berechtigung „android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL“ können Daten gesendet werden bis zum Auto.

CarService startet das Bootstrapping aller fahrzeugspezifischen Dienste und bietet Zugriff auf diese Dienste durch eine Reihe von Managern. Um mit den Diensten zu interagieren, Apps, die im Auto ausgeführt werden, können auf diese Manager zugreifen.

Für die Implementierung von Kombi-Instrumenten müssen OEMs aus der Automobilbranche eine benutzerdefinierte InstrumentClusterRendererService implementiert und die ClusterRenderingService zurückgegeben wird.

Beim Rendern eines Kombi-Instruments wird während des Bootvorgangs CarService liest den InstrumentClusterRendererService-Schlüssel des ClusterRenderingService um eine InstrumentClusterService-Implementierung zu finden. In AOSP wird dieser Eintrag verweist auf den Renderingdienst der Beispiel-Clusterimplementierung für die Navigation State API:

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

Der Dienst, auf den in diesem Eintrag verwiesen wird, wird initialisiert und an CarService Wenn Navigations-Apps wie Google Maps eine CarInstrumentClusterManager hat CarService einen Manager bereitgestellt, der aktualisiert den Status des Kombi-Instruments aus der gebundenen InstrumentClusterRenderingService. (In diesem Fall bezieht sich bound auf Android Dienste.)

Kombiinstrument-Service

OEMs müssen ein Android-Paket (APK) erstellen, das eine Unterklasse von ClusterRenderingService zurückgegeben wird.

Diese Klasse dient zwei Zwecken:

  • Bietet eine Schnittstelle zwischen Android und dem Rendering-Gerät des Kombi-Instruments Dies ist der Zweck dieser Seite.
  • Empfängt und rendert Aktualisierungen des Navigationsstatus, z. B. detaillierte Routenführung Navigationsführung.

Beim ersten Zweck: OEM-Implementierungen von InstrumentClusterRendererService muss das sekundäre Display initialisieren, das zum Rendern von Informationen auf Bildschirmen im Innenraum des Autos verwendet wird. können Sie diese Informationen durch Aufrufen an CarService InstrumentClusterRendererService.setClusterActivityOptions() und InstrumentClusterRendererService.setClusterActivityState()-Methoden.

Für die zweite Funktion muss der Kombi-Instrumentendienst Folgendes bereitstellen: Implementierung der ClusterRenderingService Schnittstelle, die Ereignisse zur Aktualisierung des Navigationsstatus empfängt. Diese sind als eventType und Ereignisdaten, die in einem Bundle codiert sind.

Integrationssequenz

Das folgende Diagramm veranschaulicht die Implementierung eines Navigationsstatus. zum Rendern von Updates:

Integrationssequenz

In dieser Abbildung stehen Farben für Folgendes:

  • Gelb. CarService und CarNavigationStatusManager die von der Android-Plattform bereitgestellt werden. Weitere Informationen finden Sie unter Auto und CAR_NAVIGATION_SERVICE
  • Cyan. InstrumentClusterRendererService implementiert durch den OEM.
  • Lila. Die von Google und Drittanbietern implementierte Navigations-App zu entwickeln.
  • Grün: CarAppFocusManager. Weitere Informationen finden Sie unter CarAppFocusManager API verwenden unten und CarAppFocusManager.

Der Informationsfluss zum Navigationsstatus folgt dieser Reihenfolge:

  1. CarService initialisiert InstrumentClusterRenderingService.
  2. Während der Initialisierung wird InstrumentClusterRenderingService aktualisiert CarService mit: <ph type="x-smartling-placeholder">
      </ph>
    1. Anzeigeeigenschaften des Kombi-Instruments, z. B. nicht verdeckte Grenzen (Weitere Details zu nicht verdeckten Grenzen finden Sie weiter unten.)
    2. Erforderliche Aktivitätsoptionen, um Aktivitäten auf dem Display des Kombi-Instruments zu starten. Weitere Informationen finden Sie unter ActivityOptions angeben.
  3. Eine Navigations-App (wie Google Maps für Android Automotive oder eine andere Karten-App) mit den erforderlichen Berechtigungen): <ph type="x-smartling-placeholder">
      </ph>
    1. Erhält ein CarAppFocusManager mit der Car-Klasse von car-lib.
    2. Bevor die detaillierte Routenführung gestartet wird, werden Anrufe bei Noch CarAppFocusManager.requestFocus() CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION als appType .
  4. CarAppFocusManager leitet diese Anfrage an CarService weiter. Wenn die Berechtigung gewährt wurde, prüft CarService das Paket der Navigations-App und findet eine Aktivität mit der Kategorie android.car.cluster.NAVIGATION markiert.
  5. Falls sie gefunden werden, verwendet die Navigations-App die ActivityOptions, die vom InstrumentClusterRenderingService, um die Aktivität zu starten, und enthält die Anzeigeeigenschaften des Kombi-Instruments als Extras im Intent.

API einbinden

Die Implementierung von InstrumentClusterRenderingService muss folgende Anforderungen erfüllen:

  • Er muss als Singleton-Dienst gekennzeichnet sein, indem Sie den folgenden Wert zu die AndroidManifest.xml-Datei. Dies ist erforderlich, um sicherzustellen, dass eine einzige Kopie des Der Kombi-Instrumentendienst wird auch während der Initialisierung und beim Nutzerwechsel ausgeführt:
    android:singleUser="true"
  • Halte die Systemberechtigung „BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE“ gedrückt. Dieses dass nur der als Teil des Kombi-Instrument-Renderingdiensts enthaltene Renderingdienst des Android-System-Images jemals an CarService gebunden ist: 
    <uses-permission android:name="android.car.permission.BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE"/>

InstrumentClusterRenderingService implementieren

So erstellen Sie den Dienst:

  1. Schreiben Sie eine Klasse, die von ClusterRenderingService und fügen Sie dann der Datei AndroidManifest.xml einen entsprechenden Eintrag hinzu. Dieser Kurs steuert die Anzeige des Kombi-Instruments und kann den Navigationsstatus (optional) rendern. API-Daten.
  2. Während onCreate() diesen Dienst verwenden, um die Kommunikation mit dem der Rendering-Hardware. Zu den Optionen gehören: <ph type="x-smartling-placeholder">
      </ph>
    • Legen Sie den sekundären Bildschirm fest, der für das Kombi-Instrument verwendet werden soll.
    • Erstellen Sie ein virtuelles Display, damit die Kombi-Instrumenten-App gerendertes Bild in eine externe Einheit über ein Video-Streaming-Format wie H.264.
  3. Wenn der oben angegebene Bildschirm fertig ist, muss dieser Dienst aufrufen, Zum Definieren InstrumentClusterRenderingService#setClusterActivityLaunchOptions() die genaue ActivityOptions, die verwendet werden muss, um eine Aktivität im Kombi-Instrument. Verwenden Sie diese Parameter: <ph type="x-smartling-placeholder">
      </ph>
    • category. ClusterRenderingService dar.
    • ActivityOptions.: Eine ActivityOptions-Instanz, die vom zum Starten einer Aktivität im Kombi-Instrument. Zum Beispiel aus der Stichprobe Implementierung des Kombi-Instruments auf AOSP: 
      getService().setClusterActivityLaunchOptions(
  CATEGORY_NAVIGATION,
  ActivityOptions.makeBasic()
      .setLaunchDisplayId(displayId));
  4. Wenn das Kombi-Instrument zum Anzeigen von Aktivitäten bereit ist, muss dieser Dienst InstrumentClusterRenderingService#setClusterActivityState() Diese Parameter: <ph type="x-smartling-placeholder">
      </ph>
    • category ClusterRenderingService dar.
    • state-Bundle generiert mit ClusterRenderingService dar. Geben Sie folgende Daten an: <ph type="x-smartling-placeholder">
        </ph>
      • visible: Gibt an, dass das Kombi-Instrument sichtbar und einsatzbereit ist angezeigt wird.
      • unobscuredBounds Ein Rechteck, das die Fläche innerhalb der Anzeige des Kombi-Instruments, auf der Inhalte ohne Bedenken dargestellt werden können. Zum Beispiel Gebiete mit Anzeigeuhren.
  5. Die Methode Service#dump() und die Informationen zum Berichtsstatus überschreiben, die nützlich für Debugging (siehe dumpsys) .

Beispiel für InstrumentClusterRenderingService-Implementierung

Im folgenden Beispiel wird ein InstrumentClusterRenderingService dargestellt. -Implementierung, die ein VirtualDisplay zur Präsentation des Zahlungsmittels erstellt. Inhalte auf einem physischen Remote-Display gruppieren

Alternativ könnte dieser Code den displayId einer physischen sekundären Instanz übergeben. mit dem HU verbundener Bildschirm, falls bekannt ist.

/**
* 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);
  }
}

CarAppFocusManager API verwenden

Die CarAppFocusManager API bietet eine Methode mit dem Namen getAppTypeOwner(), mit der Sie den von OEMs geschriebenen Clusterdienst, um zu wissen, welche Navigations-App jeweils den Schwerpunkt auf die Navigation legt . OEMs können die vorhandene CarAppFocusManager#addFocusListener()-Methode verwenden und Verwenden Sie dann getAppTypeOwner(), um zu sehen, welche App im Fokus ist. Mit diesen Informationen OEMs können:

  • Die im Cluster angezeigte Aktivität auf die Clusteraktivität der Navigations-App umstellen im Fokus.
  • Kann erkennen, ob die fokussierte Navigations-App eine Clusteraktivität hat oder nicht. Wenn der Fokus keine Clusteraktivität aufweist (oder deaktiviert ist), können OEMs dieses Signal an das Auto-DIM senden, damit das Navigationsattribut des Clusters ganz übersprungen wird.

Mit CarAppFocusManager können Sie den aktuellen App-Fokus festlegen und beobachten, z. B. eine aktive Navigation oder einen Sprachbefehl geben. Normalerweise wird nur eine Instanz einer solchen App aktiv im System ausgeführt wird.

CarAppFocusManager#addFocusListener(..)-Methode verwenden, um auf den App-Fokus zu warten Änderungen:

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
}

Verwenden Sie die Methode CarAppFocusManager#getAppTypeOwner(..), um das Paket abzurufen. Namen des aktuellen Inhabers eines bestimmten App-Typs, der im Fokus ist Diese Methode gibt möglicherweise mehrere Paketnamen, wenn der aktuelle Eigentümer die Funktion „android:sharedUserId“ verwendet. 

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
}

...

Anhang: Beispiel-App verwenden

AOSP stellt eine Beispiel-App bereit, die die Navigation State API implementiert.

So führen Sie diese Beispielanwendung aus:

  1. Erstellen und installieren Sie Android Auto auf einer unterstützten HU. Verwenden Sie die Methode Erstellungs- und Flash-Anweisungen für Android speziell für Ihr Gerät Anweisungen finden Sie unter Referenzkarten verwenden
  2. Schließen Sie ein physisches zweites Display an die HU an (falls unterstützt) oder schalten Sie das virtuelle Gerät ein Sekundäre HU: <ph type="x-smartling-placeholder">
      </ph>
    1. Wählen Sie in den Einstellungen die Option Entwicklermodus aus.
    2. Gehen Sie zu Einstellungen > System > Erweitert > Entwickleroptionen > Sekundäre Displays simulieren.
  3. HU neu starten
  4. So starten Sie die KitchenSink App:
    1. Öffnen Sie die Leiste.
    2. Rufen Sie Inst. Cluster:
    3. Klicke auf METADATEN STARTEN.

KitchenSink fordert den Fokus NAVIGATION an, wodurch DirectRenderingCluster angewiesen wird verwendet, um eine simulierte Benutzeroberfläche auf dem Kombi-Instrument anzuzeigen.