इंस्ट्रुमेंट क्लस्टर एपीआई

नेविगेशन ऐप्लिकेशन दिखाने के लिए, Instrument क्लस्टर एपीआई (Android एपीआई) का इस्तेमाल करें, जिनमें Google Maps भी शामिल है. कार के सेकंडरी डिसप्ले पर, इंस्ट्रुमेंट पैनल पर मौजूद स्टीयरिंग व्हील. इस पेज में बताया गया है कि उस सेकंडरी डिसप्ले को कंट्रोल करने और सेवा को CarService ताकि नेविगेशन ऐप्लिकेशन यूज़र इंटरफ़ेस पर काम करता है.

शब्दावली

इस पेज पर इन कीवर्ड का इस्तेमाल किया गया है.

ज़रूरी शर्तें

आगे बढ़ने से पहले, पक्का करें कि इसमें ये एलिमेंट शामिल हों:

• Android डेवलपमेंट एनवायरमेंट. Android सेट अप करने के लिए डेवलपमेंट एनवायरमेंट, देखें बिल्ड से जुड़ी ज़रूरी शर्तें.
• Android सोर्स कोड डाउनलोड करें. इसका सबसे नया वर्शन डाउनलोड करें इस लिंक पर मौजूद pi-car-release ब्रांच से (या बाद के) Android सोर्स कोड को https://android.googlesource.com पर जाएं.
• हेड यूनिट (HU). चलने की क्षमता वाला Android डिवाइस Android 9 या इसके बाद के वर्शन पर. इस डिवाइस का अपना डिसप्ले होना चाहिए. साथ ही, इसमें सुविधाएं होनी चाहिए Android के नए बिल्ड के साथ डिसप्ले को फ़्लैश कर रहा है.
• इंस्ट्रुमेंट क्लस्टर इनमें से एक है:
  • HU से अटैच किया गया फ़िज़िकल सेकंडरी डिसप्ले. अगर डिवाइस हार्डवेयर और कर्नेल एक से ज़्यादा डिसप्ले के मैनेजमेंट की सुविधा देते हैं.
  • इंडिपेंडेंट यूनिट. इससे जुड़ी कोई भी कंप्यूटेशनल यूनिट नेटवर्क कनेक्शन के ज़रिए HU, वीडियो स्ट्रीम पाने और दिखाने में सक्षम Chromebook पर दिखता है.
  • एम्युलेटेड डिसप्ले. डेवलपमेंट के दौरान, आपके पास इनमें से किसी एक को इस्तेमाल करने का विकल्प होता है ये एम्युलेट किए गए एनवायरमेंट:
    • सिम्युलेटेड सेकंडरी डिसप्ले. सिम्युलेटेड मोड को चालू करने के लिए किसी भी AOSP Android डिस्ट्रिब्यूशन पर दूसरा डिसप्ले, डेवलपर के लिए सेटिंग और टूल पर जाएं सेटिंग सेटिंग में जाकर चुनें और फिर सेकंडरी सिम्युलेट करें डिसप्ले यह कॉन्फ़िगरेशन, फ़िज़िकल सेकंडरी को अटैच करने के बराबर है दिखाई देता है, इस सीमा के साथ कि यह प्रदर्शन प्राथमिक सीमा पर सुपरइंपोज़ किया गया है डिसप्ले.
    • एमुलेट किए गए इंस्ट्रुमेंट क्लस्टर. Android एम्युलेटर शामिल है AAOS के साथ, इंस्ट्रुमेंट क्लस्टर दिखाने का विकल्प है ClusterReportingService.

इंटिग्रेशन आर्किटेक्चर

एकीकरण घटक

इंस्ट्रुमेंट क्लस्टर एपीआई के किसी भी इंटिग्रेशन में ये तीन कॉम्पोनेंट होते हैं:

• CarService
• नेविगेशन ऐप्लिकेशन
• OEM इंस्ट्रुमेंट क्लस्टर सेवा

CarService

