You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs-gen/content/governance/_index.md
+14-2Lines changed: 14 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,8 +4,6 @@ weight: 15
4
4
chapter: false
5
5
---
6
6
7
-
# Governance
8
-
9
7
The Vehicle Signal Specification (VSS) project is an initiative by [COVESA](https://covesa.global/) to define a syntax and a catalog for vehicle signals.
10
8
11
9
The artifacts maintained by the VSS project consist of:
@@ -63,6 +61,20 @@ VSS is however an evolving syntax and catalog and there are still areas where ch
63
61
Changes that breaks backward compatibility are typically introduced only in major releases (e.g. `X.0`) and shall be documented in release notes.
64
62
This concerns changes to syntax and signals, but also to tools.
65
63
64
+
Changes considered as backward incompatible include:
65
+
66
+
* Signals have been deleted, renamed or change of datatype or unit.
67
+
* New data entry attributes have been added to standard VSS catalog, only accepted by an updated VSS-tools version.
68
+
* VSS-tools CLI changed, for example arguments renamed or new mandatory arguments added.
69
+
* Columns/fields removed from VSS-tools exporter output.
70
+
71
+
72
+
Changes NOT considered as backward incompatible include:
73
+
74
+
* New signals, units or quanties added to VSS standard catalog.
75
+
* New VSS-tools exporters added.
76
+
* Columns/fields added to VSS-tools exporter output.
77
+
66
78
The VSS project has introduced a [deprecation concept]({{% ref "../rule_set/basics.md#deprecation-since-version-21" %}}).
67
79
If possible, when e.g. renaming or moving a signal or changing tools the old signal or parameter set shall be kept but marked as deprecated.
68
80
That allows the change to be introduced in a minor version (e.g. `X.Y`). The old signal shall be removed first in the next major release, or later if needed.
Copy file name to clipboardExpand all lines: docs-gen/content/license/_index.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,9 +10,9 @@ chapter: false
10
10
{{% /notice %}}
11
11
## Which license applies
12
12
13
-
VSS as well as the VSS-tools are covered by the [Mozilla Public License 2.0 (MPL-2.0)](https://opensource.org/licenses/mpl-2.0). The MPL-2.0 is an OSI approved Open Source license that gives you a lot of freedom using VSS in your products, or for (academic) research. It also provides a solid legal framework if you choose to contribute to either the standards or the tools.
13
+
VSS as well as the VSS-tools are covered by the [Mozilla Public License 2.0 (MPL-2.0)](https://opensource.org/license/mpl-2.0). The MPL-2.0 is an OSI approved Open Source license that gives you a lot of freedom using VSS in your products, or for (academic) research. It also provides a solid legal framework if you choose to contribute to either the standards or the tools.
14
14
15
-
We will line out some answers to commonly asked questions, but keep in mind this page is informational. The legally binding clauses can be found in the [license](https://opensource.org/licenses/mpl-2.0) itself. If in doubt, consult your friendly neighborhood lawyer or IP department.
15
+
We will line out some answers to commonly asked questions, but keep in mind this page is informational. The legally binding clauses can be found in the [license](https://opensource.org/license/mpl-2.0) itself. If in doubt, consult your friendly neighborhood lawyer or IP department.
16
16
17
17
## Can I use VSS / VSS-tools in my commercial products
18
18
Most definitely yes. You must inform your users that the product contains MPLed code and need to provide access to the source (e.g. by linking to this documentation or our [Github repository](https://github.com/covesa/vehicle_signal_specification)).
Copy file name to clipboardExpand all lines: docs-gen/content/rule_set/branches.md
+25-21Lines changed: 25 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,32 +10,16 @@ signals.
10
10
A branch entry example is given below:
11
11
12
12
```yaml
13
-
Trunk:
13
+
Vehicle.Trunk:
14
14
type: branch
15
15
description: All signals related to the rear trunk
16
16
aggregate: false
17
17
```
18
+
Each data entry has a name, in the example above `Vehicle.Trunk`.
19
+
VSS use a dot-notated name style where the full path of a branch consists of all parent branches from the root node separated by dots and at the end the name of the current branch. In the standard VSS catalog the root node is called `Vehicle`.
18
20
19
-
The following elements are defined:
20
-
21
-
**`Body.Trunk`**
22
-
The list element name defines the dot-notated signal name to the signal.
23
-
Please note that all parental branches included in the name must be defined as
24
-
well.
25
-
26
-
**```type```**
27
-
The value ```branch``` specifies that this is a branch entry (as
28
-
opposed to a signal entry). This is the default, in case ```type``` is omitted.
29
-
30
-
**```description```**
31
-
Describes the meaning and content of the branch.
32
-
Recommended to start with a capital letter and end with a dot (`.`).
33
-
34
-
**```comment ```** *[optional]* `since version 3.0`
35
-
A comment can be used to provide additional informal information on a branch.
36
-
This could include background information on the rationale for the branch,
37
-
references to related branches, standards and similar.
38
-
Recommended to start with a capital letter and end with a dot (`.`).
21
+
When using `*.vspec` files to define a VSS catalog it is not necessary to give the full dot-notated name for each branch as the
22
+
`*.vspec`format supports [includes](../includes/) that can be used to append entries to a specific branch.
39
23
40
24
**```instances```** *[optional]*
41
25
For specifying that multiple instances of this branch exist, for more information see documentation on
@@ -50,3 +34,23 @@ and write together. This is supposed to be deployment and tool specific,
50
34
and for that reason no branches are aggregates by default in VSS.
51
35
For branches that both have `instances` defined and `aggregate: true`, then aggregate refers to the signals for
52
36
individual instances, i.e. signals for different instances can be handled separately.
37
+
38
+
## Mandatory Branch Attributes
39
+
40
+
This is the list of attributes that must be specified for every data entry.
`comment`| A comment can be used to provide additional informal information on a branch. This could include background information on the rationale for the branch, references to related branches, standards and similar. Recommended to start with a capital letter and end with a dot (`.`). | *since version 3.0*
55
+
`instances`| For specifying that multiple instances of this branch exist, for more information see documentation on [instances](/vehicle_signal_specification/rule_set/instances/).
56
+
`aggregate` | Defines whether or not this branch is an aggregate. If not defined, this defaults to ```false```. An aggregate is a collection of signals that make sense to handle together in a system. A typical example could be GNSS location, where latitude and longitude make sense to read and write together. This is supposed to be deployment and tool specific, and for that reason no branches are aggregates by default in VSS. For branches that both have `instances` defined and `aggregate: true`, then aggregate refers to the signals for individual instances, i.e. signals for different instances can be handled separately.
Copy file name to clipboardExpand all lines: docs-gen/content/rule_set/data_entry/data_types.md
+52-2Lines changed: 52 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,8 +4,58 @@ date: 2019-08-04T11:11:48+02:00
4
4
weight: 10
5
5
---
6
6
7
-
Each [data entry](/vehicle_signal_specification/rule_set/data_entry/) specifies a ```datatype``` from the following set (from Franca IDL).
8
-
Datatypes shall not be used for [branch entry](/vehicle_signal_specification/rule_set/branches/)
7
+
In VSS each [data entry](/vehicle_signal_specification/rule_set/data_entry/) (except branches and structs) must specify a ```datatype```.
8
+
It can be a primitive type, an array of a primitive type or a struct type.
9
+
10
+
This is the default datatype for the given entry.
11
+
The VSS project typically selects datatype (and unit) so that values are easily understandable by humans,
12
+
can cover a reasonable range and supports reasonable precision.
13
+
An example is given below where `Vehicle.Speed` has been assigned the datatype `float` and the unit `km/h`.
14
+
15
+
```
16
+
Vehicle.Speed:
17
+
datatype: float
18
+
type: sensor
19
+
unit: km/h
20
+
description: Vehicle speed.
21
+
```
22
+
23
+
The meaning of this is that unless otherwise specified (by an API), the value is supposed to be given as a decimal number with km/h as unit.
24
+
An example from [VISS](https://github.com/COVESA/vehicle-information-service-specification) is given below, showing how the speed 123.45 km/h is returned As `"123.45"`.
Another example is the [Kuksa Client](https://github.com/eclipse-kuksa/kuksa-python-sdk) where values are to be given in the unit and datatype specified by VSS.
38
+
39
+
```
40
+
Test Client> setValue Vehicle.Speed 43.2
41
+
2024-10-18 16:12:54,307 INFO kuksa_client.grpc.aio: Using v2
42
+
OK
43
+
44
+
Test Client> getValue Vehicle.Speed
45
+
{
46
+
"path": "Vehicle.Speed",
47
+
"value": {
48
+
"value": 43.20000076293945,
49
+
"timestamp": "2024-10-18T14:12:54.314814+00:00"
50
+
}
51
+
}
52
+
```
53
+
54
+
It is *not* mandatory for an implementation, protocol or an API to use the datatype and unit specified by the COVESA VSS catalog.
55
+
A VSS entity can in a customized or extended VSS catalog, be annotated with information specifying that the data entry shall be transmitted or stored using a different datatype, possibly involving scaling and offset. An API may in addition or as replacement to the default datatype and offset allow the entity to be read or written using alternative representations or alternative units.
56
+
57
+
It is however recommended that the default method to read or write a dataentry shall be based on the datatype and unit definined in the standard VSS catalog for signals definied in the standard VSS catalog, as there otherwise is a risk that the client and the server interpret the value differently.
Copy file name to clipboardExpand all lines: docs-gen/content/rule_set/data_entry/default.md
+8-5Lines changed: 8 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,16 @@
1
1
---
2
-
title: "Attributes"
2
+
title: "Default Values"
3
3
date: 2019-08-04T12:37:31+02:00
4
4
weight: 40
5
5
---
6
6
7
-
An attribute is an entity that has a default value, specified by
8
-
its ```default``` member.
7
+
VSS supports default values by the `default` attribute.
8
+
The intention is to provide a mechanism to provide initial values for data entries already when loading a VSS catalog.
9
+
This could typically be useful for attributes that never or rarely change, like [vehicle VIN](https://en.wikipedia.org/wiki/Vehicle_identification_number) or vehicle color.
10
+
9
11
The standard Vehicle Signal Specification does not include default values for all attributes.
10
-
If a default value has not been specified then the OEM must define a default value matching the actual vehicle.
12
+
If a default value has not been specified then the OEM must define a default value matching the actual vehicle,
13
+
either by using the `default` concept, or by the same other mechanism.
11
14
If the standard defines a default value but it does not fit the actual vehicle,
12
15
then the OEM must override the standard default value.
13
16
@@ -51,4 +54,4 @@ SeatPosCount:
51
54
description: Number of seats across each row from the front to the rear
52
55
```
53
56
54
-
Using default values for structs is not allowed!
57
+
Default values can also be defined for [structs](/vehicle_signal_specification/rule_set/data_entry/data_types_struct/).
0 commit comments