API cụm công cụ

Sử dụng API cụm công cụ (API Android) để hiển thị các ứng dụng điều hướng, bao gồm Google Maps, trên màn hình phụ trong ô 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 dịch vụ để điều khiển màn hình phụ đó và sau đó tích hợp dịch vụ đó với CarService để các ứng dụng điều hướng có thể hiển thị giao diện người dùng.

Thuật ngữ

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

Thuật ngữ Sự miêu tả
CarInstrumentClusterManager Phiên bản CarManager cho phép các ứng dụng bên ngoài khởi chạy một hoạt động trên Cụm công cụ và nhận lệnh gọi lại khi Cụm công cụ sẵn sàng hiển thị các hoạt động.
CarManager Lớp cơ sở của tất cả các trình quản lý được các ứng dụng bên ngoài sử dụng để tương tác với các dịch vụ dành riêng cho ô tô do CarService triển khai.
CarService Dịch vụ Nền tảng Android cung cấp khả năng liên lạc giữa các ứng dụng bên ngoài (bao gồm cả Google Maps) và các tính năng dành riêng cho ô tô, chẳng hạn như quyền truy cập Cụm công cụ.
Điểm đến Điểm đến cuối cùng mà phương tiện sẽ hướng tới.
ETA Thời gian dự kiến ​​đến nơi.
Đơn vị đứng đầu (HU) Đơn vị tính toán chính được nhúng trong ô tô. HU chạy toàn bộ mã Android và được kết nối với màn hình trung tâm trên ô tô.
Cụm công cụ Màn hình phụ nằm phía sau vô lăng và giữa các bảng đồng hồ trên xe. Đây có thể là một đơn vị tính toán độc lập được kết nối với HU thông qua mạng nội bộ của ô tô (CAN bus) hoặc màn hình phụ được gắn vào HU.
InstrumentClusterRenderingService Lớp cơ sở cho dịch vụ được sử dụng để giao tiếp với màn hình Cụm công cụ. OEM phải cung cấp phần mở rộng của lớp này để tương tác với phần cứng dành riêng cho OEM.
Ứng dụng KitchenSink Ứng dụng thử nghiệm đi kèm với Android Automotive.
Tuyến đường Một con đường cụ thể mà phương tiện di chuyển để đến đích.
Dịch vụ đơn lẻ Một dịch vụ Android có thuộc tính android:singleUser . Tại bất kỳ thời điểm nào, có nhiều nhất một phiên bản của dịch vụ chạy trên hệ thống Android.

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

Để phát triển sự tích hợp, hãy đảm bảo có những yếu tố sau:

  • Môi trường phát triển Android. Để thiết lập môi trường phát triển Android, hãy xem Yêu cầu xây dựng .
  • Tải xuống mã nguồn Android. Nhận 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 .
  • Đơn vị đứng đầu (HU). Một thiết bị Android có khả năng chạy Android 9 (hoặc mới hơn). Thiết bị này phải có màn hình riêng và có khả năng nhấp nháy màn hình với 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ụ vật lý gắn liền với HU. Nếu phần cứng và kernel của thiết bị 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 thông 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 của chính nó.
    • Hiển thị mô phỏng. Trong quá trình phát triển, bạn có thể sử dụng một trong những môi trường mô phỏng sau:
      • Màn hình phụ mô phỏng. Để bật màn hình phụ mô phỏng trên bất kỳ bản phân phối AOSP Android nào, hãy đi tới cài đặt Tùy chọn nhà phát triển trong ứng dụng Hệ thống cài đặt rồi chọn Mô phỏng màn hình phụ. Cấu hình này tương đương với việc gắn một màn hình phụ vật lý, với hạn chế là màn hình này được đặt chồng lên màn hình chính.
      • Cụm công cụ mô phỏng. Trình mô phỏng Android đi kèm với Android Automotive cung cấp tùy chọn hiển thị cụm công cụ với dịch vụ ClusterRenderingService được kết nối với màn hình phụ.
      • trình giả lập _qemu-pipe . Dịch vụ ClusterRenderingService được kết nối với màn hình phụ. triển khai cụm công cụ tham chiếu để kết nối với màn hình bên ngoài được mô phỏng này.

Kiến trúc tích hợp

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

Bất kỳ sự tích hợp nào của API cụm công cụ đều bao gồm ba thành phần sau:

  • CarService
  • Ứng dụng điều hướng
  • Dịch vụ cụm công cụ OEM

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

