Metadata-Version: 2.4
Name: velocitas_model_generator
Version: 0.9.0
Summary: Generates a language-specific data model out of VSS vspec files
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: vss-tools==6.0
Dynamic: license-file

# Velocitas Vehicle Model Generator

[![License: Apache](https://img.shields.io/badge/License-Apache-yellow.svg)](http://www.apache.org/licenses/LICENSE-2.0)

## About
This generator creates a vehicle model from the given vspec specification for the target programming language.

## Supported languages

* Python 3
* C++
* TypeScript (Node.js 18+, TypeScript 5.x)

### TypeScript Code Generation Conventions
* **Properties (PascalCase)**: Tree branch and leaf properties preserve VSS PascalCase naming (e.g. `vehicle.Cabin.Seat.Row1.DriverSide.Position`) to maintain 1:1 path fidelity with VSS signal definitions and consistency across Python, C++, and TypeScript SDKs.
* **Methods (camelCase)**: SDK methods, collection accessors, and utility functions follow standard JavaScript/TypeScript camelCase conventions (e.g. `get()`, `set()`, `subscribe()`, `row()`, `element()`, `createVehicle()`).

**HINT**: C++ model generated by model generator versions >= 0.8.0 require C++ SDK versions >= 0.5.5 !

## Supported VSS versions
Out of the box the following VSS versions are supported:

.vspec
- VSS 4.2.1
- VSS 5.x
- VSS 6.x

.json
- VSS 3.x
- VSS 4.x
- VSS 5.x
- VSS 6.x

Support for other vspec version might require changes to the baseline vspec files:
- **3.0, 3.1, 3.1.1:** Convert legacy `units.yaml` entries to the `vss-tools` 6.0 schema and change `type: Actuator` to `type: actuator` in `Powertrain/Battery.vspec`. VSS 3.1 also needs a description for `Vehicle.Body.Lights.Brake`.
- **4.0:** Convert legacy `units.yaml` entries to the `vss-tools` 6.0 schema.
- **4.1:** In `units.yaml`, rename `ml.description` to `ml.definition`, `kg.label` to `kg.unit`, and `months.units` to `months.unit`.
- **5.1:** In `Vehicle/MotionManagement/Brake/Axle.vspec`, change `TorqueElectricMinimum.max` from `0.0` to `0`.

## Usage

Invoke the `src/velocitas/model_generator/cli.py` script with the path to the vspec or json file you wish to generate code for, additionally passing include paths to directories which contain referenced vspec files. You need a `units.yaml` in the same directory. If you want to use the default one see [here](https://github.com/COVESA/vehicle_signal_specification/blob/master/spec/units.yaml). For stability use release branch with tags. For example branch `release/6.0`.
```bash
python3 src/velocitas/model_generator/cli.py -I <path_to_dir_with_included_vspec_files> <path_to_your_vspec_file>
```
or
```bash
python3 src/velocitas/model_generator/cli.py <path_to_your_json_file>
```
### Example
```bash
git clone -b v6.1 https://github.com/COVESA/vehicle_signal_specification.git
python3 src/velocitas/model_generator/cli.py -I ./vehicle_signal_specification/spec ./vehicle_signal_specification/spec/VehicleSignalSpecification.vspec
```

Or use VSCode Launch: Press ```F5```, select ```Python``` or ```cpp``` and pass in the include directory and input file path.

## Arguments

| Argument                                                                 | Description                                                                                                                                                                          |
|:-------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-h`, `--help`                                                           | show this help message and exit                                                                                                                                                      |
| `-I dir`, `--include-dir dir`                                            | Add include directory to search for included vspec files.                                                                                                                            |
| `-T TARGET_FOLDER`, `--target-folder TARGET_FOLDER`                      | The folder name (with relative path) where the code will be generated into.                                                                                                          |
| `-N PACKAGE_NAME`, `--package-name PACKAGE_NAME`                         | Name of the root module/package (Python, TypeScript) or root namespace (C++).                                                                                                        |
| `-s`, `--strict`                                                         | Use strict checking: Terminate when anything not covered or not recommended by the core VSS specs is found.                                                                          |
| `-l {python,cpp,typescript}`, `--language {python,cpp,typescript}`       | The target language of the generated code; `ts` aliases TypeScript (default: python).                                                                                                |
| `-o OVERLAY_FILE`, `--overlays OVERLAY_FILE`                             | Add overlays that will be layered on top of the VSS file in the order they appear.                                                                                                   |
| `-u UNITS`, `--units UNITS`                                              | The file location of units file. If left empty it tries downloading default units file from https://github.com/COVESA/vehicle_signal_specification/blob/v4.0/spec/units.yaml.        |
| `-q QUANTITIES`, `--quantities QUANTITIES`                               | The file location of quantities file.                                                                                                                                                |
| `-e EXTENDED_ATTRIBUTES`,<br>`--extended-attributes EXTENDED_ATTRIBUTES` | Whitelisted extended attributes as comma separated list. Note, that extended attributes aren't considered by the generator. This parameter is only for suppressing warnings/errors." |

## Contribution
- [GitHub Issues](https://github.com/eclipse-velocitas/vehicle-model-generator/issues)
- [Mailing List](https://accounts.eclipse.org/mailing-list/velocitas-dev)
- [Contribution](./CONTRIBUTING.md)
