Commercial Vehicle Information Specifications
Overview
The ambition of the CVIS project is to develop a framework that can be used to define signal trees for different vehicle types, and then to use this framework to develop signal trees for vehicle types as e. g. Trucks, Trailers, Buses, and Passenger cars. The trees for these vehicle types shall share as much as possible of signals that can be commonly defined. The basis for common signals shall be the VSS tree. This tree has a focus on signals for passenger cars, but a significant part of these can very well be shared with the other vehicle types.
The CVIS project uses the Resource profile of the Hierarchical Information Model [HIM), which is fully compatible with the VSS rule set.
The basis of the framework that can be used to define signal trees for different vehicle types is the HIM configurator. It works as a pre-processor that reads the extended vspec format, vspec2, and processes the extended instruction set described below from which it generates vspec formatted files which are applied as input to the VSS-tools exporters to generate fully configured trees for desired vehicle types and models.
The HIM configuration instructions are declared in JSON formatted files. These instructions can be applied to trees that have a pre-configured vehicle type specific structure, or that have a vehicle type agnostic structure. The VSS-core tree is an example of the latter, while the other trees in the Vehicle directory have a pre-configure vehicle type specific structure.
A tree, whether it is vehicle type specific or not, shall be located on the spec/trees directory structure. These trees may then link to common objects which shall be located on the spec/objects directory structure.
The linking to common objects use the symbolic linking file system feature, which have differen syntax in Linux and Windows, see more in the Symlink chapter below.
Symbolic linking
The directory structure for a single tree follows the VSS pattern with “#include” links in the vspec files that logically links to other files of the tree. However, to link to a file in the common objects structure the corresponding file in the trees structure is realized as a symbolic link file. This means that when the content of the file is accessed the underlying file system follows the symbolic link to the file in the objects structure for the actual content of the file. This is transparent to the entity accessing the file, so e. g. the exporter tools from VSS-tools will when used for a transformation of a specific tree access file content from the common objects files transparently.
The symbolic links used in a tree structure definition shall be declared in a script file that can be run to refresh the symlinks if a link is broken. The syntax of these script files differ between Linux and Windows, see the chapter below.
Linux / Windows specific parts
Symlink script files
The symlink cript files used in Linux are standard bash script files, see e. g. cv-truck-symlinks.sh.
For Windows a Powershell script is used, see e. g. cv-truck-symlink.ps1 script in the Win-setup directory.
VSS-tools activation
The HIM configurator activates the VSS-tools exporter via a Makefile.
In Windows the setup for VSS-tools activation is done by following the instructions found in the Win-setup directory.
HIM configurator
The framework also contains a new tool, the HIM configurator. This tool is pre-processes vspec2 files to generate vspec files that are then used as input to the VSS-tools exporters. In its current version it provides support for the types of tree configuration that is described in the HIM extensions chapter below.
HIM extensions
The HIM syntax is in this project extended with the features described below. These can be preprocessed by the HIM configurator which transforms them into a HIM compliant format, thus making it possible to use the SS-tools for exporting to other formats. If these extensions are found to be useful it is likely that they will become included in the HIM standard rule set for resurce data.
The rules for when the file extension “vspec2” shall be used instead of “vspec” are the following:
- A file that contains any extended syntax must be named with the file extension “vspec2”
- If a vspec2 file is referenced from within another file then this reference shall use the extension vspec if this file is located in the “trees” directory strucure.
- If a vspec2 file is referenced from within another file then this reference shall use the extension vspec2 if this file is located in the “objects” directory strucure.
Extension 1: Variability configuration
The tree in vspec format may contain multiple variations of objects that in a deployment typically are not included. An example are the Combustion engine and the Electric engine. in an ICE vehicle the former should be included, but not the latter. For an EV vehicle it is vice versa. To enable one or the other of these objects to be included the following syntax is used, example taken from the Engine.vspec.
VariationPoint: #EngineType
- ICE #include CombustionEngine.yaml Engine
- EV #include ElectricEngine.vspec Engine
The keyword is VariationPoint, which on the same line must be followed by a hash sign (#) directly followe by a unique variation point tag (in this case EngineType. The value part of this key-value expression is an array of ‘variability object expressions’, where such an expression contains a ‘variability name’ followed by an ‘#include expression’. This expression must be compliant with the syntax rules for HIM #include expressions. The array size is not restricted.
The input to the HIM configurator for it to resolve which variations to select is found in two files.
- The Variability.json file,
- and the himConfiguration.json file.
The Variability.json file defines the available variations, and which include statements that should be selected for the variation. As can be seen in th PHEV variation example below it is possible to select multiple include statements.
"EngineType": [
{
"PHEV": [
"ICE",
"EV"
]
}
The himConfiguration.json file contains the variation that that should be included in the tree that is generated by the himConfigurator (using a VSS-tools exporter), expressed by the rows below in this example:
"variants": {
"EngineType": "PHEV"
Extension 2: Instantiation configuration
The HIM rule set supports the instantiation syntax inherited from VSS instantiation that can be used to request the VSS-tools to generate multiple instances of a branch/set of signals. This syntax has two options exemplified below
- instances: [“DriverSide”, “PassengerSide”]
- instances: Row[1,2] The examples above can be extended to two dimensions by using the array syntax, e.g.
instances:
- Row[1,2]
- ["DriverSide", "PassengerSide"]
which will generate a structure with four branches - Row1:DriverSide, Row1:PassengerSide, Row2:DriverSide, Row2:PassengerSide. It is however not possible to use this syntax to express a configuration where for Row1 there are two child nodes, e.g. [“DriverSide”, “PassengerSide”], and for Row2 there are three child nodes, e. g. [“DriverSide”, “Middle”, “PassengerSide”].
This missing flexibility is however provided in the extended syntax supported by the HIM configurator. A two-dimensional instantiation is then expressed in the vspec file as:
instances0: x #instanceTag
instances1: x #instanceTag
where ‘instances0’ is used for the ‘first-order’ instantiation (Row[1,2] in the example above), and ‘instances1’ is used for the ‘second-order’ instantiation ([“DriverSide”, “PassengerSide”] in the example above).
‘x’ is a placeholder for the instance expression in the file himConfiguration.json that is the input to the HM configurator, and ‘instanceTag’ is a unique name logically linking the two expressions, which must be preceded by a hash character (#). The two instance expressions can, but must not be on two subsequent rows. If not, then the second expression must be defined in any of the nodes that is part of the subtree under the node containing the first expression. The instance configuration input to the HIM configurator has a syntax as exemplified below.
"instances": {
"Seat": [
"Row[1,2]",
[
[
"DriverSide",
"PassengerSide"
],
[
"DriverSide",
"Middle",
"PassengerSide"
]
]
]
}
The ‘Seat’ shown above is the instanceTag name that the HIM configurator will try to match in the vspec file.
The ‘first-order’ instantiation, in this case “Row[1,2]”, is followed by two ‘second-order’ instantiation expressions.
The number of ‘second-order’ expressions must match the number of instantiaions that the ‘first-order’ expression will expand to.
The expressions can use any of the two syntax options mentioned above.
Currently this syntax can only be used for two-dimensional instantiations.
Extension 3: Local variation point
If an instantiation configuration has a need of including a variation point with different variants for the different intances then the Variation point feature described above cannot be used as it would apply the same variant to all instances. To meet this need the Local Variation point (LocalVP) is available. An expression like shown below is inserted in the subtree to be instantiated
LocalVP: #AxleFeature
- LIFTABLE #include Liftable.vspec Axle
- STEERABLE #include Steerable.vspec Axle
- DRIVING #include Driving.vspec Axle
The himConfiguration.json file is then updated with the different configurations for the different instances as shown below.
"variants": {
"AxleFeature.Row1": "AXLE+STEER",
"AxleFeature.Row2": "AXLE+LIFT",
"AxleFeature.Row3": "AXLE+STEER+DRIVE"
}
As seen the AxlePoint local varation point name is extended with the names of the different instances Row1..Row3, which must be the same as the instantiation is configured with. The Variability.json shall then contain the definition of which include alternatives in the LocalVP command that shall be included.
"AxleFeature": [
{
"AXLE": ""
},
{
"AXLE+LIFT": "LIFTABLE"
},
{
"AXLE+STEER": "STEERABLE"
},
{
"AXLE+DRIVE": "DRIVING"
},
{
"AXLE+LIFT+STEER": [
"LIFTABLE",
"STEERABLE"
]
},
{
"AXLE+LIFT+DRIVE": [
"LIFTABLE",
"STEERABLE"
]
},
{
"AXLE+STEER+DRIVE": [
"STEERABLE",
"DRIVING"
]
},
{
"AXLE+LIFT+STEER+DRIVE": [
"LIFTABLE",
"STEERABLE",
"DRIVING"
]
}
]
With the above in place the HIM configurator will create the different variants for the different instances.
Extension 4: Allowed datatype reference
One of the information rule sets that HIM supports is the type definition rule set. A type definition tree is able to define structs and enums (allowed) that can be referenced from trees of other information types. Such a tree is defined in the spec/objects/Datatypes directory, currently containing the enums (allowed) that is used in the VSS tree. This tree has a structure that mirrors the structure from the VSS tree where the enums were originally used. This structure might later be changed to a more generic structuring to yield reference path names more decoupled from the VSS structure.
An external datatype reference to an enum (allowed) shall have a syntax as shown below.
datatype: Datatype.x.y.zValues
where x, y, z may be names providing an understanding of the defined enum (allowed) that conform to the node HIM node name syntax. The name z must be postfixed with the tag Values.
If the HIM configurator is used to substitute external enum (Allowed) references it will create a Datatype.yaml file in the root directory of the signal tree that it is working on. The node type in a type definition tree shall be ‘property’ but due to that the VSS-tools will reject separate trees with that node type, the node type ‘sensor’ is used instead. This must therefore be manually edited to rename to ‘property’ until a moodified version of VSS-tools is created, or that the HIM configurator is updated to handle the node type renaming.
Extension 5: Configuration of default or description values
The configuration of default o description values are stored in a JSON file in the root directory of the tree, using the syntax described below. This file is included as input to the HIM configurator by the CLI parameter -v. As an example see configValues-truck.json.
Default values
The HIM rule set supports inclusion of default values in the node definitions. This is mainly meant to be used for nodes of the node type attribute, but can also be applied to the node types sensor and actuator. To define that a node shall be configured with a default value, a JSON expression like the example below must be added to a JSON file stored in the tree directory.
{
"default": [
{
"path": "Vehicle.Cabin.DoorCount",
"value": "6"
}
]
}
The default configuration file is specified in the CLI command when starting the HIM configurator following the -d tag.
If the tree already has a default value for a node that is in the list it will be replaced by the new value, otherwise a default line is added to the node.
Description values
When the instantiation feature is used it may be that the descriptions of the instantiated nodes needs to be updated with unique descriptions. The HIM configurator handles this in the same way as it handles the default updates, with the difference that the JSON object key-value shall be “description” instead, see below.
{
"description": [
{
"path": "Vehicle.Chassis.Axle.Row1",
"value": "A description of the first axle"
}
]
}
Tree development
The HIM rule set for resource data is used to define signals in a tree. This syntax can be directly used as input to any of the exporter tools provided by VSS-tools.
Trees under development
Currently the following trees are under development:
The VSS-core tree is a vehicle type agnostic tree that is configured by the HIM configurator to become vehicle type specific. Configuration templates for the vehicle types Car and Truck are available, and can be used as starting poin to create templates for other vehicle types.
The other trees are vehicle type specific from the start, or for Driver a supplementary tree to be used together with e. g. the Truck tree.
Alignment with other standards
The terminology used in these HIM based specifications should try to align with terminology and principles from other standards. The cases that has been identified are described below.
Axle and tire locations
The ISO xxxx(number and link missing) specification includes a centerline based approach for commercial vehicles, see diagram below.
The ISO naming conventions shown in the figure above can be realized by providing the configuration shown below as input to the HIM configurator, and inserting the “instances0/1” directives in the related vspec files.
"instances": {
"Axle": [
"Row[1,4]",
[
["Pos7","Pos9"],
["Pos7","Pos9"],
["Pos6","Pos7", "Pos9","Pos10"],
["Pos8"]
]
]
}
Further references, e.g. TMC VMRS, Fleet location codes, etc…