Vspec file structure

[erikbosch]

The vspec files are stored in https://github.com/COVESA/vehicle_signal_specification/tree/master/spec. To a high degree, but not completely, the file structure corresponds to the branch structure, but it is not consistent. I am thinking if we would benefit from creating a clear policy and change file structure accordingly. This would only affect in which files the signals reside, end result after using vss-tools should be the same.

Some ideas:

• Each branch shall normally have there own file, so that e.g. Vehicle.Body.Hood.IsOpen can be found in the file Vehicle/Body/Hood.vspec
• Files that just are used for inclusion and does not represent a branch like Identifier.vspec shall exist in an include branch, possibly Vehicle/include/Identifier.vspec or Vehicle/Body/include/Identifier.vspec, so that it is clear already from the file path that it does not represent a branch
• The top level Vehicle file (currently called VehicleSignalSpecification) should possibly be renamed to Vehicle and include only top level items (branches and signals). Today it refers to e.g. Vehicle.Powertrain.TractionBattery, it would be more logical if Vehicle.vspec only refers to Powertrain, and then Powertrain can refer to TractionBattery.

I would like feedback on if this seems reasonable.

[erikbosch]

Meeting notes:

• Ulf: Think it could be helpful, could make it easier to find signals
• Erik: Please review/comment, if no one object I might make a draft.

[elffjs]

I don't know if it's a goal for VSS, but: this would be useful for generating a Vehicle struct, which our company is doing.

You can do this now by, e.g., running protoc on the protobuf target; but it's difficult to organize the types for all of the branches, instances, and enums.

[erikbosch]

A possible restructure can be seen in boschglobal#20 (Note that only a subset of the files are restructured in that draft, but it shows how structure could look like after a restructure)

[erikbosch]

Meeting notes:

• Please review
• Check how prefix for includes are handled, can it be removed to reduce risk of errors

[erikbosch]

Following up on what was brought up yesterday by @kkoppolu1.

The general logic of the vspec files and #include syntax as of today is that there is no assumption made concerning which branch a signal belong to, so in the example below you explicitly need to state that Intensity belongs to Raindetection

Raindetection:
  type: branch
  description: Rainsensor signals.

Raindetection.Intensity:
  datatype: uint8
  type: sensor
  unit: percent
  max: 100
  description: Rain intensity. 0 = Dry, No Rain. 100 = Covered.

Similar for #include, if you want the content of SingleWindow.vspec to be added inside Window you need to specify Window as prefix, if not content will be added in parallel to Window. (Unless all content in SingleWindow.vspec start with Window. prefix, which typically is not the case as we want the included file to be independent.)

Window:
  type: branch
  description: Door window status

#include SingleWindow.vspec Window

So I think we cannot easily get rid of the prefix in includes. But we could definitively improve the checks, for example by actually checking that Window above exist as branch. We do not do that today, will create a Pull Request for that

[erikbosch]

We regularly close old issues and pull requests that appear to be abandoned or completed, where there have not been any activity for a long time. If you think your item is still relevant please feel to add a comment and re-open it. You are also very welcome to bring up the topic at one of our weekly VSS meetings.