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.
This repository contains three categories of tools:
- Community Supported Tools are tools that are actively maintained by the VSS community. They are run as part of the Continuous Integration process for both this repository and for the COVESA VSS project repository, and pull request will normally not be merged if any of the tools fails. That assures that the tools always are compatible with the latest version of the COVESA VSS.
- Contributed Tools are tools that are not actively maintained by the VSS community. Instead they are maintained by individual contributors, or not maintained at all. Even if many of them are run as part of the continuous integration process, it is not a requirement that they must run successfully on the latest VSS version and a change in VSS may be merged even if it cause some contributed tools to fail.
- Obsolete Tools are tools that are not maintained and not functional.
A tool in the Contributed Tools category may be moved to the Obsolete category if it has been non-functional for at least 6 months. Tools in the Obsolete Tools category may be deleted after 12 months.
Examples on tool usage can be found in the VSS Makefile and in tool-specific documentation, if existing.
| Tool | Description | Tool Category | Documentation |
|---|---|---|---|
| vspec2x.py | Parses and expands VSS into different text based output formats. Currently supports json, yaml,csv,idl |
Community Supported | Try ./vspec2x --help or check vspec2x documentation |
| vspec2csv.py | Shortcut for vspec2x.py generating CSV output | Community Supported | Check vspec2x documentation |
| vspec2ddsidl.py | Shortcut for vspec2x.py generating DDS-IDL output | Community Supported | VSS2DDSIDL Documentation. For general parameters check vspec2x documentation |
| vspec2json.py | Shortcut for vspec2x.py generating JSON output | Community Supported | Check vspec2x documentation |
| vspec2yaml.py | Shortcut for vspec2x.py generating flattened YAML output | Community Supported | Check vspec2x documentation |
| vspec2binary.py | The binary toolset consists of a tool that translates the VSS YAML specification to the binary file format (see below), and two libraries that provides methods that are likely to be needed by a server that manages the VSS tree, one written in C, and one in Go | Community Supported | vspec2binary Documentation. For general parameters check vspec2x documentation |
| vspec2franca.py | Parses and expands a VSS and generates a Franca IDL specification | Community Supported | Check vspec2x documentation |
| vspec2c.py | The vspec2c tooling allows a vehicle signal specification to be translated from its source YAML file to native C code that has the entire specification encoded in it. | Obsolete (2022-11-01) | Documentation |
| vspec2ocf.py | Parses and expands a VSS and generates a OCF specification | Obsolete (2022-11-01) | - |
| vspec2proto.py | Parses and expands a VSS and generates a Protobuf specification | Contrib | - |
| vspec2ttl.py | Parses and expands a VSS and generates a TTL specification | Contrib | - |
| vspec2graphql.py | Parses and expands a VSS and generates a GraphQL specification | Community Supported | Documentation |
All current tools are based on common Python functionality in the vspec folder to read, parse and expand a Vehicle Signal Specification files(*.vspec files). As an example, if the standard VSS root file is given as input then the Python tooling will read all included files, do a validation of the content, expand any instances used and create an in-memory representation which then can be used by specialized tools to generate the wanted output.
- Python 3.8.12 installed
- If the installation (pip install) is executed behind a (corporate) proxy, the following environments variables must be set:
http_proxyandhttps_proxy(including authentication e.g.,http://${proxy_username):$(proxy_password)@yourproxy.yourdomain) - If you do not run with administration rights, you may need to configure pip target path to write to your user home directory or consider using the
pipenvmethod.
On Unix and Mac OS X the configuration file is: $HOME/.pip/pip.conf
If the file does not exist, create an empty file with that name.
Add or replace the following lines:
[global]
target=/somedir/where/your/account/can/write/to
On Windows, the configuration file is: %HOME%\pip\pip.ini
If the file does not exist, create an empty file with that name.
Add or replace the following lines:
[global]
target=C:\SomeDir\Where\Your\Account\Can\Write\To
- Checkout vss-tools as submodule of the Vehicle Signal Specification repository (
git clone --recurse-submodules -j8 https://github.com/COVESA/vehicle_signal_specification.git) - If you use a custom pip installation directory, set the
PYTHONPATHenvironment variable to the directory that you set in thepip.inifile.
pipenv is a tool that manages a virtual environment and install the package and its dependencies, making the process much simpler and predictable, since the Pipfile states the dependencies, while Pipfile.lock freezes the exact version in use.
If pyenv shell command is not installed, use its installer to get it:
curl https://pyenv.run | bash # download and install
exec $SHELL # restart your shell using the new $PATHMake sure Python version 3.8.12 is installed:
pyenv install 3.8.12 # install the versions required by PipfileInstall this project and its dependencies in the local .venv folder in this project, then use it (pipenv shell):
export PIPENV_VENV_IN_PROJECT=1 # will create a local `.venv` in the project, otherwise uses global location
pipenv install --dev # install the development dependencies as well
pipenv shell # starts a shell configured to use the virtual environment