DomainConversionTool

README

Domain Conversion Tool (DCT)

It is the responsiblity of the feeder to convert a data point tha is transitioning between the northbound "VSS domain" and the southbound "Vehicle domain". The instructions for how a specific data point shall be converted is read by the feeder from a data structure containing this information that the feeder reas from file at startup. The creation of this file has been done "off line" previously by the DCT. The input to DCT for how to generate this data structure comes from three YAML files:

• A file containing the description of signals for the northbound side (VSS domain).
• A file containing the description of signals for the southbound side (Vehicle domain).
• A file containing a mapping of signals from respective domain.

The description must use the syntax as specified by VSS. It can contain a complete tree with branches, or only the leaf nodes. Before the signal descriptions there must be a line giving the name of the domain:
Domain: name-of-domain
An example of a southbound domain description is shown in the figure below.
The mapping file must first define the names of the northbound and southbound domains, respecively:
NorthBoundDomain: name-of domain
SouthBoundDomain: name-of domain
This is followed by the Mapping array of elements that each contain the North signal name and the South signal name that creates a mapping pair.
Mapping:

• North: signal-name
  South: signal-name
  
• North: signal-name
  South: signal-name
  An example of a mapping file is shown below.
  
  The DCT directory contains three signal description files:
  

• CAN-v0.1.yaml // A southbound domain example describing 5 CAN signals
• VSS-v0.1.yaml // A northbound domain example describing 6 VSS signals
• VSS-v4.1.yaml // An example of a complete tree generated by the VSS-tools YAML exporter with the standard VSS release 4.1-dev spec as input.

The directory also contain a mapping file example for mapping signals from the CAN-v0.1 domain with signals from the VSS-v0.1 domain.

• MAP-VSSv0.1-CANv0.1.yaml

For scaling due to different units representing the data of the two domains the DCT reads a file containing linear scaling coefficients. This file can be augmented with more unit scalings than its current examples.

• UnitScaling.yaml

DCT provides the following operations, that are selected by adding a command parameter to the DCT start command.

• domains // displays the domains that have been imported by the tool, i. e. that are stored in tables of the tool database.
• datamodel // displays the domains that have been imported by the tool, i. e. that are stored in tables of the tool database.
• import // reads a file containing signal descriptions of a domain and stores it in a table given the name of the domain.
• join // creates a conversion preparation table according to a mapping file, using data from domain tables i nthe DB.
• createfiles // creates the feeder instruction file for the domain that are mapped in the convesrion prepaation table, and a VSS tree of the signals in the northbound domain.

The typical work flow of the DCT to create the files needed by the feeder and the server to configure a complete "end-to-end" VISSv2 tech stack (from VISSv2 client to Vehicle interface client) is the following.

1. Create the northbound and southbound domain signal description files.
2. Create the mapping file that maps together selected signals from the northbound and southbound domains.
3. Import the northbound domain.
4. Import the southbound domain.
5. Join northbound and southbound domain signals according to the mapping data.
6. Create the feeder conversion instruction file of the joined signals from the northbound domain.
7. Apply the YAML format datamodel from 5. as input to the binary exporter of the VSS-Tools.

Steps 1. and 2. do not involve the DCT, how these files are created is not described here. These files must not be created from scratch every time, the domain signal description files can be a superset of what is being mapped.

Steps 3. and 4. are not needed if the domains already have been imported. Additional signals can be imported to an already imported domain. Duplicates of already imported signals are ignored, the DCT just logs it.

Step 5. reads data from the domain signals tables as specified by the mapping file and populates a Conversion peparation table. This table has a column named "conversionIndex" which must not contain the value 65535. If it does, the DCT has failed in joining the conversion instructions for a pair of signals. It may therefore be a good idea to inspect this table using any tool that can browse an SQLite database before continuing with the next step. How to resolve this error is not obvious, one possibility is to delete the mapping entry for this signal pair in the mapping file. That is however not a robust solution as it means this signal pair cannot be converted by the feeder, and are thus not accessible to the VISSv2 client. A more robust solution would be to analyze the reason for the DCT failure, and then to update the DCT logic for this step so that it does not fail. Step 5. also creates two files:

• A JSON file containing feeder information related to the feeder scaling operation. It is given the name "Scaling-nbd-sbd.json", where nbd and sbd are the northbound and southbound domain names respectively.
• A YAML file containing the datamodel for the mapping signals related to the northbound domain. It is given the name "Datamodel-nbd-sbd.yaml", where nbd and sbd are the northbound and southbound domain names respectively.

For more information about the content of these files, see the feeder README

Step 6. could have been merged with step 5., but as mentioned the tool may fail in some cases, and then this separation makes it possible to inspect the "conversionIndex" column of the Conversion preparation table before eventually creating the main conversion instruction file. When created, the file is given the name "nbd-sbd.cvt", where nbd and sbd are the names of the northbound and southbound domains,respectively.

Step 7. creates the binary tree representation of the northbound domain, which should then be stored in the directory of the VISSv2 server executable, renamed to "vss_vissv2.binary".

The other two files that were generated by the DCT are stored in the directory of the feeder executable. The feeder can at startup be configured to read their given file names, or else the files can be renamed to the names that the feeder tries to read per default, "VssVehicle.cvt" and VssVehicleScaling.json".

For more information about the files, see the README in the feeder-template directory.

DCT limitations

This first version of the DCT has some known limitations that are expected to be mitigated in later versions.

• Arrays in the YAML input files cannot use the syntax [elem1, .., elemN] but must be represented as

 - elem1
 ..
 - elemN

• Signals from respective domains with number datatypes must have the same datatype, i.e. a uint8 in the northbound domain can only be mapped to a uint8 in the southbound domain.
• Signals with allowed data restrictions must be defined with its elements in the same order in both domains, and with the same number of elements.
• Booleans must on the southbound side be represented by the string values "0" or "1" as the logical values false or true.
• The unit scaling is limited to the definitions in the UniScaling.yaml file. As an example, if the first defined element in one domain logically represents OFF then th first element in the other domain must also logically represent OFF.
• It is not possible to delete either single data point entries in a domain, nor entire domains. This can of course be done by using some other SQLite tool capable of it.
• Signals having array datatypes cannot be processed by DCT.