Properti Kendaraan

Antarmuka Kendaraan Hardware Abstraksi Layer (VHAL) menentukan OEM properti yang dapat menerapkan dan berisi metadata properti (misalnya, apakah properti adalah int dan mode perubahan mana yang diizinkan). Antarmuka VHAL didasarkan pada cara mengakses (membaca, menulis, berlangganan) properti, yang merupakan abstraksi untuk fungsi tertentu.

Antarmuka HAL

VHAL menggunakan antarmuka berikut:

  • getAllPropConfigs() menghasilkan (vec<VehiclePropConfig>propConfigs)
    Mencantumkan konfigurasi semua properti yang didukung oleh VHAL. CarService hanya menggunakan properti yang didukung.
  • getPropConfigs(vec<int32_t> props) menghasilkan (StatusCode status,vec<VehiclePropConfig> propConfigs);
    Menampilkan konfigurasi properti yang dipilih.
  • set(VehiclePropValue propValue) menghasilkan (StatusCodestatus);
    Tulis nilai ke properti. Hasil penulisan ditentukan per properti.
  • subscribe(IVehicleCallback callback, vec<SubscribeOptions> options) menghasilkan (StatusCode status);
    Mulai memantau perubahan nilai properti. Untuk properti berzona, unsubscribe(IVehicleCallback callback, int32_t propId) menghasilkan (StatusCode status);

VHAL menggunakan antarmuka callback berikut:

  • oneway onPropertyEvent(vec<VehiclePropValue>propValues);
    Memberi tahu perubahan nilai properti kendaraan. Sebaiknya hanya dilakukan untuk properti yang menjadi langganan.
  • oneway onPropertySetError(StatusCode errorCode,int32_t propId,int32_tareaId);
    Menampilkan error tingkat VHAL global atau error per properti. Error global menyebabkan HAL dimulai ulang, yang dapat menyebabkan komponen lain dimulai ulang (termasuk aplikasi).

Properti kendaraan

Properti dapat berupa hanya baca, hanya tulis (digunakan untuk meneruskan informasi ke level VHAL), atau baca dan tulis (dukungan sebagian besar properti bersifat opsional). Setiap properti diidentifikasi secara unik oleh kunci int32 dan memiliki jenis yang telah ditentukan (value_type):

  • BYTES
  • BOOLEAN
  • EPOCH_TIME
  • FLOAT
  • FLOAT[]
  • INT32
  • INT32[]
  • INT64
  • INT64[]
  • STRING
  • MIXED

Properti dengan zona dapat memiliki lebih dari satu nilai, berdasarkan jumlah zona yang didukung oleh properti.

Jenis area

VHAL menentukan beberapa jenis area:

Jenis Area Deskripsi
GLOBAL Properti ini adalah singleton dan tidak memiliki beberapa area.
WINDOW Area berdasarkan jendela, menggunakan enum VehicleAreaWindow.
MIRROR Area berdasarkan mirror, menggunakan enum VehicleAreaMirror.
SEAT Area berdasarkan kursi, menggunakan enum VehicleAreaSeat.
DOOR Area berdasarkan pintu, menggunakan enum VehicleAreaDoor.
WHEEL Area berdasarkan roda, menggunakan enum VehicleAreaWheel.

Setiap properti yang dizonasi harus menggunakan jenis area yang telah ditentukan sebelumnya. Setiap jenis area memiliki kumpulan tanda bit yang ditentukan dalam enum untuk jenis area. Misalnya, area SEAT menentukan enum VehicleAreaSeat:

  • ROW_1_LEFT = 0x0001
  • ROW_1_CENTER = 0x0002
  • ROW_1_RIGHT = 0x0004
  • ROW_2_LEFT = 0x0010
  • ROW_2_CENTER = 0x0020
  • ROW_2_RIGHT = 0x0040
  • ROW_3_LEFT = 0x0100
  • ...

ID Area

Properti dengan zona ditangani melalui ID Area. Setiap properti berzona dapat mendukung satu atau beberapa ID Area. ID Area terdiri dari satu atau beberapa tanda dari enumnya masing-masing. Misalnya, properti yang menggunakan VehicleAreaSeat mungkin menggunakan ID Area berikut:

Item Deskripsi
ROW_1_LEFT | ROW_1_RIGHT ID Area berlaku untuk kedua kursi depan.
ROW_2_LEFT Hanya berlaku untuk kursi kiri belakang.
ROW_2_RIGHT Hanya berlaku untuk kursi belakang kanan.