Dịch vụ cho xe ô tô

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

CarService 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 trình quản lý. Để tương tác với các dịch vụ, các ứng dụng chạy trong ô tô có thể truy cập vào những trình quản lý này.

Để triển khai cụm công cụ, các OEM ô tô phải tạo một bản triển khai tùy chỉnh InstrumentClusterRendererService và cập nhật dịch vụ ClusterRenderingService được kết nối với màn hình phụ.

Khi hiển thị Cụm công cụ, trong quá trình khởi động CarService sẽ đọc khóa InstrumentClusterRendererService của dịch vụ ClusterRenderingService được kết nối với màn hình phụ. để xác định vị trí triển khai InstrumentClusterService . Trong AOSP, mục nhập này trỏ đến dịch vụ kết xuất triển khai cụm mẫu 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 điều hướng, như Google Maps, yêu cầu CarInstrumentClusterManager , CarService cung cấp trình quản lý cập nhật trạng thái Cụm công cụ từ InstrumentClusterRenderingService bị ràng buộc. (Trong trường hợp này, ràng buộc đề cập đến Dịch vụ Android .)

Dịch vụ cụm công cụ

OEM phải tạo Gói Android (APK) chứa lớp con của dịch vụ ClusterRenderingService được kết nối với màn hình phụ. Dịch vụ ClusterRenderingService được kết nối với màn hình phụ. cho một mẫu.

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

  • Cung cấp giao diện 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à hiển thị các cập nhật trạng thái điều hướng, chẳng hạn như hướng dẫn điều hướng từng chặng.

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

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

Trình tự tích hợp

Sơ đồ sau đây minh họa việc triển khai trạng thái điều hướng hiển thị các bản cập nhật:

Trình tự tích hợp

Trong hình minh họa này, màu sắc biểu thị những điều sau:

  • Màu vàng. CarServiceCarNavigationStatusManager được cung cấp bởi nền tảng Android. Để tìm hiểu thêm, hãy xem Ô tôCAR_NAVIGATION_SERVICE .
  • Lục lam. InstrumentClusterRendererService do OEM triển khai.
  • Màu tím. Ứng dụng Điều hướng do Google và các nhà phát triển bên thứ ba triển khai.
  • Màu xanh lá. CarAppFocusManager . Để tìm hiểu thêm, hãy xem Sử dụng API CarAppFocusManager bên dưới và CarAppFocusManager .

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

  1. CarService khởi tạo InstrumentClusterRenderingService .
  2. Trong quá trình khởi tạo, InstrumentClusterRenderingService cập nhật CarService với:
    1. Các thuộc tính hiển thị của Cụm công cụ, chẳng hạn như ranh giới không bị che khuất (xem thêm chi tiết về ranh giới không bị che khuất sau).
    2. Các tùy 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ụ (xem thêm chi tiết tại Tùy chọn hoạt động .
  3. Ứ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 có các quyền cần thiết):
    1. Lấy CarAppFocusManager bằng cách sử dụng lớp Car từ car-lib.
    2. Trước khi bắt đầu chỉ đường từng chặng, hãy gọi tới CarAppFocusManager.requestFocus() để chuyển CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION làm thông số appType .
  4. CarAppFocusManager truyền đạt yêu cầu này tới CarService . Nếu được cấp, CarService sẽ kiểm tra gói ứng dụng điều hướng và định vị hoạt động được đánh dấu bằng danh mục android.car.cluster.NAVIGATION .
  5. Nếu được tìm thấy, ứng dụng điều hướng sẽ sử dụng ActivityOptions động do InstrumentClusterRenderingService báo cáo để khởi chạy hoạt động và bao gồm các thuộc tính hiển thị của Cụm công cụ làm phần bổ sung trong ý định.

Tích hợp API

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

  • Được chỉ định là dịch vụ đơn lẻ bằng cách thêm giá trị sau vào 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 công cụ sẽ chạy, ngay cả trong quá trình khởi tạo và chuyển đổi người dùng:
    android:singleUser="true"
  • Giữ quyền hệ thống BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE . Điều này đảm bảo rằng chỉ dịch vụ kết xuất Cụm công cụ được bao gồm như một phần của hình ảnh hệ thống Android mới bị ràng buộc bởi CarService :
    <uses-permission android:name="android.car.permission.BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE"/>
    

Triển khai InstrumentClusterRenderingService

