Thuộc tính xe

Giao diện Lớp trừu tượng phần cứng của xe (VHAL) xác định các thuộc tính mà OEM có thể triển khai và chứa siêu dữ liệu thuộc tính (ví dụ: liệu thuộc tính có phải là một int hay không và chế độ thay đổi nào được cho phép). Giao diện VHAL dựa trên việc truy cập (đọc, ghi, đăng ký) một thuộc tính, đây là một thuộc tính trừu tượng cho một hàm cụ thể.

Giao diện HAL

VHAL sử dụng các giao diện sau:

  • getAllPropConfigs() tạo (vec<VehiclePropConfig>propConfigs)
    Liệt kê cấu hình của tất cả các thuộc tính mà VHAL hỗ trợ. CarService chỉ sử dụng các thuộc tính được hỗ trợ.
  • getPropConfigs(vec<int32_t> props) tạo (StatusCode status,vec<VehiclePropConfig> propConfigs);
    Trả về cấu hình của các thuộc tính đã chọn.
  • set(VehiclePropValue propValue) tạo (StatusCodestatus);
    Ghi một giá trị vào thuộc tính. Kết quả ghi được xác định theo từng thuộc tính.
  • subscribe(IVehicleCallback callback, vec<SubscribeOptions> options) tạo (StatusCode status);
    Bắt đầu theo dõi sự thay đổi về giá trị thuộc tính. Đối với tài sản theo khu vực, unsubscribe(IVehicleCallback callback, int32_t propId) sẽ tạo (StatusCode status);

VHAL sử dụng các giao diện gọi lại sau:

  • oneway onPropertyEvent(vec<VehiclePropValue>propValues);
    Thông báo cho sự thay đổi về giá trị của tài sản xe. Chỉ nên thực hiện đối với các tài sản đã đăng ký.
  • oneway onPropertySetError(StatusCode errorCode,int32_t propId,int32_tareaId);
    Trả về lỗi cấp VHAL toàn cầu hoặc lỗi trên mỗi thuộc tính. Lỗi toàn cục khiến HAL khởi động lại, điều này có thể dẫn đến việc khởi động lại các thành phần khác (bao gồm cả ứng dụng).

Thuộc tính xe

Các thuộc tính có thể ở dạng chỉ đọc, chỉ ghi (dùng để truyền thông tin đến cấp VHAL) hoặc đọc và ghi (không bắt buộc phải hỗ trợ hầu hết các thuộc tính). Mỗi thuộc tính được xác định duy nhất bằng một khoá int32 và có một loại được xác định trước (value_type):

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

Một thuộc tính theo vùng có thể có nhiều giá trị, dựa trên số lượng vùng mà thuộc tính đó hỗ trợ.

Loại khu vực

VHAL xác định nhiều loại khu vực:

Loại khu vực Mô tả
GLOBAL Cơ sở lưu trú này là một singleton và không có nhiều khu vực.
WINDOW Khu vực dựa trên cửa sổ, sử dụng enum VehicleAreaWindow.
MIRROR Khu vực dựa trên gương, sử dụng enum VehicleAreaMirror.
SEAT Diện tích dựa trên số ghế, sử dụng enum VehicleAreaSeat.
DOOR Khu vực dựa trên cửa, dùng enum VehicleAreaDoor.
WHEEL Diện tích dựa trên bánh xe, sử dụng enum VehicleAreaWheel.

Mỗi cơ sở lưu trú được phân vùng phải sử dụng một loại khu vực được xác định trước. Mỗi loại vùng có một tập hợp cờ bit được xác định trong một enum cho loại vùng đó. Ví dụ: khu vực SEAT xác định 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
  • ...

Mã khu vực

Các tài sản được phân vùng được xác định thông qua Mã khu vực. Mỗi cơ sở lưu trú được phân vùng có thể hỗ trợ một hoặc nhiều Mã khu vực. Mã nhận dạng khu vực bao gồm một hoặc nhiều cờ từ enum tương ứng. Ví dụ: một tài sản sử dụng VehicleAreaSeat có thể sử dụng các Mã khu vực sau:

Mục Mô tả
ROW_1_LEFT | ROW_1_RIGHT Mã khu vực áp dụng cho cả hai ghế trước.
ROW_2_LEFT Chỉ áp dụng cho ghế sau bên trái.
ROW_2_RIGHT Chỉ áp dụng cho ghế sau bên phải.

Trạng thái của cơ sở lưu trú

Mỗi giá trị thuộc tính đều đi kèm với một giá trị VehiclePropertyStatus. Trạng thái này cho biết trạng thái hiện tại của cơ sở lưu trú:

Mục Mô tả
AVAILABLE Thuộc tính có sẵn và giá trị hợp lệ.
UNAVAILABLE Hiện không có giá trị thuộc tính. Dùng cho các tính năng bị tắt tạm thời cho một tài sản được hỗ trợ.
ERROR Thuộc tính này có vấn đề.

Định cấu hình tài sản

Sử dụng VehiclePropConfig để cung cấp thông tin cấu hình cho từng tài sản. Thông tin bao gồm:

Biến Mô tả
access r, w, rw
changeMode Biểu thị cách một thuộc tính được theo dõi, theo thay đổi so với liên tục.
areaConfigs Các giá trị areaId, min và max.
configArray Các tham số cấu hình bổ sung.
configString Thông tin bổ sung được truyền dưới dạng chuỗi.
minSampleRate maxSampleRate
prop Mã cơ sở lưu trú, int

Xử lý thuộc tính vùng

Tài sản được phân vùng tương đương với một tập hợp nhiều tài sản, trong đó bạn có thể truy cập vào từng tài sản phụ bằng giá trị Mã khu vực được chỉ định.

  • Lệnh gọi get cho tài sản được phân vùng luôn bao gồm Mã khu vực trong yêu cầu. Do đó, hệ thống chỉ trả về giá trị hiện tại của Mã khu vực được yêu cầu. Nếu thuộc tính là thuộc tính chung, thì Mã khu vực sẽ là 0.
  • Lệnh gọi set cho tài sản được phân vùng luôn bao gồm Mã khu vực trong yêu cầu. Do đó, chỉ Mã khu vực được yêu cầu mới thay đổi.
  • Lệnh gọi subscribe sẽ tạo sự kiện cho tất cả Mã khu vực của tài sản.

Nhận cuộc gọi

Trong quá trình khởi chạy, giá trị cho thuộc tính này có thể chưa có vì chưa nhận được thông báo mạng xe phù hợp. Trong những trường hợp như vậy, lệnh gọi get sẽ trả về -EAGAIN. Một số thuộc tính (chẳng hạn như HVAC) có thuộc tính nguồn điện bật/tắt riêng biệt. Việc gọi get cho một thuộc tính như vậy (khi tắt nguồn) sẽ trả về trạng thái UNAVAILABLE thay vì trả về lỗi. Ví dụ: lấy Nhiệt độ HVAC

Ví dụ về VHAL get HVAC

Hình 1 Lấy nhiệt độ HVAC (CS = CarService, VHAL = HAL của xe)

Đặt cuộc gọi

Trong một thao tác thông thường, lệnh gọi set sẽ dẫn đến việc tạo yêu cầu thay đổi trên mạng xe. Lý tưởng nhất là lệnh gọi set là một hoạt động không đồng bộ sẽ trả về sớm nhất có thể, nhưng cũng có thể đồng bộ. Một số lệnh gọi set có thể yêu cầu dữ liệu ban đầu phải sẵn sàng nhưng trong quá trình khởi chạy, dữ liệu đó có thể chưa có. Trong những trường hợp như vậy, lệnh gọi set sẽ trả về StatusCode#TRY_AGAIN. Một số thuộc tính có chế độ bật và tắt nguồn riêng biệt sẽ trả về StatusCode#NOT_AVAILABLE hoặc StatusCode#NOT_AVAILABLE_DISABLED khi thuộc tính đó bị tắt nguồn và không thể thực hiện set. Cho đến khi set có hiệu lực, get không nhất thiết phải trả về cùng một giá trị với giá trị đã đặt. Ví dụ: set HVAC Temperature

Ví dụ về việc đặt HVAC bằng VHAL

Hình 2. Đặt nhiệt độ HVAC (CS = CarService, VHAL = HAL của xe)

Xử lý thuộc tính tuỳ chỉnh

Để hỗ trợ các nhu cầu cụ thể của đối tác, VHAL cho phép các thuộc tính tuỳ chỉnh chỉ dành cho ứng dụng hệ thống. Hãy làm theo các nguyên tắc sau khi làm việc với các thuộc tính tuỳ chỉnh:

  • Bạn nên tạo mã tài sản bằng các trường sau:
    • VehiclePropertyGroup:VENDOR
      Nhóm VENDOR chỉ được dùng cho các thuộc tính tuỳ chỉnh.
    • VehicleArea
      Chọn một Loại khu vực phù hợp.
    • VehiclePropertyType
      Chọn loại dữ liệu phù hợp. Loại BYTES cho phép truyền dữ liệu thô là đủ trong hầu hết các trường hợp. Việc thường xuyên gửi dữ liệu lớn thông qua các thuộc tính tuỳ chỉnh có thể làm chậm toàn bộ quyền truy cập mạng của xe — hãy cẩn thận khi thêm tải trọng lớn.
    • Property ID
      Chọn mã nhận dạng gồm 4 nibble cho thuộc tính tuỳ chỉnh.
  • Để ngăn tình trạng phân mảnh hệ sinh thái, bạn không được sử dụng thuộc tính tuỳ chỉnh để sao chép các thuộc tính xe đã tồn tại trong SDK (VehiclePropertyIds).
  • Điền nội dung mô tả ngắn về thuộc tính tuỳ chỉnh vào VehiclePropConfig.configString. Điều này cho phép các công cụ kiểm tra tính hợp lệ gắn cờ trường hợp vô tình sao chép các thuộc tính xe hiện có. Ví dụ: "trạng thái đèn báo nguy hiểm".
  • Truy cập thông qua CarPropertyManager (đối với các thành phần Java) hoặc thông qua API Dịch vụ mạng xe (đối với các thành phần gốc). Đừng sửa đổi các API ô tô khác vì việc này có thể dẫn đến các vấn đề về khả năng tương thích trong tương lai.
  • Sau khi triển khai thuộc tính nhà cung cấp, hãy chọnchỉ danh sách quyền trong enum VehicleVendorPermission cho thuộc tính nhà cung cấp. Việc liên kết quyền của nhà cung cấp với các thuộc tính hệ thống sẽ làm hỏng CTS và VTS.

