このページは Cloud Translation API によって翻訳されました。

Instrument Cluster API

Instrument Cluster API (Android API) を使用して、Google マップなどのナビゲーションアプリを、インストルメントパネルのステアリングホイールの後ろなど、車内のセカンダリディスプレイに表示します。このページでは、セカンダリディスプレイを制御するサービスを作成し、そのサービスをCarServiceと統合して、ナビゲーションアプリがユーザーインターフェイスを表示できるようにする方法について説明します。

用語

このページでは次の用語が使用されます。

学期	説明
`CarInstrumentClusterManager`	外部アプリが計器クラスタ上でアクティビティを起動し、計器クラスタがアクティビティを表示する準備ができたときにコールバックを受信できるようにする`CarManager`インスタンス。
`CarManager`	`CarService`によって実装された自動車固有のサービスと対話するために外部アプリによって使用されるすべてのマネージャーの基本クラス。
`CarService`	外部アプリ (Google マップを含む) と、インストルメントクラスターアクセスなどの自動車固有の機能との間の通信を提供する Android プラットフォームサービス。
行き先	車両が移動する最終目的地。
到着予定時刻	目的地への到着予定時刻。
ヘッドユニット(HU)	自動車に組み込まれた主要な計算ユニット。 HU はすべての Android コードを実行し、車内の中央ディスプレイに接続されます。
計器クラスタ	セカンダリディスプレイはステアリングホイールの後ろ、車の計器の間にあります。これは、自動車の内部ネットワーク (CAN バス) を介して HU に接続された独立した計算ユニット、または HU に接続されたセカンダリディスプレイにすることができます。
`InstrumentClusterRenderingService`	計器クラスタディスプレイとのインターフェイスに使用されるサービスの基本クラス。 OEM は、OEM 固有のハードウェアと対話するこのクラスの拡張機能を提供する必要があります。
キッチンシンクアプリ	Android Automotive に含まれるテストアプリ。
ルート	車両が目的地に到着するために移動する特定の経路。
シングルトンサービス	`android:singleUser`属性を持つ Android サービス。 Android システム上では、常にサービスの最大 1 つのインスタンスが実行されます。

前提条件

統合を開発するには、次の要素が必要です。

Android開発環境。 Android 開発環境をセットアップするには、「ビルド要件」を参照してください。
Android のソースコードをダウンロードします。 https://android.googlesource.comの pi-car-release ブランチ (またはそれ以降) から Android ソースコードの最新バージョンを入手します。
ヘッドユニット (HU)。 Android 9 (以降) を実行できる Android デバイス。このデバイスには独自のディスプレイがあり、Android の新しいビルドでディスプレイをフラッシュできる必要があります。
インストルメントクラスタは次のいずれかです。
- HU に接続された物理的なセカンダリディスプレイ。デバイスのハードウェアとカーネルが複数のディスプレイの管理をサポートしている場合。
- 独立したユニット。ネットワーク接続を介して HU に接続され、ビデオストリームを受信して独自のディスプレイに表示できる計算ユニット。
- エミュレートされた表示。開発中は、次のエミュレートされた環境のいずれかを使用できます。
  - シミュレートされたセカンダリディスプレイ。 AOSP Android ディストリビューションでシミュレートされたセカンダリディスプレイを有効にするには、設定システムアプリの開発者向けオプション設定に移動し、[セカンダリディスプレイをシミュレートする] を選択します。この構成は、物理的なセカンダリディスプレイを接続するのと同じですが、このディスプレイがプライマリディスプレイに重ねられるという制限があります。
  - エミュレートされた計器クラスタ。 Android Automotive に含まれる Android エミュレータには、 ClusterRenderingServiceサービスがセカンダリディスプレイに接続されているインストルメントクラスタを表示するオプションが用意されています。

統合アーキテクチャ

統合コンポーネント

Instrument Cluster API の統合は、次の 3 つのコンポーネントで構成されます。

CarService
ナビゲーションアプリ
OEM インスツルメントクラスターサービス

統合コンポーネント

カーサービス

CarServiceナビゲーションアプリと車の間を仲介し、常に 1 つのナビゲーションアプリのみがアクティブになり、 android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL権限を持つアプリのみが車にデータを送信できるようにします。

CarService 、すべての自動車固有のサービスをブートストラップし、一連のマネージャーを通じてこれらのサービスへのアクセスを提供します。サービスと対話するために、車内で実行されているアプリはこれらのマネージャーにアクセスできます。

インストルメントクラスター実装の場合、自動車 OEM は InstrumentClusterRendererService のカスタム実装を作成し、セカンダリディスプレイに接続されているClusterRenderingServiceサービスを更新する必要があります。

