Instrument Cluster API

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Gunakan Instrument Cluster API (Android API) untuk menampilkan aplikasi navigasi, termasuk Google Maps, di layar sekunder di mobil, seperti di belakang setir pada panel instrumen. Halaman ini menjelaskan cara membuat layanan untuk mengontrol layar sekunder tersebut dan mengintegrasikan layanan dengan CarService sehingga aplikasi navigasi dapat menampilkan antarmuka pengguna.

Terminologi

Istilah berikut digunakan di halaman ini.

Prasyarat

Sebelum melanjutkan, pastikan Anda memiliki elemen berikut:

• Lingkungan pengembangan Android. Untuk menyiapkan lingkungan pengembangan Android, lihat Persyaratan build.
• Download kode sumber Android. Dapatkan versi terbaru kode sumber Android dari cabang pi-car-release (atau yang lebih baru) di https://android.googlesource.com.
• Head unit (HU). Perangkat Android yang dapat menjalankan Android 9 (atau yang lebih baru). Perangkat ini harus memiliki layarnya sendiri dan dapat mem-flash layar dengan build Android baru.
• Cluster Instrumen adalah salah satu dari berikut:
  • Layar sekunder fisik yang terpasang ke HU. Jika hardware dan kernel perangkat mendukung pengelolaan beberapa layar.
  • Unit independen. Setiap unit komputasi yang terhubung ke HU melalui koneksi jaringan, yang mampu menerima dan menampilkan streaming video di layarnya sendiri.
  • Layar yang diemulasikan. Selama pengembangan, Anda dapat menggunakan salah satu lingkungan yang diemulasi ini:
    • Simulasi tampilan sekunder. Untuk mengaktifkan layar sekunder simulasi di distribusi Android AOSP, buka setelan Opsi Developer di aplikasi sistem Setelan, lalu pilih Simulasi layar sekunder Konfigurasi ini setara dengan memasang layar sekunder fisik, dengan batasan bahwa layar ini ditempatkan di atas layar utama.
    • Cluster instrumen yang diemulasi. Emulator Android yang disertakan dengan AAOS menyediakan opsi untuk menampilkan cluster instrumen dengan ClusterRenderingService.

Arsitektur integrasi

Komponen integrasi

Setiap integrasi Instrument Cluster API terdiri dari tiga komponen berikut:

• CarService
• Aplikasi navigasi
• Layanan Cluster Instrumen OEM

LayananMobil

CarService memediasi antara aplikasi navigasi dan mobil, memastikan bahwa hanya satu aplikasi navigasi yang aktif pada waktu tertentu dan hanya aplikasi dengan izin android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL yang dapat mengirim data ke mobil.

CarService melakukan bootstrap semua layanan khusus mobil dan memberikan akses ke layanan ini melalui serangkaian pengelola. Untuk berinteraksi dengan layanan, aplikasi yang berjalan di mobil dapat mengakses pengelola ini.

Untuk penerapan cluster instrumen, OEM otomotif harus membuat penerapan kustom InstrumentClusterRendererService dan mengupdate ClusterRenderingService.

Saat merender Cluster Instrumen, selama proses booting, CarService membaca kunci InstrumentClusterRendererService dari ClusterRenderingService untuk menemukan implementasi InstrumentClusterService. Di AOSP, entri ini menunjuk ke layanan render implementasi cluster contoh Navigation State API:

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

Layanan yang dirujuk dalam entri ini diinisialisasi dan terikat dengan CarService. Saat aplikasi navigasi, seperti Google Maps, meminta CarInstrumentClusterManager, CarService akan menyediakan pengelola yang memperbarui status Cluster Instrumen dari InstrumentClusterRenderingService terikat. (Dalam hal ini, bound merujuk pada Layanan Android.)

Layanan Cluster Instrumen

OEM harus membuat Paket Android (APK) yang berisi subclass ClusterRenderingService.

Class ini memiliki dua tujuan:

• Menyediakan antarmuka Android dan perangkat rendering Cluster Instrumen (tujuan halaman ini).
• Menerima dan merender pembaruan status navigasi, seperti panduan navigasi belokan demi belokan.

Untuk tujuan pertama, implementasi OEM InstrumentClusterRendererService harus melakukan inisialisasi layar sekunder yang digunakan untuk merender informasi di layar di kabin mobil dan menyampaikan informasi ini ke CarService dengan memanggil metode InstrumentClusterRendererService.setClusterActivityOptions() dan InstrumentClusterRendererService.setClusterActivityState().

