Katalogi sygnałów pojazdów

Generator konfiguracji danych (MCG) sprawdza poprawność konfiguracji danych, sprawdzając nazwy sygnałów, przeprowadzając kontrolę typów wyrażeń i wnioskując typy danych wyjściowych. Aby wykonywać te zadania, MCG potrzebuje dostępu do definicji wiadomości bufora protokołu (protobuf) dotyczących sygnałów pojazdu.

W SDV sygnały i usługi pojazdu są definiowane za pomocą języka definicji interfejsu usług pojazdu (Vehicle Service Interface Definition Language, VSIDL). VSIDL używa plików protobuf do określania komunikatów, a te pliki protobuf stanowią podstawę katalogu sygnałów.

Aby definicje sygnałów były dostępne dla MCG, musisz spakować te pliki protobuf VSIDL do pliku protobuf FileDescriptorSet i przesłać go do usługi MCG. MCG używa terminu Vehicle Signal Catalog (Katalog sygnałów pojazdu) w odniesieniu do tych przesłanych i wersjonowanych zestawów definicji (co zasadniczo sprawia, że katalog sygnałów pojazdu jest skompilowaną, przesłaną formą definicji komunikatów proto w katalogu VSIDL).

Czym jest Vehicle Signal Catalog?

Katalog sygnałów pojazdu udostępnia MCG definicje sygnałów do weryfikacji, spakowane jako protobuf FileDescriptorSet.

W MCG katalogi są identyfikowane przez ciąg wersji przypisywany podczas przesyłania, co umożliwia zarządzanie wieloma różnymi zestawami definicji sygnałów. Możesz na przykład utrzymywać różne wersje katalogu dla wersji oprogramowania (v1.0, v1.1, v2.0) lub dla różnych modeli pojazdów bądź konfiguracji sprzętu (suv-my2025, sedan-my2025). Każda konfiguracja danych używa pola vs_version do odwoływania się do konkretnego katalogu, który definiuje sygnały dostępne jako źródła danych i zawiera definicje sygnałów na potrzeby wnioskowania o typach i walidacji.

Utwórz instancję FileDescriptorSet

Jak opisano w artykule Definiowanie wiadomości i usług RPC, sygnały pojazdu są definiowane jako wiadomości protobuf w plikach protobuf. Jeśli uczestniczysz w projekcie SDV, użyj plików protobuf z katalogu VSIDL projektu, aby utworzyć instancję FileDescriptorSet.

Aby utworzyć katalog dla MCG, połącz pliki protobuf w plik binarny FileDescriptorSet za pomocą protoc. Jeśli wszystkie pliki protobuf znajdują się w jednym folderze, uruchom to polecenie, aby wygenerować vehicle_signals.pb:

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

Przesyłanie katalogów i zarządzanie nimi

Przesłanie zestawu definicji sygnałów jako katalogu umożliwia odwoływanie się do niego według nazwy wersji w żądaniach konfiguracji danych.

Dodawanie i aktualizowanie wersji katalogu

Po wygenerowaniu pliku katalogu vehicle_signals.pb możesz go przesłać i zarządzać nim za pomocą punktów końcowych interfejsu MCG API w sekcji /api/v2/vs/. Punkt końcowy do dodawania lub aktualizowania katalogu, POST /api/v2/vs/, wymaga przekazania FileDescriptorSet jako ciągu znaków zakodowanego w formacie base64 w ładunku JSON.

Aby zakodować vehicle_signals.pb do użycia w interfejsie API, użyj polecenia base64. Flaga -w 0 wyłącza zawijanie wierszy, dzięki czemu zakodowany ciąg znaków pojawia się w jednym wierszu:

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

Aby przesłać vehicle_signals.pb jako nową wersję (np. v1.0) lub zaktualizować istniejącą wersję, wyślij żądanie POST z treścią zakodowaną w formacie base64 do punktu końcowego /api/v2/vs/ z unikalną nazwą wersji.

Treść żądania musi być obiektem JSON zawierającym ciąg tekstowy version i ciąg tekstowy vehicle_signals zakodowany w formacie base64:

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

Poniższy przykład pokazuje, jak przesłać plik vehicle_signals.pb jako wersję v1.0 za pomocą curl. W przykładzie użyto printf do utworzenia ładunku JSON i przekazania go do curl, co pozwala uniknąć konieczności tworzenia pliku JSON zawierającego bardzo długi ciąg base64 w jednym wierszu:

# 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/"

Wyświetlanie listy wersji i ich usuwanie

Możesz wyświetlić listę wszystkich dostępnych wersji katalogu lub usunąć konkretną wersję:

• Wyświetlanie listy wersji: aby wyświetlić listę identyfikatorów wszystkich przesłanych wersji katalogu, wyślij żądanie GET do /api/v2/vs/. Zobacz GET /api/v2/vs/.

• Usuwanie wersji: aby usunąć katalog, wyślij żądanie DELETE na adres /api/v2/vs/{version}, gdzie {version} to identyfikator podany podczas przesyłania katalogu (np. v1.0). Zobacz DELETE /api/v2/vs/{version}.

Pełne informacje o wszystkich punktach końcowych znajdziesz w dokumentacji API.

Używanie katalogu w konfiguracjach danych

Po przesłaniu odwołaj się do wersji katalogu w konfiguracjach danych za pomocą pola vs_version:

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

Gdy ten obiekt JSON jest wysyłany do punktów końcowych /api/v2/generate_metrics_config lub /api/v2/validate_metrics_config, MCG używa definicji sygnałów z katalogu v1.0 do przeprowadzania walidacji i wnioskowania o typach.