仪表板

Instrument Cluster API（一款 Android API）可在车载辅助显示设备（如位于方向盘后方的仪表盘上的辅助显示设备）上显示导航应用，包括 Google 地图。本页面介绍如何创建服务以控制此类辅助显示设备并将该服务与 CarService 集成，以便导航应用可以显示界面。

术语

本页面中使用了以下术语：

术语	说明
`CarInstrumentClusterManager`	一个 `CarManager`，使外部应用能够在仪表板上启动 activity，并在仪表板准备好显示 activity 时接收回调。
CarManager	所有管理器的基类，外部应用使用这些管理器与通过 `CarService` 实现的汽车特有服务进行交互。
`CarService`	一种 Android 平台服务，可在 Google 地图等外部应用与仪表板等汽车特有功能之间提供通信服务。
目的地	车辆将导航到的最终目的地。
预计到达时间	预计到达目的地的时间。
车机 (HU)	车内嵌入的主要计算单元。HU 会运行所有 Android 代码，并连接到汽车中央显示屏。
仪表板	位于方向盘后方车载仪表之间的辅助显示设备。这可以是通过汽车内部网络（CAN 总线）连接到 HU 的独立计算单元，也可以是连接到 HU 的辅助显示设备。
`InstrumentClusterRenderingService`	用于与仪表板显示屏连接的服务的基类。原始设备制造商 (OEM) 必须提供该类的扩展，以便与 OEM 特有硬件交互。
KitchenSink 应用	Android Automotive 中包含的测试应用。
路线	车辆导航到达目的地所经的特定路径。
单例服务	一种具有 `android:singleUser` 属性的 Android 服务。在任何给定时间，相应服务最多只有一个实例在 Android 系统上运行。

前提条件

如需开发集成，请确保具备以下元素：

Android 开发环境。如需设置 Android 开发环境，请参阅构建要求。
下载 Android 源代码。访问 https://android.googlesource.com，从 pi-car-release 分支（或更高版本）获取最新版 Android 源代码。
车机 (HU)。能够搭载 Android 9（或更高版本）的 Android 设备。此设备必须具有自己的显示屏，并且能够使用 Android 的新 build 刷写显示屏。
仪表板采用以下类型之一：
- 连接到 HU 的实体辅助显示设备。条件是设备硬件和内核支持对多个显示屏进行管理。
- 独立单元。通过网络连接连接到 HU 的任何计算单元，能够接收并在其显示屏上显示视频串流。
- 模拟显示屏。在开发过程中，您可以使用以下模拟环境之一：
  - 模拟辅助显示设备。如需在任何 AOSP Android 发行版上启用模拟辅助显示设备，请转到“设置”系统应用中的“开发者选项”设置，然后选择“模拟辅助显示设备”。此配置相当于连接实体辅助显示设备，只不过此显示设备叠加显示在主显示设备之上。
  - 模拟仪表板。Android Automotive 中包含的 Android 模拟器提供了一个选项，从而能够使用 Android 模拟器 _qemu-pipes 显示仪表板。使用 DirectRenderingCluster 仪表板参考实现连接到此模拟外部屏幕。

集成架构

集成组件

Instrument Cluster API 的任何集成都包括以下三个组件：

CarService
导航应用
OEM 仪表板服务

集成组件

CarService

CarService 可在导航应用与汽车之间进行协调，确保在任何时候都只有一个导航应用处于活跃状态，并且只有具有 android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL 权限的应用才能向汽车发送数据。

CarService 可以启动所有汽车特有服务，并通过一系列管理器提供对这些服务的访问。为了与服务进行交互，在汽车内运行的应用可以访问这些管理器。

对于仪表板实现，汽车 OEM 必须创建自定义的 InstrumentClusterRendererService 实现，并更新 config.xml 文件以指向该自定义实现。

当呈现仪表板时，CarService 会在启动过程中读取 config.xml 的 InstrumentClusterRendererService 键，以定位 InstrumentClusterService 实现。在 AOSP 中，此条目指向导航状态 API 集群实现呈现服务示例：

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

此条目中引用的服务经初始化处理并绑定到 CarService。当导航应用（如 Google 地图）请求 CarInstrumentClusterManager 时，CarService 会提供一个管理器，用于根据绑定的 InstrumentClusterRenderingService 更新仪表板状态。（在这种情况下，“绑定的服务”指的是 Android 服务。）

仪表板服务

OEM 必须创建包含 InstrumentClusterRendererService. 子类的 Android 软件包 (APK)。如需查看示例，请参阅 ClusterRenderingService。

此类有以下两个用途：

提供 Android 与仪表板呈现设备之间的接口（本文的用途）。
接收并呈现导航状态更新，如精细导航指导。

为实现第一个用途，OEM 的 InstrumentClusterRendererService 实现必须初始化用于在车厢内屏幕上呈现信息的辅助显示设备，并通过调用 InstrumentClusterRendererService.setClusterActivityOptions() 和 InstrumentClusterRendererService.setClusterActivityState() 方法将此信息传达给 CarService。

为实现第二个用途，仪表板服务必须提供 NavigationRenderer 接口的实现，该接口用于接收导航状态更新事件，这些事件在软件包中编码为 eventType 数据和事件数据。

