From ca75887b136dd7b0225fd60f6f0435df8089e91a 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 Fixes #700 Signed-off-by: Erik Jaegervall --- docs-gen/content/rule_set/basics.md | 16 ++++++++++++---- docs-gen/content/rule_set/data_entry/allowed.md | 10 +++++----- .../content/rule_set/data_entry/data_types.md | 13 ++++++++++--- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs-gen/content/rule_set/basics.md b/docs-gen/content/rule_set/basics.md index dd932dbc1..2deab011b 100644 --- a/docs-gen/content/rule_set/basics.md +++ b/docs-gen/content/rule_set/basics.md @@ -109,17 +109,25 @@ 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`. +* Full path of node names must be unique also when using case insensitive comparison. + It is for example not allowed to have both `Vehicle.Abc` and `Vehicle.ABC` in the standard catalog + even if that is valid VSS as VSS is case sensitive. Examples: ``` -SomeBranch.AnotherBranch.MySignalName Vehicle.Cabin.Door.Row1.Left.IsLocked +SomeOtherTree.AnotherBranch.MySignalName ``` 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..8eca2026b 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 @@ -57,6 +62,8 @@ The time and date format shall be as shown below, where the sub-second data and YYYY-MM-DDTHH:MM:SS.ssssssZ ``` +VSS also supports the unit `unix-time` that can be used together with datatype `uint32`/`uint64`/`int64`to indicate that the signal value correspond to number of non-leap seconds which have passed since 00:00:00 UTC on Thursday, 1 January 1970. + ## Data Streams Data Entries, which describe sensors offering binary streams