API Instrument Cluster

Dùng Instrument Cluster API (API của Android) để hiển thị các ứng dụng chỉ đường, bao gồm Google Maps, trên màn hình phụ của ô tô, chẳng hạn như phía sau vô lăng trên bảng điều khiển. Trang này mô tả cách tạo một để điều khiển màn hình phụ đó cũng như để tích hợp dịch vụ với CarService để các ứng dụng chỉ đường có thể cho thấy giao diện người dùng.

Thuật ngữ

Các thuật ngữ sau được sử dụng trên trang này.

Điều kiện tiên quyết

Trước khi tiếp tục, hãy đảm bảo bạn có các yếu tố sau:

• Môi trường phát triển Android. Để thiết lập thiết bị Android môi trường phát triển, xem Yêu cầu về bản dựng.
• Tải mã nguồn Android xuống. Tải phiên bản mới nhất của mã nguồn Android từ nhánh pi-car-release (hoặc mới hơn) tại https://android.googlesource.com.
• Đầu phát trung tâm (HU). Thiết bị Android có thể chạy Android 9 trở lên. Thiết bị này phải có màn hình riêng và có khả năng cài đặt ROM màn hình bằng các bản dựng Android mới.
• Cụm công cụ là một trong những cụm sau:
  • Màn hình phụ thực gắn kèm với HU. Nếu phần cứng thiết bị và nhân hệ điều hành hỗ trợ quản lý nhiều màn hình.
  • Đơn vị độc lập. Bất kỳ đơn vị tính toán nào được kết nối với HU qua kết nối mạng, có khả năng nhận và hiển thị luồng video trên màn hình riêng.
  • Màn hình mô phỏng. Trong quá trình phát triển, bạn có thể sử dụng một trong các môi trường được mô phỏng sau:
    • Màn hình phụ mô phỏng. Để bật chế độ mô phỏng màn hình phụ trên mọi bản phân phối AOSP Android, hãy chuyển đến Developer Options (Tuỳ chọn cho nhà phát triển) các chế độ cài đặt trong ứng dụng hệ thống Cài đặt, sau đó chọn Mô phỏng phụ display Cấu hình này tương đương với việc đính kèm một màn hình phụ với giới hạn là màn hình này được xếp chồng lên trên màn hình.
    • Cụm đo lường được mô phỏng. Bao gồm cả trình mô phỏng Android với AAOS cung cấp tuỳ chọn hiển thị một cụm đo lường với ClusterRenderingService.

Cấu trúc tích hợp

Thành phần tích hợp

Mọi hoạt động tích hợp của Instrument Cluster API đều bao gồm 3 thành phần sau:

• CarService
• Ứng dụng chỉ đường
• Dịch vụ cụm đo lường OEM

Dịch vụ ô tô

CarService dàn xếp giữa các ứng dụng chỉ đường và ô tô, đảm bảo rằng chỉ một ứng dụng chỉ đường hoạt động tại một thời điểm bất kỳ và chỉ những ứng dụng có Quyền android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL có thể gửi dữ liệu đến chiếc ô tô.

CarService tự động khởi động tất cả các dịch vụ dành riêng cho ô tô và cung cấp quyền truy cập vào các dịch vụ này thông qua một loạt nhà quản lý. Để tương tác với các dịch vụ, ứng dụng chạy trong ô tô có thể truy cập vào các trình quản lý này.

Để triển khai cụm công cụ, OEM trong ô tô phải tạo một thuộc tính tuỳ chỉnh triển khai InstrumentClusterRendererService và cập nhật ClusterRenderingService.

Khi kết xuất Cụm đo lường, trong quá trình khởi động, CarService đọc khoá InstrumentClusterRendererService của ClusterRenderingService để xác định bản triển khai InstrumentClusterService. Trong AOSP, mục này trỏ đến dịch vụ kết xuất triển khai cụm mẫu Navigation State API (API Trạng thái điều hướng):

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

Dịch vụ được đề cập trong mục này được khởi tạo và liên kết với CarService. Khi các ứng dụng chỉ đường, chẳng hạn như Google Maps, hãy yêu cầu CarInstrumentClusterManager, CarService cung cấp một trình quản lý cập nhật trạng thái của Cụm công cụ từ ranh giới InstrumentClusterRenderingService. (Trong trường hợp này, ràng buộc dùng để chỉ Android Dịch vụ.)

Dịch vụ cụm đo lường

OEM phải tạo Gói Android (APK) chứa lớp con của ClusterRenderingService.

Lớp này phục vụ hai mục đích:

• Cung cấp một giao diện cho Android và thiết bị kết xuất Cụm công cụ (mục đích của trang này).
• Nhận và kết xuất thông tin cập nhật về trạng thái chỉ đường, chẳng hạn như đường đi từng chặng hướng dẫn điều hướng.

