Instrument Cluster API

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

Terminologi

Istilah berikut digunakan di halaman ini.

Prasyarat

Sebelum melanjutkan, pastikan Anda memiliki elemen berikut:

• Lingkungan pengembangan Android. Untuk menyiapkan Android lingkungan pengembangan, 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 mampu menjalankan Android 9 (atau yang lebih baru). Perangkat ini harus memiliki layarnya sendiri dan mampu mengedipkan layar dengan build baru Android.
• Cluster Instrumen adalah salah satu dari berikut ini:
  • Layar sekunder fisik yang dipasang ke HU. Jika perangkat keras dan {i>kernel<i} perangkat mendukung pengelolaan beberapa tampilan.
  • Unit independen. Setiap unit komputasi yang terhubung ke HU melalui koneksi jaringan, yang mampu menerima dan menampilkan streaming video pada tampilan itu sendiri.
  • Tampilan emulasi. Selama pengembangan, Anda dapat menggunakan salah satu lingkungan yang diemulasi ini:
    • Simulasi tampilan sekunder. Untuk mengaktifkan simulasi tampilan sekunder di distribusi Android AOSP, buka Opsi Developer setelan di aplikasi sistem Setelan, lalu pilih Simulasikan sekunder tampilan Konfigurasi ini setara dengan melampirkan komponen sekunder fisik tampilan, dengan batasan bahwa tampilan ini ditumpangkan di atas tampilan utama tampilan.
    • Cluster instrumen yang diemulasi. Emulator Android menyertakan 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 melakukan mediasi antara aplikasi navigasi dan mobil, sehingga memastikan bahwa hanya satu aplikasi navigasi aktif pada waktu tertentu dan hanya aplikasi dengan Izin android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL dapat mengirim data ke mobil.

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

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

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

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

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

Layanan Cluster Instrumen

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

Class ini memiliki dua tujuan:

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

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

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

Urutan integrasi

Diagram berikut mengilustrasikan penerapan status navigasi yang merender pembaruan:

Dalam ilustrasi ini, warna menunjukkan hal berikut:

• Kuning. CarService dan CarNavigationStatusManager yang disediakan oleh platform Android. Untuk mempelajari lebih lanjut, lihat Mobil dan CAR_NAVIGATION_SERVICE.
• Sian. InstrumentClusterRendererService diterapkan oleh OEM.
• Ungu. Aplikasi Navigasi yang diterapkan oleh Google dan pihak ketiga developer.
• 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 diperbarui CarService dengan:
   1. Properti tampilan Cluster Instrumen, seperti batas yang tidak terhalang (lihat detail selengkapnya tentang batas yang tidak jelas 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 for Android Automotive atau aplikasi peta apa pun yang memiliki izin yang diperlukan):
   1. Mendapatkan CarAppFocusManager menggunakan class Car dari car-lib.
   2. Sebelum rute belokan demi belokan dimulai, panggilan ke CarAppFocusManager.requestFocus() untuk lulus CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION sebagai appType .
4. CarAppFocusManager menyampaikan permintaan ini ke CarService. Jika diberikan, CarService akan memeriksa paket aplikasi navigasi dan menemukan lokasi aktivitas ditandai dengan kategori android.car.cluster.NAVIGATION.
5. Jika ditemukan, aplikasi navigasi akan menggunakan ActivityOptions yang dilaporkan oleh InstrumentClusterRenderingService untuk meluncurkan aktivitas dan menyertakan Cluster Instrumen menampilkan properti sebagai tambahan dalam intent.

Mengintegrasikan API

Implementasi InstrumentClusterRenderingService harus:

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

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

Mengimplementasikan InstrumentClusterRenderingService

Untuk membangun layanan:

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

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

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

Contoh implementasi InstrumentClusterRenderingService

Contoh berikut menguraikan InstrumentClusterRenderingService implementasi, yang akan membuat VirtualDisplay untuk menyajikan Instrumen Kelompokkan konten pada tampilan fisik jarak jauh.

Atau, kode ini dapat meneruskan displayId dari sekunder fisik terhubung ke HU, jika diketahui ada.

/**
* 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 baik. OEM dapat menggunakan metode CarAppFocusManager#addFocusListener() yang ada, dan lalu gunakan 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 memegang fokus.
• Dapat mendeteksi apakah aplikasi navigasi yang difokuskan memiliki aktivitas cluster atau tidak. Jika fokusnya aplikasi navigasi tidak memiliki aktivitas cluster (atau jika aktivitas tersebut dinonaktifkan), OEM dapat mengirimkan sinyal ini ke DIM mobil agar faset navigasi cluster dilewati sepenuhnya.

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

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

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
}

Menggunakan metode CarAppFocusManager#getAppTypeOwner(..) untuk mengambil paket nama pemilik saat ini dari jenis aplikasi tertentu yang sedang menjadi fokus. 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 mengimplementasikan Navigation State API.

Untuk menjalankan aplikasi contoh ini:

1. Membangun dan melakukan flash Android Auto pada HU yang didukung. Gunakan Petunjuk build dan flash Android khusus untuk perangkat Anda. Untuk mengetahui petunjuknya, lihat Menggunakan Board Orisinal.
2. Hubungkan layar sekunder fisik ke HU (jika didukung) atau aktifkan layar virtual HU sekunder:
   1. Pilih Mode Developer di aplikasi Setelan.
   2. Buka Setelan > Sistem > Lanjutan > Opsi developer > Menyimulasikan tampilan 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 NAVIGASI, yang menginstruksikan DirectRenderingCluster untuk menampilkan antarmuka pengguna tiruan di Cluster Instrumen.