Instrument Cluster API

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Google Haritalar dahil olmak üzere navigasyon uygulamalarını, araçtaki ikincil bir ekranda (ör. gösterge panelindeki direksiyon arkasına) görüntülemek için gösterge paneli API'sini (Android API) kullanın. Bu sayfada, ikincil ekranı kontrol etmek ve navigasyon uygulamalarının kullanıcı arayüzü gösterebilmesi için hizmeti CarService ile entegre etmek üzere nasıl bir hizmet oluşturacağınız açıklanmaktadır.

Terminoloji

Bu sayfada aşağıdaki terimler kullanılmaktadır.

Ön koşullar

Devam etmeden önce aşağıdaki öğelere sahip olduğunuzdan emin olun:

• Android geliştirme ortamı. Android geliştirme ortamını kurmak için Derleme koşulları bölümüne bakın.
• Android kaynak kodunu indirin. https://android.googlesource.com adresindeki pi-car-release şubesinden (veya sonraki bir şubeden) Android kaynak kodunun en son sürümünü edinin.
• Ana birim (HU). Android 9 (veya sonraki sürümler) çalıştırabilen bir Android cihaz Bu cihazın kendi ekranı olmalı ve ekranda Android'in yeni sürümlerini yükleyebilmelidir.
• Gösterge paneli aşağıdakilerden biridir:
  • HU'ya bağlı fiziksel ikincil ekran. Cihaz donanımı ve çekirdeği birden fazla ekranın yönetimini destekliyorsa.
  • Bağımsız birim. HU'ya ağ bağlantısı üzerinden bağlı olan ve kendi ekranında video akışı alıp görüntüleyebilen herhangi bir hesaplama birimi.
  • Emülasyonlu ekran. Geliştirme sırasında şu emülasyon ortamlarından birini kullanabilirsiniz:
    • Simüle edilmiş ikincil ekranlar. Herhangi bir AOSP Android dağıtımında simüle edilmiş ikincil ekranı etkinleştirmek için Ayarlar sistem uygulamasındaki Geliştirici Seçenekleri ayarlarına gidip İkincil ekranları simüle et'i seçin. Bu yapılandırma, birincil ekranın üzerine yerleştirilmiş fiziksel bir ikincil ekran bağlamaya eşdeğerdir.
    • Öykünülen gösterge paneli. AAOS'a dahil edilen Android emülatöründe, ClusterRenderingService ile gösterge paneli görüntüleme seçeneği bulunur.

Entegrasyon mimarisi

Entegrasyon bileşenleri

Instrument Cluster API'nin tüm entegrasyonları aşağıdaki üç bileşenden oluşur:

• CarService
• Navigasyon uygulamaları
• OEM Gösterge Grubu Hizmeti

CarService

CarService, navigasyon uygulamaları ile araç arasında aracılık yapar. Bu sayede, herhangi bir zamanda yalnızca bir navigasyon uygulamasının etkin olmasını ve yalnızca android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL iznine sahip uygulamaların araca veri göndermesini sağlar.

CarService, araca özgü tüm hizmetleri başlatır ve bir dizi yönetici aracılığıyla bu hizmetlere erişim sağlar. Araçtaki uygulamalar, hizmetlerle etkileşimde bulunmak için bu yöneticilere erişebilir.

Otomotiv OEM'ler, gösterge paneli uygulamak için InstrumentClusterRendererService'in özel bir uygulamasını oluşturmalı ve ClusterRenderingService'i güncellemelidir.

Bir gösterge grubunu oluştururken CarService, InstrumentClusterService uygulamasını bulmak için CarService, başlatma işlemi sırasında ClusterRenderingService'in InstrumentClusterRendererService anahtarını okur. AOSP'de bu giriş, Navigation State API örnek küme uygulama oluşturma hizmetini gösterir:

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

Bu girişte bahsedilen hizmet başlatılır ve CarService ile bağlanır. Google Haritalar gibi navigasyon uygulamaları CarInstrumentClusterManager istediğinde CarService, bağlı InstrumentClusterRenderingService'den gösterge grubu durumunu güncelleyen bir yönetici sağlar. (Bu durumda bağlı, Android Hizmetleri'ni ifade eder.)

Gösterge grubu hizmeti

OEM'ler, ClusterRenderingService alt sınıfını içeren bir Android paketi (APK) oluşturmalıdır.

Bu sınıfın iki amacı vardır:

• Android ve gösterge paneli oluşturma cihazı için bir arayüz sağlar (bu sayfanın amacı budur).
• Adım adım navigasyon kılavuzu gibi navigasyon durumu güncellemelerini alır ve gösterir.