Xử lý các thuộc tính HVAC

Bạn có thể sử dụng VHAL để kiểm soát hệ thống điều hòa không khí bằng cách đặt các thuộc tính liên quan đến hệ thống điều hòa không khí. Hầu hết các tài sản HVAC đều là tài sản được phân vùng, mặc dù một số tài sản là tài sản không được phân vùng (chung). Sau đây là một số thuộc tính được xác định mẫu:

Thuộc tính Mục đích
VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET Đặt nhiệt độ cho từng vùng.
VEHICLE_PROPERTY_HVAC_RECIRC_ON Kiểm soát việc tuần hoàn lại theo từng vùng.

Để xem danh sách đầy đủ các thuộc tính HVAC, hãy tìm VEHICLE_PROPERTY_HVAC_* trong types.hal. Khi thuộc tính HVAC sử dụng VehicleAreaSeat, các quy tắc bổ sung để liên kết thuộc tính HVAC theo khu vực với Mã khu vực sẽ được áp dụng. Mỗi chỗ ngồi còn trống trong xe phải là một phần của Mã khu vực trong mảng Mã khu vực.

Ví dụ 1. Một chiếc ô tô có hai ghế trước (ROW_1_LEFT, ROW_1_RIGHT) và ba ghế sau (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). Xe có hai bộ điều khiển nhiệt độ: phía người lái và phía người ngồi.

  • Một tập hợp ánh xạ hợp lệ của Mã khu vực cho HVAC_TEMPERATURE SET là:
    • ROW_1_LEFT | ROW_2_LEFT
    • ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT
  • Một ánh xạ thay thế cho cùng một cấu hình phần cứng là:
    • ROW_1_LEFT | ROW_2_LEFT | ROW_2_CENTER
    • ROW_1_RIGHT | ROW_2_RIGHT

Ví dụ 2. Một chiếc ô tô có 3 hàng ghế với 2 chỗ ngồi ở hàng trước (ROW_1_LEFT, ROW_1_RIGHT), 3 chỗ ở hàng thứ hai (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT) và 3 chỗ ở hàng thứ ba (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). Chiếc xe này có 3 bộ điều khiển nhiệt độ: phía người lái, phía ghế phụ và phía sau. Một cách hợp lý để ánh xạ HVAC_TEMPERATURE_SET đến mã nhận dạng khu vực là dưới dạng một mảng gồm 3 phần tử:

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

Xử lý các thuộc tính cảm biến

Các thuộc tính cảm biến VHAL đại diện cho dữ liệu cảm biến thực hoặc thông tin chính sách, chẳng hạn như trạng thái lái xe. Mọi ứng dụng đều có thể truy cập một số thông tin cảm biến (chẳng hạn như trạng thái lái xe và chế độ ngày/đêm) mà không bị hạn chế vì dữ liệu này là bắt buộc để xây dựng một ứng dụng an toàn cho xe. Các thông tin khác của cảm biến (chẳng hạn như tốc độ của xe) nhạy cảm hơn và đòi hỏi các quyền cụ thể mà người dùng có thể quản lý.

Xem các thuộc tính cảm biến được hỗ trợ (trong types.hal).

Dịch vụ bản đồ dành cho ô tô

Dịch vụ bản đồ cho xe (VMS) cung cấp một cơ chế trao đổi dữ liệu bản đồ giữa các ứng dụng thông qua giao diện xuất bản/phụ để hỗ trợ các tính năng phổ biến trên xe, chẳng hạn như Hệ thống hỗ trợ người lái xe nâng cao (ADAS). Ứng dụng khách có thể bao gồm các hệ thống trên xe giao tiếp thông qua thuộc tính VMS trong VHAL hoặc các ứng dụng Android đặc quyền. Dữ liệu được chia sẻ trên VMS chỉ được giới hạn ở dữ liệu bản đồ để các hệ thống xe và ứng dụng hỗ trợ sử dụng.

VMS chỉ dùng để triển khai Android Automotive; AOSP không chứa các ứng dụng mặc định phát hành hoặc đăng ký VMS. Đối với thuộc tính VMS trong VHAL, các kiểu thông báo và cấu trúc dữ liệu được mô tả trong VHAL 2.0 trong enum VmsMessageType, trong đó liệt kê các loại thông báo VMS được hỗ trợ. enum này được dùng làm số nguyên đầu tiên trong mảng số nguyên của thuộc tính xe và xác định cách giải mã phần còn lại của thông báo.