インストルメントクラスタをレンダリングするとき、ブートプロセス中に、 CarServiceセカンダリディスプレイに接続されているClusterRenderingServiceサービスのInstrumentClusterRendererServiceキーを読み取ります。 InstrumentClusterServiceの実装を見つけます。 AOSP では、このエントリは Navigation State API サンプルクラスター実装のレンダリングサービスを指します。

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

このエントリで参照されるサービスは初期化され、 CarServiceにバインドされます。 Google マップなどのナビゲーションアプリがCarInstrumentClusterManagerをリクエストすると、 CarServiceバインドされたInstrumentClusterRenderingServiceから計器クラスタの状態を更新するマネージャーを提供します。 (この場合、 bound はAndroid サービスを指します。)

インストルメントクラスターサービス

OEM は、セカンダリディスプレイに接続されるClusterRenderingServiceサービスのサブクラスを含む Android パッケージ (APK) を作成する必要があります。 ClusterRenderingServiceサービスはセカンダリディスプレイに接続されています。サンプル用です。

このクラスは次の 2 つの目的を果たします。

Android インターフェイスとインストゥルメントクラスターレンダリングデバイスを提供します (このページの目的)。
ターンバイターンのナビゲーションガイダンスなど、ナビゲーション状態の更新を受信してレンダリングします。

最初の目的のために、 InstrumentClusterRendererServiceの OEM 実装は、車室内の画面に情報をレンダリングするために使用されるセカンダリディスプレイを初期化し、 InstrumentClusterRendererService.setClusterActivityOptions()メソッドとInstrumentClusterRendererService.setClusterActivityState()メソッドを呼び出してこの情報をCarServiceに伝達する必要があります。

2 番目の機能の場合、インストルメントクラスターサービスは、セカンダリディスプレイに接続されるClusterRenderingServiceサービスの実装を提供する必要があります。ナビゲーションステータス更新イベントを受け取るインターフェイス。 eventTypeとしてエンコードされ、バンドル内にエンコードされたイベントデータも含まれます。

統合シーケンス

次の図は、更新をレンダリングするナビゲーション状態の実装を示しています。

統合シーケンス

この図では、色は次のことを示しています。

黄色。 Android プラットフォームによって提供されるCarServiceおよびCarNavigationStatusManager 。詳細については、「自動車」と「CAR_NAVIGATION_SERVICE」を参照してください。
シアン。 OEM によって実装されたInstrumentClusterRendererService 。
紫。 Google とサードパーティの開発者によって実装されたナビゲーションアプリ。
緑。 CarAppFocusManager 。詳細については、以下のCarAppFocusManager API の使用とCarAppFocusManagerを参照してください。

ナビゲーション状態情報のフローは次の順序に従います。

CarService InstrumentClusterRenderingServiceを初期化します。
初期化中に、 InstrumentClusterRenderingServiceは次のようにCarServiceを更新します。
1. インスツルメントクラスタには、不明瞭な境界などのプロパティが表示されます (不明瞭な境界の詳細については、後ほど参照します)。
2. インストルメントクラスタ表示内でアクティビティを起動するために必要なアクティビティオプション (詳細については、「ActivityOptions」を参照してください)。
ナビゲーションアプリ (Android Automotive 用 Google マップ、または必要な権限を持つ地図アプリなど):
1. car-lib から Car クラスを使用してCarAppFocusManagerを取得します。
2. ターンバイターン方式のルート案内が開始される前に、 CarAppFocusManager.requestFocus()を呼び出して、 CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATIONをappTypeパラメーターとして渡します。
CarAppFocusManagerこのリクエストをCarServiceに伝えます。許可された場合、 CarServiceナビゲーションアプリパッケージを検査し、カテゴリandroid.car.cluster.NAVIGATIONでマークされたアクティビティを見つけます。
見つかった場合、ナビゲーションアプリは、 InstrumentClusterRenderingServiceによって報告されたActivityOptionsを使用してアクティビティを起動し、インテントにエクストラとしてインストルメントクラスター表示プロパティを含めます。

APIを統合する

InstrumentClusterRenderingService実装は次のことを行う必要があります。

次の値を AndroidManifest.xml に追加することで、シングルトンサービスとして指定されます。これは、初期化中やユーザーの切り替え中であっても、Instrument Cluster サービスの単一コピーが確実に実行されるようにするために必要です。
android:singleUser="true"
BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICEシステム権限を保持します。これにより、Android システムイメージの一部として含まれるインストゥルメントクラスタレンダリングサービスのみがCarServiceによってバインドされることが保証されます:
```
<uses-permission android:name="android.car.permission.BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE"/>
```

InstrumentClusterRenderingService の実装

サービスを構築するには:

セカンダリディスプレイに接続するClusterRenderingServiceサービスを拡張するクラスを作成します。

AndroidManifest.xml

オプションで

