Estender descrições de propriedade VHAL no emulador

O Android Automotive OS (AAOS) contém propriedades comuns do VHAL que podem ser visualizadas na janela VHAL de um emulador. Como resultado, você pode conferir muitas informações sobre VHALs, incluindo nomes, descrições e o significado dos valores. As informações são extraídas dos metadados das propriedades VHAL, que são codificadas no emulador QEMU.

Quando você adiciona suas próprias propriedades VHAL para uso exclusivo nos dispositivos, a visualização de metadados VHAL na janela VHAL exige que você modifique o código e crie um emulador QEMU personalizado. Para contornar esse problema, você pode escrever suas próprias descrições no formato JSON e adicioná-las à imagem do sistema.

Visão geral

Esta página detalha como você pode estender as descrições de propriedades VHAL em um emulador AAOS.

Criar metadados JSON para estender as propriedades do VHAL

O emulador procura metadados adicionais em todos os arquivos que terminam em -types-meta.json no caminho do Dispositivo virtual Android (AVD). Os arquivos JSON precisam consistir em uma matriz de objetos Enum, conforme mostrado abaixo.

Objeto de tipo enumerado

O objeto Enum com o nome VehicleProperty é um caso especial em que ele pode ser considerado como raiz. O conteúdo é adicionado ao mapa de propriedades do veículo. Outros Enums (com um nome diferente de VehicleProperty) definem mapas dos nomes dos valores personalizados.

Enum: {
  "name" : String,
  "values" : Array of { ValueObject }
}  

ValueObject

ValueObject: {
  "name" : String,
  "value" : Integer,
  "data_enum" : String, VehicleProperty only, optional,
}

Para VehicleProperty, o nome Enum descreve como essa propriedade é exibida na janela VHAL do emulador. O valor é o property_id da propriedade descrita pelo ValueObject. data_enum associa ValueObject a outro Enum. Essa associação é usada para mapear um valor em uma string legível por humanos e existe apenas para ValueObjects no Enum para o VehicleProperty. Confira um exemplo de VehicleProperty abaixo:

[
  {
      "name": "VehicleProperty",
      "values": [
          {
              "name": "CURRENT_GEAR",
              "value": 289408001
          }
      ]
  }
]

Neste exemplo, um property_id com um value de 289408001 é fornecido como um name para CURRENT_GEAR. No emulador, essa propriedade já está codificada como um nome, Current Gear. Não é possível reproduzir esse cenário, porque esta página foi criada depois de remover todas as propriedades codificadas para fins de demonstração.

Figura 1. VehicleProperty definido com nome e valor.

Na guia Propriedades VHAL do emulador, o nome é atualizado para CURRENT_GEAR, como esperado.

data_enum

No exemplo acima, o valor exibido é 4 quando a engrenagem está definida como P.

Figura 2. Valor exibido como 4.

Como esperado, na guia Propriedades do VHAL no emulador, o nome aparece como CURRENT_GEAR. Isso é diferente do emulador atual, em que ele aparece como P.

enum VehicleGear {
  GEAR_UNKNOWN = 0x0000,
  GEAR_NEUTRAL = 0x0001,
  GEAR_REVERSE = 0x0002,
  GEAR_PARK = 0x0004,
  GEAR_DRIVE = 0x0008,
  GEAR_1 = 0x0010,
  GEAR_2 = 0x0020,
  GEAR_3 = 0x0040,
  GEAR_4 = 0x0080,
  GEAR_5 = 0x0100,
  GEAR_6 = 0x0200,
  GEAR_7 = 0x0400,
  GEAR_8 = 0x0800,
  GEAR_9 = 0x1000,
}

Para saber mais, consulte a definição de AIDL.

Conforme definido na AIDL, o valor da engrenagem Park é 4, o que significa que você precisa traduzir o valor 4 em P. É quando você usa data_enum, que mapeia esse valor de propriedade para uma string legível por humanos em outro Enum. O emulador usa esse mapa para traduzir os valores das propriedades. Exemplo:

[
    {
        "name": "VehicleProperty",
        "values": [
            {
                "name": "CURRENT_GEAR",
                "value": 289408001,
                "data_enum": "VehicleGear"
            }
        ]
    },
    {
        "name": "VehicleGear",
        "values": [
            {
                "name": "GEAR_UNKNOWN",
                "value": 0
            },
            {
                "name": "GEAR_PARK",
                "value": 4
            }
        ]
    }

]

Adicione "data_enum": "VehicleGear" para que o emulador use um Enum chamado VehicleGear para traduzir o valor da propriedade. Adicione outro Enum com o nome VehicleGear e o valor como uma matriz de ValueObject, em que o valor da propriedade (com o valor) precisa ser mostrado como um nome.

Figura 3. O valor é exibido como GEAR_PARK.

Na guia Propriedades VHAL do emulador, o nome é atualizado para CURRENT_GEAR, como esperado. O valor da propriedade 4 é mostrado como GEAR_PARK.

Usar metadados JSON para estender propriedades do VHAL

Para usar metadados JSON para estender suas propriedades VHAL, execute este script Python (contido na fonte do Android) para gerar o JSON da propriedade estendida com base nas informações do AIDL.

O JSON resultante inclui alguns valores redundantes, como change_mode, access e unit. Embora essas informações façam parte da propriedade VHAL, esses valores JSON não afetam o que é exibido na janela de propriedades VHAL do emulador.

Adicionar metadados JSON à imagem do sistema

O nome do arquivo precisa terminar com -types-meta.json. Caso contrário, o arquivo será ignorado.

Adicionar um destino de build

Adicione o arquivo -types-meta.json ao PRODUCT_COPY_FILE. Por exemplo:

PRODUCT_COPY_FILES += \
    device/generic/car/common/vehicle-types-meta.json:vehicle-types-meta.json

Esse código copia o arquivo para out/target/product/{your_target_path}/, a raiz da saída do destino criado.