Untuk fungsi kedua, layanan Cluster Instrumen harus menyediakan implementasi antarmuka ClusterRenderingService yang menerima peristiwa update status navigasi, yang dienkode sebagai eventType dan data peristiwa yang dienkode dalam paket.

Urutan integrasi

Diagram berikut mengilustrasikan implementasi status navigasi yang merender update:

Dalam ilustrasi ini, warna menunjukkan hal berikut:

• Kuning. CarService dan CarNavigationStatusManager disediakan oleh platform Android. Untuk mempelajari lebih lanjut, lihat Mobil dan CAR_NAVIGATION_SERVICE.
• Sian. InstrumentClusterRendererService diterapkan oleh OEM.
• Ungu. Aplikasi Navigasi yang diimplementasikan oleh Google dan developer pihak ketiga.
• Hijau. CarAppFocusManager. Untuk mempelajari lebih lanjut, lihat Menggunakan CarAppFocusManager API di bawah dan CarAppFocusManager.

Alur informasi Status Navigasi mengikuti urutan ini:

1. CarService melakukan inisialisasi InstrumentClusterRenderingService.
2. Selama inisialisasi, InstrumentClusterRenderingService akan memperbarui CarService dengan:
   1. Properti tampilan Cluster Instrumen, seperti batas yang tidak tertutup (lihat detail selengkapnya tentang batas yang tidak tertutup nanti).
   2. Opsi aktivitas yang diperlukan untuk meluncurkan aktivitas di dalam layar Cluster Instrumen. Untuk mempelajari lebih lanjut, lihat ActivityOptions.
3. Aplikasi navigasi (seperti Google Maps untuk Android Automotive atau aplikasi peta apa pun dengan izin yang diperlukan):
   1. Mendapatkan CarAppFocusManager menggunakan class Mobil dari car-lib.
   2. Sebelum rute belokan demi belokan dimulai, panggilan ke CarAppFocusManager.requestFocus() untuk meneruskan CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION sebagai parameter appType.
4. CarAppFocusManager menyampaikan permintaan ini ke CarService. Jika diizinkan, CarService akan memeriksa paket aplikasi navigasi dan menemukan aktivitas yang ditandai dengan kategori android.car.cluster.NAVIGATION.
5. Jika ditemukan, aplikasi navigasi akan menggunakan ActivityOptions yang dilaporkan oleh InstrumentClusterRenderingService untuk meluncurkan aktivitas dan menyertakan properti tampilan Cluster Instrumen sebagai tambahan dalam intent.

Mengintegrasikan API

Implementasi InstrumentClusterRenderingService harus:

• Ditetapkan sebagai layanan singleton dengan menambahkan nilai berikut ke AndroidManifest.xml. Hal ini diperlukan untuk memastikan bahwa satu salinan layanan Cluster Instrumen berjalan, bahkan selama inisialisasi dan pengalihan pengguna:
  android:singleUser="true"
• Memiliki izin sistem BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE. Hal ini menjamin bahwa hanya layanan rendering Cluster Instrumen yang disertakan sebagai bagian dari image sistem Android yang pernah terikat oleh CarService:

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

Mengimplementasikan InstrumentClusterRenderingService

Untuk mem-build layanan:

1. Tulis class yang diperluas dari ClusterRenderingService, lalu tambahkan entri yang sesuai ke file AndroidManifest.xml Anda. Class ini mengontrol tampilan Cluster Instrumen dan dapat (secara opsional) merender data API Status Navigasi.
2. Selama onCreate(), gunakan layanan ini untuk melakukan inisialisasi komunikasi dengan hardware rendering. Opsi mencakup:
   • Tentukan tampilan sekunder yang akan digunakan untuk Cluster Instrumen.
   • Buat tampilan virtual sehingga aplikasi Cluster Instrumen merender dan mengirimkan gambar yang dirender ke unit eksternal (menggunakan format streaming video, seperti H.264).