CarService, नेविगेशन ऐप्लिकेशन और कार के बीच मध्यस्थता करता है. साथ ही, यह पक्का करता है कि सिर्फ़ एक समय पर एक नेविगेशन ऐप्लिकेशन चालू हो और सिर्फ़ वही ऐप्लिकेशन चालू हों जिनमें android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL अनुमति, डेटा भेज सकती है कार तक.

CarService, कार से जुड़ी सभी सेवाओं के लिए बूटस्ट्रैप करता है और इन सेवाओं का ऐक्सेस देता है मैनेजरों की एक सीरीज़ के ज़रिए ये सेवाएं ऐक्सेस कर सकते हैं. सेवाओं का इस्तेमाल करने के लिए, कार में चल रहे ऐप्लिकेशन इन मैनेजर को ऐक्सेस कर सकते हैं.

इंस्ट्रुमेंट क्लस्टर लागू करने के लिए, वाहन संबंधित OEM को एक कस्टम इंस्ट्रुमेंट क्लस्टर रेंडररService को लागू करना और ClusterReportingService.

किसी इंस्ट्रुमेंट क्लस्टर को रेंडर करते समय, बूट प्रोसेस के दौरान CarService इसकी InstrumentClusterRendererService कुंजी को पढ़ता है क्लस्टर रेंडरिंग सेवा ताकि InstrumentClusterService को लागू किया जा सके. AOSP में, यह एंट्री नेविगेशन स्टेट एपीआई सैंपल क्लस्टर लागू करने की रेंडर सेवा की ओर इशारा करता है:

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

इस एंट्री में रेफ़र की गई सेवा को शुरू किया गया है और CarService. जब Google Maps जैसे नेविगेशन ऐप्लिकेशन, CarInstrumentClusterManager, CarService एक मैनेजर तय की गई InstrumentClusterRenderingService से इंस्ट्रुमेंट क्लस्टर की स्थिति को अपडेट करता है. (इस मामले में, बाउंड का मतलब है Android सेवाएं.)

इंस्ट्रुमेंट क्लस्टर की सेवा

OEM को ऐसा Android पैकेज (APK) बनाना चाहिए जिसमें ClusterReportingService.

इस क्लास के दो मकसद हैं:

• यह Android इंटरफ़ेस और इंस्ट्रुमेंट क्लस्टर रेंडरिंग डिवाइस देता है (इस पेज का मकसद).
• इससे नेविगेशन की स्थिति के अपडेट मिलते हैं और रेंडर होते हैं. जैसे, मोड़-दर-मोड़ नेविगेशन के लिए दिशा-निर्देश.

पहले मकसद के लिए, InstrumentClusterRendererService को ओईएम से लागू करना को कार के केबिन में स्क्रीन पर जानकारी को रेंडर करने के लिए इस्तेमाल किया जाने वाला सेकंडरी डिसप्ले शुरू करना होगा और इस नंबर पर कॉल करके CarService को यह जानकारी दें InstrumentClusterRendererService.setClusterActivityOptions() और InstrumentClusterRendererService.setClusterActivityState() तरीके.

दूसरे फ़ंक्शन के लिए, इंस्ट्रुमेंट क्लस्टर की सेवा को को लागू करना क्लस्टर रेंडरिंग सेवा नेविगेशन की स्थिति से जुड़े अपडेट वाले इवेंट पाने वाला इंटरफ़ेस. इन इवेंट को कोड में बदला जाता है: बंडल में एन्कोड किया गया eventType और इवेंट डेटा.

एकीकरण क्रम

नीचे दिए गए डायग्राम में, नेविगेशन स्टेटस लागू करने के बारे में बताया गया है जो अपडेट रेंडर करता है:

इस इलस्ट्रेशन में, रंग इन चीज़ों को दिखाते हैं:

