Skip to content

VSS Layers Concept

Jump to bottom Edit New page
danielwilms edited this page Oct 17, 2021 · 8 revisions

VSS Layers

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. Those are the use cases we see:

  1. Adding new nodes: By adding nodes the standard catalog can be extended with proprietrary concepts.
  2. Change the value of existing metadata: The standard catalog defines metadata based on what is assumed to be an average vehicle. Configurations are different (e.g. instantiation), so this should be configurable.
  3. Adding new key/value pairs as additional metadata: Deploying VSS to a specific scenario, needs in many cases additional information. This should be enabled by the layer concept.
  4. Removing nodes or certain key/value pairs: Not every vehicle configuration needs the same set of nodes or metadata. Those should be removable.
  5. Multiple layer files: VSS layers can be split into several files in order to clearly separate concerns. In order to keep a determinstic result a clear order has to remain.

Create a new layer

The format for the layer file shall be the same as defined in VSS. 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

Nested file structures using the include statement is best suited, but not limited to, extensions with proprietrary signals.

ProprietrarySignalsLayer.vspec

# Content of ProprietrarySignalsLayer.vspec
MyNewBranch:
  type: branch
  description: Proprietrary branch
#include ProprietraryDetailedBranch.vspec MyNewBranch

ProprietraryDetailedBranch.vspec

# Content of ProprietraryDetailedBranch.vspec
MyNewActuator:
  type: actuator
  datatype: string
  description: My proprietrary actuator

Best Practice

Even when using a nested file structure, non-modified branches in the path to a layered node shall not be duplicated, but defined as prefix to the new/modified nodes.

ProprietrarySignalsLayer.vspec

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

ProprietrarySignalsLayer.vspec

# Content of ProprietraryDetailedBranch.vspec
MyNewActuator: #< newly defined actuator ($1)
  type: actuator
  datatype: string
  description: My proprietrary actuator

Using a flattened list of nodes

Similar to using #includes it's by definition allowed to create one file, using the dot notation to identify the nodes. Following the example above it would be:

OneFileLayer.vspec

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

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

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

#MEETING MINUTES

Functional Requirements

Add new nodes

  • Using different catalogs
  • Combine standard catalog with a proprietrary one
  • Private Branch equivalent, 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 in case of deployment
  • electrical vehicle not support other powertrain

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

Usage

Features

  1. When call the compiler, add additional folders and spec files for additional data structures to be included under the same root node.
  2. When call the compiler, add additional meta-data files
  3. Create stub files for adding metadata
  4. Define own spec files and add them during compile time under a specific subnode

Creation

How to call

Structure

Do we have to distinguish between nodes and metadata?

Add a custom footer
Clone this wiki locally