Vehicle Signal Specification standard building on the work done by W3C / AMB.
Python C Makefile
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

(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.

Further, the repository also specifies sets of data in different domains, such as the Car domain and the Media domain, that are expected to be of common interest for automotive applications.

A standardized vehicle data specification allows for an industry actor to use a common naming space for communication and, ultimately, abstracts underlying vehicle implementation details.

The collection of vehicle data specifications is vendorindependent. 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 data 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.

Signal tree
Fig 1. Generating documents from specification

The tools are available under the tools directory.

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 data specification is checked in as vss_$VERSION.json, where $VERSION is the content of the VERSION file.

A web-based JSON viewer can be used to view the current version.

Click here

CREATE JSON VEHICLE SIGNAL SPECIFICATION

Make sure that you have the python YAML parser, PyYAML, installed.

INSTALL PYTHON YAML PARSER

On ubuntu:

sudo apt-get install python-yaml

On non-ubuntu systems, install from:

http://pyyaml.org/wiki/PyYAML

RUN MAKE

make

The results will be stored in vss_$VERSION.[xxx], where $VERSION is the contents of the VERSION file and xxx is the appropriate file extension for the type of output being produced. For example, the JSON version of the output will have a .json extension.

Changes to files under the spec/ directory results in changes to the generated files, namely .json, .fidl, .csv etc. 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:

make json

BRANCH, RBRANCH, SIGNAL, ATTRIBUTE, AND ELEMENT DEFINITION

Branches, rbranches, signals, attributes, and elements are organized into a tree such as outlined in Fig 2.

Signal tree
Fig 2. A signal tree example

BRANCH ENTRY

A 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 branch. The only required field for a branch are type and description.

RBRANCH ENTRY

A 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 rbranch. It can host zero or more element nodes, and it contains the format definition of its element nodes. Besides the required fields type and description, are also the following.

RBRANCH CHILDTYPE

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.

RBRANCH CHILDPROPERTIES

An rbranch child format is defined through a number of properties, each property is defined by the attributes: name, description, type, format, unit, and value.

RBRANCH PROPNAME

This is the key value used to refer to this property. An element must contain the properties named id, name, and uri <inherited from VIWI?>.

RBRANCH PROPDESCRIPTION

This is a description of the property.

RBRANCH PROPTYPE

This is the type of the property.

RBRANCH PROPFORMAT

This is the format of this property.

RBRANCH PROPUNIT

This is the unit of this property.

RBRANCH PROPVALUE

If this property is a logical link to other elements, then the path to the rbranch of these elements is given here. The id value of these elements are provided in a list.

SIGNAL ENTRY

A signal is a named entity, such as rpm, that can have a value, such as 3400, at any given time.

SIGNAL TYPE

Each signal specifies a type from the following set (from FrancaIDL):

Name Type Min Max
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
Boolean boolean value 0/false 1/true
Float floating point number -3.4e -38 3.4e 38
Double double precision floating point number -1.7e -300 1.7e 300
String character string n/a n/a
ByteBuffer buffer of bytes (aka BLOB) n/a n/a

Please note that the special type branch denotes a branch, not a signal. See the branch entry chapter for details.

SIGNAL RANGE [OPTIONAL]

A signal can optionally be specified with a minimum and maximum limit, defining the valid range that the signal can assume.

SIGNAL ENUMERATION [OPTIONAL]

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.

SIGNAL UNIT TYPE [OPTIONAL]

A signal can optionally specify a unit of measurement from the following set. This list intends to be according to International Units (SI): Specification, Wikipedia

Unit type Domain Description
km/h Speed Kilometers per hour
m/s Speed Meters per second
celsius Temperature Degrees Celsius
mbar Pressure millibar
pa Pressure Pascal
kpa Pressure Kilo-Pascal
percent Relation Percent
ratio Relation Ratio
lat Position Decimal latitude
lon Position Decimal longitude
inch Distance Inch
mm Distance Millimeter
m Distance Meter
km Distance Kilometer
rpm Frequency Rotations per minute
Hz Frequency Frequency
W Power Watt
kW Power Kilowatt
kWh Power Kilowatt hours
ms Time Milliseconds
s Time Seconds
min Time Minutes
h Time Hours
g Weight Grams
kg Weight Kilograms
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
N Force Newton
Nm Force Torque
l Volume Liter
ml Volume Milliliter
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
... ... ...

SIGNAL SENSOR & ACTUATOR [OPTIONAL]

A signal can optionally specify a sensor and/or actuator respectively producing or consuming the signal. They are independant from the technology used.

ATTRIBUTE ENTRY

An attribute is an entry, such as vehicle weight or fuel type, with a static value. 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.

ATTRIBUTE TYPE

Each attribute specifies a type in the same way that a signal does.

ATTRIBUTE VALUE

Each attribute specifies a static value of the correct type.

ATTRIBUTE UNIT TYPE [OPTIONAL]

An attribute can optionally specify a unit of measurement in the same way that a signal does.

ELEMENT ENTRY

An element node must only be a child of an rbranch node. Default and mandatory fields are type, and description, other mandatory fields are specified by the property definitions in the rbranch parent.

SIGNAL NAMING CONVENTION

Signals are named, left-to-right, from the root of the signal tree toward the signal itself. Each element in the name is delimited with a period (".") .

For example, the dimming status of the rearview mirror in the cabin is named:

Cabin.RearviewMirror.Dimmed

If there are an array of elements, such as door rows 1-3, they will be named 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 spec.

PARENT NODES

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.

BRANCH ENTRY

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:

SIGNAL ENTRY

A signal entry defines a single signal and its members. A signal entry example is given below:

- Drivetrain.Transmission.Speed:
  type: Uint16
  unit: km/h
  min: 0
  max: 300
  description: The vehicle speed, as measured by the drivetrain.
  • Drivetrain.Transmission.Speed
    Defines the dot-notated signal name of the signal. Please note that all parental branches included in the name must be defined as well.

  • type
    The string value of the type specifies the scalar type of the signal value. See signal type chapter for a list of available types.

  • min [optional]
    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 enum is specified for the same signal entry.

  • max [optional]
    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 enum is specified for the same signal entry.

  • unit [optional]
    The unit of measurement that the signal has. See Unit Type chapter for a list of available unit types.
    This cannot be specified if enum is specified as the signal type.

  • description
    A description string to be included (when applicable) in the various specification files generated from this signal entry.

  • sensor[optional]
    The sensing appliance used to produce the signal.

  • actuator[optional]
    The actuating appliance consuming the signal.

ENUMERATED SIGNAL ENTRY

A signal 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: Uint16,
  enum: [ -1, 1, 2, 3, 4, 5, 6, 7, 8 ]
  description: The selected gear. -1 is reverse.

An enumerated signal entry has no min, max, or unit element.

The enum element is an array of values, all of which must be specified in the enum list. This signal can only be assigned one of the values specified in the enum list. The type specifier is the type of the individual elements of the enum list.

ATTRIBUTES

An attribute is a signal with a default value, specified by its value member.

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:  Uint16
  default: 0
  description: Peak power, in kilowatts, that engine can generate.

EXTENDING AND OVERRIDING SIGNALS

The core signal specification can be extended with additional signals through the use of private branches, as is shown in Fig 3.

Signal Extension
Fig 3. Extended signals

In this case the core signal specification, vss_23.vspec is included by a OEM-specific master vspec file that adds the two proprietary signals Private.OEM_X.AntiGravity.Power and Private.OEM_X.Teleport.TargetLoc.

Signals can, in a similar manner, be overridden and replaced with a new definition, as is shown in Fig 4.

Signal Extension
Fig 4. Overridden signals

In this case, the GearChangeMode signal provided by the core specification lacks an additional semi-automatic mode featured by an OEM-specific vehicle.

By having an OEM master spec file, oem_x_proprietary.vspec include the core spec file, vss_23.vspec and then overriding the original GearChangeMode signal and add the semi-auto element as an enumerated value

DECLARING VS. DEFINING ATTRIBUTES

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.

Attributes
Fig 5. Declaring and defining attributes

The Attributes.Engine.Displacement and Attributes.Chassis.Weight attributes are declare in the vss_23.vspec file with a default value of zero.

A project/vehicle specific vspec file, oem_x_proprietary.vspec then overrides the attributes with the correct values.

INCLUDE DIRECTIVES

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.

Include directive
Fig 6. Include directives

The include directive has the following format:

#include <filename> [prefix]

The <filename> part specifies the path, relative to the file with the #include directive, to the vspec file to replace the directive with.

The optional [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

The door.vspec section specifies the file to include.

The chassis.doors section specifies that all signal entries in door.vspec should have their names prefixed with chassis.doors.

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.

Include directrive
Fig 7. Reusing signal trees

The door.vspec file is included four times by the master root.vspec file. The signals of door.vspec, Locked, WinPos, and Open are attached on the front left and right doors of row 1 (front) and row 2 (back).

If door.vspec is changed, the changes will be propagated to all four doors.

SIGNAL ID DATABASES

The tools vspec2franca, vspec2json and 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 -i option:

vspec2json -i <prefix>:<database_file>:<start_id> vspec_file json_file

The -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>
    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.Curbweight will be stored in vspec_attr.id while a signal named Attribute.Cabin.Seat.DriverPosition will be stored in the vspec_attr_cab.id database.
  • <database_file>
    The name of the database file.
  • <start_id>
    The first ID value for a signal ID database. Note that the ID is only unique for the same database. If you use the -i option 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.