उपकरण क्लस्टर एपीआई

कार में सेकेंडरी डिस्प्ले पर, जैसे कि इंस्ट्रूमेंट पैनल पर स्टीयरिंग व्हील के पीछे, Google मैप्स सहित नेविगेशन ऐप्स प्रदर्शित करने के लिए इंस्ट्रूमेंट क्लस्टर एपीआई (एक एंड्रॉइड एपीआई) का उपयोग करें। यह पृष्ठ वर्णन करता है कि उस द्वितीयक डिस्प्ले को नियंत्रित करने के लिए एक सेवा कैसे बनाई जाए और फिर सेवा को CarService के साथ एकीकृत किया जाए ताकि नेविगेशन ऐप्स एक उपयोगकर्ता इंटरफ़ेस प्रदर्शित कर सकें।

शब्दावली

इस पृष्ठ पर निम्नलिखित शब्दों का उपयोग किया गया है:

आवश्यक शर्तें

एकीकरण विकसित करने के लिए, इन तत्वों का होना सुनिश्चित करें:

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

एकीकरण वास्तुकला

एकीकरण घटक

इंस्ट्रूमेंट क्लस्टर एपीआई के किसी भी एकीकरण में ये तीन घटक शामिल होते हैं:

• CarService
• नेविगेशन ऐप्स
• OEM उपकरण क्लस्टर सेवा

कार सेवा

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

CarService सभी कार-विशिष्ट सेवाओं को बूटस्ट्रैप करता है और प्रबंधकों की एक श्रृंखला के माध्यम से इन सेवाओं तक पहुंच प्रदान करता है। सेवाओं के साथ इंटरैक्ट करने के लिए, कार में चल रहे ऐप्स इन प्रबंधकों तक पहुंच सकते हैं।

इंस्ट्रूमेंट क्लस्टर कार्यान्वयन के लिए, ऑटोमोटिव OEM को InstrumentClusterRendererService का एक कस्टम कार्यान्वयन बनाना होगा और ClusterRenderingService सेवा को द्वितीयक डिस्प्ले से कनेक्ट करना होगा।

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

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

इस प्रविष्टि में संदर्भित सेवा प्रारंभ की गई है और CarService से जुड़ी है। जब Google मैप्स जैसे नेविगेशन ऐप्स, CarInstrumentClusterManager का अनुरोध करते हैं, CarService एक प्रबंधक प्रदान करता है जो बाउंड InstrumentClusterRenderingService से इंस्ट्रूमेंट क्लस्टर स्थिति को अपडेट करता है। (इस मामले में, बाउंड एंड्रॉइड सेवाओं को संदर्भित करता है।)

उपकरण क्लस्टर सेवा

OEM को एक Android पैकेज (APK) बनाना होगा जिसमें ClusterRenderingService सेवा का एक उपवर्ग शामिल हो जो द्वितीयक डिस्प्ले से जुड़ा हो। ClusterRenderingService सेवा द्वितीयक डिस्प्ले से जुड़ी है। एक नमूने के लिए.

यह वर्ग दो उद्देश्यों को पूरा करता है:

• एक इंटरफ़ेस एंड्रॉइड और इंस्ट्रूमेंट क्लस्टर रेंडरिंग डिवाइस (इस पृष्ठ का उद्देश्य) प्रदान करता है।
• नेविगेशन स्थिति अपडेट प्राप्त करता है और प्रस्तुत करता है, जैसे कि बारी-बारी नेविगेशन मार्गदर्शन।

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

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

एकीकरण क्रम

निम्नलिखित आरेख एक नेविगेशन स्थिति के कार्यान्वयन को दर्शाता है जो अद्यतन प्रस्तुत करता है:

इस चित्रण में, रंग निम्नलिखित दर्शाते हैं:

• पीला। CarService और CarNavigationStatusManager एंड्रॉइड प्लेटफॉर्म द्वारा प्रदान किया गया। अधिक जानने के लिए, कार और CAR_NAVIGATION_SERVICE देखें।
• सियान. InstrumentClusterRendererService OEM द्वारा कार्यान्वित की गई है।
• बैंगनी। नेविगेशन ऐप Google और तृतीय-पक्ष डेवलपर्स द्वारा कार्यान्वित किया गया है।
• हरा। CarAppFocusManager । अधिक जानने के लिए, नीचे CarAppFocusManager API का उपयोग करना और CarAppFocusManager देखें।

नेविगेशन स्थिति सूचना प्रवाह इस क्रम का अनुसरण करता है:

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

एपीआई को एकीकृत करें

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

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

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

नमूना InstrumentClusterRenderingService कार्यान्वयन

निम्नलिखित उदाहरण एक InstrumentClusterRenderingService कार्यान्वयन की रूपरेखा तैयार करता है, जो दूरस्थ भौतिक डिस्प्ले पर इंस्ट्रूमेंट क्लस्टर सामग्री प्रस्तुत करने के लिए एक VirtualDisplay बनाता है।

वैकल्पिक रूप से, यह कोड एचयू से जुड़े भौतिक माध्यमिक डिस्प्ले के displayId पास कर सकता है, यदि कोई उपलब्ध हो।

/**
* 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 का उपयोग करें

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

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

वर्तमान ऐप फ़ोकस, जैसे सक्रिय नेविगेशन या वॉयस कमांड को सेट करने और सुनने के लिए 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
}

...

परिशिष्ट: नमूना ऐप का उपयोग करें

एओएसपी एक नमूना ऐप प्रदान करता है जो नेविगेशन स्टेट एपीआई लागू करता है।

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

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

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