3. Saat tampilan yang ditunjukkan di atas siap, layanan ini harus memanggil InstrumentClusterRenderingService#setClusterActivityLaunchOptions() untuk menentukan ActivityOptions yang tepat yang harus digunakan untuk menampilkan Aktivitas di Cluster Instrumen. Gunakan parameter ini:
   • category. ClusterRenderingService.
   • ActivityOptions. Instance ActivityOptions yang dapat digunakan untuk meluncurkan Aktivitas di Cluster Instrumen. Misalnya, dari contoh penerapan Cluster Instrumen di AOSP:

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

4. Saat Cluster Instrumen siap menampilkan aktivitas, layanan ini harus memanggil InstrumentClusterRenderingService#setClusterActivityState(). Gunakan parameter berikut:
   • category ClusterRenderingService.
   • state Paket yang dibuat dengan ClusterRenderingService. Pastikan untuk memberikan data ini:
     • visible Menentukan Cluster Instrumen sebagai terlihat dan siap menampilkan konten.
     • unobscuredBounds Persegi panjang yang menentukan area dalam tampilan Cluster Instrumen yang aman untuk menampilkan konten. Misalnya, area yang tertutup oleh tombol dan pengukur.
5. Ganti metode Service#dump() dan laporkan informasi status yang berguna untuk proses debug (lihat dumpsys untuk informasi selengkapnya).

Contoh implementasi InstrumentClusterRenderingService

Contoh berikut menguraikan implementasi InstrumentClusterRenderingService, yang membuat VirtualDisplay untuk menampilkan konten Cluster Instrumen di layar fisik jarak jauh.

Atau, kode ini dapat meneruskan displayId layar sekunder fisik yang terhubung ke HU, jika diketahui tersedia.

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

Menggunakan CarAppFocusManager API

CarAppFocusManager API menyediakan metode bernama getAppTypeOwner(), yang memungkinkan layanan cluster yang ditulis oleh OEM untuk mengetahui aplikasi navigasi mana yang memiliki fokus navigasi pada waktu tertentu. OEM dapat menggunakan metode CarAppFocusManager#addFocusListener() yang ada, lalu menggunakan getAppTypeOwner() untuk mempelajari aplikasi mana yang memiliki fokus. Dengan informasi ini, OEM dapat:

• Alihkan aktivitas yang ditampilkan di cluster ke aktivitas cluster yang disediakan oleh aplikasi navigasi yang memegang fokus.
• Dapat mendeteksi apakah aplikasi navigasi yang difokuskan memiliki aktivitas cluster atau tidak. Jika aplikasi navigasi yang difokuskan tidak memiliki aktivitas cluster (atau jika aktivitas tersebut dinonaktifkan), OEM dapat mengirim sinyal ini ke DIM mobil sehingga faset navigasi cluster dilewati sepenuhnya.

Gunakan CarAppFocusManager untuk menyetel dan memproses fokus aplikasi saat ini, seperti navigasi aktif atau perintah suara. Biasanya, hanya satu instance aplikasi tersebut yang aktif berjalan (atau difokuskan) dalam sistem.

Gunakan metode CarAppFocusManager#addFocusListener(..) untuk memproses perubahan fokus aplikasi:

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
}

Gunakan metode CarAppFocusManager#getAppTypeOwner(..) untuk mengambil nama paket pemilik saat ini dari jenis aplikasi tertentu yang sedang difokuskan. Metode ini dapat menampilkan lebih dari satu nama paket jika pemilik saat ini menggunakan fitur 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
}

...

Lampiran: Menggunakan aplikasi contoh

AOSP menyediakan aplikasi contoh yang menerapkan Navigation State API.

Untuk menjalankan aplikasi contoh ini:

1. Mem-build dan mem-flash Android Auto di HU yang didukung. Gunakan petunjuk pembuatan dan flashing Android khusus untuk perangkat Anda. Untuk mengetahui petunjuknya, lihat Menggunakan Papan Referensi.
2. Hubungkan layar sekunder fisik ke HU (jika didukung) atau aktifkan HU sekunder virtual:
   1. Pilih Mode Developer di aplikasi Setelan.
   2. Buka Setelan > Sistem > Lanjutan > Opsi developer > Simulasikan layar sekunder.
3. Mulai ulang HU
4. Untuk meluncurkan aplikasi KitchenSink:
   1. Buka panel samping.
   2. Buka Inst. Cluster.
   3. Klik MULAI METADATA.

KitchenSink meminta fokus NAVIGATION, yang menginstruksikan layanan DirectRenderingCluster untuk menampilkan antarmuka pengguna tiruan di Cluster Instrumen.