Status properti

Setiap nilai properti dilengkapi dengan nilai VehiclePropertyStatus. Ini menunjukkan status properti saat ini:

Item Deskripsi
AVAILABLE Properti tersedia dan nilainya valid.
UNAVAILABLE Nilai properti saat ini tidak tersedia. Digunakan untuk fitur yang dinonaktifkan sementara untuk properti yang didukung.
ERROR Terjadi error dengan properti ini.

Mengonfigurasi properti

Gunakan VehiclePropConfig untuk memberikan informasi konfigurasi untuk setiap properti. Informasi mencakup:

Variabel Deskripsi
access r, w, rw
changeMode Menampilkan cara properti dipantau, berdasarkan perubahan versus berkelanjutan.
areaConfigs Nilai areaId, min, dan max.
configArray Parameter konfigurasi tambahan.
configString Informasi tambahan yang diteruskan sebagai string.
minSampleRate maxSampleRate
prop ID Properti, int

Menangani properti zona

Properti zona setara dengan kumpulan beberapa properti tempat setiap sub-properti dapat diakses dengan nilai ID Area yang ditentukan.

  • Panggilan get untuk properti berzona selalu menyertakan ID Area dalam permintaan. Oleh karena itu, hanya nilai saat ini untuk ID Area yang diminta yang ditampilkan. Jika properti bersifat global, ID Area adalah 0.
  • Panggilan set untuk properti yang dikategorikan selalu menyertakan ID Area dalam permintaan. Oleh karena itu, hanya ID Area yang diminta yang diubah.
  • Panggilan subscribe menghasilkan peristiwa untuk semua ID Area untuk properti.

Mendapatkan panggilan

Selama inisialisasi, nilai untuk properti mungkin belum tersedia karena pesan jaringan kendaraan yang cocok belum diterima. Dalam kasus tersebut, panggilan get akan menampilkan -EAGAIN. Beberapa properti (seperti HVAC) memiliki properti daya aktif/nonaktif terpisah. Memanggil get untuk properti tersebut (saat dinonaktifkan) akan menampilkan status UNAVAILABLE, bukan menampilkan error. Misalnya, dapatkan Suhu HVAC

Contoh HVAC get VHAL

Gambar 1. Mendapatkan suhu HVAC (CS = CarService, VHAL = HAL Kendaraan)

Menetapkan panggilan

Dalam operasi standar, panggilan set akan menghasilkan permintaan perubahan di jaringan kendaraan. Panggilan set idealnya adalah operasi asinkron yang ditampilkan sesegera mungkin, tetapi juga dapat bersifat sinkron. Beberapa panggilan set mungkin memerlukan data awal agar siap, tetapi selama inisialisasi, data tersebut mungkin belum tersedia. Dalam kasus tersebut, panggilan set akan menampilkan StatusCode#TRY_AGAIN. Beberapa properti dengan daya yang diaktifkan dan dinonaktifkan secara terpisah akan menampilkan StatusCode#NOT_AVAILABLE atau StatusCode#NOT_AVAILABLE_DISABLED saat properti dimatikan dan set tidak dapat dilakukan. Hingga set diterapkan, get tidak selalu menampilkan nilai yang sama dengan yang ditetapkan. Contohnya, set HVAC Temperature.

Contoh HVAC set VHAL

Gambar 2. Menetapkan suhu HVAC (CS = CarService, VHAL = HAL Kendaraan)

Menangani properti kustom

Untuk mendukung kebutuhan khusus partner, VHAL mengizinkan properti kustom yang dibatasi untuk aplikasi sistem. Gunakan panduan berikut saat menggunakan properti kustom:

  • ID properti harus dibuat menggunakan kolom berikut:
    • VehiclePropertyGroup:VENDOR
      Grup VENDOR hanya digunakan untuk properti kustom.
    • VehicleArea
      Pilih Jenis Area yang sesuai.
    • VehiclePropertyType
      Pilih jenis data yang tepat. Jenis BYTES memungkinkan penerusan data mentah yang memadai dalam sebagian besar kasus. Mengirim big data secara rutin melalui properti kustom dapat memperlambat seluruh akses jaringan kendaraan — berhati-hatilah saat menambahkan payload besar.
    • Property ID
      Pilih ID empat nibble untuk properti kustom.
  • Untuk mencegah fragmentasi ekosistem, properti kustom tidak boleh digunakan untuk mereplikasi properti kendaraan yang sudah ada di (VehiclePropertyIds SDK).
  • Isi VehiclePropConfig.configString dengan deskripsi singkat properti kustom. Hal ini memungkinkan alat pemeriksaan keandalan menandai replikasi properti kendaraan yang ada secara tidak sengaja. Misalnya, "kondisi lampu bahaya".
  • Akses melalui CarPropertyManager (untuk komponen Java) atau melalui Vehicle Network Service API (untuk native). Jangan ubah API mobil lain karena tindakan tersebut dapat menyebabkan masalah kompatibilitas di masa mendatang.
  • Setelah menerapkan properti vendor, pilihhanya daftar izin di enum VehicleVendorPermission untuk properti vendor. Memetakan izin vendor ke properti sistem akan merusak CTS dan VTS.

