From 3904ee37823cd03472db5ecbf4d5547a5276a1c5 Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Thu, 19 Sep 2024 13:38:03 +0200 Subject: [PATCH] 5.0rc0 preparation Signed-off-by: Erik Jaegervall --- BUILD.md | 3 +- CHANGELOG.md | 301 +++++++++++---------- README.md | 8 +- docs-gen/layouts/partials/menu-footer.html | 2 +- scripts/install_vss_tools.sh | 4 +- spec/Vehicle/Vehicle.vspec | 2 +- 6 files changed, 169 insertions(+), 151 deletions(-) diff --git a/BUILD.md b/BUILD.md index bd9604abf..cf02d0920 100644 --- a/BUILD.md +++ b/BUILD.md @@ -32,7 +32,8 @@ For development a typical workflow to set up the development environment is as f 1. Clone the [VSS repository](https://github.com/COVESA/vehicle_signal_specification 2. Get all submodules (`git submodule update --init`) -3. Follow instructions in [VSS-tools](https://github.com/COVESA/vss-tools/blob/master/README.md) to install dependencies +3. Follow instructions in [VSS-tools](https://github.com/COVESA/vss-tools/blob/master/README.md) to prepare an environment suitable for vss-tools (for example a Python virtual environment) +3. Run [scripts/install_vss_tools.sh](https://github.com/COVESA/vehicle_signal_specification/blob/master/scripts/install_vss_tools.sh) to install vss-tools. 4. Verify that your development environment is fully functional by running `make` from your `vehicle_signal_specification` folder. ### Generating artifacts diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a5ef17c3..aa762e740 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,166 @@ It includes changes that are included in released version, but also changes plan *This document only contains changes introduced in VSS 3.0 or later!* +## Planned Changes VSS 6.0 + +### OBD Branch removed + +The `Vehicle.OBD` branch is now removed. If needed there is an OBD overlay in the `overlays` directory. + +## VSS 5.0 + +### Signal Updates + +* Signals deprecated in 4.X versions removed +* Some signals added, but nothing significant compared to 4.2 + +### UUID removed from release artifacts + +VSS Release artifacts (VSS standard catalog in various formats) will no longer contain UUID information. +If you need artifacts with UUID you need to generate the artifact yourself. + +Instructions: + +1. Clone the repo and check out the tag you want, for example `git checkout v5.0`. +2. Update submodules, for example `git submodule update --init`. +3. Add `--uuid` as argument to the relevant command in `Makefile`. +4. Run generation, for example `make csv`. + +### OBD Branch deprecated + +The `Vehicle.OBD` branch is now deprecated. The plan is to remove it in VSS 6.0. +The background is a decision that VSS standard catalog shall not contain a one-to-one representation of the OBD standard. +Instead, VSS standard catalog may contain corresponding information elsewhere. As an example, instead of +`Vehicle.OBD.EngineSpeed` (PID `0C`), the VSS signal `Vehicle.Powertrain.CombustionEngine.Speed` can be used. +Note that not all signals in `Vehicle.OBD` have "duplicates", especially in the area of combustion engine control +(like Oxygen sensor lambda and voltage readings) VSS currently does not have any counterparts in other parts of the tree. + + +What to do if you as of today use signals from the OBD file: + +* Check if any suitable replacement signal exist. + Example: if you use `Vehicle.OBD.Speed`, consider using `Vehicle.Speed` instead. +* If not and the data may be of general interest; consider creating a pull request + with a replacement signal. + Example: VSS as of today only have Lambda information in OBD branch. + If you need VSS signals for Lambda, consider creating new signals in + `Vehicle.Powertrain.CombustionEngine` branch. +* If you really need the signals in this file and cannot replace them, then consider using the overlay file in the + `overlays` directory from VSS 6.0 onwards. + +### Updated tool dependency + +#### CLI updates + +The vss-tools CLI has been refactored. Makefile in this repository updated. + +#### Overlay Support + +VSS-tools support for overlays have been improved. It is now in many cases not necessary to specify +`type` and `datatype` for items in the overlay if you are changing an existing item. + + +## VSS 4.2 + +### New signals + +New signals in the following areas + +* Engine Coolant and Engine Oil +* Wheel Angular Speed +* Screen Mirroring +* Head Position and Eye Gaze +* TimeInUse for electrical motors +* Battery Precondition + +## VSS 4.1 + +### Unit file syntax updated, Quantity file introduced + +A new syntax for unit files is introduced. Old syntax still supported. +It is also possible to define quantity files, and a default quantity file (`quantities.yaml`) +has been added. + +### New signals + +Some signals have been added. + +### Updated tool dependency + +A new version of vss-tools is used, with support for static IDs and jsonschema. + +### Deprecated or Deleted signals + +* `Vehicle.Cabin.Seat.*.*.Heating` deprecated from 4.1. New signal `Vehicle.Cabin.Seat.*.*.HeatingCooling` added. + + +## VSS 4.0 + +### Struct Support (Official) + +The VSS-syntax now supports structs. +Note however that not all exporters in [VSS-tools](https://github.com/COVESA/vss-tools) 4.0 support structs yet. + +### Change of instance handling for seats, doors, mirrors and other branches. + +Previously many signals used position for instance, where position 1 meant the leftmost item. +This caused problems for some use-cases where it was more practical to reference to a door by its relative position, +like the "DriverSide" door, as you then can describe wanted behavior in the same way for both LHD and RHD vehicles. +By that reason instance handling has for some signal been changed to use `["DriverSide","Middle","PassengerSide"]`. + +### Actuator and Sensor Attributes + +The attributes `sensor` and `actuator`, deprecated from VSS 3.1, +have been removed from the [VSS syntax](docs-gen/content/rule_set/data_entry/sensor_actuator.md). + +### Deprecated or Deleted signals + +* `Vehicle.TravelledDistance` +* `Vehicle.Powertrain.FuelSystem.TimeSinceStart` + +## VSS 3.1 + +### Struct Support (Experimental) + +VSS has been extended with syntax to define structs, and to use them for signals. +For VSS 3.1, support is only experimental and syntax may change. + +*Note: Only a subset of VSS-tools for VSS 3.1 supports structs!* + +### Actuator and Sensor Attributes + +VSS has two attributes `sensor` and `actuator` that gives the possibility to specify which system/entity provides the value +or tries to actuate the value. A possible hypothetical example is shown below showing that it is `TemperatureSensorUnderDriverSeat` that +provides the values of `Vehicle.Cabin.Temperature` and it is `HVACSystem` that tries to assure that the specified temperature is achieved. +These two attributes have never been used by signals in the VSS repository and it has been decided that these attributes no longer shall +be part of the official VSS syntax. If needed, this type of information shall be provided by overlays. + +``` +Vehicle.Cabin.Temperature: + type: actuator + description: Temperature in cabin + datatype: float + unit: km/h + sensor: 'TemperatureSensorUnderDriverSeat' + actuator: 'HVACSystem' +``` + +For VSS 3.1 the two attributes will remain in the VSS Syntax, but are marked as deprecated. +No change to tooling is implemented, as the vss-tools already give a warning if the attributes are used: + +``` +Warning: Attribute(s) sensor in element Temperature not a core or known extended attribute. +``` + +### Deprecated or Deleted signals + +* `Vehicle.TravelledDistance` deprecated from 3.1. New signal `Vehicle.TraveledDistance`added. + Background is to be aligned with VSS style guide using American English. +* `Vehicle.Powertrain.FuelSystem.TimeSinceStart` deprecated from 3.1. New signal `Vehicle.StartTime` added. + Reason is that `TimeSinceStart` is not powertrain-related and other signals related to current trip are located on top-level. + After discussion it was agreed that it is better to have a signal for start time rather than duration. +* Refactoring of signals in `Vehicle.Body.Lights` branch performed, some signals have new names. + ## VSS 3.0 [Complete release notes](https://github.com/COVESA/vehicle_signal_specification/releases/tag/v3.0) @@ -103,144 +263,3 @@ Warning: Attribute(s) enum in element Position not a core or known extended attr The signals in `Vehicle.Cabin.Seat` have been significantly refactored. The background is that the old representation included limitations and ambiguities. - -## VSS 3.1 - -### Struct Support (Experimental) - -VSS has been extended with syntax to define structs, and to use them for signals. -For VSS 3.1, support is only experimental and syntax may change. - -*Note: Only a subset of VSS-tools for VSS 3.1 supports structs!* - -### Actuator and Sensor Attributes - -VSS has two attributes `sensor` and `actuator` that gives the possibility to specify which system/entity provides the value -or tries to actuate the value. A possible hypothetical example is shown below showing that it is `TemperatureSensorUnderDriverSeat` that -provides the values of `Vehicle.Cabin.Temperature` and it is `HVACSystem` that tries to assure that the specified temperature is achieved. -These two attributes have never been used by signals in the VSS repository and it has been decided that these attributes no longer shall -be part of the official VSS syntax. If needed, this type of information shall be provided by overlays. - -``` -Vehicle.Cabin.Temperature: - type: actuator - description: Temperature in cabin - datatype: float - unit: km/h - sensor: 'TemperatureSensorUnderDriverSeat' - actuator: 'HVACSystem' -``` - -For VSS 3.1 the two attributes will remain in the VSS Syntax, but are marked as deprecated. -No change to tooling is implemented, as the vss-tools already give a warning if the attributes are used: - -``` -Warning: Attribute(s) sensor in element Temperature not a core or known extended attribute. -``` - -### Deprecated or Deleted signals - -* `Vehicle.TravelledDistance` deprecated from 3.1. New signal `Vehicle.TraveledDistance`added. - Background is to be aligned with VSS style guide using American English. -* `Vehicle.Powertrain.FuelSystem.TimeSinceStart` deprecated from 3.1. New signal `Vehicle.StartTime` added. - Reason is that `TimeSinceStart` is not powertrain-related and other signals related to current trip are located on top-level. - After discussion it was agreed that it is better to have a signal for start time rather than duration. -* Refactoring of signals in `Vehicle.Body.Lights` branch performed, some signals have new names. - -## VSS 4.0 - -### Struct Support (Official) - -The VSS-syntax now supports structs. -Note however that not all exporters in [VSS-tools](https://github.com/COVESA/vss-tools) 4.0 support structs yet. - -### Change of instance handling for seats, doors, mirrors and other branches. - -Previously many signals used position for instance, where position 1 meant the leftmost item. -This caused problems for some use-cases where it was more practical to reference to a door by its relative position, -like the "DriverSide" door, as you then can describe wanted behavior in the same way for both LHD and RHD vehicles. -By that reason instance handling has for some signal been changed to use `["DriverSide","Middle","PassengerSide"]`. - -### Actuator and Sensor Attributes - -The attributes `sensor` and `actuator`, deprecated from VSS 3.1, -have been removed from the [VSS syntax](docs-gen/content/rule_set/data_entry/sensor_actuator.md). - -### Deprecated or Deleted signals - -* `Vehicle.TravelledDistance` -* `Vehicle.Powertrain.FuelSystem.TimeSinceStart` - - -## VSS 4.1 (Latest Release) - -### Unit file syntax updated, Quantity file introduced - -A new syntax for unit files is introduced. Old syntax still supported. -It is also possible to define quantity files, and a default quantity file (`quantities.yaml`) -has been added. - -### New signals - -Some signals have been added. - -### Updated tool dependency - -A new version of vss-tools is used, with support for static IDs and jsonschema. - -### Deprecated or Deleted signals - -* `Vehicle.Cabin.Seat.*.*.Heating` deprecated from 4.1. New signal `Vehicle.Cabin.Seat.*.*.HeatingCooling` added. - -## Planned Changes VSS 5.0 - -### UUID removed from release artifacts - -VSS Release artifacts (VSS standard catalog in various formats) will no longer contain UUID information. -If you need artifacts with UUID you need to generate the artifact yourself. - -Instructions: - -1. Clone the repo and check out the tag you want, for example `git checkout v5.0`. -2. Update submodules, for example `git submodule update --init`. -3. Add `--uuid` as argument to the relevant command in `Makefile`. -4. Run generation, for example `make csv`. - -### OBD Branch deprecated - -The `Vehicle.OBD` branch is now deprecated. The plan is to remove it in VSS 6.0. -The background is a decision that VSS standard catalog shall not contain a one-to-one representation of the OBD standard. -Instead, VSS standard catalog may contain corresponding information elsewhere. As an example, instead of -`Vehicle.OBD.EngineSpeed` (PID `0C`), the VSS signal `Vehicle.Powertrain.CombustionEngine.Speed` can be used. -Note that not all signals in `Vehicle.OBD` have "duplicates", especially in the area of combustion engine control -(like Oxygen sensor lambda and voltage readings) VSS currently does not have any counterparts in other parts of the tree. - - -What to do if you as of today use signals from the OBD file: - -* Check if any suitable replacement signal exist. - Example: if you use `Vehicle.OBD.Speed`, consider using `Vehicle.Speed` instead. -* If not and the data may be of general interest; consider creating a pull request - with a replacement signal. - Example: VSS as of today only have Lambda information in OBD branch. - If you need VSS signals for Lambda, consider creating new signals in - `Vehicle.Powertrain.CombustionEngine` branch. -* If you really need the signals in this file and cannot replace them, then consider using the overlay file in the - `overlays` directory from VSS 6.0 onwards. - -### Updated tool dependency - -#### CLI updates - -The vss-tools CLI has been refactored. Makefile in this repository updated. - -#### Overlay Support - -VSS-tools support for overlays have been improved. It is now in many cases not necessary to specify -`type` and `datatype` for items in the overlay if you are changing an existing item. - -## Planned Changes VSS 6.0 - -### OBD Branch removed - -The `Vehicle.OBD` branch is now removed. If needed there is an OBD overlay in the `overlays` directory. diff --git a/README.md b/README.md index 5eea901ee..c0740df54 100644 --- a/README.md +++ b/README.md @@ -32,16 +32,14 @@ For detailed information see our [contribution guide](CONTRIBUTING.md)! ### VSS version and release handling Both VSS (this repository) and [VSS-tools](https://github.com/COVESA/vss-tools) use a [PEP](https://peps.python.org/pep-0440/) -inspired version scheme. Artifacts generated by the [Makefile](Makefile) gets version from the file [VERSION](VERSION) -resulting in artifact names of the form `vss_rel_.` where `` typically is `X.Y` or `X.Y.Z` -for released versions and `X.Y-dev` for ongoing work in master-branch towards version `X.Y`. +inspired version scheme. -Version is also visible in the [Vehicle.vspec](spec/Vehicle/Vehicle.vspec) file where `VersionVSS.Label` typically is +Version is visible in the [Vehicle.vspec](spec/Vehicle/Vehicle.vspec) file where `VersionVSS.Label` typically is `-dev` for ongoing work in master-branch and an empty string for released versions. Versions are tagged in the form `vX.Y(.Z)` and the same syntax is used as names for VSS releases. VSS-tools is tagged but not released. -For release candidates the form `vX.YrcN` is used. The `rcN` suffix is not used in [VERSION](VERSION) and +For release candidates the form `vX.YrcN` is used. The `rcN` suffix is not used in [Vehicle.vspec](spec/Vehicle/Vehicle.vspec) files. For more information on how versions are managed see the [Release Instruction](https://github.com/COVESA/vehicle_signal_specification/wiki/Release-Instructions-and-Checklist) diff --git a/docs-gen/layouts/partials/menu-footer.html b/docs-gen/layouts/partials/menu-footer.html index 3dfd64b5d..c8c495a97 100644 --- a/docs-gen/layouts/partials/menu-footer.html +++ b/docs-gen/layouts/partials/menu-footer.html @@ -8,7 +8,7 @@ Fork - Latest Released Version: 4.0 + Latest Released Version: 5.0 diff --git a/scripts/install_vss_tools.sh b/scripts/install_vss_tools.sh index 4d62bcbb7..f67c4b991 100755 --- a/scripts/install_vss_tools.sh +++ b/scripts/install_vss_tools.sh @@ -11,7 +11,7 @@ # ************ MASTER *************'' # For master (ongoing development) we typically rely on latest master of vss-tools # -pip install git+https://github.com/COVESA/vss-tools@master +# pip install git+https://github.com/COVESA/vss-tools@master # Examples for other scenarios below # @@ -26,7 +26,7 @@ pip install git+https://github.com/COVESA/vss-tools@master # Either a released version or a pre-release, referenced with "--pre" # See https://pypi.org/project/vss-tools/ # -# pip install --pre vss-tools==5.0.0.dev0 +pip install --pre vss-tools==5.0rc0 # # # *********************** RELEASES *************************** diff --git a/spec/Vehicle/Vehicle.vspec b/spec/Vehicle/Vehicle.vspec index 8656a0889..3b52e5955 100644 --- a/spec/Vehicle/Vehicle.vspec +++ b/spec/Vehicle/Vehicle.vspec @@ -39,7 +39,7 @@ VersionVSS.Patch: VersionVSS.Label: datatype: string type: attribute - default: 'dev' + default: '' description: Label to further describe the version. comment: COVESA VSS project typically use dev for latest master, and empty string for released versions.