From e63e9311f1cc0ff330724e9328e13427174fe863 Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Tue, 14 Nov 2023 15:22:25 +0100 Subject: [PATCH] Align usage of the word type. This PR intends align terms used in documentation * If we refer to a VSS data type, the term "datatype" is used * If we refer to the VSS node attribute "type" that specifies if a node is a branch, sensor, actuator, struct, ... we use the term "type" Fixes #683 --- .../content/rule_set/data_entry/allowed.md | 10 +-- .../content/rule_set/data_entry/data_types.md | 8 +-- .../rule_set/data_entry/data_types_struct.md | 67 ++++++++++--------- .../rule_set/data_entry/data_unit_types.md | 22 +++--- .../rule_set/data_entry/sensor_actuator.md | 18 ++--- 5 files changed, 63 insertions(+), 62 deletions(-) diff --git a/docs-gen/content/rule_set/data_entry/allowed.md b/docs-gen/content/rule_set/data_entry/allowed.md index 12b329c47..7e5adf39e 100644 --- a/docs-gen/content/rule_set/data_entry/allowed.md +++ b/docs-gen/content/rule_set/data_entry/allowed.md @@ -26,8 +26,8 @@ The `allowed` element is an array of values, all of which must be specified in a list. Only values can be assigned to the data entry, which are specified in this list. -The `datatype` specifier gives the type of the individual elements of the `allowed` -list. In general `allowed:` is valid for all datatypes, including integer- and float-based types, unless othwerise specified. +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. ## Recommendation on String values @@ -39,9 +39,9 @@ The background is that a signal with an array of allowed values shall be handled 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. -## Allowed values for array types +## Allowed values for array datatypes -The `allowed` keyword can also be used for signals of array type. In that case, `allowed` specifies the only valid values for array elements. +The `allowed` keyword can also be used for signals of array datatype. In that case, `allowed` specifies the only valid values for array elements. The actual value of the signal is expected to contain a subset of the values specified in `allowed`. Example: @@ -70,6 +70,6 @@ Example of an invalid array: ['PAPILLON', 'VIZSLA', 'LOBSTER'] # LOBSTER is not in the allowed value list ``` -## Allowed for struct types +## Allowed for struct datatypes Please see [struct]({{< ref "data_types_struct#allowed-values" >}} ) documentation. 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 17d60bff0..3ebb4ae00 100644 --- a/docs-gen/content/rule_set/data_entry/data_types.md +++ b/docs-gen/content/rule_set/data_entry/data_types.md @@ -1,15 +1,15 @@ --- -title: "Data Types" +title: "Datatypes" date: 2019-08-04T11:11:48+02:00 weight: 10 --- Each [data entry](/vehicle_signal_specification/rule_set/data_entry/) specifies a ```datatype``` from the following set (from Franca IDL). -Datatypes shall not be used in [branch entry](/vehicle_signal_specification/rule_set/branches/) +Datatypes shall not be used for [branch entry](/vehicle_signal_specification/rule_set/branches/) ## Supported datatypes -Name | Type | Min | Max +Name | Datatype | Min | Max :----------|:---------------------------|:-----|:--- uint8 | unsigned 8-bit integer | 0 | 255 int8 | signed 8-bit integer | -128 | 127 @@ -61,7 +61,7 @@ YYYY-MM-DDTHH:MM:SS.ssssssZ Data Entries, which describe sensors offering binary streams (e.g. cameras), are not supported directly by VSS with a -dedicated data type. Instead, they are described through the +dedicated datatype. Instead, they are described through the meta data about the sensor itself and how to retrieve the corresponding data stream. diff --git a/docs-gen/content/rule_set/data_entry/data_types_struct.md b/docs-gen/content/rule_set/data_entry/data_types_struct.md index c90277505..84f55d6f6 100644 --- a/docs-gen/content/rule_set/data_entry/data_types_struct.md +++ b/docs-gen/content/rule_set/data_entry/data_types_struct.md @@ -9,14 +9,14 @@ weight: 15 ## Introduction -VSS has historically supported only the following types: +VSS has historically supported only the following datatypes: -* Integer-based types (e.g. uint8, int32) -* Float-based types (float, double) +* Integer-based datatypes (e.g. uint8, int32) +* Float-based datatypes (float, double) * String * Boolean -In addition to this VSS arrays of the types given above has been supported. +In addition to this VSS arrays of the datatypes given above has been supported. This has been considered insufficient for some use-cases. Typical examples are when something cannot be described by a single value, but multiple values are needed. @@ -39,7 +39,7 @@ The order of elements in a struct is from a VSS perspective considered as arbitr The VSS project will by this reason not publish guidelines on how to order items in the struct to minimize size, and no concept for introducing padding will exist. -Structs shall be used in VSS standard catalog only when considered to give a significant advantage compared to using only primitive types. +Structs shall be used in VSS standard catalog only when considered to give a significant advantage compared to using only primitive datatypes. ## Structs vs. Aggregate @@ -61,10 +61,10 @@ With this view, aggregate shall never be used in the standard catalog, but can b ## General Idea and Basic Semantics -A signal of struct type shall be defined in the same way as other VSS signals, -the only difference would be that instead of using a primitive type there shall be a reference to a struct datatype. +A signal of struct datatype shall be defined in the same way as other VSS signals, +the only difference would be that instead of using a primitive datatype there shall be a reference to a struct datatype. This means that structs can be used for all types of VSS signals (i.e. sensor, attribute and actuator). -If a signal of struct type is sent or received, VSS expects all included items to have valid values, i.e. all items are mandatory. +If a signal of struct datatype is sent or received, VSS expects all included items to have valid values, i.e. all items are mandatory. For example, if a struct contains the items A, B and C - then it is expected that the sent signal contains value for all items. If some items are considered optional then the value range of the items must be adapted to include values indicating "not available" or "undefined", or additional items needs to be added to indicate which items that have valid values. @@ -73,13 +73,14 @@ VSS makes no assumption on how structs are transferred or stored by implementati It is however expected that they are read and written by atomic operations. This means that the data storage shall be "locked" while the items of the struct are read, preventing changes to happen while reading/writing the items. -Structs shall be defined in a separate tree. This means that signal definitions and types cannot exist in the same files. -Tooling must thus accept one (or more) parameters for specifying type definition(s). +Structs shall be defined in a separate tree intended for definition of datatypes only. +This means that signal definitions and struct definitions cannot exist in the same files. +Tooling must thus accept one (or more) parameters for specifying datatype definition(s). The tree must have a branch as root, i.e. it is not possible to have a struct as root. -The top level types file(s) (e.g. `vss_types.vspec`) can refer to other type files similar to the +The top level datatypes file(s) (e.g. `vss_types.vspec`) can refer to other datatype files similar to the [top VSS file](https://github.com/COVESA/vehicle_signal_specification/blob/master/spec/VehicleSignalSpecification.vspec). -It is possible to specify that multiple type files shall be used, but all types must belong to the same root. +It is possible to specify that multiple datatype files shall be used, but all datatypes must belong to the same root. This means if the first file defines `A.B`, then the seconds file can define `A.C`, but not `X.Y` as that would result in two roots (`A` and `X`). @@ -87,14 +88,14 @@ For current vss-tools support for structs see [documentation](https://github.com ## Naming Restrictions -The VSS syntax and tooling shall not enforce any restrictions on naming for the type tree. +The VSS syntax and tooling shall not enforce any restrictions on naming for the datatype tree. It may even use the same branch structure as the signal tree. This means that it theoretically at the same time could exist both a signal `A.B.C` and a struct `A.B.C`. -This is not a problem as it always from context is clear whether a name refers to a signal or a type. +This is not a problem as it always from context is clear whether a name refers to a signal or a datatype. ## Simple Definition and Usage -This could be a hypothetical content of a VSS type file +This could be a hypothetical content of a VSS datatype file ``` Types: @@ -102,7 +103,7 @@ Types: Types.DeliveryInfo: type: struct - description: A struct type containing info for each delivery + description: A struct datatype containing info for each delivery Types.DeliveryInfo.Address: datatype: string @@ -123,7 +124,7 @@ Delivery: type: sensor ``` -The type file may contain sub-branches and `#include`-statements just like regular VSS files +The datatype file may contain sub-branches and `#include`-statements just like regular VSS files ``` Types: @@ -131,16 +132,16 @@ Types: Types.Powertrain: type: branch - description: Powertrain types. + description: Powertrain datatypes. #include Powertrain/Powertrain.vspec Types.Powertrain ``` ## Name resolution -Two ways of referring to a type are considered correct: +Two ways of referring to a datatype are considered correct: -In Type Tree: +In Datatype Tree: * Reference by absolute path * Reference by (leaf) name to a struct definition within the same branch @@ -183,7 +184,7 @@ DeliveryList: ### Expectations on VSS implementations (e.g. VISS, KUKSA.val) -For array types (like above) VSS implementations may support several mechanisms +For array datatypes (like above) VSS implementations may support several mechanisms * It is expected that they can support read/write/subscribe of the whole array, i.e. write all or read all in the same request * They may optionally support additional operations like @@ -193,12 +194,12 @@ For array types (like above) VSS implementations may support several mechanisms ## Structure in Structure -It is allowed to refer to a structure type from within a structure +It is allowed to refer to a structure datatype from within a structure ``` OpenHours: type: struct - description: A struct type containing information on open hours + description: A struct datatype containing information on open hours OpenHours.Open: datatype: uint8 @@ -214,7 +215,7 @@ OpenHours.Close: DeliveryInfo: type: struct - description: A struct type containing info for each delivery + description: A struct datatype containing info for each delivery DeliveryInfo.Address: datatype: string @@ -236,7 +237,7 @@ DeliveryInfo.Open: ## Order of declaration/definition The order of declaration/definition shall not matter. -As signals and types are defined in different trees this is a topic only for struct definitions referring to other struct definitions. +As signals and datatypes are defined in different trees this is a topic only for struct definitions referring to other struct definitions. A hypothetical example is shown below. An item in the struct `DeliveryInfo` can refer to the struct `OpenHours` even if that struct is defined further down in the same file. If using `-vt < file>` multiple times all files except the first will be treated similar to overlays. @@ -246,7 +247,7 @@ what has been defined previously. ``` DeliveryInfo: type: struct - description: A struct type containing info for each delivery + description: A struct datatype containing info for each delivery ... @@ -257,7 +258,7 @@ DeliveryInfo.Open: OpenHours: type: struct - description: A struct type containing information on open hours + description: A struct datatype containing information on open hours ... @@ -271,17 +272,17 @@ Inline/anonymous structs are not allowed! VSS supports [default values](/vehicle_signal_specification/rule_set/data_entry/attributes/). -Default values are not allowed for signals of struct type. +Default values are not allowed for signals of struct datatype. This also mean that VSS does not need to specify notation for struct values. -An exception is arrays of struct-types, where "empty array", i.e. `[]` shall be supported as default value. +An exception is arrays of struct-datatypes, where "empty array", i.e. `[]` shall be supported as default value. -It shall be possible to define default values for properties (unless the item is of struct type). -If all items of a struct type have default values, -then a signal (or item) using the struct type is also considered to have a default value. +It shall be possible to define default values for properties (unless the item is of struct datatype). +If all items of a struct datatype have default values, +then a signal (or item) using the struct datatype is also considered to have a default value. ## Allowed Values VSS supports [specification of allowed values](/vehicle_signal_specification/rule_set/data_entry/allowed/). Using `allowed` for `type: property` is allowed (if `allowed` is supported for the used datatype). -Using `allowed` for signals and items of struct type or array of struct type is not allowed. +Using `allowed` for signals and items of struct datatype or array of struct datatype is not allowed. diff --git a/docs-gen/content/rule_set/data_entry/data_unit_types.md b/docs-gen/content/rule_set/data_entry/data_unit_types.md index 7a7f83ac2..68578c6ff 100644 --- a/docs-gen/content/rule_set/data_entry/data_unit_types.md +++ b/docs-gen/content/rule_set/data_entry/data_unit_types.md @@ -1,13 +1,13 @@ --- -title: "Data Unit Types" +title: "Data Units" date: 2019-08-04T12:36:12+02:00 weight: 20 --- -## Introduction to Data Unit Types in VSS +## Introduction to Data Units in VSS -It is in VSS possible for signals to specify a unit of measurement from a list of predefined data unit types. -For most signals in the VSS standard catalog, a data unit type has been selected. A typical example is `Vehicle.Speed`, as shown below. +It is in VSS possible for signals to specify a unit of measurement from a list of predefined data units. +For most signals in the VSS standard catalog, a data unit has been selected. A typical example is `Vehicle.Speed`, as shown below. ``` Vehicle.Speed: @@ -17,17 +17,17 @@ Vehicle.Speed: description: Vehicle speed. ``` -The ambition when selecting data unit types for signals in VSS standard catalog has been to use either a unit based on SI-units, +The ambition when selecting data unit for signals in VSS standard catalog has been to use either a unit based on SI-units, or a unit commonly used within the vehicle industry. For the `Vehicle.Speed` example above this means that `km/h` has been selected, even if `m/s` from an SI-perspective would have been a better choice. It must be noted that the selected unit does not imply that the value of `Vehicle.Speed` always needs to be sent or visualized as `km/h` (with float as datatype). A user interface or API may show or request vehicle speed in any unit it likes, and a transport protocol may send speed in another unit, possibly also involving scaling and offset. -But in protocols not explicitly specifying data unit types (like [VISS](https://raw.githack.com/w3c/automotive/gh-pages/spec/VISSv2_Core.html)) +But in protocols not explicitly specifying data units (like [VISS](https://raw.githack.com/w3c/automotive/gh-pages/spec/VISSv2_Core.html)) it is expected that `Vehicle.Speed` is sent and received as `km/h` (without scaling or offset). -In some cases it is natural to omit the data unit type. This concerns typically signals where data type `string` is used, +In some cases it is natural to omit the data unit. This concerns typically signals where datatype `string` is used, but also signals where the value just represents a number, like in the example below: ``` @@ -37,9 +37,9 @@ Vehicle.Cabin.DoorCount: default: 4 description: Number of doors in vehicle. ``` -### Logical Data Unit Types +### Logical Data Units -VSS supports `percent` as data unit type, typically with 0 to 100% as the allowed range. +VSS supports `percent` as data unit, typically with 0 to 100% as the allowed range. In some cases, the definition on how to calculate the signal value is obvious, like for `Vehicle.Powertrain.FuelSystem.Level` below. It is likely that all VSS users will calculate fuel level in the same way, i.e. the meaning of a fuel level of 50% is well agreed, the liters of fuel in the tank is exactly 50% of nominal capacity. @@ -72,12 +72,12 @@ Vehicle.Powertrain.Transmission.ClutchWear: ``` -## List of supported Data Unit Types +## List of supported Data Unit This list composed with definition according to International Units (SI) and few automotive specific units: [Specification](https://www.iso.org/standard/30669.html), [Wikipedia](https://en.wikipedia.org/wiki/International_System_of_Units) -Unit type | Domain | Description +Unit | Domain | Description :-------------|:--------------------------------|:------------- mm | Distance | Distance measured in millimeters cm | Distance | Distance measured in centimeters diff --git a/docs-gen/content/rule_set/data_entry/sensor_actuator.md b/docs-gen/content/rule_set/data_entry/sensor_actuator.md index c551926ad..cee4d6c2f 100644 --- a/docs-gen/content/rule_set/data_entry/sensor_actuator.md +++ b/docs-gen/content/rule_set/data_entry/sensor_actuator.md @@ -31,8 +31,8 @@ Defines the type of the node. This can be `branch`, `sensor`, `actuator` or `attribute`. **```datatype```** -The string value of the type specifies the scalar type of the data entry -value. See [data type](/vehicle_signal_specification/rule_set/data_entry/data_types/) chapter for a list of available types. +The string value of the datatype specifies the scalar type of the data entry +value. See [datatype](/vehicle_signal_specification/rule_set/data_entry/data_types/) chapter for a list of available datatypes. **```description```** Describes the meaning and content of the signal. @@ -47,18 +47,18 @@ references to related signals, standards and similar. Recommended to start with a capital letter and end with a dot (`.`). **```min```** *[optional]* -The minimum value, within the interval of the given ```type```, that the +The minimum value, within the interval of the given ```datatype```, that the data entry can be assigned. -If omitted, the minimum value will be the "Min" value for the given type. +If omitted, the minimum value will be the "Min" value for the given datatype. Cannot be specified if ```allowed``` is defined for the same data entry. **```max```** *[optional]* -The maximum value, within the interval of the given ```type```, that the +The maximum value, within the interval of the given ```datatype```, that the data entry can be assigned. -If omitted, the maximum value will be the "Max" value for the given type. +If omitted, the maximum value will be the "Max" value for the given datatype. Cannot be specified if ```allowed``` is defined for the same data entry. **```unit```** *[optional]* -The unit of measurement that the data entry has. See [Data Unit Types](/vehicle_signal_specification/rule_set/data_entry/data_unit_types/) -chapter for a list of available unit types. This -cannot be specified if ```allowed``` is defined as the signal type. +The unit of measurement that the data entry has. See [Data Units](/vehicle_signal_specification/rule_set/data_entry/data_unit_types/) +chapter for a list of available units. This +cannot be specified if ```allowed``` is defined for the same data entry.