diff --git a/docs-gen/content/rule_set/basics.md b/docs-gen/content/rule_set/basics.md index 2f4a7ffb..c5b4c594 100644 --- a/docs-gen/content/rule_set/basics.md +++ b/docs-gen/content/rule_set/basics.md @@ -96,7 +96,7 @@ if the meta-data of the moved node hasn't changed. * 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 +```yaml Vehicle.Navigation.CurrentLocation: type: branch description: The current latitude and longitude of the vehicle. diff --git a/docs-gen/content/rule_set/branches.md b/docs-gen/content/rule_set/branches.md index b697f614..94204d85 100644 --- a/docs-gen/content/rule_set/branches.md +++ b/docs-gen/content/rule_set/branches.md @@ -9,7 +9,7 @@ signals. A branch entry example is given below: -```YAML +```yaml Trunk: type: branch description: All signals related to the rear trunk diff --git a/docs-gen/content/rule_set/data_entry/allowed.md b/docs-gen/content/rule_set/data_entry/allowed.md index 184236b6..dabdbb04 100644 --- a/docs-gen/content/rule_set/data_entry/allowed.md +++ b/docs-gen/content/rule_set/data_entry/allowed.md @@ -10,7 +10,7 @@ It is expected, that any value not mentioned in the array is considered an error The datatype of the array elements is the `datatype` defined for the data entry itself. For `attributes` it is possible to optionally set a default value. -```YAML +```yaml SteeringWheel.Position: datatype: string type: attribute @@ -46,7 +46,7 @@ The actual value of the signal is expected to contain a subset of the values spe Example: -```YAML +```yaml DogBreeds: datatype: string[] type: attribute diff --git a/docs-gen/content/rule_set/data_entry/attributes.md b/docs-gen/content/rule_set/data_entry/attributes.md index 8c07b264..f79b69fc 100644 --- a/docs-gen/content/rule_set/data_entry/attributes.md +++ b/docs-gen/content/rule_set/data_entry/attributes.md @@ -18,7 +18,7 @@ or else it should be defined as a sensor instead. Below is an example of a complete attribute describing engine power -```YAML +```yaml MaxPower: datatype: uint16 type: attribute @@ -31,19 +31,19 @@ It is possible to give default values also for arrays. In this case square brack Example 1: Empty Array -```YAML +```yaml default: [] ``` Example 2: Array with 3 elements, first element has value 1, second element value 2, third element value 0 -```YAML +```yaml default: [1, 2, 0] ``` Full example, array with two elements, first with value2, second with value 3: -```YAML +```yaml SeatPosCount: datatype: uint8[] type: attribute diff --git a/docs-gen/content/rule_set/data_entry/data_types.md b/docs-gen/content/rule_set/data_entry/data_types.md index 76a39eb8..0746ba95 100644 --- a/docs-gen/content/rule_set/data_entry/data_types.md +++ b/docs-gen/content/rule_set/data_entry/data_types.md @@ -37,7 +37,7 @@ definition*, wherein it's specified. By default the size of the array is undefin By the optional keyword `arraysize` the size of the array can be specified. The following syntax shall be used to declare an array: -```YAML +```yaml # Array of datatype uint32, by default size of the array is undefined datatype: uint32[] # Optional: specified number of elements in the array @@ -62,7 +62,7 @@ corresponding data stream. A camera can be a good example of it. The Data Entry for the camera and the corresponding video stream could look like: -```YAML +```yaml Camera: type: branch description: Information about the camera and how to connect to the video stream diff --git a/docs-gen/content/rule_set/data_entry/data_types_struct.md b/docs-gen/content/rule_set/data_entry/data_types_struct.md index 26973065..d30d24cb 100644 --- a/docs-gen/content/rule_set/data_entry/data_types_struct.md +++ b/docs-gen/content/rule_set/data_entry/data_types_struct.md @@ -102,7 +102,7 @@ This is not a problem as it always from context is clear whether a name refers t This could be a hypothetical content of a VSS datatype file -``` +```yaml Types: type: branch @@ -123,7 +123,7 @@ Types.DeliveryInfo.Receiver: This struct definition could then be referenced from the VSS signal tree -``` +```yaml Delivery: datatype: Types.DeliveryInfo type: sensor @@ -131,7 +131,7 @@ Delivery: The datatype file may contain sub-branches and `#include`-statements just like regular VSS files -``` +```yaml Types: type: branch @@ -168,7 +168,7 @@ They may support read of parts of signal, e.g. `DeliveryList.Receiver` It is allowed to use a struct type in an array -``` +```yaml DeliveryList: datatype: Types.DeliveryInfo[] type: sensor @@ -178,7 +178,7 @@ DeliveryList: By default the array has an arbitrary number of element and may be empty. If a fixed size array is wanted the keyword `arraysize` can be used to specify size: -``` +```yaml DeliveryList: datatype: Types.DeliveryInfo[] arraysize: 5 @@ -201,7 +201,7 @@ For array datatypes (like above) VSS implementations may support several mechani It is allowed to refer to a structure datatype from within a structure -``` +```yaml OpenHours: type: struct description: A struct datatype containing information on open hours @@ -245,17 +245,16 @@ The order of declaration/definition shall not matter. As signals and datatypes are defined in different trees this is a topic only for struct definitions referring to other struct definitions. A hypothetical example is shown below. An item in the struct `DeliveryInfo` can refer to the struct `OpenHours` even if that struct is defined further down in the same file. -If using `-vt < file>` multiple times all files except the first will be treated similar to overlays. +If using `--types ` multiple times all files except the first will be treated similar to overlays. This means that is allowed to define `A.B.C` in multiple files, but then subsequent (re-)definitions will overwrite -what has been defined previously. +what has been defined previously. Note that if type files want to use structs from other files that the dependent +files are specified first. Therefore the order of given type files matters. -``` +```yaml DeliveryInfo: type: struct description: A struct datatype containing info for each delivery -... - DeliveryInfo.Open: datatype: OpenHours type: property @@ -264,9 +263,6 @@ DeliveryInfo.Open: OpenHours: type: struct description: A struct datatype containing information on open hours - -... - ``` ## Inline Struct diff --git a/docs-gen/content/rule_set/data_entry/data_units.md b/docs-gen/content/rule_set/data_entry/data_units.md index 45c46c3e..196dd9e7 100644 --- a/docs-gen/content/rule_set/data_entry/data_units.md +++ b/docs-gen/content/rule_set/data_entry/data_units.md @@ -9,7 +9,7 @@ weight: 20 It is in VSS possible for signals to specify a unit of measurement from a list of predefined data units. For most signals in the VSS standard catalog, a data unit has been selected. A typical example is `Vehicle.Speed`, as shown below. -``` +```yaml Vehicle.Speed: datatype: float type: sensor @@ -26,6 +26,7 @@ as `km/h` (with float as datatype). A user interface or API may show or request and a transport protocol may send speed in another unit, possibly also involving scaling and offset. But in protocols not explicitly specifying data units (like [VISS](https://raw.githack.com/w3c/automotive/gh-pages/spec/VISSv2_Core.html)) it is expected that `Vehicle.Speed` is sent and received as `km/h` (without scaling or offset). +However since units define possible `allowed-datatypes` the given `datatype` has to match the allowed ones. VSS does not offer any syntax for defining alternative units for a specific signal. The VSS project has specified for all units a corresponding quantity e.g. `velocity` for `km/h`. @@ -36,7 +37,7 @@ the quantity `velocity`, it is not specified how they relate to each other. In some cases it is natural to omit the data unit. This concerns typically signals where datatype `string` is used, but also signals where the value just represents a number (dimensionless quantities), like in the example below: -``` +```yaml Vehicle.Cabin.DoorCount: datatype: uint8 type: attribute @@ -51,7 +52,7 @@ In some cases, the definition on how to calculate the signal value is obvious, l below. It is likely that all VSS users will calculate fuel level in the same way, i.e. the meaning of a fuel level of 50% is well agreed, the liters of fuel in the tank is exactly 50% of nominal capacity. -``` +```yaml Vehicle.Powertrain.FuelSystem.Level: datatype: uint8 type: sensor @@ -69,7 +70,7 @@ Some vehicles might monitor actual wear, others might estimate it based on vehic This is in VSS called a logical range, a VSS user knows what range to use but are free to define the formula for calculating the value. Values from different vehicles (of different make/model) can not always be compared, as the formula used for calculation may differ. -``` +```yaml Vehicle.Powertrain.Transmission.ClutchWear: datatype: uint8 type: sensor @@ -81,8 +82,8 @@ Vehicle.Powertrain.Transmission.ClutchWear: ## Supported Data Units in VSS Standard Catalog The VSS syntax does not in itself specify what units can be used, the unit attribute as declared for signals in *.vspec files is optional and can contain an arbitrary string value. -[VSS-Tools](https://github.com/COVESA/vss-tools) however require that all units used are defined, -and at is also a requirement for signals in the VSS standard catalog. +[VSS-Tools](https://github.com/COVESA/vss-tools) however require that all units used are defined +and therefore is also a requirement for signals in the VSS standard catalog. Units are defined by including them in a unit file with syntax as described below. One or more unit files can be specified by the `-u` parameter and, if not given, the tools search for a file `units.yaml` in the same directory as the root *.vspec file. @@ -129,7 +130,7 @@ using different units but defined with the same quantity. Example: -``` +```yaml m: definition: Length measured in meters unit: meter @@ -158,8 +159,7 @@ The `deprecation` keyword can be used to indicate that a specific unit may be re Tooling shall preferably give a warning if a signal uses a deprecated unit or the unit used belongs to a deprecated quantity. The reason should preferably list when and why the unit is deprecated, a hypothetical example is given below: -``` - +```yaml inch: definition: Distance measured in inches unit: inch @@ -171,29 +171,14 @@ The reason should preferably list when and why the unit is deprecated, a hypothe quantity: distance ``` - -The unit syntax has recently been changed. To simplify transition to the new syntax it is recommended that -tooling also supports unit files using the old syntax described below. - -``` -units: - [ - : # Typically unit abbreviation, like km/h or mm, but - label: # Replaced with "unit" - description: # Replaced with "definition" - quantity: - ]* -``` - ## Quantity file syntax -Defining quantities is recommended, but currently optional for backward compatibility reasons. +Defining of quantities is required. If tooling supports quantity files it can verify that all units provided in unit files use defined quantities. For the VSS standard catalog it is required that matching quantities have been defined for all units. ``` - [ : # Identifier preferably taken from a standard, like ISO 80000 definition: @@ -226,9 +211,7 @@ As this unit is not commonly used and not described in any standards, it might b That is however only informative, as it a custom unit a downstream implementation supporting unit conversion may not support automatic conversion of furlong to other units. - - -``` +```yaml units: furlong: definition: Length measured in furlong, 1 furlong equals 201.1680 m 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 cee4d6c2..89251fdc 100644 --- a/docs-gen/content/rule_set/data_entry/sensor_actuator.md +++ b/docs-gen/content/rule_set/data_entry/sensor_actuator.md @@ -11,7 +11,7 @@ Actuators are used to control the desired value of a property. Some properties i A data entry for a sensor or actuator defines its members. A data entry example is given below: -```YAML +```yaml Speed: type: sensor description: The vehicle speed. diff --git a/docs-gen/content/rule_set/includes.md b/docs-gen/content/rule_set/includes.md index 58011738..32d781a8 100644 --- a/docs-gen/content/rule_set/includes.md +++ b/docs-gen/content/rule_set/includes.md @@ -6,7 +6,7 @@ weight: 6 An include directive in a vspec file will read the file it refers to and the contents of that file will be inserted into the current buffer in place of the -include directive. The included file will, in its turn, be scanned for +include directive. The included file will, in its turn, be scanned for include directives to be replaced, effectively forming a tree of included files. @@ -21,6 +21,8 @@ The include directive has the following format: #include [prefix] The `````` part specifies the path, relative to the file with the ```#include``` directive, to the vspec file to replace the directive with. +Additionally, include paths to search for the file can be added when using `vss-tools` using the `-I/--include-dirs`. +The order of include paths to be searched is first the relative path of the vspec specifying the include and then given include paths in the given order. The optional ```[prefix]``` specifies a branch name to be prepended to all signal entries in the included file. This allows a vspec file diff --git a/docs-gen/content/rule_set/instances.md b/docs-gen/content/rule_set/instances.md index f18967ea..36d56e9f 100644 --- a/docs-gen/content/rule_set/instances.md +++ b/docs-gen/content/rule_set/instances.md @@ -55,7 +55,7 @@ example for details. The example from above in the specification: -```YAML +```yaml # Cabin.vspec Door: type: branch @@ -73,7 +73,7 @@ Door.SomeSignal: ``` -```yml +```yaml # SingleDoor.vspec # @@ -103,7 +103,7 @@ instance definitions, then the last found definition will be used. As an example, if three row of doors are needed, then the default VSS instance definition can be overridden by redefining the Door branch as shown in the example below. -```YAML +```yaml #Redefinition changing number of rows from 2 to 3 #The redefinition must appear "after" the original definition Vehicle.Cabin.Door: @@ -126,7 +126,7 @@ and that offers heating for both windshields. But that is not the case for all v it is not even certain that all vehicles have two windshields. This sections gives recommendations on how to use VSS for a vehicle if the VSS specification does not offer an exact match of the capabilities of the vehicle. -```YAML +```yaml Windshield: type: branch instances: ["Front", "Rear"] @@ -159,7 +159,7 @@ of the following methods are recommended: - Redefine the branch. If a vehicle for example does not have a rear windshield then append a redefinition at the end of the VSS: -```YAML +```yaml Vehicle.Body.Windshield: type: branch instances: ["Front"] diff --git a/docs-gen/content/rule_set/overlay.md b/docs-gen/content/rule_set/overlay.md index 616fc402..7e04e011 100644 --- a/docs-gen/content/rule_set/overlay.md +++ b/docs-gen/content/rule_set/overlay.md @@ -30,12 +30,16 @@ and modify the standard catalog in a standardized way. 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. +the original specification. Before you start you should know: +- **Overlay files do not need to be valid specification files by themselves but the merged result counts** + In practice that means, that nodes in the overlay files (e.g. branches) do not need + to specify all the required attributes (like `type`, `description`, ...) if they are supposed to overwrite certain attributes + of an already existing branch in vss. - **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 + However, the tooling does not allow implicit branches by design. + So if you are creating new branches in overlays they need to be correctly linked + to an existing branch in vss. +- **Order matters.** The order on how the overlay files are passed 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 @@ -45,9 +49,11 @@ separate overlay files, an example call of the tooling and the resulting tree. *Figure: Overview on how overlays work within VSS* -```YAML +```yaml # In this overlay all parent branches are included. -# That is not mandatory, as tooling supports implicit branches. +# If you do not want to change existing branches, it is not necessary to specify them. +# Also note that some elements are missing required attributes (description) +# but since those elements will be merged with the ones in VSS, the result is valid. Vehicle: type: branch @@ -73,11 +79,10 @@ Vehicle.Cabin.Door.IsOpen: ``` *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. +```yaml +# This overlay would not be valid on its own since `NewBranch` is missing. +# When being applied in conjunction with the previous overlay, it would create +# `HasNewAttribute` accordingly. Vehicle.Cabin.NewBranch.HasNewAttribute: #< ...with a new attribute type: attribute @@ -95,22 +100,17 @@ Vehicle.Cabin.Door.IsOpen: ### Node content in Overlays If you are adding a node you need to specify all attributes required for that node type. -If you are changing an existing node you typically only need to specify name and what is changed, -like in the `Vehicle.Speed` example below. -Vss-tools will then look up the node name and reuse existing definitions. -An exception is if you are changing a node for a particular instance. -In that case you need to give `type`and `datatype`even if they are not changed, -as the lookup mechanism currently cannot extract them from the existing definition. - -```YAML +If you are changing an existing node you typically only need to specify the name and what you would like to overwrite, +like in the `Vehicle.Speed` example below. That also works for overwriting nodes that are created using `instances`. +`vss-tools` will then look up the node name and merges the attributes. + +```yaml # Type and Datatype not needed Vehicle.Speed: unit: m/s -# Type and Datatype needed as overlay affects a particular instance +# Overwriting the unit of a node created by instances also works Vehicle.Occupant.Row1.DriverSide.HeadPosition.Yaw: - type: sensor - datatype: float unit: mm ```