Catálogos de señales de vehículos

El generador de configuración de métricas (MCG) valida las configuraciones de métricas verificando los nombres de los indicadores, realizando una verificación de tipos en las expresiones y deduciendo los tipos de salida. MCG necesita acceso a las definiciones de mensajes de búfer de protocolo (protobuf) para que los indicadores del vehículo realicen estas tareas.

En SDV, los indicadores y servicios del vehículo se definen con el lenguaje de definición de interfaz de servicio del vehículo (VSIDL). VSIDL usa archivos protobuf para especificar mensajes, y estos archivos protobuf forman la base de un catálogo de indicadores.

Para que las definiciones de indicadores estén disponibles para MCG, debes empaquetar estos archivos protobuf de VSIDL en un FileDescriptorSet de protobuf y subirlo al servicio de MCG. MCG usa el término Catálogo de indicadores de vehículos para estos conjuntos de definiciones subidos y con versiones (básicamente, convierte un catálogo de indicadores de vehículos en el formato compilado y subido de las definiciones de mensajes proto en tu catálogo de VSIDL).

¿Qué es un catálogo de indicadores de vehículos?

Un catálogo de indicadores de vehículos proporciona al MCG definiciones de indicadores para la validación, empaquetadas como un protobuf FileDescriptorSet.

En MCG, los catálogos se identifican con una cadena de versión que asignas durante la carga, lo que te permite administrar varios conjuntos de definiciones de indicadores distintos. Por ejemplo, puedes mantener diferentes versiones de catálogo para las versiones de software (v1.0, v1.1, v2.0) o para diferentes modelos de vehículos o configuraciones de hardware (suv-my2025, sedan-my2025). Cada configuración de métricas usa el campo vs_version para hacer referencia a un catálogo específico, que define los indicadores que están disponibles como fuentes de datos y proporciona definiciones de indicadores para la inferencia y validación de tipos.

Crea una instancia de FileDescriptorSet

Como se describe en Define mensajes y servicios de RPC, los indicadores del vehículo se definen como mensajes de protobuf en archivos protobuf. Si formas parte de un proyecto de SDV, usa los archivos protobuf del catálogo de VSIDL de tu proyecto para crear una instancia de FileDescriptorSet.

Para crear un catálogo para MCG, empaqueta tus archivos protobuf en un archivo binario FileDescriptorSet con protoc. Si todos tus archivos protobuf están en una carpeta, ejecuta el siguiente comando para generar vehicle_signals.pb:

protoc --include_imports --descriptor_set_out=vehicle_signals.pb path/to/your/protos/*.proto

Sube y administra catálogos

Subir tu conjunto de definiciones de indicadores como un catálogo te permite hacer referencia a él por nombre de versión en las solicitudes de configuración de métricas.

Agrega o actualiza una versión del catálogo

Después de generar el archivo de catálogo vehicle_signals.pb, puedes subirlo y administrarlo con los extremos de la API de MCG en /api/v2/vs/. El extremo para agregar o actualizar un catálogo, POST /api/v2/vs/, requiere que el FileDescriptorSet se pase como una cadena codificada en base64 en la carga útil de JSON.

Para codificar vehicle_signals.pb para el uso de la API, usa el comando base64. La marca -w 0 inhabilita el ajuste de línea para que la cadena codificada aparezca en una sola línea:

VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

Para subir vehicle_signals.pb como una versión nueva (por ejemplo, v1.0) o para actualizar una versión existente, envía una solicitud POST con el contenido codificado en Base64 al extremo /api/v2/vs/ con un nombre de versión único.

El cuerpo de la solicitud debe ser un objeto JSON que contenga la cadena version y la cadena vehicle_signals codificada en Base64:

{
  "version": "v1.0",
  "vehicle_signals": "Q2lSb1pYB3jCRkRt..."
}

En el siguiente ejemplo, se muestra cómo subir vehicle_signals.pb como la versión v1.0 con curl. En el ejemplo, se usa printf para construir la carga útil de JSON y se canaliza a curl, lo que evita la necesidad de crear un archivo JSON que contenga una cadena base64 muy larga de una sola línea:

# 1. Encode the FileDescriptorSet to a Base64 string
VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

# 2. Define catalog version and build JSON payload
VERSION="v1.0"
JSON_PAYLOAD=$(jq -n --arg v "$VERSION" --arg d "$VEHICLE_SIGNALS_BASE64" \
  '{version: $v, vehicle_signals: $d}')

# 3. POST the data to the API endpoint
echo "$JSON_PAYLOAD" | curl -H "Content-Type: application/json" --data-binary @- "$SERVICE_URL/api/v2/vs/"

Enumera y borra versiones

Puedes enumerar todas las versiones disponibles del catálogo o borrar una versión específica:

• Enumera las versiones: Para ver una lista de identificadores de todas las versiones del catálogo subidas, envía una solicitud GET a /api/v2/vs/. Consulta GET /api/v2/vs/.

• Borra una versión: Para quitar un catálogo, envía una solicitud DELETE a /api/v2/vs/{version}, en la que {version} es el identificador proporcionado cuando se subió el catálogo (por ejemplo, v1.0). Consulta DELETE /api/v2/vs/{version}.

Para obtener todos los detalles sobre todos los extremos, consulta la referencia de la API.

Usa un catálogo en las configuraciones de métricas

Cuando se suba, haz referencia a una versión del catálogo en las configuraciones de métricas con el campo vs_version:

{ "vs_version": "v1.0", ... }

Cuando este objeto JSON se envía a los extremos /api/v2/generate_metrics_config o /api/v2/validate_metrics_config, MCG usa las definiciones de indicadores del catálogo v1.0 para realizar la validación y la inferencia de tipos.