• पीला. CarService और CarNavigationStatusManager Android प्लैटफ़ॉर्म की ओर से उपलब्ध कराया जाता है. इस बारे में ज़्यादा जानने के लिए, यह देखें कार और CAR_NAVIGATION_SERVICE.
• सायन. InstrumentClusterRendererService लागू किया गया की ओर से शेयर किया जा सकता है.
• बैंगनी. नेविगेशन ऐप्लिकेशन, जिसे Google और तीसरे पक्ष ने लागू किया है डेवलपर.
• हरा. CarAppFocusManager. इस बारे में ज़्यादा जानने के लिए, यह देखें CarAppFocusManager एपीआई का इस्तेमाल करना और नीचे CarAppFocusManager.

नेविगेशन स्टेट की जानकारी का फ़्लो इस क्रम के बाद आता है:

1. CarService, InstrumentClusterRenderingService को शुरू करता है.
2. शुरू करने के दौरान, InstrumentClusterRenderingService अपडेट हो जाता है CarService:
   1. इंस्ट्रुमेंट क्लस्टर की डिसप्ले प्रॉपर्टी, जैसे कि अनऑब्स्चर सीमाएं (अब तक साफ़ तौर पर न बताई गई सीमाओं के बारे में ज़्यादा जानकारी देखें).
   2. इंस्ट्रुमेंट क्लस्टर की डिसप्ले में गतिविधियों को लॉन्च करने के लिए ज़रूरी गतिविधि के विकल्प. इस बारे में ज़्यादा जानने के लिए, यह देखें ActivityOptions.
3. नेविगेशन ऐप्लिकेशन (जैसे कि Android Automotive के लिए Google Maps या कोई मैप ऐप्लिकेशन) ज़रूरी अनुमतियों के साथ):
   1. कार-लिब से कार क्लास का इस्तेमाल करके CarAppFocusManager हासिल करता है.
   2. मोड़-दर-मोड़ दिशा-निर्देश शुरू होने से पहले, इस पर कॉल करें: पास होने के लिए CarAppFocusManager.requestFocus() CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION का appType पैरामीटर.
4. CarAppFocusManager, CarService को इस अनुरोध की जानकारी देता है. अगर दिया गया हो, तो CarService नेविगेशन ऐप्लिकेशन पैकेज की जांच करता है और गतिविधि को android.car.cluster.NAVIGATION श्रेणी से चिह्नित किया गया.
5. अगर पाया जाता है, तो नेविगेशन ऐप्लिकेशन, Google की ओर से रिपोर्ट किए गए ActivityOptions का इस्तेमाल करता है गतिविधि को लॉन्च करने के लिए, InstrumentClusterRenderingService और इसमें इंस्ट्रुमेंट क्लस्टर की मदद से, इंटेंट में अतिरिक्त के तौर पर जानकारी दिखाई जाती है.

एपीआई को इंटिग्रेट करें

InstrumentClusterRenderingService लागू करने के लिए ज़रूरी है कि:

• इसमें निम्न मान जोड़कर सिंगलटन सेवा के रूप में निर्दिष्ट करें AndroidManifest.xml. यह सुनिश्चित करने के लिए आवश्यक है कि इंस्ट्रुमेंट क्लस्टर की सेवा काम करती है. यह सुविधा, शुरू करने और उपयोगकर्ता के स्विच करने के दौरान भी काम करती है:
  android:singleUser="true"
• BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE के सिस्टम की अनुमति को होल्ड करें. यह यह गारंटी देती है कि सिर्फ़ इंस्ट्रुमेंट क्लस्टर रेंडरिंग सेवा को ही शामिल किया गया है हमेशा CarService से बाउंड होती है:

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

इंस्ट्रुमेंट क्लस्टर रेंडरिंग सेवा लागू करें

सेवा बनाने के लिए:

1. ऐसी क्लास लिखें जो इससे बड़ी हो क्लस्टर रेंडरिंग सेवा और फिर अपनी AndroidManifest.xml फ़ाइल में संबंधित एंट्री जोड़ें. यह क्लास इंस्ट्रुमेंट क्लस्टर की स्क्रीन को कंट्रोल करता है और नेविगेशन की स्थिति को रेंडर (ज़रूरी नहीं) कर सकता है एपीआई डेटा.
2. onCreate() के दौरान, इस सेवा का इस्तेमाल रेंडरिंग हार्डवेयर. आपके पास रिलीज़ के टाइप चुनने के लिए, ये विकल्प उपलब्ध होते हैं:
   • इंस्ट्रुमेंट क्लस्टर के लिए इस्तेमाल किया जाने वाला सेकंडरी डिसप्ले तय करें.
   • ऐसा वर्चुअल डिसप्ले बनाएं जिससे इंस्ट्रुमेंट क्लस्टर ऐप्लिकेशन, किसी बाहरी इकाई में इमेज रेंडर की गई हो (वीडियो स्ट्रीमिंग फ़ॉर्मैट का इस्तेमाल करके, जैसे कि H.264).
3. जब ऊपर बताया गया डिसप्ले तैयार हो, तो इस सेवा को कॉल करना चाहिए तय करने के लिए InstrumentClusterRenderingService#setClusterActivityLaunchOptions() वही ActivityOptions जिसका इस्तेमाल इंस्ट्रुमेंट क्लस्टर. इन पैरामीटर का इस्तेमाल करें:
   • category. अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है क्लस्टर रेंडरिंगसेवा.
   • ActivityOptions. ActivityOptions इंस्टेंस, जो का इस्तेमाल इंस्ट्रुमेंट क्लस्टर में किसी गतिविधि को लॉन्च करने के लिए किया जाता है. उदाहरण के लिए, नमूने के तौर पर एओएसपी पर इंस्ट्रुमेंट क्लस्टर की सुविधा लागू करना:

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

4. जब इंस्ट्रुमेंट क्लस्टर, गतिविधियां दिखाने के लिए तैयार होता है, तो इस सेवा को शुरू करना होगा InstrumentClusterRenderingService#setClusterActivityState(). इनका इस्तेमाल करें पैरामीटर:
   • category अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है क्लस्टर रेंडरिंगसेवा.
   • state बंडल इसके साथ जनरेट हुआ क्लस्टर रेंडरिंगसेवा. यह डेटा देना न भूलें:
     • visible तय करता है कि इंस्ट्रुमेंट क्लस्टर किस तरह दिखेगा और इसके लिए तैयार है कॉन्टेंट नहीं है.
     • unobscuredBounds एक रेक्टैंगल, जो इंस्ट्रुमेंट क्लस्टर वाला डिसप्ले, जिसमें कॉन्टेंट दिखाना सुरक्षित होता है. उदाहरण के लिए, क्षेत्र डायल और गेज से कवर किया जाता है.
5. Service#dump() तरीके को बदलें और रिपोर्ट की स्थिति की जानकारी, इन कामों के लिए काम की है डीबग करना (dumpsys देखें देखें).

इंस्ट्रुमेंट क्लस्टर रेंडरिंग सेवा का सैंपल

यहां दिए गए उदाहरण में, InstrumentClusterRenderingService के बारे में बताया गया है इसे लागू करने पर, इंस्ट्रुमेंट प्रज़ेंट करने के लिए VirtualDisplay बन जाता है रिमोट फ़िज़िकल डिसप्ले पर कॉन्टेंट को क्लस्टर करें.

इसके अलावा, यह कोड फ़िज़िकल सेकंडरी के displayId को पास कर सकता है HU से कनेक्ट किया गया डिसप्ले नहीं होगा, अगर कोई उपलब्ध हो.

