(C) 2018 Volvo Cars
(C) 2016 Jaguar Land Rover
All files and artifacts in this repository are licensed under the provisions of the license provided by the LICENSE file in this repository.
VEHICLE SIGNAL SPECIFICATION
This repository specifies a data model that can be used in automotive applications to communicate different kinds of data that are relevant in an automotive context. The data model is adapted to handle both the signal data that is related to the various sensors and actuators on vehicle buses, and the type of data that is more commonly associated with the infotainment system, such as media data.
A standardized vehicle data specification allows an industry actor to use a common naming space for communication and, ultimately, abstracts underlying vehicle implementation details.
The representation of vehicle data specifications is vendor independent. Vendor-specific extensions can be specified in a dedicated and uncontrolled branch of the specification tree.
The format of the directories and specification files is aimed at allowing easy, git-based management with branching, merging, and release. With this in mind, the vehicle signal specification can be broken up into smaller files that can be edited and re-used while minimizing merge conflicts.
A released specification can be used, together with tools in this repository, to automatically generate a number of different target specification formats, such as JSON, FrancaIDL, etc.
Fig 1 shows the schematics of the top-level process.
The tools are available under the
The release management process will be driven in the context of GENIVI and its Remote Vehicle Interaction expert group.
BROWSE JSON VEHICLE SIGNAL SPECIFICATION
A variant of the vehicle signal specification is checked in
$VERSION is the content of
A web-based JSON viewer can be used to view the current version.
CREATE JSON VEHICLE SIGNAL SPECIFICATION
Make sure that you have the python YAML parser, PyYAML, installed.
INSTALL PYTHON YAML PARSER
sudo apt-get install python-yaml
On non-ubuntu systems, install from:
The results will be stored in
$VERSION is the contents of the
VERSION file and
the appropriate file extension for the type of output being produced. For
example, the JSON version of the output will have a
Changes to files under the spec/ directory results in changes to the generated
Hence, it is recommended to run
make, post spec/ file changes.
By default, the
make processor will produce all of the currently
installed output formats. If only a single format is desired, specify it as
an arguement. For example, to generate only the json format, type:
BRANCH, RBRANCH, SIGNAL, ATTRIBUTE, AND ELEMENT DEFINITION
Branches, rbranches, signals, attributes, and elements are organized into a tree such as outlined in Fig 2.
branch is an entity that can host other branches, signals, and attributes.
A branch is identified as an entry with its signal type set to
The only required field for a branch are
resource branch is an entity that can host only element nodes.
A resorce branch is identified as an entry with its node type set to
It can host zero or more element nodes, and it contains the format definition
of its element nodes. Besides the required fields
are also the following.
An rbranch child must be of the generic type
element, but it also has a uniquely specified part that can be referred to by the child type.
An rbranch child format is defined through a number of
properties, each property is defined by the attributes:
prop-nameThis is the key value used to refer to this property. An element must contain the properties named
uri<inherited from VIWI?>.
prop-descriptionThis is a description of the property.
prop-typeThis is the type of the property.
prop-formatThis is the format of this property.
prop-unitThis is the unit of this property.
prop-valueIf this property is a logical link to other elements, then the path to the rbranch of these elements is given here. The
idvalue of these elements are provided in a list.
Leaf nodes of the tree contain metadata describing the data associated to the node.
This specification makes a distinction between signals - in the following undefined
stream - and
The difference between a signal and an attribute is that the signal has
a publisher (or producer) that continuously updates the signal value while an
attribute has a set value, defined in the specification, that never changes.
As summary, besides
rbranch type can be:
attribute, which describes static read-only value.
sensor, which describes non-static read-only signal.
actuator, same as sensor plus the possibility of changing the value.
stream, data stream like video.
Each data entry specifies a
datatype from the following set
|UInt8||unsigned 8-bit integer||0||255|
|Int8||signed 8-bit integer||-128||127|
|UInt16||unsigned 16-bit integer||0||65535|
|Int16||signed 16-bit integer||-32768||32767|
|UInt32||unsigned 32-bit integer||0||4294967295|
|Int32||signed 32-bit integer||-2147483648||2147483647|
|UInt64||unsigned 64-bit integer||0||2^64|
|Int64||signed 64-bit integer||-2^63||2^63 - 1|
|Float||floating point number||-3.4e -38||3.4e 38|
|Double||double precision floating point number||-1.7e -300||1.7e 300|
|ByteBuffer||buffer of bytes (aka BLOB)||n/a||n/a|
Datatypes are not specified for
A signal can optionally be specified with a minimum and maximum limit, defining the valid range that the signal can assume.
A signal can optionally be specified with a set of allowed values that the signal can be assigned, effectively turning it into an enumerator. The values are of the same type as the signal itself.
|km/h||Speed||Kilometers per hour|
|m/s||Speed||Meters per second|
|rpm||Frequency||Rotations per minute|
|g/s||Flow||Grams per second|
|l/h||Flow||Liters per hour|
|m/s2||Acceleration||Acceleration in meters per second squared|
|cm/s2||Acceleration||Acceleration in centimeters per second squared|
|degree||Angle||Angle in degrees|
|degrees/s||Angular Speed||Angular speed in degrees/s|
|l/100km||Consumption||Liters per 100 km|
|ml/100km||Consumption||Milliliters per 100 km|
|V||Electrical||Potential difference in volt|
|A||Electrical||Current in amperes|
A data node specifying "function: attribute" must specify a static value of the correct type. Data nodes specifying and other function value must not specify a data value.
An element node must only be a child of an rbranch node.
Default and mandatory fields are
description, other mandatory fields are specified by
the property definitions in the rbranch parent.
NODE ADDRESSING CONVENTION
Tree nodes are addressed, left-to-right, from the root of the tree toward the node itself. Each element in the name is delimited with a period (".") .
For example, the dimming status of the rearview mirror in the cabin is addressed:
If there are an array of elements, such as door rows 1-3, they will be addressed with an index branch:
Cabin.Door.Row1.Left.IsLocked Cabin.Door.Row1.Left.Window.Position Cabin.Door.Row2.Left.IsLocked Cabin.Door.Row2.Left.Window.Position Cabin.Door.Row3.Left.IsLocked Cabin.Door.Row3.Left.Window.Position
In a similar fashion, seats are located by row and their left-to-right position.
Cabin.Seat.Row1.Pos1.IsBelted # Left front seat Cabin.Seat.Row1.Pos2.IsBelted # Right front seat Cabin.Seat.Row2.Pos1.IsBelted # Left rear seat Cabin.Seat.Row2.Pos2.IsBelted # Middle rear seat Cabin.Seat.Row2.Pos3.IsBelted # Right rear seat
The exact use of
PosX elements and how they correlate to actual
positions in the car, is dependent on the actual vehicle using the
If a signal is defined, all parent branches included in its name must be included as well, as shown below:
[Signal] Cabin.Door.Row1.Left.IsLocked [Branch] Cabin.Door.Row1.Left [Branch] Cabin.Door.Row1 [Branch] Cabin.Door [Branch] Cabin
The branches do not have to be defined in any specific order as long as each branch component is defined somewhere in the vspec file (or an included vspec file).
SIGNAL SPECIFICATION FORMAT
A signal specification is written as a flat YAML list, where each signal and branch is a self-contained YAML list element.
The YAML list is a single file, called a vspec file.
A vspec can, in addition to a YAML list, also contain include directives.
An include directive refers to another vspec file that is to replace the
directive, much like
#include in C/C++. Please note that, from a YAML
perspective, the include directive is just another comment.
A branch entry describes a tree branch (or node) containing other branches and signals.
A branch entry example is given below:
- Body.Trunk: type: branch aggregate: true description: All signals related to the rear trunk
The following elements are defined:
The list element name defines the dot-notated signal name to the signal. Please note that all parental branches included in the name must be defined as well.
branchspecifies that this is a branch entry (as opposed to a signal entry). This is the default, in case
Defines whether or not this branch is an aggregate. See aggregate branch chapter for more information.
If not defined, this defaults to
A description string to be included (when applicable) in the various specification files generated from this branch entry.
SENSOR/ACTUATOR DATA ENTRY
A data entry defines a single signal and its members. A data entry example is given below:
- Drivetrain.Transmission.Speed: type: sensor datatype: uint16 unit: km/h min: 0 max: 300 description: The vehicle speed, as measured by the drivetrain.
Defines the dot-notated signal name of the signal. Please note that all parental branches included in the name must be defined as well.
Defines the type of the node. This can be
The string value of the type specifies the scalar type of the signal value. See data type chapter for a list of available types.
The minimum value, within the interval of the given
type, that the signal can be assigned.
If omitted, the minimum value will be the "Min" value for the given type.
Cannot be specified if
enumis specified for the same signal entry.
The maximum value, within the interval of the given
type, that the signal can be assigned.
If omitted, the maximum value will be the "Max" value for the given type.
Cannot be specified if
enumis specified for the same signal entry.
The unit of measurement that the signal has. See Unit Type chapter for a list of available unit types.
This cannot be specified if
enumis specified as the signal type.
A description string to be included (when applicable) in the various specification files generated from this signal entry.
The sensing appliance used to produce the signal.
The actuating appliance consuming the signal.
ENUMERATED SENSOR/ACTUATOR DATA ENTRY
A data entry can optionally be enumerated, allowing it to be assigned a value from a specified set of values. An example of an enumerated signal is given below:
- Chassis.Transmission.Gear: type: sensor datatype: uint16 enum: [ -1, 1, 2, 3, 4, 5, 6, 7, 8 ] description: The selected gear. -1 is reverse.
An enumerated signal entry has no
enum element is an array of values, all of which must be specified
in the emum list. This signal can only be assigned one of the values
specified in the enum list.
type specifier is the type of the individual elements of the enum
An attribute is a signal with a default value, specified by
The value set for an attribute by a vspec file can be read by a consumer without the need of having the value sent out by a publisher. The attribute, in effect, is configuration data that can be specified when the vspec file is installed.
Below is an example of a complete attribute describing engine power
- MaxPower: type: attribute datatype: uint16 default: 0 description: Peak power, in kilowatts, that engine can generate.
The core signal specification can be extended with additional signals through the use of private branches, as is shown in Fig 3.
Fig 3. Extended signals
In this case the core signal specification,
included by a OEM-specific master vspec file that adds the two
Signals can, in a similar manner, be overridden and replaced with a new definition, as is shown in Fig 4.
Fig 4. Overridden signals
In this case, the
GearChangeMode signal provided by the core
specification lacks an additional semi-automatic mode featured by an
By having an OEM master spec file,
include the core spec file,
vss_23.vspec and then overriding
GearChangeMode signal and add the
element as an enumerated value
The signal extension mechanism described above is also used to declare an attribute in one vspec file and define it in another. This is used to setup a attribute structure standard in the core specification that is to be defined on a per-deployment (vehicle) basis.
An example is given in Fig 5.
Fig 5. Declaring and defining attributes
are declare in the
vss_23.vspec file with a default value of zero.
A project/vehicle specific vspec file,
then overrides the attributes with the correct values.
An include directive in a vspec file will read the file it refers to and the contents of that file will be inserted into the current buffer in place of the include directive. The included file will, in its turn, be scanned for include directives to be replaced, effectively forming a tree of included files.
See Fig 6 for an example of such a tree.
Fig 6. Include directives
The include directive has the following format:
#include <filename> [prefix]
<filename> part specifies the path, relative to the file with the
#include directive, to the vspec file to replace the directive with.
[prefix] specifies a branch name to be
prepended to all signal entries in the included file. This allows a vspec file
to be reused multiple times by different files, each file specifying their
own branch to attach the included file to.
An example of an include directive is:
#include doors.vpsec chassis.doors
door.vspec section specifies the file to include.
chassis.doors section specifies that all signal entries in
door.vspec should have their names prefixed with
If an included vspec file has branch or signal specifications that have already been defined prior to the included file, the new specifications in the included file will override the previous specifications.
REUSING SIGNAL TREES
Complete subtrees of signals and attributes can be reused by including them multiple times, attaching them to different branches each time they are included.
An example is given in Fig 7 where a generic door signal specification is included four times to describe all doors in the vehicle.
Fig 7. Reusing signal trees
door.vspec file is included four times by the master
The signals of
Open are attached
on the front left and right doors of row 1 (front) and row 2 (back).
door.vspec is changed, the changes will be propagated to all four doors.
SIGNAL ID DATABASES
vspec2vsi can also automatically create signal ID databases, essentially text files, that assign an ID to a particular signal.
To instruct any of the tools to create signal ID databases use the
vspec2json -i <prefix>:<database_file>:<start_id> vspec_file json_file
-i option can be specified any number of times to created different signal ID databases based on
<prefix. Signal IDs are positive integer values.
Prefix that is matched against signal names. The longest match will be used to determine the signal ID database the signal is stored into. For example, two signal ID databases are specified with
-i Attribute:vspec_attr.id:0 -i Attribute.Cabin:vspec_attr_cab.id:0. A signal named
Attribute.Chassis.Curbweightwill be stored in
vspec_attr.idwhile a signal named
Attribute.Cabin.Seat.DriverPositionwill be stored in the
The name of the database file.
The first ID value for a signal ID database. Note that the ID is only unique for the same database. If you use the
-ioption multiple times and would like to have unique IDs across all database files, you need to make sure to specify start IDs for each database so that there is no overlap.
The signal ID databases with their mappings of signal names to ID can be used for easy indexing of signals without the need of providing the entire qualified signal name. However, if vspec files are updated and new signals are added, the existing signal mappings must not change. If database files with mappings already exist, the tools first search them for a signal name and only assign a new signal ID if no existing mapping was found. The signal ID number continues from the highest ID found.
To avoid signal ID conflicts blocks of IDs are reserved as follows:
|Block First ID||Block Last ID||Description|
1 | 999,999 | reserved for standardized signals
1,000,000 | 1,199,999 | reserved for signals to be merged from the development branch 1,200,000 | 1,999,999 | currently unused 2,000,000 | 2,999,999 | private and unpublished signals
Private and unpublished signals are not expected to conflict with each other as it is not deemed to be likely that private signals from different entities are going to be used within the same signal tree.