Menangani properti HVAC

Anda dapat menggunakan VHAL untuk mengontrol HVAC dengan menetapkan properti terkait HVAC. Sebagian besar properti HVAC adalah properti zona, meskipun beberapa di antaranya merupakan properti non-zona (global). Contoh properti yang ditentukan meliputi:

Properti Tujuan
VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET Menyetel suhu per zona.
VEHICLE_PROPERTY_HVAC_RECIRC_ON Mengontrol sirkulasi ulang per zona.

Untuk melihat daftar lengkap properti HVAC, telusuri VEHICLE_PROPERTY_HVAC_* di types.hal. Jika properti HVAC menggunakan VehicleAreaSeat, aturan tambahan untuk memetakan properti HVAC berzona ke ID Area akan berlaku. Setiap kursi yang tersedia di mobil harus menjadi bagian dari ID Area dalam array ID Area.

Contoh Satu. Mobil memiliki dua kursi depan (ROW_1_LEFT, ROW_1_RIGHT) dan tiga kursi belakang (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). Mobil memiliki dua unit kontrol suhu: sisi pengemudi dan sisi penumpang.

  • Kumpulan pemetaan ID Area yang valid untuk HVAC_TEMPERATURE SET adalah:
    • ROW_1_LEFT | ROW_2_LEFT
    • ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT
  • Pemetaan alternatif untuk konfigurasi hardware yang sama adalah:
    • ROW_1_LEFT | ROW_2_LEFT | ROW_2_CENTER
    • ROW_1_RIGHT | ROW_2_RIGHT

Contoh Kedua. Mobil memiliki tiga baris kursi dengan dua kursi di baris depan (ROW_1_LEFT, ROW_1_RIGHT), tiga kursi di baris kedua (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT), dan tiga kursi di baris ketiga (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). Mobil memiliki tiga unit kontrol suhu: sisi pengemudi, sisi penumpang, dan belakang. Cara yang wajar untuk memetakan HVAC_TEMPERATURE_SET ke ID Area adalah sebagai array tiga elemen:

  • ROW_1_LEFT
  • ROW_1_RIGHT
  • ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT

Menangani properti sensor

Properti sensor VHAL mewakili data sensor atau informasi kebijakan sebenarnya seperti status mengemudi. Beberapa informasi sensor (seperti status mengemudi dan mode siang/malam) dapat diakses oleh aplikasi apa pun tanpa batasan karena data bersifat wajib untuk membuat aplikasi kendaraan yang aman. Informasi sensor lainnya (seperti kecepatan kendaraan) lebih sensitif dan memerlukan izin tertentu yang dapat dikelola pengguna.

Lihat properti sensor yang didukung (di types.hal).

Layanan Peta Kendaraan (VMS)

Vehicle Map Service (VMS) menyediakan mekanisme untuk bertukar data peta antara klien melalui antarmuka pub/sub untuk mendukung fitur kendaraan umum, seperti Advanced Driver Assistance Systems (ADAS). Klien dapat menyertakan sistem kendaraan yang berinteraksi melalui properti VMS di VHAL atau aplikasi Android dengan hak istimewa. Data yang dibagikan di VMS dimaksudkan untuk dibatasi pada data peta untuk digunakan oleh sistem kendaraan dan aplikasi pendukung.

VMS hanya ditujukan untuk digunakan dalam implementasi Android Automotive; AOSP tidak berisi klien default yang memublikasikan atau berlangganan VMS. Untuk properti VMS di VHAL, jenis pesan dan struktur data dijelaskan di VHAL 2.0 dalam enum VmsMessageType, yang mencantumkan jenis pesan VMS yang didukung. Enum ini digunakan sebagai bilangan bulat pertama dalam array bilangan bulat properti kendaraan dan menentukan cara dekode pesan lainnya.