Để xây dựng dịch vụ:

  1. Viết một lớp mở rộng từ dịch vụ ClusterRenderingService được kết nối với màn hình phụ.
  2. rồi thêm mục nhập tương ứng vào tệp AndroidManifest.xml của bạn. Lớp này điều khiển màn hình Cụm công cụ và có thể ( tùy chọn ) hiển thị dữ liệu API trạng thái điều hướng.
  3. Trong thời gian onCreate() , hãy sử dụng dịch vụ này để khởi tạo giao tiếp với phần cứng kết xuất. Các tùy chọn bao gồm:
    • Xác định màn hình phụ sẽ được sử dụng cho Cụm thiết bị.
    • Tạo màn hình ảo để ứng dụng Cụm công cụ hiển thị và truyền hình ảnh được hiển thị đến thiết bị bên ngoài (sử dụng định dạng truyền phát video, chẳng hạn như H.264).
  4. 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 sử dụng để hiển thị Hoạt động trên Cụm công cụ. Sử dụng các tham số sau:
    • loại. Dịch vụ ClusterRenderingService được kết nối với màn hình phụ.
    • ActivityOptions. Một phiên bản ActivityOptions có thể được sử dụng để khởi chạy Hoạt động trong Cụm công cụ. Ví dụ: từ triển khai Cụm công cụ mẫu trên AOSP:
      getService().setClusterActivityLaunchOptions(
         CATEGORY_NAVIGATION,
         ActivityOptions.makeBasic()
            .setLaunchDisplayId(displayId));
      
  5. Khi Cụm công cụ 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 các tham số sau:
    • dịch vụ ClusterRenderingService category được kết nối với màn hình phụ.
    • state Gói được tạo bằng dịch vụ ClusterRenderingService được kết nối với màn hình phụ.
    • Hãy chắc chắn cung cấp các dữ liệu sau:
      • visible Chỉ định Cụm công cụ ở 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 khu vực trong màn hình Cụm công cụ nơi an toàn để hiển thị nội dung. Ví dụ: các khu vực được bao phủ bởi mặt đồng hồ và đồng hồ đo.
  6. Ghi đè phương thức Service#dump() và báo cáo thông tin trạng thái hữu ích cho việc gỡ lỗi (xem dumpsys để biết thêm thông tin).

Triển khai InstrumentClusterRenderingService mẫu

Ví dụ sau đây phác thảo cách triển khai InstrumentClusterRenderingService , tạo ra VirtualDisplay để trình bày nội dung Cụm công cụ trên màn hình vật lý từ xa.

Ngoài ra, mã này có thể chuyển displayId của màn hình phụ vật lý được kết nối với HU, nếu biết là có sẵn.

/**
* 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 API CarAppFocusManager

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 viết biết ứng dụng điều hướng nào có tiêu điểm điều hướng tại bất kỳ thời điểm nào. OEM có thể sử dụng phương thức CarAppFocusManager#addFocusListener() hiện có, sau đó sử dụng getAppTypeOwner() để tìm hiểu ứng dụng nào cần tập trung. Với thông tin này, OEM có thể:

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

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

Sử dụng phương thức CarAppFocusManager#addFocusListener(..) để lắng nghe những thay đổi về tiêu điểm của ứng dụng:

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 tên gói của chủ sở hữu hiện tại của loại ứng dụng nhất định đang được chú ý. 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: Sử 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.

Để chạy ứng dụng mẫu này:

  1. Xây dựng và cài đặt Android Auto trên HU được hỗ trợ. Sử dụng hướng dẫn cài đặt và nhấp nháy 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 khảo .
  2. Kết nối màn hình phụ vật lý với HU (nếu được hỗ trợ) hoặc bật HU phụ ảo:
    1. Chọn Chế độ nhà phát triển trong ứng dụng Cài đặt.
    2. Đi tới Cài đặt > Hệ thống > Nâng cao > Tùy chọn nhà phát triển > Mô phỏng màn hình phụ .
  3. Khởi động lại HU. Dịch vụ ClusterRenderingService được kết nối với màn hình phụ.
  4. Để khởi chạy ứng dụng KitchenSink:
    1. Mở ngăn kéo.
    2. Chuyển đến Inst. Cụm .
    3. Nhấp vào BẮT ĐẦU SIÊU DỮ LIỆU .

KitchenSink yêu cầu tiêu điểm NAVIGATION, hướng dẫn dịch vụ DirectRenderingCluster hiển thị giao diện người dùng mô phỏng trên Cụm công cụ.