diff --git a/.github/workflows/buildcheck.yml b/.github/workflows/buildcheck.yml index f7780246a..2c0cd7567 100644 --- a/.github/workflows/buildcheck.yml +++ b/.github/workflows/buildcheck.yml @@ -25,13 +25,9 @@ jobs: python -V python -m pip --quiet --no-input install --upgrade pip python -m pip --quiet --no-input install --upgrade pipenv wheel - pipenv --version - pipenv run python --version cd vss-tools - pipenv install - echo done! - pipenv run python setup.py install + pipenv run python setup.py -q install env: PIPENV_VENV_IN_PROJECT: 1 @@ -53,10 +49,10 @@ jobs: - name: Install hugo env: - HUGO_VER : 0.103.1 + HUGO_VER : 0.78.1 run: | - curl -LO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VER}/hugo_${HUGO_VER}_linux-amd64.deb - sudo dpkg -i hugo_${HUGO_VER}_linux-amd64.deb + curl -LO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VER}/hugo_${HUGO_VER}_Linux-64bit.deb + sudo dpkg -i hugo_${HUGO_VER}_Linux-64bit.deb - name: Make docs run: | diff --git a/.gitignore b/.gitignore index deaba9f6c..217986060 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,10 @@ *.id # Generated files -vss_rel_* +vss_rel_*.cnative +vss_rel_*.csv +vss_rel_*.fidl +vss_rel_*.binary +vss_rel_*.h +vss_rel_*.json +vss_rel_*_macro.h diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 679f197f7..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,158 +0,0 @@ -# VSS Changelog - -The intention of this document is to highlight major changes in the VSS specification (syntax and/or signals). -It shall include all changes that affect backward compatibility or may be important to know when upgrading from one version to another. -It includes changes that are included in released version, but also changes planned for upcoming releases. - -*This document only contains changes introduced in VSS 3.0 or later!* - - - -## VSS 3.0 (Latest Release) - -[Complete release notes](https://github.com/COVESA/vehicle_signal_specification/releases/tag/v3.0) - -### Instantiate - -A new attribute `instantiate` has been added to the syntax to exclude a child-node from the instantiation of the *direct* parent node. -This attribute is by default true and is only relevant to use for signals - -An example on how this signals shall be handled by tools: - -```YAML -Vehicle.X: - type: branch - instances: Test[1,2] - description: High-level vehicle data. - -Vehicle.X.InstantiatedSignal: - type: attribute - description: "Instantiated Signal" - datatype: string - -Vehicle.X.NotInstantiatedSignal: - type: attribute - description: "Not Instantiated Signal" - datatype: string - instantiate: False -``` - -Results in the following dot-notated output: - -``` -Vehicle.X -Vehicle.X.NotInstantiatedSignal -Vehicle.X.Test1.NotInstantiatedSignal -Vehicle.X.Test2.NotInstantiatedSignal -``` -The new attribute is not used for any signals in VSS 3.0. -For more information see [documentation](https://github.com/COVESA/vehicle_signal_specification/blob/master/docs-gen/content/rule_set/instances.md). - -### Changed Path to Battery Signals - -The path `Vehicle.Powertrain.Battery` was renamed to `Vehicle.Powertrain.TractionBattery`. -The path name was changed to make it clear that the signals in the path concerns the traction battery (high voltage battery) used by electrical or hybrid vehicles, -and not the supply battery (low voltage battery, typically 12 or 24 Volts). - -### Enum/Allowed attribute - -Before VSS 3.0 the attribute `enum` could be used to list allowed values for a VSS signals, like in the example below: - -``` -LowVoltageSystemState: - datatype: string - type: sensor - enum: [ - "UNDEFINED", # State of low voltage system not known - "LOCK", # Low voltage system off, steering lock or equivalent engaged - "OFF", # Low voltage system off, steering lock or equivalent not engaged - "ACC", # Vehicle Accessories on/living - "ON", # Engine start enabled (e.g. ignition on, diesel pre-heating, electrical drive released) - "START" # Engine starter relay closed (not applicable for electrical vehicles) - ] - description: State of the supply voltage of the control units (usually 12V). -``` - -From VSS 3.0 this attribute has been renamed to `allowed`. The background is that the old name was misleading, -as it does not correspond to enum definitions in many programming languages, but rather just is a limitation of what values -that are supported by the signal. - - -All signals in VSS previously using `enum`has been updated to use `allowed`, like in the example below: - -``` -LowVoltageSystemState: - datatype: string - type: sensor - allowed: [ - 'UNDEFINED', # State of low voltage system not known - 'LOCK', # Low voltage system off, steering lock or equivalent engaged - 'OFF', # Low voltage system off, steering lock or equivalent not engaged - 'ACC', # Vehicle Accessories on/living - 'ON', # Engine start enabled (e.g. ignition on, diesel pre-heating, electrical drive released) - 'START' # Engine starter relay closed (not applicable for electrical vehicles) - ] - description: State of the supply voltage of the control units (usually 12V). -``` - -If the old keyword `enum` is used most tools will ignore it and give a warning. - -``` -Warning: Attribute(s) enum in element Position not a core or known extended attribute. -``` - -### Seat signals - -The signals in `Vehicle.Cabin.Seat` have been significantly refactored. -The background is that the old representation included limitations and ambiguities. - -## Planned Changes VSS 3.1 - -### Actuator and Sensor Attributes - -VSS has two attributes `sensor` and `actuator` that gives the possibility to specify which system/entity that 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 today 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. - -## Planned Changes VSS 4.0 - -### Actuator and Sensor Attributes - -The attributes `sensor` and `actuator`, deprecated from VSS 3.1, will be removed from the [VSS syntax](docs-gen/content/rule_set/data_entry/sensor_actuator.md). - - -### Deprecated or Deleted signals - -* `Vehicle.TravelledDistance` ,deprecated from VSS 3.1, will be removed. -* `Vehicle.Powertrain.FuelSystem.TimeSinceStart` ,deprecated from VSS 3.1, will be removed. - -## Planned Changes VSS 5.0 - -- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 790f9fee7..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,110 +0,0 @@ -# Introduction to VSS Contribution Process - -The COVESA VSS project has public two GitHub repositories - -- [Vehicle Signal Specification (VSS)](https://github.com/COVESA/vehicle_signal_specification), containing signal specifications and documentation. -- [VSS Tools](https://github.com/COVESA/vss-tools), containing tools for validating and transforming VSS specifications. - -The examples below refer to the VSS repository, but the process is similar for the VSS-Tools repository. - -There are two main methods to propose changes or extensions to VSS: - -- If you have an idea or a question you can create an [issue](https://github.com/COVESA/vehicle_signal_specification/issues) in GitHub. -- If you already have prepared changes or extension that you think would be interesting for COVESA to include in VSS - then you can create a [Pull Request (PR)](https://github.com/COVESA/vehicle_signal_specification/pulls). - -All contributions must follow the [COVESA contribution guidelines](https://www.covesa.global/contribute). - -The VSS project has regular meetings at Tuesdays 16.00 CET (see [COVESA VSS Wiki](https://wiki.covesa.global/display/WIK4/VSS+-+Vehicle+Signal+Specification)). -In the meetings Pull Requests and Issues are discussed, and if a Pull Request is acceptable the meeting will decide that it shall be merged. -Everyone interested is welcome to join the meetings. - -## Creating a Pull Request towards VSS - -This is the typical workflow for preparing a pull request. A Github account is required. - -1. Create a personal or company fork of the [VSS repository](https://github.com/COVESA/vehicle_signal_specification) - and/or [VSS-Tools repository](https://github.com/COVESA/vss-tools). -2. Clone the forked repository into your local development environment. -3. Create a local branch based on the VSS master branch to use for the proposed changes. -4. Introduce the wanted changes or extensions in your local development environment, see guidelines below. - If you want change/extend VSS-signals, it is the *.vspec files in the [spec](https://github.com/COVESA/vehicle_signal_specification/tree/master/spec) folder that - needs to be updated. -5. Run "make travis_targets" to verify that the changes are syntactically correct and does not introduce any side effects. - This will verify that tools and test-cases in vss-tools repository accepts the changes. -6. Create a commit and upload to your own fork. -7. In the GitHub UI create a Pull Request from your fork to the master branch of [the VSS repository](https://github.com/COVESA/vehicle_signal_specification). -8. Validate that automatic build checks for the PR succeed. - -## Handling of the created Pull Request - -1. The PR creator shall follow up on any comments or questions received on the Pull Request. -2. The PR will be discussed at one of the next VSS weekly meetings. - It is preferable if the PR creator can participate and give a quick introduction on the rationale for the change. -3. Unless trivial, PRs shall typically be open for at least a week before merging is considered, to give time for comments. -4. If needed, the PR creator needs to refactor the PR to address received comments and remarks. -4. After a while, if all comments and concerns have been sorted out and no-one objects merging the PR the meeting will decide to merge the PR. - It is not guaranteed that all PRs will be accepted. The VSS meeting may reject and close Pull Requests. -5. A VSS maintainer will perform the merge. - -## Guidelines and Recommendations - -This section includes general guidelines and recommendations for anyone interested in contributing to VSS. - -### VSS Signals shall be generic - -Signals added to standard VSS shall be generic, i.e. it shall be possible that other manufacturers can reuse the signal. -Manufacturer-specific signals shall preferably be part of private overlays, and not part of standard VSS. - -### Logical path - -VSS aims to put all signals in a logical path based on physical topology of the vehicle. -As an example, signals related to wheels should typically reside under `Vehicle.Chassis.Axle`. -When proposing a new signal, reuse an existing path if a relevant path exists. - -### Consider adding a new file if adding a large number of signals - -VSS has no strict rules that every branch must have its own file, -but if a file becomes too big you can consider splitting it if feasible. - -### Signals shall have a clear definition without ambiguities - -It shall be possible to interpret a signal value by reading the signal description. -Describe if needed how the value shall be calculated/interpreted, -for example if it is based on a standard or if it is up to the manufacturer to select algorithm/method. - -* Example: A signal Vehicle.Weight would be ambiguous unless you specify that it refers to e.g. gross weight or curb weight. -* Example: Specifying an allowed value `MODE_2` is ambiguous unless you also specify what `MODE_2` means, e.g. by referring to a standard. - -### No duplicates - -VSS generally avoids to have duplicates in the signal tree, i.e. signals with same purpose and description in different part of the tree. - -### Use existing style - -Try to reuse the same style as used for existing signals. -Only specify min/max-values if there is a logical reason to limit the range. -Boolean signals should start with `Is*`. -American English is preferred over British English. -Follow the style guide in the [documentation](https://covesa.github.io/vehicle_signal_specification/rule_set/basics/#style-guide). - -### No scaling, SI-unit, natural datatype - -VSS is not concerned with how signals are transmitted, and does not consider scaling/offset typically used in transport protocols. -VSS signals typically use the unit used by humans when talking about the value, but prefers SI-units when feasible, -see [documentation](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/data_unit_types/) for all supported units. -If it is unlikely that someone is interested in decimals for this value, select a signed or unsigned integer type. -Select a size which with reasonable margins can cover all vehicles. -If it is likely that decimal values are needed select float or if relevant double. - -### Avoid backward incompatible changes - -VSS sometimes change or remove existing signals, but only if there is a good reason. -Merging can be delayed, as VSS may decide to wait with the change until the next major release is prepared. - -### Getting Support - -To avoid time consuming refactoring it could for bigger contributions be relevant to ask VSS if the wanted changes -seems to be reasonable and likely will be accepted by VSS. Create an [issue](https://github.com/COVESA/vehicle_signal_specification/issues) -and describe what you intend to do and ask for feedback. You can also create a draft pull request at an early stage and ask for comments. - diff --git a/Makefile b/Makefile index 71ef692f3..eef500312 100644 --- a/Makefile +++ b/Makefile @@ -2,13 +2,13 @@ # Makefile to generate specifications # -.PHONY: clean all travis_targets json franca yaml csv ddsidl tests binary protobuf ttl graphql ocf c install overlays +.PHONY: clean all travis_targets json franca yaml csv ddsidl tests binary protobuf ttl graphql ocf c install deploy -all: clean json franca yaml csv ddsidl binary tests protobuf graphql overlays ttl +all: clean json franca yaml csv ddsidl binary tests protobuf graphql # All mandatory targets that shall be built and pass on each pull request for # vehicle-signal-specification or vss-tools -travis_targets: clean json franca yaml binary csv graphql ddsidl overlays tests tar +travis_targets: clean json franca yaml binary csv graphql ddsidl tests deploy # Additional targets that shall be built by travis, but where it is not mandatory @@ -17,60 +17,67 @@ travis_targets: clean json franca yaml binary csv graphql ddsidl overlays tests # from time to time # Can be run from e.g. travis with "make -k travis_optional || true" to continue # even if errors occur and not do not halt travis build if errors occur -travis_optional: clean protobuf ttl +travis_optional: clean c ocf protobuf ttl DESTDIR?=/usr/local TOOLSDIR?=./vss-tools +DEPLOYDIR?=./docs-gen/static/releases/nightly + json: - ${TOOLSDIR}/vspec2json.py -I ./spec --uuid -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).json + ${TOOLSDIR}/vspec2json.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).json franca: - ${TOOLSDIR}/vspec2franca.py -v $$(cat VERSION) -I ./spec --uuid -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).fidl + ${TOOLSDIR}/vspec2franca.py -v $$(cat VERSION) -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).fidl yaml: - ${TOOLSDIR}/vspec2yaml.py -I ./spec --uuid -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).yaml + ${TOOLSDIR}/vspec2yaml.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).yaml csv: - ${TOOLSDIR}/vspec2csv.py -I ./spec --uuid -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).csv + ${TOOLSDIR}/vspec2csv.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).csv ddsidl: - ${TOOLSDIR}/vspec2ddsidl.py -I ./spec --uuid -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).idl - -# Verifies that supported overlay combinations are syntactically correct. -overlays: - ${TOOLSDIR}/vspec2json.py -I ./spec --uuid -u ./spec/units.yaml -o overlays/profiles/motorbike.vspec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION)_motorbike.json - ${TOOLSDIR}/vspec2json.py -I ./spec --uuid -u ./spec/units.yaml -o overlays/extensions/dual_wiper_systems.vspec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION)_dualwiper.json + ${TOOLSDIR}/vspec2ddsidl.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).idl tests: PYTHONPATH=${TOOLSDIR} pytest binary: gcc -shared -o ${TOOLSDIR}/binary/binarytool.so -fPIC ${TOOLSDIR}/binary/binarytool.c - ${TOOLSDIR}/vspec2binary.py --uuid -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).binary + ${TOOLSDIR}/vspec2binary.py ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).binary protobuf: - ${TOOLSDIR}/contrib/vspec2protobuf.py -I ./spec -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).proto + ${TOOLSDIR}/contrib/vspec2protobuf.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).proto graphql: - ${TOOLSDIR}/vspec2graphql.py -I ./spec --uuid -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).graphql.ts + ${TOOLSDIR}/vspec2graphql.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).graphql.ts + +ocf: + ${TOOLSDIR}/contrib/ocf/vspec2ocf.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).ocf.json ttl: - ${TOOLSDIR}/contrib/vspec2ttl/vspec2ttl.py -I ./spec -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).ttl + ${TOOLSDIR}/contrib/vspec2ttl/vspec2ttl.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).ttl -# Include all offically supported outputs (i.e. those created by travis_targets). -# Exception is binary as it might be target specific and library anyway needs to be rebuilt. -# As of today all artifacts generated for release shall include UUID if supported. -tar: - tar -czvf vss_rel_$$(cat VERSION).tar.gz vss_rel_$$(cat VERSION).json vss_rel_$$(cat VERSION).fidl vss_rel_$$(cat VERSION).yaml \ - vss_rel_$$(cat VERSION).csv vss_rel_$$(cat VERSION).graphql.ts vss_rel_$$(cat VERSION).idl +c: + (cd ${TOOLSDIR}/contrib/vspec2c/; make ) + PYTHONPATH=${TOOLSDIR} ${TOOLSDIR}/contrib/vspec2c.py -I ./spec ./spec/VehicleSignalSpecification.vspec vss_rel_$$(cat VERSION).h vss_rel_$$(cat VERSION)_macro.h clean: rm -f vss_rel_* + (cd ${TOOLSDIR}/contrib/vspec2c/; make clean) install: git submodule init git submodule update (cd ${TOOLSDIR}/; python3 setup.py install --install-scripts=${DESTDIR}/bin) + $(MAKE) DESTDIR=${DESTDIR} -C ${TOOLSDIR}/vspec2c install install -d ${DESTDIR}/share/vss (cd spec; cp -r * ${DESTDIR}/share/vss) + +deploy: + if [ -d $(DEPLOYDIR) ]; then \ + rm -f ${DEPLOYDIR}/vss_rel_*;\ + else \ + mkdir -p ${DEPLOYDIR}; \ + fi; + cp vss_rel_* ${DEPLOYDIR}/ diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 61fe81528..1afdf1542 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -26,9 +26,6 @@ Each release is incrementally numbered, starting with 1. A release is tagged in git with the tag - v[m.n] + v[n] -where [m.n] is the release number. - -Detailed instructions on how releases are created can be found in the -[Release Instructions and Checklist](https://github.com/COVESA/vehicle_signal_specification/wiki/Release-Instructions-and-Checklist). +where [n] is the release number. diff --git a/VERSION b/VERSION index cc6a6fc03..89d4a3cf7 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -3.1-develop +3.0-develop diff --git a/docs-gen/README.md b/docs-gen/README.md index 1815250d4..0c17c99ca 100644 --- a/docs-gen/README.md +++ b/docs-gen/README.md @@ -13,9 +13,8 @@ The static page is generated with: - [HUGO](https://gohugo.io/) - [Learn Theme](https://themes.gohugo.io/hugo-theme-learn/) -Please follow the [documentation](https://gohugo.io/documentation/) for installation and further questions around the framework. -Currently, the HUGO version used for generating VSS documentation is `0.103.1`, -as controlled by the [buildcheck.yml](https://github.com/COVESA/vehicle_signal_specification/blob/master/.github/workflows/buildcheck.yml) +Please follow the [documentation](https://gohugo.io/documentation/) for +installation and further questions around the framework. Currently, the minimal tested HUGO version for the VSS documentation is `0.78.1` ### Run the documentation server locally @@ -50,7 +49,8 @@ page under http://localhost:1313/vehicle_signal_specification. ### Contribute -If you want to contribute, do the following: +Right now there is no pipeline in place to build the documentation. If you want +to contribute, do the following: 1. **Change documentation in ```/docs-gen```** diff --git a/docs-gen/config.toml b/docs-gen/config.toml index ac9bbcde8..630c2f89e 100644 --- a/docs-gen/config.toml +++ b/docs-gen/config.toml @@ -5,7 +5,7 @@ theme = "learn" publishDir = "../docs" [params] # Change default color scheme with a variant one. Can be "red", "blue", "green". - themeVariant = "blue" + themeVariant = "green" disableInlineCopyToClipBoard = true editURL = "https://github.com/covesa/vehicle_signal_specification/edit/master/docs-gen/content/" disableLandingPageButton = true @@ -21,7 +21,3 @@ weight = 10 name = " Releases" url = "https://github.com/covesa/vehicle_signal_specification/releases" weight = 12 - -# Generation of JSON index to allow search -[outputs] -home = [ "HTML", "RSS", "JSON"] diff --git a/docs-gen/content/_index.md b/docs-gen/content/_index.md index 3463b989d..9aad85ed6 100644 --- a/docs-gen/content/_index.md +++ b/docs-gen/content/_index.md @@ -3,17 +3,13 @@ title: "Vehicle Signal Specification" --- # Vehicle Signal Specification -The Vehicle Signal Specification (VSS) is an initiative by [COVESA](https://www.covesa.global/) to define a syntax and a catalog for vehicle signals. -The source code and releases can be found in the [VSS github repository](https://github.com/COVESA/vehicle_signal_specification). -Some tools for parsing and converting VSS files can be found in the [VSS-tools github repository](https://github.com/COVESA/vss-tools). - -This documentation gives you an overview of VSS: +This documentation gives you an overview of the current ```Vehicle Signal +Specification```: * [Introduction](/vehicle_signal_specification/introduction)
Read this part if you want to know more about what the specification is all about, what's in and out and how to quickly browse through the current status. -* [Governance](/vehicle_signal_specification/governance)
Introduction to VSS governance model and change log. * [Rule Set](/vehicle_signal_specification/rule_set)
Get familiar with the rule set behind the -specification, the structure, the format and concepts. -* [License](/vehicle_signal_specification/license)
Information on the VSS license. +specification, the structure, the format and concepts. Basic knowledge needed +to write first extensions. * [Ecosystem](/vehicle_signal_specification/ecosystem) How to use the specification? Check out the existing tools and standards to transform or make use of VSS. \ No newline at end of file diff --git a/docs-gen/content/governance/_index.md b/docs-gen/content/governance/_index.md deleted file mode 100644 index 6aafe217d..000000000 --- a/docs-gen/content/governance/_index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Governance -weight: 15 -chapter: false ---- - -# Governance - -The Vehicle Signal Specification (VSS) project is an initiative by [COVESA](https://www.covesa.global/) to define a syntax and a catalog for vehicle signals. - -The artifacts maintained by the VSS project consist of: - -* Source code, documentation and releases in the [VSS github repository](https://github.com/COVESA/vehicle_signal_specification). -* Tools for parsing and converting VSS files in the [VSS-tools github repository](https://github.com/COVESA/vss-tools). - -The VSS project has an informal structure with a chair and github maintainers appointed by COVESA. -Tasks for the chair includes hosting regular meeting to discuss incoming pull requests and issues, as well as roadmap and release planning. - -## Contribution process - -Anyone may propose changes to VSS. It is up to the VSS project to decide if the changes are feasible to include in VSS. -The VSS project does not have any developers or maintainers paid by COVESA. -Instead, the VSS project relies on voluntary contributions, typically from member organizations. -The maintainers are expected to review incoming pull requests. -All contributions must follow the [COVESA contribution guidelines](https://www.covesa.global/contribute). - -In general, pull requests shall be opened for at least a week before being merged to give time for COVESA members to review the pull request and provide comments. -In case of larger changes or changes that affect backward compatibility pull requests are typically opened for a longer period, to allow for a through review. -Pull requests, unless trivial, are typically merged first after a decision at one of the regular VSS meetings, see link at [COVESA VSS wiki page](https://wiki.covesa.global/display/WIK4/VSS+-+Vehicle+Signal+Specification). -These rules concerns primarily normative content (see below), non-normative content may be updated without thorough reviews. - -For more information and guides on how to contribute see [CONTRIBUTING.md](https://github.com/COVESA/vehicle_signal_specification/blob/master/CONTRIBUTING.md). - -## Branches - -VSS development is typically developed in the master branch only. -Each release is tagged and a maintenance branch is created (e.g. `release/3.0`) which could be used as target for pull requests intending to patch a release. - -## Normative vs. non-normative content - -The VSS repositories contain some artifacts that can be considered normative, i.e. an implementation claiming to "support" VSS shall: - -* Support signals defined according to the rules in the VSS documentation - ([source](https://github.com/COVESA/vehicle_signal_specification/tree/master/docs-gen), [generated](https://covesa.github.io/vehicle_signal_specification/)) -* Support the signals currently defined in VSS. - * The signals in source format (*.vspec files) can be found in [Github repository](https://github.com/COVESA/vehicle_signal_specification/tree/master/spec). - * Derived formats supported by VSS project are included in each [release](https://github.com/COVESA/vehicle_signal_specification/releases), - originating from the tools in the [VSS-tools github repository](https://github.com/COVESA/vss-tools). - -In addition to this the VSS repositores contain artifacts that currently are considered non-normative. This includes immature concepts and work-in progress. Non-normative content include: - -* [VSS Github Wiki](https://github.com/COVESA/vehicle_signal_specification/wiki) -* [VSS Tools Wiki](https://github.com/COVESA/vss-tools/wiki) -* [Overlays and Profiles](https://github.com/COVESA/vehicle_signal_specification/tree/master/overlays) -* [Contributed tools](https://github.com/COVESA/vss-tools/tree/master/contrib) - -The list of what is considered normative and non-normative is no static, it may change over time. - -## Handling of backward compatibility - -The VSS project aims to keep backward compatibility as far as feasible. -VSS is however an evolving syntax and catalog and there are still areas where changes are need to fit the need of users. -Changes that breaks backward compatibility are typically introduced only in major releases (e.g. `X.0`) and shall be documented in release notes. -This concerns changes to syntax and signals, but also to tools. - -The VSS project has introduced a [deprecation concept](../rule_set/basics.md#deprecation-since-version-21). -If possible, when e.g. renaming or moving a signal or changing tools the old signal or parameter set shall be kept but marked as deprecated. -That allows the change to be introduced in a minor version (e.g. `X.Y`). The old signal shall be removed first in the next major release, or later if needed. - -A history of past changes and planned changes that affects backward compatibility can be found in the [Changelog](https://github.com/COVESA/vehicle_signal_specification/blob/master/CHANGELOG.md). - -## Release Process - -The release process is further described in the [Github repository](https://github.com/COVESA/vehicle_signal_specification/blob/master/RELEASE_PROCESS.md). - diff --git a/docs-gen/content/introduction/_index.md b/docs-gen/content/introduction/_index.md index c962663c1..01757c68e 100644 --- a/docs-gen/content/introduction/_index.md +++ b/docs-gen/content/introduction/_index.md @@ -6,4 +6,4 @@ chapter: true # Introduction -Discover what the Vehicle Signal Specification is all about. +Discover what the Vehicle Signal Specification is all about. diff --git a/docs-gen/content/introduction/overview.md b/docs-gen/content/introduction/overview.md index 75375f974..e3df5aa89 100644 --- a/docs-gen/content/introduction/overview.md +++ b/docs-gen/content/introduction/overview.md @@ -7,11 +7,6 @@ chapter: false ## What is VSS? The Vehicle Signal Specification introduces a domain taxonomy for vehicle signals. -In short this means that VSS introduces: - -* A syntax for defining vehicle signals in a structured manner. -* A catalog of signals related to vehicles. - It can be used as standard in automotive applications to communicate information around the vehicle, which is semantically well defined. It focuses on vehicle signals, in the sense of classical attributes, sensors and actuators with the raw data @@ -22,18 +17,18 @@ A standardized vehicle data specification allows an industry actor to use a common naming space for communication and, ultimately, abstracts underlying vehicle implementation details. -While the data in the VSS standard catalog aims to be vendor-independent, -vendor specific extensions and adaptations complying with the VSS syntax rules can be specified -(see [Overlays](../rule_set/overlay.md). +The representation of vehicle data specifications is vendor independent. +Vendor-specific extensions can be specified in a dedicated and uncontrolled +branch of the specification tree. -### What's in -* Standardized data definition for vehicle signals. -* Same semantic understanding across different domains. -* Basic definition for interfaces working on vehicle data (w3c, etc.). +#### What's in +* Standardized data definition for vehicle signals +* Same semantic understanding across different domains +* Basic definition for interfaces working on vehicle data (w3c, etc.) -### What's out -* Everything outside the vehicle signal domain (customer, weather, etc.). -* Concrete interface definition. +#### What's out +* Everything outside the vehicle signal domain (customer, weather, etc.) +* Concrete interface definition ## Example The figure below shows an example snapshot of a generated tree of the @@ -41,10 +36,3 @@ specification. The leafs contain the actual information as shown in the figure. Before going into detail of the specification, let's dig deeper into taxonomies. ![Example tree](/vehicle_signal_specification/images/tree.png?classes=shadow&width=60pc) - -## VSS usage for other domains - -The VSS catalog focuses on signals related to vehicles. -It is not the intention of the VSS project to add signals for other domains. -The syntax used for defining VSS signals and related tooling could however be used to define similar signal trees -for other domains. diff --git a/docs-gen/content/license/_index.md b/docs-gen/content/license/_index.md index 1094a21c8..ddeb3aad1 100644 --- a/docs-gen/content/license/_index.md +++ b/docs-gen/content/license/_index.md @@ -22,11 +22,11 @@ If you use the code internally within your organisation (company), you have no o In any case we _do_ recommend you to consider sharing generally useful improvements with the community. Not only will you win karma points with the community and gain visibility as an innovation leader in the automotive industry, you will most likely also get more robust software as you will have more users and testers. -## I changed VSS or added custom signals to the standard catalog. Do I need to give them away? -No. One important selling point of VSS is, that you can always extend the standard catalog with your own use case specific signals. There is no obligation to release any added signals or proprietary information to third parties. +## I changed VSS or added custom signals to the standard catalogue. Do I need to give them away? +No. One important selling point of VSS is, that you can always extend the standard catalogue with your own use case specific signals. There is no obligation to release any added signals or proprietary information to third parties. -From an MPL-2.0 point of view the information of the previous question applies. To be extra sure, put any additions in separate files, and use the layering approach to modify the standard catalog. This community does not consider deleting elements from the standard catalog or adding VSS `#include` statements "modifications" in the sense of clause 1.10 of the MPL-2.0. +From an MPL-2.0 point of view the information of the previous question applies. To be extra sure, put any additions in separate files, and use the layering approach to modify the standard catalogue. This community does not consider deleting elements from the standard catalogue or adding VSS `#include` statements "modifications" in the sense of clause 1.10 of the MPL-2.0. -As with the tools, we _do_ recommend you to consider sharing generally useful standard catalog improvements with the community. +As with the tools, we _do_ recommend you to consider sharing generally useful standard catalogue improvements with the community. diff --git a/docs-gen/content/rule_set/_index.md b/docs-gen/content/rule_set/_index.md index 3487fae70..f5b5243ed 100644 --- a/docs-gen/content/rule_set/_index.md +++ b/docs-gen/content/rule_set/_index.md @@ -8,18 +8,4 @@ chapter: true The `Rule Set` of a [domain taxonomy](/vehicle_signal_specification/introduction/taxonomy/) is used to describe how to write the data definition syntactically. -This chapter defines and describes the rule set for VSS. -Tools in the [vss-tools repository](https://github.com/COVESA/vss-tools) can be used to validate that a specification follows the rule set for VSS, -but those tools may have limitations and may not check all rules stated in this document. -In case of conflict, what is stated in the rule set in this documentation is considered to have precedence over tool implementations. - -## Version handling - -The source for the rule set is in [VSS Git repository](https://github.com/COVESA/vehicle_signal_specification/tree/master/docs-gen/content). -The online version of the rule set in the [generated VSS documentation](https://covesa.github.io/vehicle_signal_specification/) -is updated whenever a new commit is merged to the VSS master branch and does this not necessarily correspond to the rule set for the last release VSS version. - -To highlight important changes to the VSS rule set two notations are used in the documen - -* `since version X.Y` means that the concept/syntax was introduced in version X.Y. Older tools not supporting VSS version X.Y may not support this concept/syntax. -* `deprecated since version X.Y` means that the concept/syntax is no longer recommended from version X.Y onwards. The concept/syntax may be removed in the next major release. +In this chapter you learn about the rule set for VSS. diff --git a/docs-gen/content/rule_set/basics.md b/docs-gen/content/rule_set/basics.md index faf1f4f3f..b7ccbd1f9 100644 --- a/docs-gen/content/rule_set/basics.md +++ b/docs-gen/content/rule_set/basics.md @@ -4,18 +4,16 @@ date: 2019-08-04T13:05:11+02:00 weight: 1 --- ## Specification format +A domain specification is written as a flat YAML list, where each signal and +branch is a self-contained YAML list element. -The Vehicle Signal Specification domain specification consist of *vspec* files. -*vspec* files are YAML files following the rule set defined for VSS. -They also support the use of include directives to refer to other *vspec* files, much like ```#include``` in C/C++. . -Please note that, from a YAML perspective, the include directive is just another comment. +The YAML list is a single file, called a *vspec* file. -The file [VehicleSignalSpecification.vspec](https://github.com/COVESA/vehicle_signal_specification/blob/master/spec/VehicleSignalSpecification.vspec) serves as root -and includes other *vspec* files from the [VSS repository](https://github.com/COVESA/vehicle_signal_specification). +A vspec can, in addition to a YAML list, also contain include directives. -The raw specification files can, with help of tools in the [vss-tools repository](https://github.com/COVESA/vss-tools), -be converted to other formats that are more user friendly to read. -Converted representations are also included as release artifacts for each [VSS release](https://github.com/COVESA/vehicle_signal_specification/releases). +An include directive refers to another vspec file that is to replace the +directive, much like ```#include``` in C/C++. Please note that, from a YAML +perspective, the include directive is just another comment. ## Addressing Nodes @@ -26,32 +24,32 @@ a period ("."). The element hops from the root to the leaf is called ```path```. For example, the dimming status of the rearview mirror in the cabin is addressed: - Vehicle.Cabin.RearviewMirror.Dimmed + Cabin.RearviewMirror.Dimmed If there are an array of elements, such as door rows 1-3, they will be addressed with an index branch: ``` -Vehicle.Cabin.Door.Row1.Left.IsLocked -Vehicle.Cabin.Door.Row1.Left.Window.Position +Cabin.Door.Row1.Left.IsLocked +Cabin.Door.Row1.Left.Window.Position -Vehicle.Cabin.Door.Row2.Left.IsLocked -Vehicle.Cabin.Door.Row2.Left.Window.Position +Cabin.Door.Row2.Left.IsLocked +Cabin.Door.Row2.Left.Window.Position -Vehicle.Cabin.Door.Row3.Left.IsLocked -Vehicle.Cabin.Door.Row3.Left.Window.Position +Cabin.Door.Row3.Left.IsLocked +Cabin.Door.Row3.Left.Window.Position ``` In a similar fashion, seats are located by row and their left-to-right position. ``` -Vehicle.Cabin.Seat.Row1.Pos1.IsBelted # Left front seat -Vehicle.Cabin.Seat.Row1.Pos2.IsBelted # Right front seat +Cabin.Seat.Row1.Pos1.IsBelted # Left front seat +Cabin.Seat.Row1.Pos2.IsBelted # Right front seat -Vehicle.Cabin.Seat.Row2.Pos1.IsBelted # Left rear seat -Vehicle.Cabin.Seat.Row2.Pos2.IsBelted # Middle rear seat -Vehicle.Cabin.Seat.Row2.Pos3.IsBelted # Right rear seat +Cabin.Seat.Row2.Pos1.IsBelted # Left rear seat +Cabin.Seat.Row2.Pos2.IsBelted # Middle rear seat +Cabin.Seat.Row2.Pos3.IsBelted # Right rear seat ``` The exact use of ```PosX``` elements and how they correlate to actual @@ -63,12 +61,11 @@ If a new leaf node is defined, all parent branches included in its name must be included as well, as shown below: ``` -[Signal] Vehicle.Cabin.Door.Row1.Left.IsLocked -[Branch] Vehicle.Cabin.Door.Row1.Left -[Branch] Vehicle.Cabin.Door.Row1 -[Branch] Vehicle.Cabin.Door -[Branch] Vehicle.Cabin -[Branch] Vehicle +[Signal] Cabin.Door.Row1.Left.IsLocked +[Branch] Cabin.Door.Row1.Left +[Branch] Cabin.Door.Row1 +[Branch] Cabin.Door +[Branch] Cabin ``` The branches do not have to be defined in any specific order as long @@ -84,13 +81,13 @@ changes, the original nodes are marked as deprecated with the following rules. * Nodes, which are moved in the tree or are intended to be removed from the specification are marked with the deprecation keyword. * The string following the deprecation keyword shall start with the version, when the node was deprecated starting with `V` (e.g. `V2.1`) followed by the reason for deprecation. * If the node was moved, it shall be indicated by `moved to` followed by the new node name in dot notation as deprecation reason. This keyword shall be used only -if the meta-data of the moved node hasn't changed. +if the meta-data of the moved node hasn't changed. * If the node is intended to be removed from the specification or the meta data changed, it shall be indicated by `removed` and optionally the reason for the removal as deprecation reason. * Nodes which are deprecated will be removed from the specification, either in the second minor update or, if earlier, the next major update. ### Example ```YAML -Vehicle.Navigation.CurrentLocation: +Navigation.CurrentLocation: type: branch description: The current latitude and longitude of the vehicle. deprecation: V2.1 moved to Vehicle.CurrentLocation @@ -111,7 +108,7 @@ Examples: ``` SomeBranch.AnotherBranch.MySignalName -Vehicle.Cabin.Door.Row1.Left.IsLocked +Cabin.Door.Row1.Left.IsLocked ``` Naming convention for string literals can be found in the [chapter](/vehicle_signal_specification/rule_set/data_entry/allowed)for specifying allowed values. diff --git a/docs-gen/content/rule_set/data_entry/attributes.md b/docs-gen/content/rule_set/data_entry/attributes.md index e9aeaab08..fa5348117 100644 --- a/docs-gen/content/rule_set/data_entry/attributes.md +++ b/docs-gen/content/rule_set/data_entry/attributes.md @@ -4,7 +4,7 @@ date: 2019-08-04T12:37:31+02:00 weight: 4 --- -An attribute is an entity that has a default value, specified by +An attribute is an entity that has a default value, specified by its ```default``` member. The standard Vehicle Signal Specification does not include default values for all attributes. If a default value has not been specified then the OEM must define a default value matching the actual vehicle. diff --git a/docs-gen/content/rule_set/data_entry/sensor_actuator.md b/docs-gen/content/rule_set/data_entry/sensor_actuator.md index d359d0819..e300f3b18 100644 --- a/docs-gen/content/rule_set/data_entry/sensor_actuator.md +++ b/docs-gen/content/rule_set/data_entry/sensor_actuator.md @@ -63,14 +63,8 @@ The unit of measurement that the data entry has. See [Unit Type](data_unit_types/) chapter for a list of available unit types. This cannot be specified if ```allowed``` is defined as the signal type. -**```sensor```** *[optional]* `deprecated since version 3.1` +**```sensor```** *[optional]* The sensing appliance used to produce the data entry. -*The VSS signal metadata attributes `sensor` and `actuator` are no longer considered part of the core VSS syntax* -*If needed, they shall be used as additional metadata, see [overlays](../overlay.md) * - -**```actuator```** *[optional]* `deprecated since version 3.1` +**```actuator```** *[optional]* The actuating appliance consuming the data entry. - -*The VSS signal metadata attributes `sensor` and `actuator` are no longer considered part of the core VSS syntax* -*If needed, they shall be used as additional metadata, see [overlays](../overlay.md) * diff --git a/docs-gen/content/rule_set/instances.md b/docs-gen/content/rule_set/instances.md index 0feac6f9a..585bd01d9 100644 --- a/docs-gen/content/rule_set/instances.md +++ b/docs-gen/content/rule_set/instances.md @@ -18,8 +18,6 @@ interpreted by the tools. ## Definition -### How can I create instances for my `branch`? - 1. An instance can be defined in any branch. 2. The instantiation is done for every node in the following path. 3. Instances are defined with the key-word `instances`, followed by its @@ -37,19 +35,6 @@ interpreted by the tools. four position instances will be created for each of the 'Left' and 'Right' instances, resulting into a total number of 8 instances. -### How can I exclude child-nodes from instantiation? - -Often it makes sense to instantiate all child-nodes of a branch. -But there are cases, when nodes are linked more the general concept of -a branch, but not to the single instance. This could be the `DoorCount`, -which would rather be `Door.Count`, `WheelDiameter`, which is rather linked -to an axle rather than the wheel itself or `Brake.FluidLevel` which is not -measured for a single break, but rather a system indication. - -To exclude a child-node from the instantiation of the *direct* parent node, set the -keyword `instantiate` to `false` (`true` by default). Please check the following -example for details. - ## Example The example from above in the specification: @@ -64,16 +49,7 @@ Door: description: All doors, including windows and switches #include SingleDoor.vspec Door -Door.Count: - datatype: uint8 - type: attribute - default: 4 - instantiate: false - description: Number of doors in vehicle. -``` - -```yml # SingleDoor.vspec # @@ -89,7 +65,6 @@ Results in the following dot-notated output: ``` Vehicle.Cabin.Door -Vehicle.Cabin.Door.Count Vehicle.Cabin.Door.Row1 Vehicle.Cabin.Door.Row1.Left Vehicle.Cabin.Door.Row1.Left.IsOpen diff --git a/docs-gen/content/rule_set/overlay.md b/docs-gen/content/rule_set/overlay.md deleted file mode 100644 index af1965a10..000000000 --- a/docs-gen/content/rule_set/overlay.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "Overlay" -date: 2019-08-04T12:46:30+02:00 -weight: 7 ---- - -VSS defines the standard catalog for vehicle signals independent of the used protocol and environment. -In order to adopt the specification we realize that certain additions and modifications to the standard catalog are necessary. -**VSS Overlays** are meant to bring you a standardized way of handling those changes. - -The following features with the intended usage patterns are currently supported: -1. **Adding new nodes:** By adding nodes the standard catalog can be extended with proprietary concepts. -1. **Changing the value of existing metadata:** The standard catalog defines metadata based on what is assumed to be an average vehicle. -Configurations may differ slightly (e.g. the instantiation of number of available seats), or special situations that require a (limited) modification of existing metadata. -1. **Adding new key/value pairs as additional metadata:** -Extending the model with richer information is a fundamental feature enabled by the layer concept. For example, deploying VSS into a specific scenario or with a particular binding/technology often needs some additional information. -1. **Multiple layer files:** VSS layers can be split into several files in order to clearly separate concerns. Layering allows all the features above to be applied in a composable manner. In order to keep a determinstic result a clear order has to remain. - -### Scenarios for using Overlays - -The standard catalog is specified within COVESA and defines a common view of the major -attributes, sensors and actuators of vehicles. This is used in many different scenarios, -protocols and environments. Additional meta data might be required for data-governance, --quality or -sources. The instantiation of branches might not fit your vehicle. -Proprietary signals might be needed for extending the specification for your own use-cases. -Up to now you were on your own in these scenarios. Overlays give you the chance to change -and modify the standard catalog in a standardized way. - -### How does it work? - -Simply said, the tooling accepts, *n* additional spec files, next to the original -specification file, which can overwrite or extend data in the VSS tree defined by -the original specification.Before you start you should know: -- **Overlay-files have to be valid specification files by themselves.** - In practice that means, that the path to a node has to be well defined. -- **You can omit parent branches if there is no need to change them** - Tooling supports implicit branches. -- **Order matters.** The order on how the overlay files are called in the CLI - command matters! An example is shown in the figure below. - -The Figure below illustrates an example of the main specification and two -separate overlay files, an example call of the tooling and the resulting tree. - -![Include directive](/vehicle_signal_specification/images/overlay.drawio.png)
-*Figure: Overview on how overlays work within VSS* - - -```YAML -# In this overlay all parent branches are included. -# That is not mandatory, as tooling supports implicit branches. - -Vehicle: - type: branch - -Vehicle.Cabin: - type: branch - -Vehicle.Cabin.NewBranch: #< introduction of a new branch - type: branch - description: "new test branch" - -Vehicle.Cabin.NewBranch.HasNewSignal: #< introduction of a new signal - type: sensor - description: "new test signal" - datatype: int8 - -Vehicle.Cabin.Door: - type: branch - -Vehicle.Cabin.Door.IsOpen: - type: sensor #< change of node type - datatype: boolean -``` -*File: overlay_1.vspec* - -```YAML - -# This overlay use implicit branches. -# This means that tooling will either reuse the existing Vehicle.Cabin.NewBranch, -# or if not found create it with default values. - -Vehicle.Cabin.NewBranch.HasNewAttribute: #< ...with a new attribute - type: attribute - description: "new test attribute" - datatype: string - -Vehicle.Cabin.Door.IsOpen: - type: sensor - newKey: value #< Add a new key to the node and add a value - datatype: boolean - -``` -*File: overlay_2.vspec* - -### Overlays in the standard catalog - -With the feature of overlays, we introduced a new folder in the -repository called `overlays`. In there you'll find two additional folders: - -* `profiles`: Larger overlays to adapt VSS to a specific vehicle category, like motorbikes. -* `extensions`: Smaller overlays typically to be applied after applying profiles (if any). - -{{% notice warning %}} -**DISCLAIMER:** Use of overlays is a new concept for VSS. -The overlays in those folders shall currently be seen as examples only, and are not part of the official VSS specification. -{{% /notice %}} diff --git a/docs-gen/content/rule_set/private_branch.md b/docs-gen/content/rule_set/private_branch.md new file mode 100644 index 000000000..345369a62 --- /dev/null +++ b/docs-gen/content/rule_set/private_branch.md @@ -0,0 +1,54 @@ +--- +title: "Private Branch" +date: 2019-08-04T12:46:30+02:00 +weight: 7 +--- +The private branch offers a way to clearly separate OEM specific definitions +and the specification. It helps adapting the specification to the needs of the +organisation. + +## Extending and overriding Data Entries +The core signal specification can be extended with additional signals through the +use of private branches, as is shown in Fig 3. + + +![Signal Extension](/vehicle_signal_specification/images/private_extensions.png)
+*Fig 3. Extended signals* + +In this case the core signal specification, ```vss_23.vspec``` is +included by a OEM-specific master vspec file that adds the two +proprietary signals ```Private.OEM_X.AntiGravity.Power``` +and ```Private.OEM_X.Teleport.TargetLoc```. + +Signals can, in a similar manner, be overridden and replaced with a new definition, +as is shown in Fig 4. + + +![Signal Extension](/vehicle_signal_specification/images/signal_override.png)
+*Fig 4. Overridden signals* + +In this case, the ```GearChangeMode``` signal provided by the core +specification lacks an additional semi-automatic mode featured by an +OEM-specific vehicle. + +By having an OEM master spec file, ```oem_x_proprietary.vspec``` +include the core spec file, ```vss_23.vspec``` and then overriding +the original ```GearChangeMode``` signal and add the ```semi-auto``` +element as an enumerated value + +## DECLARING VS. DEFINING ATTRIBUTES +The signal extension mechanism described above is also used to declare +an attribute in one vspec file and define it in another. This is used +to setup a attribute structure standard in the core specification that +is to be defined on a per-deployment (vehicle) basis. + +An example is given in Fig 5. + +![Attributes](/vehicle_signal_specification/images/attributes.png)
+*Fig 5. Declaring and defining attributes* + +The ```Attributes.Engine.Displacement``` and ```Attributes.Chassis.Weight``` attributes +are declare in the ```vss_23.vspec``` file with a default value of zero. + +A project/vehicle specific vspec file, ```oem_x_proprietary.vspec``` +then overrides the attributes with the correct values. diff --git a/docs-gen/layouts/partials/menu-footer.html b/docs-gen/layouts/partials/menu-footer.html index a85efa9df..10306b29a 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: 3.0 + Latest Released Version: 2.2 diff --git a/docs-gen/static/images/attributes.png b/docs-gen/static/images/attributes.png new file mode 100644 index 000000000..b5f0e1861 Binary files /dev/null and b/docs-gen/static/images/attributes.png differ diff --git a/docs-gen/static/images/fav.png b/docs-gen/static/images/fav.png index b66a3d3b6..374803b40 100644 Binary files a/docs-gen/static/images/fav.png and b/docs-gen/static/images/fav.png differ diff --git a/docs-gen/static/images/overlay.drawio.png b/docs-gen/static/images/overlay.drawio.png deleted file mode 100644 index 9a4ab9684..000000000 Binary files a/docs-gen/static/images/overlay.drawio.png and /dev/null differ diff --git a/docs-gen/static/images/private_extensions.png b/docs-gen/static/images/private_extensions.png new file mode 100644 index 000000000..7896fe02e Binary files /dev/null and b/docs-gen/static/images/private_extensions.png differ diff --git a/docs-gen/static/images/signal_override.png b/docs-gen/static/images/signal_override.png new file mode 100644 index 000000000..f3f8f7915 Binary files /dev/null and b/docs-gen/static/images/signal_override.png differ diff --git a/docs-gen/static/images/vss.png b/docs-gen/static/images/vss.png index b441f753a..323662391 100644 Binary files a/docs-gen/static/images/vss.png and b/docs-gen/static/images/vss.png differ diff --git a/overlays/profiles/motorbike.vspec b/overlays/profiles/motorbike.vspec index 98fa382f1..5df39eb4b 100644 --- a/overlays/profiles/motorbike.vspec +++ b/overlays/profiles/motorbike.vspec @@ -1,6 +1,5 @@ # # (C) 2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG) -# (C) 2022 Robert Bosch GmbH # # All files and artifacts in this repository are licensed under the # provisions of the license provided by the LICENSE file in this repository. @@ -43,49 +42,4 @@ Vehicle.Cabin.Handlebar.GripHeating: type: sensor datatype: string allowed: ["HEATING_OFF", "HEATING_STEP_1", "HEATING_STEP_2", "HEATING_STEP_3", "HEATING_STEP_4", "HEATING_STEP_5", "HEATING_AUTOMATIC"] - description: Grip Heating Status in motorbikes. The signal shows if the handlebar grip heating is on or not, and if yes, to which level. - -Vehicle.LeanAngle: - type: sensor - datatype: float - unit: degrees - description: Lean Angle of the Motorcycle in Y direction. 0 = upright, - positive = leaning right from rider perspective, - negative = leaning left from rider perspective. - -Vehicle.IMU: - type: branch - description: Information related to the Inertial Measurement Unit to record angular rates and velocity-related information. - -Vehicle.IMU.IsOK: - type: sensor - datatype: boolean - description: Indicates if IMU is working. True = OK. False = Failure. - -Vehicle.ADAS: - type: branch - -# Motorbikes typically have different ABS-systems for front and rear wheel -Vehicle.ADAS.ABS: - type: branch - instances: ["Front","Rear"] - -Vehicle.Powertrain: - type: branch - -Vehicle.Powertrain.Transmission: - type: branch - -Vehicle.Powertrain.Transmission.IsClutchSwitchOperated: - type: sensor - datatype: boolean - description: Indicates if the Clutch switch is operated, so engine and transmission are partially or fully decoupled. False = Clutch switch not operated. True = Clutch switch operated. - -Vehicle.Powertrain.CombustionEngine: - type: branch - -Vehicle.Powertrain.CombustionEngine.FuelInjectionQuantity: - type: sensor - datatype: float - unit: ml - description: Amount of injected Fuel in millilitres per cylinder per injection. + description: Grip Heating Status in motorbikes. The signal shows if the handlebar grip heating is on or not, and if yes, to which level. \ No newline at end of file diff --git a/pics/logo/black-with-black-text.svg b/pics/logo/black-with-black-text.svg deleted file mode 100644 index fa818f0b4..000000000 --- a/pics/logo/black-with-black-text.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/pics/logo/colored-with-black-text.svg b/pics/logo/colored-with-black-text.svg deleted file mode 100644 index a139aff02..000000000 --- a/pics/logo/colored-with-black-text.svg +++ /dev/null @@ -1,11 +0,0 @@ - - - - - - - - - - - diff --git a/pics/logo/colored-with-white-text.svg b/pics/logo/colored-with-white-text.svg deleted file mode 100644 index 79f6e192c..000000000 --- a/pics/logo/colored-with-white-text.svg +++ /dev/null @@ -1,11 +0,0 @@ - - - - - - - - - - - diff --git a/pics/logo/white-with-white-text.svg b/pics/logo/white-with-white-text.svg deleted file mode 100644 index 64eac3e1f..000000000 --- a/pics/logo/white-with-white-text.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/pics/release_management.png b/pics/release_management.png new file mode 100644 index 000000000..f25b2b4ae Binary files /dev/null and b/pics/release_management.png differ diff --git a/spec/ADAS/ADAS.vspec b/spec/ADAS/ADAS.vspec index e27bca267..40b14ef32 100644 --- a/spec/ADAS/ADAS.vspec +++ b/spec/ADAS/ADAS.vspec @@ -285,5 +285,3 @@ EBA.IsEngaged: type: sensor description: Indicates if EBA is currently regulating brake pressure. True = Engaged. False = Not Engaged. -#include include/PowerOptimize.vspec - diff --git a/spec/Body/Body.vspec b/spec/Body/Body.vspec index 4e9bb396f..e954fda22 100644 --- a/spec/Body/Body.vspec +++ b/spec/Body/Body.vspec @@ -28,16 +28,12 @@ RefuelPosition: Hood: type: branch description: Hood status. - comment: The hood is the hinged cover over the engine compartment of a motor vehicles. - Depending on vehicle, it can be either in the front or back of the vehicle. - Luggage compartments are in VSS called trunks, even if they are located at the front of the vehicle. Hood.IsOpen: datatype: boolean type: actuator description: Hood open or closed. True = Open. False = Closed. - # # Trunk description # @@ -45,9 +41,6 @@ Trunk: type: branch instances: ["Front", "Rear"] description: Trunk status. - comment: A trunk is a luggage compartment in a vehicle. - Depending on vehicle, it can be either in the front or back of the vehicle. - Some vehicles may have trunks both at the front and at the rear of the vehicle. Trunk.IsOpen: datatype: boolean @@ -175,74 +168,11 @@ Windshield.WasherFluid.Level: ## Lights: type: branch - description: Exterior lights. - -Lights.LightSwitch: - datatype: string - type: actuator - allowed: ['OFF', 'POSITION', 'DAYTIME_RUNNING_LIGHTS', 'AUTO', 'BEAM'] - description: Status of the vehicle main light switch. - comment: A vehicle typically does not support all alternatives. - Which lights that actually are lit may vary according to vehicle configuration and local legislation. - OFF is typically indicated by 0. - POSITION is typically indicated by ISO 7000 symbol 0456. - DAYTIME_RUNNING_LIGHTS (DRL) can be indicated by ISO 7000 symbol 2611. - AUTO indicates that vehicle automatically selects suitable lights. - BEAM is typically indicated by ISO 7000 symbol 0083. - -Lights.IsHighBeamSwitchOn: - datatype: boolean - type: actuator - description: Status of the high beam switch. True = high beam enabled. False = high beam not enabled. - comment: This signal indicates the status of the switch and does not indicate if low or high beam actually are on. - That typically depends on vehicle logic and other signals like Lights.LightSwitch and Vehicle.LowVoltageSystemState. - -Lights.Beam: - type: branch - instances: ["Low","High"] - description: Beam lights. -#include StaticLights.vspec Lights.Beam - -Lights.Running: - type: branch - description: Running lights. -#include StaticLights.vspec Lights.Running + description: All lights. -Lights.Backup: - type: branch - description: Backup lights. -#include StaticLights.vspec Lights.Backup +# Include lights specification and attach it to the Lights branch +#include ExteriorLights.vspec Lights -Lights.Parking: - type: branch - description: Parking lights. -#include StaticLights.vspec Lights.Parking - -Lights.Fog: - type: branch - instances: ["Rear","Front"] - description: Fog lights. -#include StaticLights.vspec Lights.Fog - -Lights.LicensePlate: - type: branch - description: License plate lights. -#include StaticLights.vspec Lights.LicensePlate - -Lights.Brake: - type: branch -#include BrakeLights.vspec Lights.Brake - -Lights.Hazard: - type: branch - description: Hazard lights. -#include SignalingLights.vspec Lights.Hazard - -Lights.DirectionIndicator: - type: branch - instances: ["Left","Right"] - description: Indicator lights. -#include SignalingLights.vspec Lights.DirectionIndicator ## # Mirrors definition @@ -265,5 +195,3 @@ RearMainSpoilerPosition: min: 0 max: 100 description: Rear spoiler position, 0% = Spoiler fully stowed. 100% = Spoiler fully exposed. - -#include include/PowerOptimize.vspec diff --git a/spec/Body/BrakeLights.vspec b/spec/Body/BrakeLights.vspec deleted file mode 100644 index 4bba7e472..000000000 --- a/spec/Body/BrakeLights.vspec +++ /dev/null @@ -1,14 +0,0 @@ -# -# (C) 2022 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) - All rights reserved. -# - -IsActive: - datatype: string - type: actuator - allowed: ['INACTIVE', 'ACTIVE', 'ADAPTIVE'] - description: Indicates if break-light is active. INACTIVE means lights are off. ACTIVE means lights are on. ADAPTIVE means that break-light is indicating emergency-breaking. - -IsDefect: - datatype: boolean - type: sensor - description: Indicates if light is defect. True = Light is defect. False = Light has no defect. \ No newline at end of file diff --git a/spec/Body/ExteriorLights.vspec b/spec/Body/ExteriorLights.vspec new file mode 100644 index 000000000..633000fdb --- /dev/null +++ b/spec/Body/ExteriorLights.vspec @@ -0,0 +1,66 @@ +# +# (C) 2018 Volvo Cars +# (C) 2016 Jaguar Land Rover +# +# All files and artifacts in this repository are licensed under the +# provisions of the license provided by the LICENSE file in this repository. +# + +# +# All exterior lights +# + +IsHighBeamOn: + datatype: boolean + type: actuator + description: Is high beam on? + +IsLowBeamOn: + datatype: boolean + type: actuator + description: Is low beam on? + +IsRunningOn: + datatype: boolean + type: actuator + description: Are running lights on? + +IsBackupOn: + datatype: boolean + type: actuator + description: Is backup (reverse) light on? + +IsParkingOn: + datatype: boolean + type: actuator + description: Is parking light on? + +IsBrakeOn: + datatype: boolean + type: actuator + description: Is brake light on? + +IsRearFogOn: + datatype: boolean + type: actuator + description: Is rear fog light on? + +IsFrontFogOn: + datatype: boolean + type: actuator + description: Is front fog light on? + +IsHazardOn: + datatype: boolean + type: actuator + description: Are hazards on? + +IsLeftIndicatorOn: + datatype: boolean + type: actuator + description: Is left indicator flashing? + +IsRightIndicatorOn: + datatype: boolean + type: actuator + description: Is right indicator flashing? diff --git a/spec/Body/SignalingLights.vspec b/spec/Body/SignalingLights.vspec deleted file mode 100644 index f9d26a016..000000000 --- a/spec/Body/SignalingLights.vspec +++ /dev/null @@ -1,13 +0,0 @@ -# -# (C) 2022 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) - All rights reserved. -# - -IsSignaling: - datatype: boolean - type: actuator - description: Indicates if light is signaling or off. True = signaling. False = Off. - -IsDefect: - datatype: boolean - type: sensor - description: Indicates if light is defect. True = Light is defect. False = Light has no defect. \ No newline at end of file diff --git a/spec/Body/StaticLights.vspec b/spec/Body/StaticLights.vspec deleted file mode 100644 index 40b01d4e9..000000000 --- a/spec/Body/StaticLights.vspec +++ /dev/null @@ -1,13 +0,0 @@ -# -# (C) 2022 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) - All rights reserved. -# - -IsOn: - datatype: boolean - type: actuator - description: Indicates if light is on or off. True = On. False = Off. - -IsDefect: - datatype: boolean - type: sensor - description: Indicates if light is defect. True = Light is defect. False = Light has no defect. \ No newline at end of file diff --git a/spec/Cabin/Cabin.vspec b/spec/Cabin/Cabin.vspec index 64e0ce852..1359a3b06 100644 --- a/spec/Cabin/Cabin.vspec +++ b/spec/Cabin/Cabin.vspec @@ -184,5 +184,3 @@ Convertible.Status: type: sensor allowed: ['UNDEFINED', 'CLOSED', 'OPEN', 'CLOSING', 'OPENING', 'STALLED'] description: Roof status on convertible vehicles. - -#include include/PowerOptimize.vspec diff --git a/spec/Cabin/HVAC.vspec b/spec/Cabin/HVAC.vspec index 1a4ea59d4..56d885014 100644 --- a/spec/Cabin/HVAC.vspec +++ b/spec/Cabin/HVAC.vspec @@ -43,5 +43,3 @@ AmbientAirTemperature: type: sensor unit: celsius description: Ambient air temperature inside the vehicle. - -#include include/PowerOptimize.vspec diff --git a/spec/Cabin/Infotainment.vspec b/spec/Cabin/Infotainment.vspec index a1195105b..4271dd484 100644 --- a/spec/Cabin/Infotainment.vspec +++ b/spec/Cabin/Infotainment.vspec @@ -49,14 +49,6 @@ Media.Played.URI: type: sensor description: User Resource associated with the media -Media.Played.PlaybackRate: - datatype: float - type: actuator - description: Current playback rate of media being played. - comment: The normal playback rate is multiplied by this value to obtain the current rate, so a value of 1.0 indicates normal speed. - Values of lower than 1.0 make the media play slower than normal. - Values of higher than 1.0 make the media play faster than normal. - Media.DeclinedURI: datatype: string type: sensor @@ -72,7 +64,6 @@ Media.Volume: type: actuator min: 0 max: 100 - unit: percent description: Current Media Volume Navigation: @@ -98,20 +89,6 @@ Navigation.DestinationSet.Longitude: max: 180 unit: degrees description: Longitude of destination in WGS 84 geodetic coordinates. - -Navigation.Mute: - datatype: string - type: actuator - allowed: ['MUTED', 'ALERT_ONLY', 'UNMUTED'] - description: Navigation mute state that was selected. - -Navigation.Volume: - datatype: uint8 - type: actuator - min: 0 - max: 100 - unit: percent - description: Current navigation volume HMI: type: branch @@ -140,12 +117,6 @@ HMI.DistanceUnit: allowed: ['MILES', 'KILOMETERS'] description: Distance unit used in the current HMI -HMI.FuelVolumeUnit: - datatype: string - type: actuator - allowed: ['LITER', 'GALLON_US', 'GALLON_UK'] - description: Fuel volume unit used in the current HMI - HMI.FuelEconomyUnits: datatype: string type: actuator @@ -164,52 +135,8 @@ HMI.TemperatureUnit: allowed: ['C', 'F'] description: Temperature unit used in the current HMI -HMI.TirePressureUnit: - datatype: string - type: actuator - allowed: ['PSI', 'KPA', 'BAR'] - description: Tire pressure unit used in the current HMI - - -HMI.Brightness: - datatype: float - type: actuator - unit: percent - min: 0 - max: 100 - description: Brightness of the HMI, relative to supported range. - 0 = Lowest brightness possible. - 100 = Maximum Brightness possible. - comment: The value 0 does not necessarily correspond to a turned off HMI, - as it may not be allowed/supported to turn off the HMI completely. - HMI.DayNightMode: datatype: string type: actuator allowed: ['DAY', 'NIGHT'] description: Current display theme - -SmartphoneProjection: - type: branch - description: All smartphone projection actions. - -SmartphoneProjection.Active: - datatype: string - type: actuator - allowed: [ 'NONE', 'ACTIVE', 'INACTIVE' ] - description: Projection activation info. - comment: NONE indicates that projection is not supported. - -SmartphoneProjection.Source: - datatype: string - type: actuator - allowed: ['USB', 'BLUETOOTH', 'WIFI'] - description: Connectivity source selected for projection. - -SmartphoneProjection.SupportedMode: - datatype: string[] - type: attribute - allowed: [ 'ANDROID_AUTO', 'APPLE_CARPLAY', 'MIRROR_LINK', 'OTHER' ] - description: Supportable list for projection. - -#include include/PowerOptimize.vspec diff --git a/spec/Cabin/SingleSeat.vspec b/spec/Cabin/SingleSeat.vspec index 24b9760e6..1a756fed2 100644 --- a/spec/Cabin/SingleSeat.vspec +++ b/spec/Cabin/SingleSeat.vspec @@ -79,12 +79,8 @@ Tilt: datatype: float type: actuator unit: degrees - description: Tilting of seat (seating and backrest) relative to vehicle x-axis. - 0 = seat bottom is flat, seat bottom and vehicle x-axis are parallel. - Positive degrees = seat tilted backwards, seat x-axis tilted upward, seat z-axis is tilted backward. - comment: In VSS it is assumed that tilting a seat affects both seating (seat bottom) and backrest, i.e. the angle - between seating and backrest will not be affected when changing Tilt. - + description: Tilting of seat relative to vehicle z-axis. 0 = seating is flat, seat and vehicle z-axis are parallel. + Positive degrees = seat tilted backwards, seat z-axis is tilted backward. Backrest: type: branch @@ -136,7 +132,7 @@ Backrest.SideBolster.Support: Seating: type: branch - description: Describes signals related to the seat bottom of the seat. + description: Describes signals related to the seating/base of the seat. comment: Seating is here considered as the part of the seat that supports the thighs. Additional cushions (if any) for support of lower legs is not covered by this branch. diff --git a/spec/Chassis/Chassis.vspec b/spec/Chassis/Chassis.vspec index f6c9bddca..3ef4ef337 100644 --- a/spec/Chassis/Chassis.vspec +++ b/spec/Chassis/Chassis.vspec @@ -60,13 +60,7 @@ Axle.WheelWidth: unit: inch description: Width of wheels (rims without tires), in inches, as per ETRTO / TRA standard. -Axle.SteeringAngle: - datatype: float - type: sensor - unit: degrees - description: Single track two-axle model steering angle. - Angle according to ISO 8855. Positive = degrees to the left. Negative = degrees to the right. - comment: Single track two-axle model steering angle refers to the angle that a centrally mounted wheel would have. + # # Tire attributes # diff --git a/spec/Chassis/Wheel.vspec b/spec/Chassis/Wheel.vspec index e2d4ace35..094f6131e 100644 --- a/spec/Chassis/Wheel.vspec +++ b/spec/Chassis/Wheel.vspec @@ -61,13 +61,3 @@ Tire.Temperature: type: sensor unit: celsius description: Tire temperature in Celsius. - - -# -# Wheel signals -# -Speed: - datatype: float - type: sensor - unit: km/h - description: Rotational speed of a vehicle's wheel. diff --git a/spec/Powertrain/FuelSystem.vspec b/spec/Powertrain/FuelSystem.vspec index 32198a7ae..8d6742f45 100644 --- a/spec/Powertrain/FuelSystem.vspec +++ b/spec/Powertrain/FuelSystem.vspec @@ -76,12 +76,8 @@ ConsumptionSinceStart: type: sensor unit: l description: Fuel amount in liters consumed since start of current trip. - comment: A new trip is considered to start when engine gets enabled (e.g. LowVoltageSystemState in ON or START mode). - A trip is considered to end when engine is no longer enabled. - The signal may however keep the value of the last trip until a new trip is started. TimeSinceStart: - deprecation: V3.1 replaced by Vehicle.StartTime and Vehicle.TripDuration datatype: uint32 type: sensor unit: s diff --git a/spec/Powertrain/Powertrain.vspec b/spec/Powertrain/Powertrain.vspec index 05be528c1..a9c5d1c46 100644 --- a/spec/Powertrain/Powertrain.vspec +++ b/spec/Powertrain/Powertrain.vspec @@ -22,5 +22,4 @@ Type: description: Defines the powertrain type of the vehicle. comment: For vehicles with a combustion engine (including hybrids) more detailed information on fuels supported can be found in FuelSystem.SupportedFuelTypes and FuelSystem.SupportedFuels. - -#include include/PowerOptimize.vspec + \ No newline at end of file diff --git a/spec/Private/Private.vspec b/spec/Private/Private.vspec new file mode 100644 index 000000000..ccd4c79e5 --- /dev/null +++ b/spec/Private/Private.vspec @@ -0,0 +1,14 @@ +# +# (C) 2018 Volvo Cars +# (C) 2016 Jaguar Land Rover +# +# All files and artifacts in this repository are licensed under the +# provisions of the license provided by the LICENSE file in this repository. +# + +# +# The Private branch. +# OEM unique data may be added here. +# + + diff --git a/spec/Vehicle/Battery.vspec b/spec/Vehicle/Battery.vspec deleted file mode 100644 index 674bbd606..000000000 --- a/spec/Vehicle/Battery.vspec +++ /dev/null @@ -1,38 +0,0 @@ -# -# (C) 2022 Robert Bosch GmbH -# All files and artifacts in this repository are licensed under the -# provisions of the license provided by the LICENSE file in this repository. -# - -# -# Signals and attributes related to the low voltage battery in Vehicles -# This is the 12 Volt or 24 Volt battery typically used for infotainment systems and to start the combustion engine -# in traditional petrol/diesel vehecles. -# - -NominalVoltage: - datatype: uint16 - type: attribute - unit: V - description: Nominal Voltage of the battery. - comment: Nominal voltage typically refers to voltage of fully charged battery when delivering rated capacity. - -NominalCapacity: - datatype: uint16 - type: attribute - unit: Ah - description: Nominal capacity of the low voltage battery. - -CurrentVoltage: - datatype: float - type: sensor - unit: V - description: Current Voltage of the low voltage battery. - -CurrentCurrent: - datatype: float - type: sensor - unit: A - description: Current current flowing in/out of the low voltage battery. Positive = Current flowing in to battery, - e.g. during charging or driving. - Negative = Current flowing out of battery, e.g. when using the battery to start a combustion engine. diff --git a/spec/Vehicle/Vehicle.vspec b/spec/Vehicle/Vehicle.vspec index b683ba834..41dfc4c01 100644 --- a/spec/Vehicle/Vehicle.vspec +++ b/spec/Vehicle/Vehicle.vspec @@ -29,7 +29,7 @@ VersionVSS.Major: VersionVSS.Minor: datatype: uint32 type: attribute - default: 1 + default: 0 description: Supported Version of VSS - Minor version. VersionVSS.Patch: @@ -167,16 +167,6 @@ LowVoltageSystemState: ] description: State of the supply voltage of the control units (usually 12V). -## -# Low voltage battery -## -LowVoltageBattery: - type: branch - description: Signals related to low voltage battery. - -#include Battery.vspec LowVoltageBattery - - Speed: datatype: float type: sensor @@ -184,53 +174,16 @@ Speed: description: Vehicle speed. TravelledDistance: - deprecation: V3.1 moved to Vehicle.TraveledDistance - datatype: float - type: sensor - unit: km - description: Odometer reading, total distance traveled during the lifetime of the vehicle. - -TraveledDistance: - datatype: float - type: sensor - unit: km - description: Odometer reading, total distance traveled during the lifetime of the vehicle. - -TraveledDistanceSinceStart: datatype: float type: sensor unit: km - description: Distance traveled since start of current trip. - comment: A new trip is considered to start when engine gets enabled (e.g. LowVoltageSystemState in ON or START mode). - A trip is considered to end when engine is no longer enabled. - The signal may however keep the value of the last trip until a new trip is started. - -StartTime: - datatype: string - type: attribute - default: '0000-01-01T00:00Z' - description: Start time of current or latest trip, formatted according to ISO 8601 with UTC time zone. - comment: This signal is supposed to be set whenever a new trip starts. - A new trip is considered to start when engine gets enabled (e.g. LowVoltageSystemState in ON or START mode). - A trip is considered to end when engine is no longer enabled. - The default value indicates that the vehicle never has been started, or that latest start time is unknown. - -TripDuration: - datatype: float - type: sensor - unit: s - description: Duration of latest trip. - comment: This signal is not assumed to be continuously updated, but instead set to 0 when a trip starts - and set to the the actual duration of the trip when a trip ends. - A new trip is considered to start when engine gets enabled (e.g. LowVoltageSystemState in ON or START mode). - A trip is considered to end when engine is no longer enabled. + description: Odometer reading, total distance travelled during the lifetime of the vehicle. TripMeterReading: datatype: float - type: actuator + type: sensor unit: km - description: Trip meter reading. - comment: The trip meter is an odometer that can be manually reset by the driver + description: Current trip meter reading. IsBrokenDown: datatype: boolean @@ -251,10 +204,7 @@ AverageSpeed: type: sensor unit: km/h description: Average speed for the current trip. - comment: A new trip is considered to start when engine gets enabled (e.g. LowVoltageSystemState in ON or START mode). - A trip is considered to end when engine is no longer enabled. - The signal may however keep the value of the last trip until a new trip is started. - Calculation of average speed may exclude periods when the vehicle for example is not moving or transmission is in neutral. + # # Spatial Acceleration @@ -498,7 +448,7 @@ CurrentLocation.GNSSReceiver.MountingPosition.Y: Axis definitions according to ISO 8855. Origin at center of (first) rear axle. Positive values = left of origin. Negative values = right of origin. Left/Right is as seen from driver perspective, i.e. by a person looking forward. - + CurrentLocation.GNSSReceiver.MountingPosition.Z: datatype: int16 type: attribute @@ -506,6 +456,4 @@ CurrentLocation.GNSSReceiver.MountingPosition.Z: description: Mounting position of GNSS receiver on Z-axis. Axis definitions according to ISO 8855. Origin at center of (first) rear axle. Positive values = above center of rear axle. Negative values = below center of rear axle. - -#include include/PowerOptimize.vspec - + diff --git a/spec/VehicleSignalSpecification.vspec b/spec/VehicleSignalSpecification.vspec index cfa46995a..7919a5001 100644 --- a/spec/VehicleSignalSpecification.vspec +++ b/spec/VehicleSignalSpecification.vspec @@ -27,6 +27,12 @@ Vehicle: #include Vehicle/Vehicle.vspec Vehicle +Vehicle.Private: + type: branch + description: Uncontrolled branch where non-public signals can be defined. + +#include Private/Private.vspec Vehicle.Private + # # The power train branch used to host the signals and attributes. diff --git a/spec/include/PowerOptimize.vspec b/spec/include/PowerOptimize.vspec deleted file mode 100644 index 492c6e3f1..000000000 --- a/spec/include/PowerOptimize.vspec +++ /dev/null @@ -1,109 +0,0 @@ -# -# (C) 2023 Robert Bosch GmbH -# -# All files and artifacts in this repository are licensed under the -# provisions of the license provided by the LICENSE file in this repository. -# - -# -# Architectural Concept -# -# A vehicle may have a power optimization system to control functionality in order to extend available range of the vehicle. -# It is assumed that the power optimization system does not know in detail which functionalities that exist in the vehicle -# and which functionalities that can be turned off without causing interruptions to essential functionality. -# -# This is proposed to be handled by a distributed system where the power optimization system only gives recommendations -# on power optimization for different areas. -# The areas are in standard VSS catalog initially assumed to correspond to branches in VSS, and are represented as a signal in the corresponding branch, -# like `Vehicle.[.]*PowerOptimizeLevel`. -# A global signal `Vehicle.PowerOptimizeLevel` also exists for features that does not have a matching signal in sub-branches. -# -# The signal can be added to a branch by including this file, like: -# -# "#include include/PowerOptimize.vspec" -# -# -# Initially the standard VSS catalog contains the following level signals: -# -#Vehicle.PowerOptimizeLevel -#Vehicle.Powertrain.PowerOptimizeLevel -#Vehicle.Body.PowerOptimizeLevel -#Vehicle.Cabin.PowerOptimizeLevel -#Vehicle.Cabin.HVAC.PowerOptimizeLevel -#Vehicle.Cabin.Infotainment.PowerOptimizeLevel -#Vehicle.ADAS.PowerOptimizeLevel -# -# When there are multiple level signals in a subtree (like for the Cabin subtree) a feature may typically consider the "closest" level signal. -# -# Example 1: HVAC functionality (signals in branch Vehicle.Cabin.HVAC) may consider Vehicle.Cabin.HVAC.PowerOptimizeLevel -# Example 2: Sunroof functionality (signals in branch Vehicle.Cabin.Sunroof) may consider Vehicle.Cabin.PowerOptimizeLevel -# as there is no specific level signal in Vehicle.Cabin.Sunroof. -# Example 3: Tire monitoring systems may consider Vehicle.PowerOptimizeLevel as there is no dedicated signal for Chassis branch. -# -# The power optimization level has a numerical value from 0 to 10. -# Level 0 means that power optimization is not needed, all functionality can behave "normally". -# Level 10 means that power consumption shall be minimized. Non-essential functionality shall be disabled. -# Essential functionality to fulfill legal and safety requirements shall still be enabled. -# Intermediate numbers (1-9) indicates intermediate states, where a higher number indicates a more aggressive power optimization policy. -# -# This allows for subsystems to implement their own power saving logic. -# It is totally up to the subsystem to know "what to do" for different power optimize levels. -# It is also assumed that the subsystem knows what is required for legal and safety reasons and does not turn off -# essential functionality regardless of power optimization level. -# It is up to the OEM to configure subsystems to achieve the wanted behavior. -# It is expected that power optimizations that are activated already at a low level have limited impact on the driver experience, -# but power optimizations on higher levels will have significant impact on driver experience. -# -# A hypothetical example for Display/HMI brightness could be as follows -# -# There is a signal Vehicle.Cabin.Infotainment.HMI.Brightness that for example the driver could use to change HMI Brightness. -# The signal has a range 0-100 percent, where 0% means the lowest value allowed from legal/safety-reasons as well as usability reasons. -# To allow for energy optimization an OEM might want to change the actual brightness based on power optimization level for cabin. -# -# A possible schema could be as follows -# - -# REAL_MIN = 30 /* Lowest allowed value for safety/legal/convenience-reasons */ -# REAL_MAX = 90 /* Maximum allowed value for safety/legal/convenience/technical-reasons */ -# POWERSAVE_MAX_RELATIVE = 45 /* Maximum relative brightness during power optimize */ -# POWERSAVE_LIMIT = 5 /* Reduce brightness if level is above this value */ -# -# if (Vehicle.Cabin.Infotainment.PowerOptimizeLevel > POWERSAVE_LIMIT): -# old_value = Vehicle.Cabin.Infotainment.HMI.Brightness; -# if (Vehicle.Cabin.Infotainment.HMI.Brightness > POWERSAVE_MAX_RELATIVE): -# Vehicle.Cabin.Infotainment.HMI.Brightness = POWERSAVE_MAX_RELATIVE; -# else -# // Revert to old value -# Vehicle.Cabin.Infotainment.HMI.Brightness = old_value; -# -# -# Note that no additional VSS signals is added to represent wanted brightness at power optimization. -# It is possible that a such signal may be needed in individual deployments, but if so it can be handled by a vehicle specific overlay. -# -# Customization -# -# In addition to power optimize signals added in standard VSS catalog a project/OEM may customize the model using overlays by: -# -# 1. Adding additional power optimize level signals -# -# For instance by adding `#include include/PowerOptimize.vspec` in additional files -# -# 2. Adding signals for supporting data -# -# In specific deployments there might be a need for private signals with additional data for the power optimization strategy used. -# This could for instance be signals to specify maximum speed for a specific power optimization levels. - -## -# Power Optimization -## - - -PowerOptimizeLevel: - datatype: uint8 - type: actuator - min: 0 - max: 10 - description: Power optimization level for this branch/subsystem. - A higher number indicates more aggressive power optimization. - Level 0 indicates that all functionality is enabled, no power optimization enabled. - Level 10 indicates most aggressive power optimization mode, only essential functionality enabled. diff --git a/spec/units.yaml b/spec/units.yaml deleted file mode 100644 index 82752557d..000000000 --- a/spec/units.yaml +++ /dev/null @@ -1,221 +0,0 @@ -# This file defines units supported in the VSS catalog -# It has precedence over the file defined in https://github.com/COVESA/vss-tools/blob/master/vspec/config.yaml -# This file must be specified with the -u parameter when using vss-tools -units: - mm: - label: millimeter - description: Distance measured in millimeters - domain: distance - cm: - label: centimeter - description: Distance measured in centimeters - domain: distance - m: - label: meter - description: Distance measured in meters - domain: distance - km: - label: kilometer - description: Distance measured in kilometers - domain: distance - inch: - label: inch - description: Distance measured in inches - domain: distance - km/h: - label: kilometer per hour - description: Speed measured in kilometers per hours - domain: speed - m/s: - label: meters per second - description: Speed measured in meters per second - domain: speed - m/s^2: - label: meters per second squared - description: Acceleration measured in meters per second squared - domain: acceleration - cm/s^2: - label: centimeters per second squared - description: Acceleration measured in centimeters per second squared - domain: acceleration - ml: - label: milliliter - description: Volume measured in milliliters - domain: volume - l: - label: liter - description: Volume measured in liters - domain: volume - cm^3: - label: cubic centimeters - description: Volume measured in cubic centimeters - domain: volume - celsius: - label: degree celsius - description: Temperature measured in degree celsius - domain: temperature - degrees: - label: degree - description: Angle measured in degrees - domain: angle - degrees/s: - label: degree per second - description: Angular speed measured in degrees per second - domain: angular speed - W: - label: watt - description: Power measured in watts - domain: power - kW: - label: kilowatt - description: Power measured in kilowatts - domain: power - PS: - label: horsepower - description: Power measured in horsepower - domain: power - kWh: - label: kilowatt hours - description: Energy consumption measured in kilowatt hours - domain: energy consumption - g: - label: gram - description: Mass measured in grams - domain: mass - kg: - label: kilogram - description: Mass measured in kilograms - domain: mass - lbs: - label: pound - description: Mass measured in pounds - domain: mass - V: - label: volt - description: Electric potential measured in volts - domain: electric potential - A: - label: ampere - description: Electric current measured in amperes - domain: electric current - Ah: - label: ampere hours - description: Electric charge measured in ampere hours - domain: electric charge - ms: - label: millisecond - description: Time measured in milliseconds - domain: time - s: - label: second - description: Time measured in seconds - domain: time - min: - label: minute - description: Time measured in minutes - domain: time - h: - label: hour - description: Time measured in hours - domain: time - day: - label: days - description: Time measured in days - domain: time - weeks: - label: weeks - description: Time measured in weeks - domain: time - months: - label: months - description: Time measured in months - domain: time - years: - label: years - description: Time measured in years - domain: time - UNIX Timestamp: - label: UNIX Timestamp - description: Unix time is a system for describing a point in time. It is the number of seconds that have elapsed since the Unix epoch, excluding leap seconds. - domain: point in time - mbar: - label: millibar - description: Pressure measured in millibars - domain: pressure - Pa: - label: pascal - description: Pressure measured in pascal - domain: pressure - kPa: - label: kilopascal - description: Pressure measured in kilopascal - domain: pressure - stars: - label: stars - description: Rating measured in stars - domain: rating - g/s: - label: grams per second - description: Mass per time measured in grams per second - domain: mass per time - g/km: - label: grams per kilometer - description: Mass per distance measured in grams per kilometers - domain: mass per distance - kWh/100km: - label: kilowatt hours per 100 kilometers - description: Energy consumption per distance measured in kilowatt hours per 100 kilometers - domain: energy consumption per distance - ml/100km: - label: milliliter per 100 kilometers - description: Volume per distance measured in milliliters per 100 kilometers - domain: volume per distance - l/100km: - label: liter per 100 kilometers - description: Volume per distance measured in liters per 100 kilometers - domain: volume per distance - l/h: - label: liter per hour - description: Flow measured in liters per hour - domain: flow - mpg: - label: miles per gallon - description: Distance per volume measured in miles per gallon - domain: distance per volume - N: - label: newton - description: Force measured in newton - domain: force - Nm: - label: newton meter - description: Torque measured in newton meters - domain: torque - rpm: - label: revolutions per minute - description: Rotational speed measured in revolutions per minute - domain: rotational speed - Hz: - label: frequency - description: Frequency measured in hertz - domain: frequency - ratio: - label: ratio - description: Relation measured as ratio - domain: relation - percent: - label: percent - description: Relation measured in percent - domain: relation - nm/km: - label: nano meter per kilometer - description: nm/km - domain: nm/km - dBm: - label: decibel milliwatt - description: Power level expressed in decibels with reference to one milliwatt - domain: relation - kN: - label: kilo newton - description: Force measured in kilo newton - domain: force - diff --git a/structure.txt b/structure.txt new file mode 100644 index 000000000..d33a15221 --- /dev/null +++ b/structure.txt @@ -0,0 +1,204 @@ +Below is a textual representation of the proposed signal structure. +These are to be translated into vspec files. +Feel free to help out and send pull requests. + +engine + ect + rpm + maf + eot... + + +transmission + gear + diff + 1 + temp + lock_level + ... + 2wd + 4wd + + +chassis + dampers + steering + brakes + tire_pressure + more?? + +body + wipers + level (off, auto, interval) + interval_level + washer_fluid + rain_sensor + + mirrors + left + dimming + heated + right + dimming + heated + + lights + high_beam + low_beam + + running + front + rear + side + + parking_light + + daylight_running + + parking + backup + brakes + fog + rear + front + turn_indicator + hazard + +hmi + bt + phones... + + media + audio + video + tuner + am + fm + sirius + tv + cd + dvd + blueray + usb + bt_streaming + + nav + ... + + wifi + + internet + ip_address + link_type + .. + + telematics + ecall + bcall + + amplifier + balance + dolby... + + channel + + input + command: aggergate + source: [ voice, screen, keyboard, hard_button, internal ] + path: "x/y/z" + + screen + key + hard + soft + voice + scratchpad + gesture + + feature_select + ????? + + sim_card? + + + +camera + internal + external + +cabin + hvac + Well known + + windows + global_up + global_down + front + locked + heated + rear + heated + + row + 1 + position + 1 + window_position + one_shot_down + one_shot_down + + blinds + sunroof + rearview_mirror + dimming + + seatbelts + + home_link + button + 1 + pressed + 2 + pressed + 3 + pressed + + lights + interior + glove_box + trunk + dome + ambient_daylight_sensor + ambient + color + level + sunshade + + instrumentation + level + color + + seats + row + 1 + position + 1 + belted + position + 21 pos (including folding) + heat + headrest_position + massage + cooling + + 2 + ... + # Row 2 + 2 + ... + + +ALIAS FILE + driver: alias cabin.seats.row.1.left + passenger: alias cabin.seats.row.1.right + diff --git a/vss-tools b/vss-tools index de88c8aec..3159418a3 160000 --- a/vss-tools +++ b/vss-tools @@ -1 +1 @@ -Subproject commit de88c8aec035bfb66a49f4c334a7ffb34ce69d76 +Subproject commit 3159418a3b76a5339bd0b7d7cb5f28685dc81fe8