onCreate()中に、このサービスを使用してレンダリングハードウェアとの通信を初期化します。オプションには次のものが含まれます。
- インストルメントクラスターに使用するセカンダリディスプレイを決定します。
- Instrument Cluster アプリがレンダリングイメージをレンダリングし、レンダリングされたイメージを外部ユニットに送信できるように、仮想ディスプレイを作成します (H.264 などのビデオストリーミング形式を使用)。
上記の表示の準備ができたら、このサービスはInstrumentClusterRenderingService#setClusterActivityLaunchOptions()を呼び出して、計測器クラスタ上でアクティビティを表示するために使用する必要がある正確なActivityOptionsを定義する必要があります。次のパラメータを使用します。
- カテゴリー。 ClusterRenderingServiceサービスはセカンダリディスプレイに接続されています。
- ActivityOptions.インストルメントクラスターでアクティビティを起動するために使用できるActivityOptionsインスタンス。たとえば、AOSP 上のサンプルインストルメントクラスタ実装から:
```
getService().setClusterActivityLaunchOptions(
   CATEGORY_NAVIGATION,
   ActivityOptions.makeBasic()
      .setLaunchDisplayId(displayId));
```
インストルメントクラスタがアクティビティを表示する準備ができたら、このサービスはInstrumentClusterRenderingService#setClusterActivityState()を呼び出す必要があります。次のパラメータを使用します。
- category ClusterRenderingServiceサービスがセカンダリディスプレイに接続されています。
- state ClusterRenderingServiceサービスで生成されたバンドルがセカンダリディスプレイに接続されています。
Service#dump()メソッドをオーバーライドして、デバッグに役立つステータス情報を報告します (詳細については、 dumpsysを参照してください)。

InstrumentClusterRenderingService 実装のサンプル

次の例は、 InstrumentClusterRenderingServiceの実装の概要を示しています。これは、リモートの物理ディスプレイに計器クラスタのコンテンツを表示するVirtualDisplayを作成します。

あるいは、このコードは、HU に接続されている物理セカンダリディスプレイが利用可能であることがわかっている場合、そのdisplayIdを渡すこともできます。

/**
* 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 を使用する

CarAppFocusManager API には、 getAppTypeOwner()という名前のメソッドが用意されています。これにより、OEM が作成したクラスターサービスは、いつでもどのナビゲーションアプリがナビゲーションフォーカスを持っているかを知ることができます。 OEM は、既存のCarAppFocusManager#addFocusListener()メソッドを使用してから、 getAppTypeOwner()を使用してどのアプリにフォーカスがあるかを知ることができます。この情報により、OEM は次のことが可能になります。

クラスターに表示されているアクティビティを、フォーカスを保持しているナビゲーションアプリによって提供されるクラスターアクティビティに切り替えます。
フォーカスされたナビゲーションアプリにクラスターアクティビティがあるかどうかを検出できます。フォーカスされたナビゲーションアプリにクラスターアクティビティがない場合 (またはそのようなアクティビティが無効になっている場合)、OEM はこの信号を車の DIM に送信して、クラスターのナビゲーションファセットが完全にスキップされるようにできます。

CarAppFocusManagerを使用して、アクティブナビゲーションや音声コマンドなどの現在のアプリフォーカスを設定およびリッスンします。通常、システム内でアクティブに実行されている (または集中している) のは、このようなアプリの 1 つのインスタンスだけです。

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 は、Navigation State API を実装するサンプルアプリを提供します。

このサンプルアプリを実行するには:

サポートされている HU 上で Android Auto をビルドしてフラッシュします。お使いのデバイスに固有の Android の構築およびフラッシュ手順を使用してください。手順については、「リファレンスボードの使用」を参照してください。
物理セカンダリディスプレイを HU に接続するか (サポートされている場合)、仮想セカンダリ HU をオンにします。
1. 設定アプリで開発者モードを選択します。
2. [設定] > [システム] > [詳細設定] > [開発者向けオプション] > [セカンダリディスプレイのシミュレート]に移動します。
HU を再起動します。 ClusterRenderingServiceサービスはセカンダリディスプレイに接続されています。
KitchenSink アプリを起動するには:
1. 引き出しを開けます。
2. インスタに行きます。集まる。
3. [メタデータの開始]をクリックします。

KitchenSink は NAVIGATION フォーカスを要求し、 DirectRenderingClusterサービスにインストルメントクラスター上にモックアップされたユーザーインターフェイスを表示するように指示します。

Instrument Cluster API

用語

前提条件

統合アーキテクチャ

統合コンポーネント

カーサービス

インストルメントクラスターサービス

統合シーケンス

APIを統合する

InstrumentClusterRenderingService の実装

InstrumentClusterRenderingService 実装のサンプル

CarAppFocusManager API を使用する

付録: サンプル アプリの使用

付録: サンプルアプリの使用