Đối với mục đích đầu tiên, việc triển khai OEM của InstrumentClusterRendererService phải khởi chạy màn hình phụ dùng để kết xuất thông tin trên màn hình trong cabin trên xe và truyền thông tin này đến CarService bằng cách gọi đến InstrumentClusterRendererService.setClusterActivityOptions() và Phương thức InstrumentClusterRendererService.setClusterActivityState().

Đối với hàm thứ hai, dịch vụ Cụm công cụ phải cung cấp một việc triển khai ClusterRenderingService giao diện nhận sự kiện cập nhật trạng thái điều hướng, được mã hoá dưới dạng eventType và dữ liệu sự kiện được mã hoá trong một gói.

Trình tự tích hợp

Sơ đồ dưới đây minh hoạ cách triển khai một trạng thái điều hướng hiển thị các bản cập nhật:

Trong minh hoạ này, các màu biểu thị những điều sau:

• Màu vàng. CarService và CarNavigationStatusManager do nền tảng Android cung cấp. Để tìm hiểu thêm, hãy xem Xe ô tô và CAR_NAVIGATION_SERVICE.
• Xanh lơ. Đã triển khai InstrumentClusterRendererService bởi OEM (Nhà sản xuất thiết bị gốc).
• Tím. Ứng dụng Điều hướng do Google và bên thứ ba triển khai nhà phát triển.
• Xanh lục. CarAppFocusManager. Để tìm hiểu thêm, hãy xem Sử dụng API CarAppFocusManager thấp hơn và CarAppFocusManager.

Luồng thông tin về Trạng thái điều hướng tuân theo trình tự sau:

1. CarService khởi chạy InstrumentClusterRenderingService.
2. Trong quá trình khởi chạy, InstrumentClusterRenderingService sẽ cập nhật CarService bằng:
   1. Thuộc tính màn hình Cụm đo lường, chẳng hạn như ranh giới không bị che khuất (xem thêm thông tin chi tiết về ranh giới không bị che khuất sau đó).
   2. Các tuỳ chọn hoạt động cần thiết để khởi chạy các hoạt động bên trong màn hình Cụm công cụ. Để tìm hiểu thêm, hãy xem ActivityOptions.
3. Một ứng dụng chỉ đường (chẳng hạn như Google Maps dành cho Android Automotive hoặc bất kỳ ứng dụng bản đồ nào) với các quyền cần thiết):
   1. Lấy CarAppFocusManager bằng lớp Car từ car-lib.
   2. Trước khi đường đi từng chặng bắt đầu, cuộc gọi đến CarAppFocusManager.requestFocus() để vượt qua CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION trong vai trò appType .
4. CarAppFocusManager sẽ truyền yêu cầu này đến CarService. Nếu đã được cấp, CarService sẽ kiểm tra gói ứng dụng chỉ đường và tìm một hoạt động được đánh dấu bằng danh mục android.car.cluster.NAVIGATION.
5. Nếu tìm thấy, ứng dụng chỉ đường sẽ dùng ActivityOptions do InstrumentClusterRenderingService để khởi chạy hoạt động và đưa vào Các thuộc tính hiển thị của Cụm đo lường dưới dạng dữ liệu bổ sung trong ý định.

Tích hợp API

Việc triển khai InstrumentClusterRenderingService phải:

• Được chỉ định là dịch vụ singleton bằng cách thêm giá trị sau vào tệp AndroidManifest.xml. Điều này là cần thiết để đảm bảo rằng một bản sao duy nhất của Dịch vụ Cụm đo lường hoạt động, ngay cả trong quá trình khởi chạy và chuyển đổi người dùng:
  android:singleUser="true"
• Có quyền hệ thống BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE. Chiến dịch này đảm bảo rằng chỉ có dịch vụ kết xuất Cụm đo lường được đưa vào dưới dạng một phần của hình ảnh hệ thống Android luôn bị ràng buộc bởi CarService:

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

Triển khai InstrumentClusterRenderingService

Cách tạo dịch vụ:

1. Viết một lớp mở rộng từ ClusterRenderingService rồi thêm mục nhập tương ứng vào tệp AndroidManifest.xml. Lớp này điều khiển màn hình Cụm công cụ và có thể (không bắt buộc) kết xuất Trạng thái điều hướng Dữ liệu API.
2. Trong onCreate(), hãy sử dụng dịch vụ này để khởi tạo hoạt động giao tiếp với phần cứng kết xuất hình ảnh. Các lựa chọn bao gồm:
   • Xác định màn hình phụ sẽ dùng cho Cụm đo lường.
   • Tạo một màn hình ảo để ứng dụng Instrument Cluster kết xuất và truyền kết xuất hình ảnh sang đơn vị bên ngoài (sử dụng định dạng phát video trực tuyến, chẳng hạn như H.264).
3. Khi màn hình hiển thị ở trên đã sẵn sàng, dịch vụ này phải gọi InstrumentClusterRenderingService#setClusterActivityLaunchOptions() để xác định ActivityOptions chính xác phải được dùng để hiển thị một Hoạt động trên Cụm đo lường. Hãy dùng các thông số sau:
   • category. ClusterRenderingService.
   • ActivityOptions. Một thực thể ActivityOptions có thể dùng để khởi chạy một Hoạt động trong cụm Instrument. Ví dụ: từ mẫu Triển khai Cụm công cụ trên AOSP:

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

