Skip to content

VSS Layers Concept

Jump to bottom Edit New page
gunnarx edited this page Feb 23, 2022 · 8 revisions

VSS Layers [DRAFT]

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 Layers are meant to bring you a standardized way of handling those changes.

These are some usage patterns we see:

  1. Adding new nodes: By adding nodes the standard catalog can be extended with proprietary concepts.
  2. 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.
  3. Adding new key/value pairs as additional metadata: Extending the model is 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.
  4. Removing nodes or certain key/value pairs: Not every vehicle configuration needs the same set of nodes or metadata so they should be removable.
  5. 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.

Create a new layer

The fundamental format for a VSS layer file is the same as any other VSS-compliant file. VSS layers reference a signal by name and/or its location in a tree, and below the signal name are a set of metadata fields. It's assumed that the layers are defined in separate vspec files outside the standard catalog. There are two ways of defining the structure:

Using #include statement

Refer to the VSS documentation for how the include statement works and how the complete set of signals is built from multiple files. Layers that add additional signals are likely to follow a similar approach, by providing a parallel hierarchy of files (that get merged together with standard VSS catalog into one signal model):

Example of new branches/nodes in separate vspec files:

ProprietarySignalsLayer.vspec

# Content of ProprietarySignalsLayer.vspec
MyNewBranch:
  type: branch
  description: Proprietary branch
#include ProprietaryDetailedBranch.vspec MyNewBranch
# ^^^ contents of branch

ProprietaryDetailedBranch.vspec

# Content of ProprietaryDetailedBranch.vspec
MyNewActuator:
  type: actuator
  datatype: string
  description: My proprietary actuator

(The result of the above two files is to define a new signal in the position: MyNewBranch.MyNewActuator)

Best Practice

Even when using a nested file structure, non-modified branches in the path to a layered node need not be mentioned again. Instead of creating an include-structure it is then possible to use path prefix (whole or part-of) in the definitions where appropriate.

The following example shows modifying and adding new metadata of an existing signal (only if really necessary). It also shows specifying dot-separated path in some part of the definition, as opposed to the path being built up from multiple include statements:

ProprietarySignalsLayer.vspec

# Content of ProprietarySignalsLayer.vspec
Vehicle.Cabin.Sunroof.Position: #< modification of an existing node
  min: 0 #< modified min value (§2)
  proprietary: metadata #< new metadata added (§3)
Vehicle.Cabin.Infotainment.MyNewBranch: #< newly defined branch (§1)
  type: branch
  description: Proprietary branch
#include ProprietaryDetailedBranch.vspec MyNewBranch

ProprietarySignalsLayer.vspec

# Content of ProprietaryDetailedBranch.vspec
MyNewActuator: #< newly defined actuator
  type: actuator
  datatype: string
  description: My proprietary actuator

Using a flattened list of nodes

Above we proposed that layers could be in a hierarchical directory/file collection, just like the standard vspec. It's sometimes useful to use only the dot notation and the fully-qualified path to identify the nodes in a single-level file. Following the example above, a single file would look like this:

OneFileLayer.vspec

# Content of ProprietarySignalsLayer.vspec
Vehicle.Cabin.Sunroof.Position: #< modification of an existing node
  min: 0 #< modified min value (§2)
  prorietary: metadata #< new metadata added (§3)

Vehicle.Cabin.Infotainment.MyNewBranch: #< newly defined branch (§1)
  type: branch
  description: Proprietary branch

Vehicle.Cabin.Infotainment.MyNewBranch.MyNewActuator: #< newly defined actuator ($1)
  type: actuator
  datatype: string
  description: My proprietary actuator

MEETING MINUTES

Functional Requirements

Add new nodes

  • Using different catalogs
  • Combine standard catalog with a proprietary one
  • Equivalent of the private branch, but more generic

Change the value of existing meta data

  • As example default value, instances, min, max (does it have to be in standard?)
  • Mandatory data not meant to be changed (name, description, datatype (?)) / needs more work

Tickets

Add new key/value pairs as additional meta data

  • Add more metadata on existing nodes, metadata which is not defined in VSS

Tickets

Remove nodes

  • Remove nodes, for example to indicate that a certain deployment does not include them.
  • Electrical vehicle might remove the existence of combustion-engine related information.

Tickets

Remove existing key/value pairs from the meta data

  • Make a key being undefined

Multiple Layer Files

  • Useful in multiple scenarios (separation of concerns, e.g. deployment + privacy + access control)

The How

  • Format should be the same as in VSS
  • Long .-notation and include statement possible
  • Order of layers should matter,
  • Manifest file as optional way of configuration of layers, besides CLI
  • by flagging it's decided if:
    • tree is extended
    • metadata is changed
    • nodes/metadata are deleted

Removal of nodes

Various ideas:

Removal example, using empty value = removal

Motor.CoolantTemperature:
  datatype: int16
  type:              <- removes "type:" entirely (*if* we allow type to be removed)
  unit: celsius
  description: Motor coolant temperature (if applicable).

Removal example, using no meta-data = remove signal

Motor.CoolantTemperature:  <- removed because meta-data is empty

Vehicle.Powertrain.Transmission.Speed:
  datatype: int32          <- modified

Removal example, requires all signals to be named in "deployment file" otherwise they are not included (in a code generator for example):

"deployment file"

Motor.CoolantTemperature:   <- signal mentioned, therefore included
   deployment_stuff: foo

Tool invocation

Example with flags to define if it's a (m)odel or (R)emoval file:

 $ mytool -m vss_rel_2.yaml -m privacy_layer.yaml -m deployment_info.yaml -R stuff_to_remove.yaml

... in this case nodes listed in stuff_to_remove.yaml gets removed.

Example with flags to define if it's a (m)odel or (I)nclusion file:

 $ mytool -m vss_rel_2.yaml -m privacy_layer.yaml -m deployment_info.yaml -I deployment_whitelist.yaml

... in this case any node NOT listed in deployment_whitelist.yaml gets removed (not used in output).

Proposal: "Allow" tools to include equivalent of -R and -I flags, one or the other or both, depending on need.

Also support a manifest file instead of listing on command line

 $ mytool -f filelist.txt

filelist.txt example 1:

 vss_rel_2.2
 +vss_privacy_info
 +deployment
 -removed_signals

filelist.txt example 2:

 basemodel: vss_rel_2.2
 layer: vss_privacy_info
 modification: ...
 deployment: mydepl.yaml

filelist.txt example 3:

 model: vss_rel_2.2
 model: vss_privacy_info
 model: ...
 Removal: mydepl.yaml
Add a custom footer
Add a custom sidebar
Clone this wiki locally