Propriedades do veículo

A interface Camada de abstração de hardware do veículo (VHAL, na sigla em inglês) define as propriedades que os OEMs podem implementar e contém metadados de propriedade, por exemplo, se a propriedade é um int e quais modos de mudança são permitidos. A interface VHAL é baseada no acesso (leitura, gravação, inscrição) a uma propriedade, que é uma abstração para uma função específica.

Interfaces HAL

A VHAL usa as seguintes interfaces:

  • getAllPropConfigs() gera (vec<VehiclePropConfig>propConfigs)
    Lista a configuração de todas as propriedades aceitas pelo VHAL. CarService usa apenas propriedades compatíveis.
  • getPropConfigs(vec<int32_t> props) gera (StatusCode status,vec<VehiclePropConfig> propConfigs);
    Retorna a configuração das propriedades selecionadas.
  • set(VehiclePropValue propValue) gera (StatusCodestatus);
    Grava um valor na propriedade. O resultado da gravação é definido por propriedade.
  • subscribe(IVehicleCallback callback, vec<SubscribeOptions> options) gera (StatusCode status);
    Comece a monitorar uma mudança no valor de uma propriedade. Para a propriedade em zonas, unsubscribe(IVehicleCallback callback, int32_t propId) gera (StatusCode status);.

O VHAL usa as seguintes interfaces de callback:

  • oneway onPropertyEvent(vec<VehiclePropValue>propValues);
    Notifica a mudança de valor da propriedade do veículo. Deve ser feito apenas para propriedades inscritas.
  • oneway onPropertySetError(StatusCode errorCode,int32_t propId,int32_tareaId);
    Retorna um erro global de nível VHAL ou um erro por propriedade. O erro global faz com que o HAL seja reiniciado, o que pode levar à reinicialização de outros componentes (incluindo aplicativos).

Propriedades do veículo

As propriedades podem ser somente leitura, somente gravação (usadas para transmitir informações ao nível da VHAL) ou de leitura e gravação (a compatibilidade com a maioria das propriedades é opcional). Cada propriedade é identificada de forma exclusiva por uma chave int32 e tem um tipo predefinido (value_type):

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

Uma propriedade zonada pode ter mais de um valor, com base no número de zonas oferecidas pela propriedade.

Tipos de área

A VHAL define vários tipos de área:

Tipo de área Descrição
GLOBAL Essa propriedade é um singleton e não tem várias áreas.
WINDOW Área baseada em janelas, usa a enumeração VehicleAreaWindow.
MIRROR Área baseada em espelhos, usa o tipo enumerado VehicleAreaMirror.
SEAT Área com base nos assentos, usa o tipo enumerado VehicleAreaSeat.
DOOR Área com base em portas, usa o tipo enumerado VehicleAreaDoor.
WHEEL Área baseada em rodas, usa a enumeração VehicleAreaWheel.

Cada propriedade com zona precisa usar um tipo de área predefinido. Cada tipo de área tem um conjunto de sinalizações de bit definidas em um tipo enumerado para o tipo de área. Por exemplo, a área SEAT define tipos enumerados 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
  • …

IDs de área

As propriedades com zonas são tratadas usando IDs de área. Cada propriedade com zona pode oferecer suporte a um ou mais IDs de área. Um ID de área é composto por uma ou mais sinalizações do respectivo tipo enumerado. Por exemplo, uma propriedade que usa VehicleAreaSeat pode usar os seguintes IDs de área:

Nome Descrição
ROW_1_LEFT | ROW_1_RIGHT O ID de área se aplica aos dois assentos dianteiros.
ROW_2_LEFT Aplicável apenas ao banco traseiro esquerdo.
ROW_2_RIGHT Aplicável apenas ao banco traseiro direito.

Status da propriedade

Cada valor de propriedade vem com um valor VehiclePropertyStatus. Isso indica o status atual da propriedade:

Nome Descrição
AVAILABLE A propriedade está disponível e o valor é válido.
UNAVAILABLE O valor da propriedade não está disponível no momento. Usado para recursos temporariamente desativados em uma propriedade compatível.
ERROR Há algo errado com essa propriedade.

