From fdd5b6b0d80c8c6f4e19a5ac4b92d755e573203e Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Thu, 8 Feb 2024 15:06:05 +0100 Subject: [PATCH] Update documentation Clarifies string/float/double. Reformat recommendatations to state that they also are rules for VSS catalog Remove enum recommendation Fixes #705 Fixes #706 Partially solves #700 Fixes #662 Signed-off-by: Erik Jaegervall --- docs-gen/content/rule_set/basics.md | 23 +++++++++++++------ .../content/rule_set/data_entry/allowed.md | 10 ++++---- .../content/rule_set/data_entry/data_types.md | 22 +++++++----------- 3 files changed, 29 insertions(+), 26 deletions(-) diff --git a/docs-gen/content/rule_set/basics.md b/docs-gen/content/rule_set/basics.md index dd932dbc1..2f4a7ffb6 100644 --- a/docs-gen/content/rule_set/basics.md +++ b/docs-gen/content/rule_set/basics.md @@ -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: @@ -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. diff --git a/docs-gen/content/rule_set/data_entry/allowed.md b/docs-gen/content/rule_set/data_entry/allowed.md index 7e5adf39e..033cb401e 100644 --- a/docs-gen/content/rule_set/data_entry/allowed.md +++ b/docs-gen/content/rule_set/data_entry/allowed.md @@ -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 diff --git a/docs-gen/content/rule_set/data_entry/data_types.md b/docs-gen/content/rule_set/data_entry/data_types.md index 3ebb4ae00..76a39eb84 100644 --- a/docs-gen/content/rule_set/data_entry/data_types.md +++ b/docs-gen/content/rule_set/data_entry/data_types.md @@ -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 @@ -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