VSS Tools

The overall goal of VSS Tools is to provide a set of tools that can be used to convert or verify Vehicle Signal Specifications defined by the format specified by the COVESA VSS project. VSS Tools is developed in parallel with VSS, please visit the COVESA VSS project for information on how to contribute. If any questions arise, please check out the FAQ for more information.

Installation

There are several ways of installing vss-tools. If you would like to contribute then please follow the contribute section instead. All of them are recommended to be done in an activated python virtual environment:

python -m venv .venv
source .venv/bin/activate

pypi

pip install vss-tools

from source:

# default branch
pip install git+https://github.com/COVESA/vss-tools.git
# explicit branch
pip install git+https://github.com/COVESA/vss-tools.git@master
# commit
pip install git+https://github.com/COVESA/vss-tools.git@1234567

See usage for how to start using it.

Usage

General CLI help should be used for up-to-date info of how to use the tools.

# Help for toplevel options and lists sub commands
vspec --help

# Help for export sub command options and lists sub commands
vspec export --help

# Help for json exporter options
vspec export json --help

Please check here for generic info about exporters and their arguments as well as here for design decision, architecture and limitations.

Compatibility with VSS

The COVESA VSS project repository includes vss-tools as a submodule. The vss-tools version linked by the VSS repository is the preferred vss-tools version to use for that particular version of the VSS repository. It is not guaranteed that newer or older versions of vss-tools can successfully handle that particular version of the VSS repository. The table below gives an overview of basic version support for e.g. vspec export json. Other exporters may have stricter requirements.

VSS-tools version	Supported VSS catalog versions	Comments
v3.0	v3.0 - v3.1.1
v3.1	v3.0 -v4.0
v4.0	v4.0
v4.1	v4.0 -
4.2	v4.0 -
5.0	v5.0 -
<latest source>	v5.0 -

Changes affecting compatibility

Examples on changes affecting compatibility

• Somewhat stricter control in VSS-tools 5.0 onwards, minor changes required in VSS 4.X catalogs to make it pass the control.
• VSS version v4.1 introduced a new syntax for the unit files that cannot be handled by vss-tools < v4.1
• From v4.0 vss-tools expects unit file to be explicitly specified or provided in the same directory as the VSS input. VSS v3.1 is the first VSS version including a unit file in the VSS repository. This means vss-tools from v4.0 onwards cannot handle VSS-versions prior to VSS v3.1
• VSS-tools v3.1 only supported default for attributes, resulting in that newer VSS-versions is not supported.
• VSS-tools v4.0 requires case-sensitive for type, resulting in that VSS versions v3.1 and earlier is not supported.

Contributing

UV

We are using uv as a python package and project manager. Therefore, a requirement to develop is to install uv on your host machine. Check here for official installation instructions. The recommended one is the following, however installing it through pip/pipx works as well:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

You can then use the following command in the root directory of vss-tools to install all dependencies:

uv sync

It will create a .venv in the root of the project. You can use the venv like you would without the usage of uv:

source .venv/bin/activate
vspec --help

Alternatively you can use uv to run the vspec tool:

uv run vspec --help

If you have a working setup of direnv, navigating into the directory activates the venv (after an initial uv sync and direnv allow)

vspec --help

uv can manage independent python versions. If you would like to use a specific python version (e.g. python3.12):

# Python 3.12
uv sync -p python3.12
# From the activated env:
python --version # --> Python 3.12.7

# Python 3.13
uv sync -p python3.13
python --version # --> Python 3.13.0

Pre-commit

This project uses pre-commit which helps to format the source code in a streamlined way. It is very recommended to use it. To install hooks you can do pre-commit install from an activated environment. Hooks will then run every time you do a git commit on changed files. If you would like to run all hooks on all files you can do pre-commit run --all. Since pre-commit dependencies are installed in the virtual environment, it needs to be activated to be able to run them on a commit.

Installing additional tools

If you intend to run test cases related to vspec proto exporter you need to install the protobuf compiler. Please follow official instructions for your OS. For Debian systems it would be:

sudo apt update
sudo apt install -y golang-go protobuf-compiler
protoc --version  # Ensure compiler version is 3+