Como configurar uma propriedade

Use VehiclePropConfig para fornecer informações de configuração para cada propriedade. As informações incluem:

Variável Descrição
access r, w, rw
changeMode Representa como uma propriedade é monitorada, em mudança ou contínua.
areaConfigs Valores areaId, min e max.
configArray Outros parâmetros de configuração.
configString Informações adicionais transmitidas como uma string.
minSampleRate maxSampleRate
prop ID da propriedade, int

Como processar propriedades de zona

Uma propriedade com zona é equivalente a uma coleção de várias propriedades em que cada subpropriedade pode ser acessada com o valor do ID de área especificado.

  • A chamada get para a propriedade com zonas sempre inclui o ID de área na solicitação. Portanto, apenas o valor atual do ID da área solicitada é retornado. Se a propriedade for global, o ID de área será 0.
  • A chamada set para a propriedade zonada sempre inclui o ID da área na solicitação. Portanto, apenas o ID da área solicitado é alterado.
  • A chamada subscribe gera eventos para todos os IDs de área da propriedade.

Receber ligações

Durante a inicialização, o valor da propriedade pode ainda não estar disponível, porque a mensagem da rede do veículo correspondente ainda não foi recebida. Nesses casos, a chamada get precisa retornar -EAGAIN. Algumas propriedades (como AVAC) têm uma propriedade de energia ligada/desligada separada. Chamar get para essa propriedade (quando desligado) precisa retornar um status UNAVAILABLE em vez de um erro. Por exemplo, receber a temperatura do AVAC

Exemplo de AVAC de get de VHAL

Figura 1. Conseguir a temperatura do AVAC (CS = CarService, VHAL = HAL do veículo)

Definir chamadas

Em uma operação típica, uma chamada set leva à solicitação de mudança na rede do veículo. Uma chamada set é, idealmente, uma operação assíncrona que retorna o mais rápido possível, mas também pode ser síncrona. Algumas chamadas set podem exigir que os dados iniciais estejam prontos, mas, durante a inicialização, esses dados podem ainda não estar disponíveis. Nesses casos, a chamada set precisa retornar StatusCode#TRY_AGAIN. Algumas propriedades com alimentação ligada e desligada separadas precisam retornar StatusCode#NOT_AVAILABLE ou StatusCode#NOT_AVAILABLE_DISABLED quando a propriedade está desligada e set não pode ser realizada. Até que set seja efetivado, get não necessariamente retorna o mesmo valor que o definido. Por exemplo, set HVAC Temperature.

Exemplo de AVAC definido por VHAL

Figura 2. Definir a temperatura do AVAC (CS = CarService, VHAL = HAL do veículo)

Como processar propriedades personalizadas

Para atender às necessidades específicas dos parceiros, o VHAL permite propriedades personalizadas restritas a apps do sistema. Siga as diretrizes abaixo ao trabalhar com propriedades personalizadas:

  • O ID da propriedade precisa ser gerado usando os seguintes campos:
    • VehiclePropertyGroup:VENDOR
      O grupo VENDOR é usado somente para propriedades personalizadas.
    • VehicleArea
      Selecione um tipo de área adequado.
    • VehiclePropertyType
      Selecione o tipo de dados correto. O tipo BYTES permite a transmissão de dados brutos, que é suficiente na maioria dos casos. O envio frequente de Big Data por meio de propriedades personalizadas pode atrasar o acesso a toda a rede do veículo. Tenha cuidado ao adicionar um payload grande.
    • Property ID
      Escolha um ID de quatro nibbles para a propriedade personalizada.
  • Para evitar a fragmentação do ecossistema, as propriedades personalizadas não podem ser usadas para replicar as propriedades do veículo que já existem no (SDK de VehiclePropertyIds).
  • Preencha VehiclePropConfig.configString com uma breve descrição da propriedade personalizada. Isso permite que as ferramentas de verificação de sanidade sinalizem a replicação acidental de propriedades de veículos existentes. Por exemplo, "estado da luz de advertência".
  • Acesso por CarPropertyManager (para componentes Java) ou pela API Vehicle Network Service (para nativo). Não modifique outras APIs do carro, porque isso pode causar problemas de compatibilidade no futuro.
  • Depois de implementar as propriedades do fornecedor, selecione apenas a lista de permissões no tipo enumerado VehicleVendorPermission para as propriedades do fornecedor. O mapeamento de permissões do fornecedor para propriedades do sistema vai interromper o CTS e o VTS.