集成序列

下图展示了呈现更新的导航状态的实现：

集成序列

在此图中，各种颜色的含义如下：

黄色：由 Android 平台提供的 CarService 和 CarNavigationStatusManager。如需了解详情，请参阅 Car 和 CAR_NAVIGATION_SERVICE。
青色：由 OEM 实现的 InstrumentClusterRendererService。
紫色。由 Google 和第三方开发者实现的导航应用。
绿色：CarAppFocusManager。如需了解详情，请参阅下文的使用 CarAppFocusManager API 和 CarAppFocusManager。

导航状态信息流程遵循以下序列：

CarService 初始化 InstrumentClusterRenderingService。
在初始化期间，InstrumentClusterRenderingService 使用以下选项更新 CarService：
1. 仪表板屏幕属性，如无遮挡边界（可稍后了解有关无遮挡边界的更多详情）。
2. 在仪表板屏幕内启动 activity 所需要的 activity 选项（如需了解更多详情，请参阅 ActivityOptions）。
导航应用（如适用于 Android Automotive 的 Google 地图或任何具有所需权限的地图应用）：
1. 使用 Car 类从 car-lib 中获取 CarAppFocusManager。
2. 在启动精细导航路线之前，调用 CarAppFocusManager.requestFocus() 以将 CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION 作为 appType 参数传递。
CarAppFocusManager 会将此请求传达给 CarService。在授予条件下，CarService 会检查导航应用软件包，并定位标有类别 android.car.cluster.NAVIGATION 的 activity。
找到之后，导航应用会使用 InstrumentClusterRenderingService 报告的 ActivityOptions 启动 activity，并在 intent 中包含仪表板屏幕属性作为附加内容。

集成 API

InstrumentClusterRenderingService 实现必须满足以下条件：

通过将以下值添加到 AndroidManifest.xml，将实现指定为单例服务。这是确保仪表板服务的单个副本可运行的前提条件，即使在初始化和用户切换期间也可运行：
android:singleUser="true"
具有 BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE 系统权限。这样可以确保只有 Android 系统映像中包含的仪表板呈现服务才由 CarService 绑定：
```
<uses-permission android:name="android.car.permission.BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE"/>
```

实现 InstrumentClusterRenderingService

如需构建服务，请执行以下操作：

编写一个从 InstrumentClusterRenderingService 扩展的类，然后向您的 AndroidManifest.xml 文件添加相应的条目。此类用于控制仪表板屏幕，并且可以呈现导航状态 API 数据（可选）。
在 onCreate() 期间，使用此服务初始化与呈现硬件之间的通信。选项包括：
- 确定用于仪表板的辅助显示设备。
- 创建一个虚拟屏幕，以便仪表板应用呈现图像并将呈现的图像传输到外部单元（使用 H.264 等视频串流格式）。
当上述屏幕准备就绪后，此服务必须调用 InstrumentClusterRenderingService#setClusterActivityLaunchOptions() 才能对在仪表板上显示 activity 必须使用的确切 ActivityOptions 进行定义。请使用以下参数：
- category。 CarInstrumentClusterManager#CATEGORY_NAVIGATION
- ActivityOptions.。一个 ActivityOptions 实例，可以用于在仪表板中启动 activity。例如，从 AOSP 上的仪表板实现示例中：
```
getService().setClusterActivityLaunchOptions(
   CATEGORY_NAVIGATION,
   ActivityOptions.makeBasic()
      .setLaunchDisplayId(displayId));
```
当仪表板准备好显示 activity 时，此服务必须调用 InstrumentClusterRenderingService#setClusterActivityState()。请使用以下参数：
- category CarInstrumentClusterManager#CATEGORY_NAVIGATION
- state。通过 ClusterActivityState 生成的软件包。请务必提供以下数据：
  - visible。用于将仪表板指定为可见，并准备好显示内容。
  - unobscuredBounds。一个矩形，用于定义仪表板屏幕内可以安全显示内容的区域。例如，表盘和量表覆盖的区域。
替换 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 that will 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 可以：

将仪表板中显示的 activity 切换为获得焦点的导航应用提供的仪表板 activity。
检测聚焦的导航应用是否有仪表板 activity。如果聚焦的导航应用没有仪表板 activity（或者此类 activity 已停用），OEM 可以将此信号发送到车载 DIM，以便完全跳过仪表板的导航 Facet。

使用 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 application 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 的示例应用。

如需运行此示例应用，请执行以下操作：

在受支持的 HU 上构建并刷写 Android Auto。使用适用于您的设备的 Android 构建和刷写说明。如需了解相关说明，请参阅使用参考开发板。
将实体辅助显示设备连接到 HU（如支持）或打开虚拟辅助 HU：
1. 在“设置”应用中，选择开发者模式。
2. 依次转到设置 > 系统 > 高级 > 开发者选项 > 模拟辅助显示设备。
重新启动 HU。ClusterRenderingService 服务连接到辅助显示设备。
如需启动 KitchenSink 应用，请执行以下操作：
1. 打开抽屉式导航栏。
2. 转到仪表板。
3. 点击启动元数据。

KitchenSink 会请求导航焦点，此举会指示 DirectRenderingCluster 服务在仪表板上显示模拟界面。