İlk amaç için InstrumentClusterRendererService OEM uygulamalarının, araba kabinindeki ekranlarda bilgi oluşturmak için kullanılan ikincil ekranı başlatması ve InstrumentClusterRendererService.setClusterActivityOptions() ile InstrumentClusterRendererService.setClusterActivityState() yöntemlerini çağırarak bu bilgileri CarService'a iletmesi gerekir.

İkinci işlev için gösterge paneli hizmeti, eventType olarak kodlanmış navigasyon durumu güncelleme etkinliklerini ve bir pakette kodlanmış etkinlik verilerini alan ClusterRenderingService arayüzünün bir uygulamasını sağlamalıdır.

Entegrasyon sırası

Aşağıdaki şemada, güncellemeleri oluşturan bir gezinme durumunun uygulanması gösterilmektedir:

Bu görselde renkler aşağıdakileri ifade eder:

• Sarı. CarService ve CarNavigationStatusManager Android platformu tarafından sağlanır. Daha fazla bilgi için Araba ve CAR_NAVIGATION_SERVICE başlıklı makaleleri inceleyin.
• Camgöbeği. InstrumentClusterRendererService OEM tarafından uygulanır.
• Mor. Google ve üçüncü taraf geliştiriciler tarafından uygulanan Navigasyon uygulaması.
• Yeşil. CarAppFocusManager. Daha fazla bilgi edinmek için aşağıdaki CarAppFocusManager API'yi kullanma bölümüne ve CarAppFocusManager'a bakın.

Gezinme Durumu bilgi akışı şu sırayı izler:

1. CarService, InstrumentClusterRenderingService değerini başlatır.
2. Başlatma sırasında InstrumentClusterRenderingService, CarService'u şu bilgilerle günceller:
   1. Gösterge paneli görüntüleme özellikleri (ör. engellenmeyen sınırlar) (engellenmeyen sınırlar hakkında daha fazla bilgiyi aşağıda bulabilirsiniz).
   2. Gösterge grubu ekranında etkinlikleri başlatmak için gereken etkinlik seçenekleri. Daha fazla bilgi için ActivityOptions konusuna bakın.
3. Bir navigasyon uygulaması (ör. Android Automotive için Google Haritalar veya gerekli izinlere sahip herhangi bir haritalar uygulaması):
   1. car-lib'deki Car sınıfını kullanarak bir CarAppFocusManager alır.
   2. Adım adım yol tarifleri başlamadan önce CarAppFocusManager.requestFocus() çağrıları, CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION parametresi olarak appType parametresini iletir.
4. CarAppFocusManager bu isteği CarService'a iletir. İzin verilirse CarService, navigasyon uygulaması paketini inceler ve android.car.cluster.NAVIGATION kategorisiyle işaretlenmiş bir etkinlik bulur.
5. Bulunursa navigasyon uygulaması, etkinliği başlatmak için InstrumentClusterRenderingService tarafından bildirilen ActivityOptions değerini kullanır ve gösterge paneli görüntüleme özelliklerini intent'e ek olarak ekler.

API'yi entegre etme

InstrumentClusterRenderingService uygulaması:

• AndroidManifest.xml dosyasına aşağıdaki değeri ekleyerek tekil hizmet olarak atanmalıdır. Bu, başlatma ve kullanıcı geçişi sırasında bile gösterge grubu hizmetinin tek bir kopyasının çalıştırılmasını sağlamak için gereklidir:
  android:singleUser="true"
• BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE sistem iznini basılı tutun. Bu, yalnızca Android sistem görüntüsünün bir parçası olarak dahil edilen gösterge paneli oluşturma hizmetinin CarService ile bağlanmasını sağlar:

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

InstrumentClusterRenderingService'i uygulama

Hizmeti oluşturmak için:

1. ClusterRenderingService sınıfından türetilen bir sınıf yazın ve ardından AndroidManifest.xml dosyanıza ilgili bir giriş ekleyin. Bu sınıf, gösterge grubu ekranını kontrol eder ve isteğe bağlı olarak Navigasyon Durumu API verilerini oluşturabilir.
2. onCreate() sırasında, oluşturma donanımıyla iletişimi başlatmak için bu hizmeti kullanın. Seçenekler arasında şunlar bulunur:
   • Gösterge paneli için kullanılacak ikincil ekranı belirleyin.
   • Gösterge paneli uygulamasının oluşturulan görüntüyü oluşturması ve harici bir birime (H.264 gibi bir video akış biçimi kullanarak) aktarması için sanal bir ekran oluşturun.
3. Yukarıda belirtilen ekran hazır olduğunda bu hizmet, gösterge tablosunda bir etkinlik görüntülemek için kullanılması gereken tam ActivityOptions değerini tanımlamak üzere InstrumentClusterRenderingService#setClusterActivityLaunchOptions() işlevini çağırmalıdır. Şu parametreleri kullanın:
   • category. ClusterRenderingService.
   • ActivityOptions. Gösterge grubunda etkinlik başlatmak için kullanılabilen bir ActivityOptions örneği. Örneğin, AOSP'deki örnek gösterge paneli uygulamasından:

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

