Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
Clarifies string/float/double.
Reformat recommendatations to state that they also are rules for VSS catalog
Remove enum recommendation

Fixes COVESA#705
Fixes COVESA#706
Partially solves COVESA#700
Fixes COVESA#662

Signed-off-by: Erik Jaegervall <[email protected]>
  • Loading branch information
erikbosch committed Feb 14, 2024
1 parent f28c3e7 commit fdd5b6b
Show file tree
Hide file tree
Showing 3 changed files with 29 additions and 26 deletions.
23 changes: 16 additions & 7 deletions docs-gen/content/rule_set/basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,18 @@ as some implementations may treat VSS identifiers as case insensitive.

## Addressing Nodes

VSS supports only a single tree, that means that all signals must belong to the same root.
In the VSS standard catalog the root branch is called `Vehicle`, so all signals
must be part of the `Vehicle` tree.

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 ("."). The element hops from the root to the leaf is called ```path```.
a period ("."). The element hops from the root to the leaf is called ```path```

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


Vehicle.Cabin.RearviewMirror.Dimmed


If there are an array of elements, such as door rows 1-3, they will be
addressed with an index branch:

Expand Down Expand Up @@ -109,17 +111,24 @@ The VSS specification must adhere to YAML syntax. To keep the standardized VSS s
### Naming Conventions
The recommended naming convention for node elements is to use camel case notation starting with a capital letter. It is recommended to use only
`A-Z`, `a-z` and `0-9` in node names. For boolean signals it is recommended to start the name with `Is`.
Node names in VSS must follow the restrictions specified in [Yaml](https://yaml.org/spec/1.2.2/#chapter-5-character-productions) i.e. must only use the printable subset of the Unicode character set.
Tools and Generators supporting VSS may however put additional restrictions on which characters that are allowed. For maximum portability, node names in the VSS standard catalog must fulfill the following rules
* Node names in the VSS standard catalog shall use camel case notation starting with a capital letter.
* Node names in the VSS standard catalog shall use only `A-Z`, `a-z` and `0-9` in node names.
* Boolean signals must start with `Is`.
* Node names are case insensitive for comparison operations,
therefore the full path of node names must be unique e.g.
`Vehicle.Abc` and `Vehicle.ABC` are the same in comparison and therefore the presence of both is prohibited.

Examples:

```
SomeBranch.AnotherBranch.MySignalName
Vehicle.Cabin.Door.Row1.Left.IsLocked
```
Naming convention for string literals can be found in the [chapter](/vehicle_signal_specification/rule_set/data_entry/allowed/)for specifying allowed values.

### Line Length

It is recommended that line length for files in this repository ( e.g. `*.vspec` and `*.md` files) shall not exceed 120 characters. This is not a strict limit, it is e.g. not recommended to split long URLs present in files over multiple lines.
It is recommended that line length for files in this repository ( e.g. `*.vspec` and `*.md` files) shall not exceed 120 characters. This is not a strict limit, it is e.g. not recommended to split long URLs over multiple lines.
10 changes: 5 additions & 5 deletions docs-gen/content/rule_set/data_entry/allowed.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,17 +27,17 @@ in a list. Only values can be assigned to the data entry, which are
specified in this list.

The `datatype` specifier gives the datatype of the individual elements of the `allowed`
list. In general `allowed:` is valid for all datatypes, including integer- and float-based datatypes, unless othwerise specified.
list. In general `allowed:` is valid for all datatypes, including integer- and float-based datatypes, unless otherwise specified.

## Recommendation on String values

For string values used for `default` and `allowed` statements it is recommended to start with `A-Z`
and then use only `A-Z`, `0-9` and underscore (`_`).
It is recommended to use single quotes (`'`) as tooling otherwise might handle literals like `OFF` as boolean values with unexpected result.
String values used for `default` and `allowed` statements may contain characters from the printable subset of the Unicode character set.
If using [COVESA VSS-tools](https://github.com/COVESA/vss-tools) it is recommended to use single quotes (`'`) around values as tooling otherwise might handle literals like `OFF` as boolean values with unexpected result.
It is recommended not to specify a dedicated value corresponding to "unknown" or "undefined" unless there is a relevant use-case for that particular signal.
The background is that a signal with an array of allowed values shall be handled just as any other signal.
If e.g. the value of current speed or vehicle weight is unknown, then the vehicle shall not publish the corresponding signal.
Similarly, for the example above, if the steering wheel position is unknown then `SteeringWheel.Position`shall not be published.
Similarly, for the example above, if the steering wheel position is unknown then
`SteeringWheel.Position` shall not be published.

## Allowed values for array datatypes

Expand Down
22 changes: 8 additions & 14 deletions docs-gen/content/rule_set/data_entry/data_types.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,14 @@ int32 | signed 32-bit integer | -2147483648 | 2147483647
uint64 | unsigned 64-bit integer | 0 | 2^64 - 1
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
float | IEEE 754-2008 binary32 floating point number | -3.40e 38 | 3.40e 38
double | IEEE 754-2008 binary64 floating point number | -1.80e 308 | 1.80e 308
string | character string (unicode) | n/a | n/a

## Strings

Strings in VSS supports the unicode character set. Actual encoding like UTF-8 or UTF-16 is not
specified by VSS, that is to up to the Protocol/API/SDK implementing VSS support to decide.

## Arrays

Expand All @@ -46,17 +51,6 @@ of Diagnostic Trouble Codes (DTCs) present in a vehicle.

VSS struct support is further described on [this page](/vehicle_signal_specification/rule_set/data_entry/data_types_struct/).

## Timestamps

Timestamps are in VSS typically represented as strings, formatted according to ISO 8601.
Timestamps shall be expressed in UTC (Coordinated Universal Time), with special UTC designator ("Z").
Time resolution SHALL at least be seconds, with subsecond resolution as an optional degree of precision when desired.
The time and date format shall be as shown below, where the sub-second data and delimiter is optional.

```
YYYY-MM-DDTHH:MM:SS.ssssssZ
```
## Data Streams

Data Entries, which describe sensors offering binary streams
Expand Down

0 comments on commit fdd5b6b

Please sign in to comment.