/**
* 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 एपीआई का इस्तेमाल करना

CarAppFocusManager API, getAppTypeOwner() नाम का एक तरीका उपलब्ध कराता है. इससे, यह जानने के लिए OEM की लिखी गई क्लस्टर सेवा किस नेविगेशन ऐप्लिकेशन में नेविगेशन फ़ोकस की सुविधा है समय. OEM मौजूदा CarAppFocusManager#addFocusListener() तरीके का इस्तेमाल कर सकते हैं और इसके बाद, getAppTypeOwner() का इस्तेमाल करके जानें कि किस ऐप्लिकेशन में फ़ोकस है. इस जानकारी के साथ, OEM ये काम कर सकते हैं:

• क्लस्टर में दिखाई गई गतिविधि को, नेविगेशन ऐप्लिकेशन से मिले क्लस्टर की गतिविधि पर स्विच करें फ़ोकस बनाए रखना.
• यह पता लगा सकता है कि फ़ोकस किए गए नेविगेशन ऐप्लिकेशन में कोई क्लस्टर गतिविधि है या नहीं. अगर फ़ोकस करने वाले नेविगेशन ऐप्लिकेशन में कोई क्लस्टर गतिविधि नहीं है (या अगर ऐसी गतिविधि बंद है), तो OEM ये काम कर सकते हैं यह सिग्नल कार DIM को भेजें, ताकि क्लस्टर के नेविगेशन पहलू को पूरी तरह से छोड़ दिया जाए.

मौजूदा ऐप्लिकेशन फ़ोकस को सेट करने और सुनने के लिए CarAppFocusManager का इस्तेमाल करें. जैसे या बोलकर निर्देश देने की सुविधा का इस्तेमाल करें. आम तौर पर, इस तरह के ऐप्लिकेशन का सिर्फ़ एक इंस्टेंस सक्रिय होता है आप भी सही दिशा में काम कर रहे हैं (या फ़ोकस कर रहे हैं).

ऐप्लिकेशन का फ़ोकस सुनने के लिए, CarAppFocusManager#addFocusListener(..) तरीके का इस्तेमाल करें बदलाव:

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
}

पैकेज को वापस पाने के लिए, CarAppFocusManager#getAppTypeOwner(..) तरीके का इस्तेमाल करें दिए गए ऐप्लिकेशन प्रकार के मौजूदा मालिक के नाम जो फ़ोकस में हैं. इस तरीके से नतीजे मिल सकते हैं अगर मौजूदा मालिक 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
}

...

अपेंडिक्स: ऐप्लिकेशन के सैंपल का इस्तेमाल करना

AOSP एक सैंपल ऐप्लिकेशन उपलब्ध कराता है, जो नेविगेशन स्टेट एपीआई को लागू करता है.

ऐप्लिकेशन के इस नमूने को चलाने के लिए:

1. इस सुविधा के साथ काम करने वाले HU पर Android Auto बनाएं और फ़्लैश करें. इसका इस्तेमाल करें आपके डिवाइस के लिए खास Android बिल्डिंग और फ़्लैश करने के निर्देश. निर्देशों के लिए, इसे देखें रेफ़रंस बोर्ड का इस्तेमाल करना.
2. फ़िज़िकल सेकंडरी डिसप्ले को HU से कनेक्ट करें (अगर यह सुविधा काम करती है) या वर्चुअल डिसप्ले को चालू करें सेकंडरी एचयू:
   1. Settings ऐप्लिकेशन में डेवलपर मोड चुनें.
   2. Settings > पर जाएं सिस्टम > बेहतर > डेवलपर के लिए सेटिंग और टूल > सेकंडरी डिसप्ले सिम्युलेट करें.
3. HU को फिर से चालू करें
4. KitchenSink ऐप्लिकेशन लॉन्च करने के लिए:
   1. पैनल खोलें.
   2. Inst. पर जाएं क्लस्टर.
   3. मेटाडेटा शुरू करें पर क्लिक करें.

KitchenSink, नेविगेशन पर फ़ोकस करने का अनुरोध करता है. इसमें DirectRenderingCluster को निर्देश दिया जाता है इंस्ट्रुमेंट क्लस्टर पर, मॉक-अप यूज़र इंटरफ़ेस दिखाने की सेवा का इस्तेमाल करता है.