4. Gösterge paneli etkinlikleri göstermeye hazır olduğunda bu hizmetin InstrumentClusterRenderingService#setClusterActivityState() çağrılması gerekir. Aşağıdaki parametreleri kullanın:
   • category ClusterRenderingService.
   • state ClusterRenderingService ile oluşturulan paket. Aşağıdaki verileri sağladığınızdan emin olun:
     • visible Gösterge panelinin görünür ve içerik göstermeye hazır olduğunu belirtir.
     • unobscuredBounds Gösterge paneli ekranındaki içeriğin güvenli bir şekilde gösterildiği alanı tanımlayan dikdörtgen. Örneğin, kadranlar ve göstergelerin kapladığı alanlar.
5. Service#dump() yöntemini geçersiz kılın ve hata ayıklama için yararlı olan durum bilgilerini bildirin (daha fazla bilgi için dumpsys bölümüne bakın).

Örnek InstrumentClusterRenderingService uygulaması

Aşağıdaki örnekte, Enstrüman Kümesi içeriğini uzaktaki fiziksel bir ekranda sunmak için bir VirtualDisplay oluşturan bir InstrumentClusterRenderingServiceuygulaması özetlenmiştir.

Alternatif olarak bu kod, HU'ya bağlı fiziksel bir ikincil ekranın displayId değerini (mevcut olduğu biliniyorsa) iletebilir.

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

CarAppFocusManager API'yi kullanma

CarAppFocusManager API, OEM'ler tarafından yazılan küme hizmetinin, belirli bir zamanda hangi navigasyon uygulamasının navigasyon odağına sahip olduğunu bilmesine olanak tanıyan getAppTypeOwner() adlı bir yöntem sağlar. OEM'ler mevcut CarAppFocusManager#addFocusListener() yöntemini kullanabilir ve ardından hangi uygulamanın odakta olduğunu öğrenmek için getAppTypeOwner() yöntemini kullanabilir. OEM'ler bu bilgilerle:

• Odağı tutarak grupta gösterilen etkinliği, navigasyon uygulaması tarafından sağlanan grup etkinliğine geçirin.
• Odaklanmış navigasyon uygulamasının bir küme etkinliği olup olmadığını algılayabilir. Odaklanan navigasyon uygulamasında grup etkinliği yoksa (veya bu tür bir etkinlik devre dışıysa) OEM'ler bu sinyali araba DIM'ine gönderebilir. Böylece, grubun navigasyon yönü tamamen atlanır.

Mevcut uygulama odağını (ör. etkin navigasyon veya sesli komut) ayarlamak ve dinlemek için CarAppFocusManager simgesini kullanın. Sistemde genellikle bu tür bir uygulamanın yalnızca bir örneği etkin olarak çalışır (veya odaklanır).

Uygulama odak değişikliklerini dinlemek için CarAppFocusManager#addFocusListener(..) yöntemini kullanın:

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
}

Odaktaki belirli bir uygulama türünün mevcut sahibinin paket adlarını almak için CarAppFocusManager#getAppTypeOwner(..) yöntemini kullanın. Mevcut sahip android:sharedUserId özelliğini kullanıyorsa bu yöntem birden fazla paket adı döndürebilir.

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
}

...

Ek: Örnek uygulamayı kullanma

AOSP, Gezinme Durumu API'sini uygulayan bir örnek uygulama sağlar.

Bu örnek uygulamayı çalıştırmak için:

1. Android Auto'yu desteklenen bir HU'da derleyip flaşlayın. Cihazınıza özel Android derleme ve yanıp sönme talimatlarını kullanın. Talimatlar için Referans panolarını kullanma başlıklı makaleyi inceleyin.
2. HU'ya fiziksel bir ikincil ekran bağlayın (destekleniyorsa) veya sanal ikincil HU'yu açın:
   1. Ayarlar uygulamasında Geliştirici Modu'nu seçin.
   2. Ayarlar > Sistem > Gelişmiş > Geliştirici seçenekleri > İkincil ekranları simüle et'e gidin.
3. HU'yu yeniden başlatma
4. KitchenSink uygulamasını başlatmak için:
   1. Çekmeceyi açın.
   2. Inst. Cluster'a gidin.
   3. META VERİLERİ BAŞLAT'ı tıklayın.

KitchenSink, NAVIGATION odağını ister. Bu, DirectRenderingClusterhizmetine gösterge panelinde bir kullanıcı arayüzü taslağı göstermesini söyler.