VSS Toolsを使ってVSSで定義した車両信号仕様のオーバーレイを試してみた
2025.05.22VSS ToolsはVSS(Vehicle Signal Specification)で定義される車両信号仕様を変換または検証するためのツールセットです。
今回はVSS Toolsを使って、VSSで定義した車両信号仕様のオーバーレイによるカスタマイズを試してみます。
試してみる
バージョン
- uv: 0.7.6
- python: 3.13.3
- vss-tools: 5.0
VSS Toolsの機能の確認
uvを使って、VSS Toolsを実行し、ヘルプを表示します。パッケージ名はvss-toolsですが、実行コマンドはvspecになります。
uvx(uv tool run)によって、自動的に一時的な分離環境にインストールされます。uvxの使い方については、uvのドキュメントを参照してください。
※ pipを使う場合は、pip install vss-toolsでインストール後に、vspecで実行できます。
uvx --from vss-tools vspec --help
次のようにオプションとコマンドの一覧が表示されます。現在はexportコマンドがあります。
Usage: vspec [OPTIONS] COMMAND [ARGS]...
╭─ Options ─────────────────────────────────────────────────────────────────────────────╮
│ --log-level [debug|info|WARNING|error|critica Log level. [default: INFO] │
│ l] │
│ --log-file FILE Log file. │
│ --version Show the version and exit. │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────────────────────╮
│ export Export a vspec to a chosen format │
╰───────────────────────────────────────────────────────────────────────────────────────╯
exportのヘルプを表示します。
uvx --from vss-tools vspec export --help
利用可能なコマンドには、出力可能なファイル形式の一覧が表示されています。各形式への出力についての説明は以下のドキュメントに記載があります。
Usage: vspec export [OPTIONS] COMMAND [ARGS]...
Export a vspec to a chosen format
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ apigear Export to ApiGear. │
│ binary Export to Binary. │
│ csv Export as CSV. │
│ ddsidl Export as DDSIDL. │
│ franca Export as Franca. │
│ graphql Export as GraphQL. │
│ id Export as IDs. │
│ json Export as JSON. │
│ jsonschema Export as a jsonschema. │
│ protobuf Export as protobuf. │
│ samm Export COVESA VSS to Eclipse Semantic Modeling Framework (ESMF) - Semantic │
│ Aspect Meta Model (SAMM) - .ttl files. │
│ tree Export as Tree. │
│ yaml Export as YAML. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
元となるファイルの作成と構造の確認
元となるbase.vspecは次のような速度とドアの開閉状態だけのシンプルなものにします。
Vehicle:
type: branch
description: 車両の基本情報
Vehicle.Speed:
type: sensor
description: 車両の速度
datatype: float
Vehicle.Cabin:
type: branch
description: 車内
Vehicle.Cabin.Door:
type: branch
description: ドア
Vehicle.Cabin.Door.IsOpen:
type: actuator
description: ドアの開閉状態
datatype: boolean
※ 普通速度には単位を指定しますが、単位がある場合にはunitとquantityの一覧を定義したファイルが必要になるため、今回は単位を指定していません。単位の指定については以下のドキュメントを参照してください。
作成したファイルをツリー形式で出力してみます。
uvx --from vss-tools vspec export tree -s v
次のようにWARNINGとINFOの後にツリー形式の構造が表示されました。
このWARNINGログは、quantityファイルとunitファイルを指定しておらず、かつデフォルトのquantityファイルとunitファイルが存在しないために表示されています。vspecファイルでunitを指定してないため無視します。
INFOログでは、読み込んだファイル数が表示されています。
[16:42:01] WARNING No 'quantity' files defined. Default not main.py:60
existing:
{実行パス}/quantiti
es.yaml
WARNING No 'unit' files defined. Default not existing: main.py:66
{実行パス}/units.ya
ml
INFO VSpecs loaded, amount=1 vspec.py:122
INFO Vehicle vss2tree.py:90
├── Speed
└── Cabin
└── Door
└── IsOpen
オーバーレイを試す
次に、オーバーレイに用いるoverlay.vspecを作成します。ノードの変更と追加、削除それぞれを試します。
# 既存のノードの変更
Vehicle.Cabin.Door:
description: ドア(変更後)
customAttribute: test
# 新しいノードの追加
Vehicle.Cabin.Door.Window:
type: branch
description: 窓
Vehicle.Cabin.Door.Window.IsOpen:
type: actuator
description: 窓の開閉状態
datatype: boolean
# 既存のノードの削除
Vehicle.Speed:
delete: true
base.vspecにoverlay.vspecを適用（オーバーレイ）した結果をツリー形式で表示します。オーバーレイファイルは-l / --overlayで指定します。オーバーレイファイルに、標準のVSSには存在しないキーを追加しているので、-e / --extended-attributesで指定します。
uvx --from vss-tools vspec export tree -s base.vspec -l overlay.vspec -e customAttribute
出力結果は次のようになりました。(WARNING部分は除外)
customAttributeが追加されていることや、読み込んだファイル数は2つになり、1つのノードが削除された旨がINFOで表示されています。
また、ノードとしてSpeedが消えてWindow.IsOpenが追加されていることがツリー表示でわかります
INFO User defined extra attributes: main.py:203
('customAttribute',)
INFO VSpecs loaded, amount=2 vspec.py:122
INFO Nodes deleted, given=1, overall=1 tree.py:274
INFO Vehicle vss2tree.py:90
└── Cabin
└── Door
├── IsOpen
└── Window
└── IsOpen
次は、オーバーレイした結果をyaml形式で保存します。
uvx --from vss-tools vspec export yaml -s base.vspec -l overlay.vspec -e customAttribute -o exported.vspec
次のように表示され、すぐに処理は完了します。 (WARNINGは除外)
INFO User defined extra attributes: main.py:203
('customAttribute',)
INFO VSpecs loaded, amount=2 vspec.py:122
INFO Nodes deleted, given=1, overall=1 tree.py:274
INFO Generating YAML output... vss2yaml.py:97
処理完了後、exported.vspecは保存されており、中身は次のようになっていました。Vehicle.Cabin.Doorのdescriptionの変更とcustomAttributeの追加も反映されています。
Vehicle:
description: 車両の基本情報
type: branch
Vehicle.Cabin:
description: 車内
type: branch
Vehicle.Cabin.Door:
customAttribute: test
description: ドア(変更後)
type: branch
Vehicle.Cabin.Door.IsOpen:
datatype: boolean
description: ドアの開閉状態
type: actuator
Vehicle.Cabin.Door.Window:
description: 窓
type: branch
Vehicle.Cabin.Door.Window.IsOpen:
datatype: boolean
description: 窓の開閉状態
type: actuator
出力されたファイルをvspecファイルとして用いることもできます。ツリー形式での出力を試してみます。
uvx --from vss-tools vspec export tree -s exported.vspec
次のように表示されました。(WARNINGは除外)
INFO VSpecs loaded, amount=1 vspec.py:122
INFO Vehicle vss2tree.py:90
└── Cabin
└── Door
├── IsOpen
└── Window
└── IsOpen
これで今回の検証を終わります。
今回は試していませんが、オーバーレイするファイルは複数指定することもできます。詳細は以下のドキュメントを参照してください。
さいごに
VSS ToolsのvspecコマンドでVSSのオーバーレイ機能を試しました。VSSの標準カタログを使う場合もそうでない場合も、車両モデルのカスタマイズが必要なケースは多いかと思います。オーバーレイによって車両モデルのカスタマイズが簡単に実現できそうです。
vspecコマンドでは、FrancaやProtocol BuffersなどのIDLへの出力も対応しています。共通のVSS形式の車両信号仕様を元に、さまざまな通信プロトコルで車両の信号データをやり取りするシステムの開発に活用できそうです。
