Skip to content

Commit

Permalink
Align usage of the word type.
Browse files Browse the repository at this point in the history 
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

Signed-off-by: Erik Jaegervall <[email protected]>
  • Loading branch information
@erikbosch
erikbosch committed Nov 21, 2023
1 parent 3ec3c25 commit f6ef12d
Show file tree
Hide file tree
Showing 5 changed files with 63 additions and 62 deletions.
10 changes: 5 additions & 5 deletions docs-gen/content/rule_set/data_entry/allowed.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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.
8 changes: 4 additions & 4 deletions docs-gen/content/rule_set/data_entry/data_types.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.
Expand Down
67 changes: 34 additions & 33 deletions docs-gen/content/rule_set/data_entry/data_types_struct.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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.
Expand All @@ -73,36 +73,37 @@ 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`).

For current vss-tools support for structs see [documentation](https://github.com/COVESA/vss-tools/blob/master/docs/vspec2x.md) in the vss-tools repository.

## 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:
type: branch
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
Expand All @@ -123,24 +124,24 @@ 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:
type: branch
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

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
...
Expand All @@ -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
...
Expand All @@ -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.
22 changes: 11 additions & 11 deletions docs-gen/content/rule_set/data_entry/data_unit_types.md
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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:

```
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down
18 changes: 9 additions & 9 deletions docs-gen/content/rule_set/data_entry/sensor_actuator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

0 comments on commit f6ef12d

Please sign in to comment.