Como lidar com propriedades de AVAC

É possível usar o VHAL para controlar o AVAC definindo propriedades relacionadas a ele. A maioria das propriedades de AVAC são propriedades com zonas, embora várias sejam propriedades sem zonas (globais). Confira alguns exemplos de propriedades definidas:

Propriedade Objetivo
VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET Definir a temperatura por zona.
VEHICLE_PROPERTY_HVAC_RECIRC_ON Controle a recirculação por zona.

Para acessar uma lista completa de propriedades do sistema AVAC (aquecimento, ventilação e ar-condicionado), pesquise VEHICLE_PROPERTY_HVAC_* em types.hal. Quando a propriedade AVAC usa VehicleAreaSeat, regras adicionais para mapear uma propriedade AVAC zonada para IDs de área são aplicadas. Cada assento disponível no carro precisa fazer parte de um ID de área no array de ID de área.

Exemplo 1. Um carro tem dois bancos dianteiros (ROW_1_LEFT, ROW_1_RIGHT) e três bancos traseiros (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). O carro tem duas unidades de controle de temperatura: o lado do motorista e o lado do passageiro.

  • Um conjunto de mapeamento válido de IDs de área para HVAC_TEMPERATURE SET é:
    • ROW_1_LEFT | ROW_2_LEFT
    • ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT
  • Um mapeamento alternativo para a mesma configuração de hardware é:
    • ROW_1_LEFT | ROW_2_LEFT | ROW_2_CENTER
    • ROW_1_RIGHT | ROW_2_RIGHT

Exemplo 2. Um carro tem três fileiras com dois assentos na primeira fila (ROW_1_LEFT, ROW_1_RIGHT), três na segunda (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT) e três na terceira fila (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). O carro tem três unidades de controle de temperatura: lado do motorista, lado do passageiro e traseiro. Uma maneira razoável de mapear HVAC_TEMPERATURE_SET para IDs de área é como uma matriz de três elementos:

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

Como processar propriedades de sensores

As propriedades do sensor VHAL representam dados reais do sensor ou informações de política, como o status de direção. Algumas informações do sensor (como status de direção e modo dia/noite) podem ser acessadas por qualquer app sem restrições, já que os dados são obrigatórios para criar um aplicativo de veículo seguro. Outras informações do sensor (como velocidade do veículo) são mais sensíveis e exigem permissões específicas que os usuários possam gerenciar.

Consulte as propriedades de sensores com suporte (em types.hal).

Serviço de mapa veicular

O serviço de mapa veicular (VMS, na sigla em inglês) oferece um mecanismo para trocar dados do mapa entre clientes por uma interface do Pub/Sub para oferecer suporte a recursos comuns do veículo, como os Sistemas avançados de assistência ao motorista (ADAS). Os clientes podem incluir sistemas de veículos que fazem a interface pela propriedade VMS nas VHAL ou em apps Android privilegiados. Os dados compartilhados no VMS devem ser limitados a dados de mapa para uso por sistemas de veículos e apps compatíveis.

O VMS é destinado apenas a implementações do Android Automotive. O AOSP não contém clientes padrão que publicam ou se inscrevam no VMS. Para a propriedade VMS no VHAL, os tipos de mensagem e as estruturas de dados são descritos no VHAL 2.0 no enum VmsMessageType, que lista os tipos de mensagens VMS com suporte. Esse enum é usado como o primeiro número inteiro na matriz de números inteiros da propriedade do veículo e determina como o restante da mensagem é decodificado.