واجهات برمجة التطبيقات لأجهزة السيارة

بدءًا من المستوى 3 من Car App API، يمكنك استخدام واجهات برمجة التطبيقات في Car App Library للوصول إلى خصائص المركبة وأجهزة الاستشعار.

المتطلبات

لاستخدام واجهات برمجة التطبيقات مع Android Auto، ابدأ بإضافة تبعية إلى androidx.car.app:app-projected في ملف build.gradle لوحدة Android Auto. بالنسبة إلى نظام التشغيل Android Automotive، أضِف تبعية على androidx.car.app:app-automotive إلى ملف build.gradle لوحدة Android Automotive OS.

بالإضافة إلى ذلك، عليك في ملف AndroidManifest.xml الإفصاح عن الأذونات ذات الصلة المطلوبة لطلب بيانات السيارة التي تريد استخدامها. ويجب أن يمنحك المستخدم هذه الأذونات أيضًا. يمكنك استخدام الرمز البرمجي نفسه على Android Auto ونظام التشغيل Android Automotive، بدلاً من إنشاء مسارات تعتمد على النظام الأساسي. ومع ذلك، تختلف الأذونات المطلوبة.

CarInfo

يوضّح هذا الجدول الخصائص المتوفّرة في واجهات برمجة التطبيقات CarInfo والأذونات التي يجب طلبها لاستخدامها.

الطرق الخصائص الأذونات:
Android Auto		 الأذونات:
AAOS		 Car App API
fetchModel الصنع والطراز وسنة الصنع android.car.permission.CAR_INFO 3
fetchEnergyProfile أنواع وصلات المركبات الكهربائية وأنواع الوقود com.google.android.gms.permission.CAR_FUEL android.car.permission.CAR_INFO 3
fetchExteriorDimensions

تتوفّر البيانات فقط في بعض المركبات التي تعمل بنظام التشغيل Android Automotive (AAOS) الذي يتضمّن الإصدار 30 من واجهة برمجة التطبيقات أو الإصدارات الأحدث.

 الأبعاد الخارجية لا ينطبق android.car.permission.CAR_INFO 7

addTollListener

removeTollListener

 حالة بطاقة تحصيل رسوم العبور ونوعها 3

addEnergyLevelListener

removeEnergyLevelListener

 مستوى البطارية ومستوى الوقود ومستوى الوقود منخفض والمدى المتبقي com.google.android.gms.permission.CAR_FUEL android.car.permission.CAR_ENERGY

android.car.permission.CAR_ENERGY_PORTS

android.car.permission.READ_CAR_DISPLAY_UNITS 		3

addSpeedListener

removeSpeedListener

 السرعة الأولية، وسرعة العرض (المعروضة على شاشة عدّاد السيارة) com.google.android.gms.permission.CAR_SPEED android.car.permission.CAR_SPEED

android.car.permission.READ_CAR_DISPLAY_UNITS 		3

addMileageListener

removeMileageListener

 مسافة عدّاد المسافات com.google.android.gms.permission.CAR_MILEAGE البيانات غير متاحة لتطبيقات نظام التشغيل Android Automotive المثبَّتة من Google Play. 3

على سبيل المثال، للحصول على النطاق المتبقي، أنشئ مثيلاً لكائن CarInfo، ثم أنشئ OnCarDataAvailableListener وسجِّله:

Kotlin

val carInfo = carContext.getCarService(CarHardwareManager::class.java).carInfo

val listener = OnCarDataAvailableListener<EnergyLevel> { data ->
    if (data.rangeRemainingMeters.status == CarValue.STATUS_SUCCESS) {
      val rangeRemaining = data.rangeRemainingMeters.value
    } else {
      // Handle error
    }
  }

carInfo.addEnergyLevelListener(carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener)

Java

CarInfo carInfo = getCarContext().getCarService(CarHardwareManager.class).getCarInfo();

OnCarDataAvailableListener<EnergyLevel> listener = (data) -> {
  if(data.getRangeRemainingMeters().getStatus() == CarValue.STATUS_SUCCESS) {
    float rangeRemaining = data.getRangeRemainingMeters().getValue();
  } else {
    // Handle error
  }
};

carInfo.addEnergyLevelListener(getCarContext().getMainExecutor(), listener);
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener);

لا تفترض أنّ البيانات من السيارة متاحة في جميع الأوقات. في حال ظهور خطأ، تحقَّق من حالة القيمة التي طلبتها لمعرفة سبب عدم إمكانية استرداد البيانات التي طلبتها. لمزيد من المعلومات حول تعريف فئة CarInfo، يُرجى الاطّلاع على المستندات المرجعية.

CarSensors

يمنحك الصف CarSensors إمكانية الوصول إلى بيانات مقياس التسارع والجيروسكوب والبوصلة والموقع الجغرافي في المركبة. وقد يختلف مدى توفّر هذه القيم حسب الشركة المصنّعة للجهاز الأصلي. يكون تنسيق البيانات الواردة من مقياس التسارع والجيروسكوب والبوصلة هو نفسه التنسيق الذي تحصل عليه من واجهة برمجة التطبيقات SensorManager.

على سبيل المثال، للتحقّق من اتجاه المركبة:

Kotlin

val carSensors = carContext.getCarService(CarHardwareManager::class.java).carSensors

val listener = OnCarDataAvailableListener<Compass> { data ->
    if (data.orientations.status == CarValue.STATUS_SUCCESS) {
      val orientation = data.orientations.value
    } else {
      // Data not available, handle error
    }
  }

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener)

Java

CarSensors carSensors = getCarContext().getCarService(CarHardwareManager.class).getCarSensors();

OnCarDataAvailableListener<Compass> listener = (data) -> {
  if (data.getOrientations().getStatus() == CarValue.STATUS_SUCCESS) {
    List<Float> orientations = data.getOrientations().getValue();
  } else {
    // Data not available, handle error
  }
};

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, getCarContext().getMainExecutor(),
    listener);
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener);

للوصول إلى بيانات الموقع الجغرافي من السيارة، عليك أيضًا الإفصاح عن إذن android.permission.ACCESS_FINE_LOCATION وطلبه.

اختبار

لمحاكاة بيانات جهاز الاستشعار عند الاختبار على Android Auto، راجِع قسمَي أجهزة الاستشعار وإعدادات المستشعر في دليل &quot;وحدة رأسية للكمبيوتر المكتبي&quot;. لمحاكاة بيانات جهاز الاستشعار عند الاختبار على نظام التشغيل Android Automotive، يُرجى الرجوع إلى محاكاة حالة الأجهزة في دليل محاكي نظام التشغيل Android Automotive.

السابق
واجهة برمجة تطبيقات القيود
التالي
التسجيل من ميكروفون السيارة