4. Khi cụm Đo lường đã sẵn sàng hiển thị các hoạt động, dịch vụ này phải gọi InstrumentClusterRenderingService#setClusterActivityState(). Sử dụng thông số:
   • category ClusterRenderingService.
   • state gói được tạo bằng ClusterRenderingService. Hãy nhớ cung cấp dữ liệu sau:
     • visible Chỉ định Cụm đo lường là ở chế độ hiển thị và sẵn sàng để hiển thị nội dung.
     • unobscuredBounds Một hình chữ nhật xác định diện tích bên trong Màn hình cụm công cụ nơi có thể hiển thị nội dung an toàn. Ví dụ: các khu vực được bao phủ bởi mặt số và đồng hồ đo.
5. Ghi đè phương thức Service#dump() và thông tin về trạng thái báo cáo hữu ích để gỡ lỗi (xem dumpsys để biết thêm thông tin).

Triển khai InstrumentClusterRenderingService mẫu

Ví dụ sau đây mô tả một InstrumentClusterRenderingService Phương thức triển khai này, sẽ tạo một VirtualDisplay để trình bày Công cụ Nội dung theo cụm trên một màn hình thực từ xa.

Ngoài ra, mã này có thể truyền displayId của một trường phụ màn hình kết nối với HU, nếu biết có một màn hình nào đó.

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

Sử dụng CarAppFocusManager API

API CarAppFocusManager cung cấp một phương thức có tên getAppTypeOwner(), cho phép dịch vụ cụm do OEM (Nhà sản xuất thiết bị gốc) viết để biết ứng dụng chỉ đường nào có tâm điểm điều hướng tại một thời điểm bất kỳ bất cứ lúc nào. OEM có thể sử dụng phương thức CarAppFocusManager#addFocusListener() hiện có và sau đó sử dụng getAppTypeOwner() để tìm hiểu xem ứng dụng nào có tiêu điểm. Với thông tin này, OEM có thể:

• Chuyển đổi hoạt động hiển thị trong cụm sang hoạt động trên cụm do ứng dụng chỉ đường cung cấp đang giữ tiêu điểm.
• Có thể phát hiện xem ứng dụng đi theo chỉ dẫn được lấy tiêu điểm có hoạt động theo cụm hay không. Nếu giá trị tập trung ứng dụng chỉ đường không có hoạt động theo cụm (hoặc nếu hoạt động đó bị tắt), OEM có thể gửi tín hiệu này tới DIM của ô tô để thuộc tính điều hướng của cụm được bỏ qua hoàn toàn.

Sử dụng CarAppFocusManager để đặt và nghe tiêu điểm hiện tại của ứng dụng, chẳng hạn như điều hướng đang hoạt động hoặc lệnh thoại. Thường chỉ có một phiên bản của ứng dụng này đang hoạt động đang chạy (hoặc được đặt tiêu điểm) trong hệ thống.

Sử dụng phương thức CarAppFocusManager#addFocusListener(..) để theo dõi tiêu điểm của ứng dụng các thay đổi:

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
}

Sử dụng phương thức CarAppFocusManager#getAppTypeOwner(..) để truy xuất gói tên của chủ sở hữu hiện tại của một loại ứng dụng cụ thể đang được xem xét. Phương thức này có thể trả về nhiều tên gói nếu chủ sở hữu hiện tại sử dụng tính năng 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
}

...

Phụ lục: Dùng ứng dụng mẫu

AOSP cung cấp một ứng dụng mẫu triển khai API Trạng thái điều hướng.

Cách chạy ứng dụng mẫu này:

1. Tạo và cài đặt ROM Android Auto trên HU được hỗ trợ. Sử dụng Hướng dẫn xây dựng và cài đặt ROM Android dành riêng cho thiết bị của bạn. Để biết hướng dẫn, hãy xem Sử dụng Bảng tham chiếu.
2. Kết nối màn hình phụ thực với HU (nếu được hỗ trợ) hoặc bật màn hình ảo HU phụ:
   1. Chọn Chế độ nhà phát triển trong ứng dụng Cài đặt.
   2. Chuyển đến phần Cài đặt > Hệ thống > Nâng cao > Tuỳ chọn cho nhà phát triển > Mô phỏng màn hình phụ.
3. Khởi động lại HU
4. Cách mở ứng dụng KitchenSink:
   1. Mở ngăn.
   2. Chuyển đến phần Inst. Cụm.
   3. Nhấp vào BẮT ĐẦU SIÊU DỮ LIỆU.

KitchenSink yêu cầu tập trung vào ĐIỀU hướng để hướng dẫn DirectRenderingCluster để hiển thị giao diện người dùng mô phỏng trên Cụm đo lường.