https://github.com/covesa/vss-tools
Software for working with VSS (https://github.com/COVESA/vehicle_signal_specification)
https://github.com/covesa/vss-tools
Last synced: 15 days ago
JSON representation
Software for working with VSS (https://github.com/COVESA/vehicle_signal_specification)
- Host: GitHub
- URL: https://github.com/covesa/vss-tools
- Owner: COVESA
- License: mpl-2.0
- Created: 2020-02-21T15:29:15.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-04-22T14:06:43.000Z (about 1 month ago)
- Last Synced: 2025-05-16T10:06:51.637Z (15 days ago)
- Language: Python
- Homepage:
- Size: 3.03 MB
- Stars: 59
- Watchers: 13
- Forks: 61
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# VSS Tools
[](https://opensource.org/licenses/MPL-2.0)
[](https://github.com/COVESA/vss-tools/actions/workflows/buildcheck.yml?query=branch%3Amaster)
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](https://github.com/COVESA/vehicle_signal_specification).
VSS Tools is developed in parallel with VSS, please visit the [COVESA VSS project](https://github.com/COVESA/vehicle_signal_specification) for information on how to contribute.
If any questions arise, please check out the [FAQ](FAQ.md) for more information.
## Installation
There are several ways of installing `vss-tools`.
If you would like to contribute then please follow the [contribute](#contributing) section instead.
All of them are recommended to be done in an activated python virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate
```
pypi
```bash
pip install vss-tools
```
from source:
```bash
# 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](#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.
```bash
# 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](./docs/vspec.md) for generic info about exporters and their arguments
as well as [here](./docs/vspec_arch.md) for design decision, architecture and limitations.
## Compatibility with VSS
The [COVESA VSS project repository](https://github.com/COVESA/vehicle_signal_specification) 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` - |
| `` | `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](https://docs.astral.sh/uv/) as a python package and project manager.
Therefore, a requirement to develop is to install `uv` on your host machine.
Check [here](https://docs.astral.sh/uv/#getting-started) for official installation instructions. The recommended one is the following, however installing it through pip/pipx works as well:
```bash
# 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:
```bash
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`:
```bash
source .venv/bin/activate
vspec --help
```
Alternatively you can use `uv` to run the `vspec` tool:
```bash
uv run vspec --help
```
If you have a working setup of [direnv](https://direnv.net/), navigating into the directory
activates the `venv` (after an initial `uv sync` and `direnv allow`)
```bash
vspec --help
```
`uv` can manage independent python versions.
If you would like to use a specific python version (e.g. `python3.12`):
```bash
# 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](https://pre-commit.com/) 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](#uv).
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](https://github.com/protocolbuffers/protobuf) for your OS. For Debian systems it would be:
```bash
sudo apt update
sudo apt install -y golang-go protobuf-compiler
protoc --version # Ensure compiler version is 3+
```