Updating doc and refactoring unit file

Signed-off-by: Erik Jaegervall <erik.jaegervall@se.bosch.com>
COVESA · Nov 2, 2023 · cfad371 · cfad371
1 parent e243391
commit cfad371
Show file tree

Hide file tree

Showing 2 changed files with 206 additions and 159 deletions.
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
@@ -28,7 +28,7 @@ But in protocols not explicitly specifying data unit types (like [VISS](https://
 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,
-but also signals where the value just represents a number, like in the example below:
+but also signals where the value just represents a number (dimensionless quantities), like in the example below:
 
 ```
 Vehicle.Cabin.DoorCount:
@@ -74,67 +74,138 @@ Vehicle.Powertrain.Transmission.ClutchWear:
 
 ## List of supported Data Unit Types
 
-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
-:-------------|:--------------------------------|:-------------
-mm            | Distance                        | Distance measured in millimeters
-cm            | Distance                        | Distance measured in centimeters
-m             | Distance                        | Distance measured in meters
-km            | Distance                        | Distance measured in kilometers
-inch          | Distance                        | Distance measured in inches
-km/h          | Speed                           | Speed measured in kilometers per hours
-m/s           | Speed                           | Speed measured in meters per second
-m/s^2         | Acceleration                    | Acceleration measured in meters per second squared
-cm/s^2        | Acceleration                    | Acceleration measured in centimeters per second squared
-ml            | Volume                          | Volume measured in milliliters
-l             | Volume                          | Volume measured in liters
-cm^3          | Volume                          | Volume measured in cubic centimeters
-celsius       | Temperature                     | Temperature measured in degree celsius
-degrees       | Angle                           | Angle measured in degrees
-degrees/s     | Angular Speed                   | Angular speed measured in degrees per second
-W             | Power                           | Power measured in watts
-kW            | Power                           | Power measured in kilowatts
-PS            | Power                           | Power measured in horsepower
-kWh           | Energy Consumption              | Energy consumption measured in kilowatt hours
-g             | Weight                          | Mass measured in grams
-kg            | Weight                          | Mass measured in kilograms
-lbs           | Weight                          | Mass measured in pounds
-V             | Electric Potential              | Electric potential measured in volts
-A             | Electric Current                | Electric current measured in amperes
-Ah            | Electric Charge                 | Electric charge measured in ampere hours
-ms            | Time                            | Time measured in milliseconds
-s             | Time                            | Time measured in seconds
-min           | Time                            | Time measured in minutes
-h             | Time                            | Time measured in hours
-day           | Time                            | Time measured in days
-weeks         | Time                            | Time measured in weeks
-months        | Time                            | Time measured in months
-years         | Time                            | Time measured in years
-UNIX Timestamp| Time                            | Unix time is a system for describing a point in time. It is the number of seconds that have elapsed since the Unix epoch, excluding leap seconds.
-mbar          | Pressure                        | Pressure measured in millibars
-Pa            | Pressure                        | Pressure measured in pascal
-kPa           | Pressure                        | Pressure measured in kilopascal
-stars         | Rating                          | Rating measured in stars
-g/s           | Mass per time                   | Mass per time measured in grams per second
-g/km          | Mass per distance               | Mass per distance measured in grams per kilometers
-kWh/100km     | Energy Consumption per distance | Energy consumption per distance measured in kilowatt hours per 100 kilometers
-ml/100km      | Volume per distance             | Volume per distance measured in milliliters per 100 kilometers
-l/100km       | Volume per distance             | Volume per distance measured in liters per 100 kilometers
-l/h           | Flow                            | Flow measured in liters per hour
-mpg           | Distance per Volume             | Distance per volume measured in miles per gallon
-N             | Force                           | Force measured in newton
-Nm            | Torque                          | Torque measured in newton meters
-rpm           | Rotational Speed                | Rotational speed measured in revolutions per minute
-Hz            | Frequency                       | Frequency measured in hertz
-ratio         | Relation                        | Relation measured as ratio
-percent       | Relation                        | Relation measured in percent
-... | ... | ...
-
-[VSS-Tools](https://github.com/COVESA/vss-tools) require that a unit file is available when transforming *.vspec files.
-It can be specified by the `-u` parameter, and if not given the tools will search for a file `units.yaml`
+The VSS syntax does not in itself specify what units that can be used, the unit attribute as declared for signals in *.vspec files is optional and can contain an arbitrary string value.
+[VSS-Tools](https://github.com/COVESA/vss-tools) however require that all units used are defined.
+Units are defined by including them in an a unit file with syntax as described below.
+One or more unit files can be specified by the `-u` parameter, and if not given the tools will search for a file `units.yaml`
 in the same directory as the root *.vspec file.
 
-The VSS standard catalog is based on [units.yaml](https://github.com/COVESA/vehicle_signal_specification/blob/master/spec/units.yaml),
-i.e. only units from that file can be used.
+For the VSS standard catalog the VSS-project has defined a set of units that can be used for signals in the VSS standard catalog.
+This list is composed with definitions 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)
+
+The VSS list of units for the standard catalog exists in [units.yaml](https://github.com/COVESA/vehicle_signal_specification/blob/master/spec/units.yaml).
+
+
+## Unit file syntax
+
+Unit files have the syntax defined below:
+
+```
+[
+  quantities:
+  [
+    <vss-quantity-identifier>: # Identifier preferably taken from a standard, like ISO 80000
+      definition: <string>
+      [remark: <string>]
+      [comment: <string>]
+      [deprecation: <reason>]
+  ]*
+]
+[
+  units:
+  [
+    <vss-unit-identifier>: # Typically unit abbreviation, like km/h or mm, but
+      definition: <string>
+      [unit: <string>] # Full name of unit, optional, if not given assumed to be equal to vss-unit-identifier
+      quantity: <string> # Shall preferably match a defined quantity
+      [allowed-datatypes] : ['numeric', 'string', uint8', ...]] # Allowed datatypes in VSS standard catalog
+      [deprecation: <reason>]
+
+  ]*
+```
+
+Defing quantities is recommended, but currently optional for backward compatibility reasons.
+If two or more units are of the same quantity then it shall be possible to convert between those units.
+
+*Example: It is possible to convert between `m/s`and `km/h` as they are based on the same quantity!*
+
+The `allowed-datatypes` attributes can be used to specify which VSS datatypes that can contain values of a particular unit.
+For most units the symbolic datatype `numeric` meaning any float or integer datatype can be used.
+As an example, both `uint8` and `float` can be used to represent a length value.
+If using `uint8` you will have range restrictions, but that might be acceptable for some signals.
+For some units more specific datatype restrictions are relevant. Some examples:
+
+* A date/time expressed in ISO 8061 format can only be represented in string
+* A UNIX Timestamp signal must be at least 32 bit unsigned to be able to handle date/time after year 2038.
+
+The `deprecation` keyword can be used to indicate that a specific quantity or unit may be removed in the future,
+VSS-tools shall preferably give a warning if a signal use a deprecated unit or the unit used belongs to a deprecated quantity. The reason should preferably list when and why the unit is deprecated, a hypothetical example is given below:
+
+```
+
+  inch:
+    label: inch
+    description: Distance measured in inches
+    domain: distance
+    deprecation: V5.0 replaced with in
+  in:
+    label: inch
+    description: Distance measured in inches
+    domain: distance
+```
+
+
+Below is an excerpt of the unit file for the VSS standard catalog
+
+
+```
+quantities:
+  length:
+    definition: Linear extent in space between any two points (ISO 80000-3:2019)
+    remark: Length does not need to be measured along a straight line.
+            Length is one of the seven base quantities in the International System of Units (ISO 80000-1).
+  datetime:
+    definition: Specific point in time
+    remark: This quantity is not described in ISO 80000.
+    comment: Example usage of this quanity could be ISO 8601 string representation of date and time, or UNIX timestamp
+  duration:
+    definition: Measure of the time difference between two events (ISO 80000-3:2019)
+  relation:
+    definition: Dimensionsless quantity for relation between two values of the same quantity.
+    remark: This quantity is not described in ISO 80000.
+units:
+  # Note: Only a subset of units shown below
+  m:
+    definition: Length measured in meters
+    unit: meter
+    quantity: length
+    allowed-datatypes: ['numeric']
+  iso8061:
+    definition: Date and Time expressed as a string according to ISO 8601
+    unit: ISO 8601
+    quantity: datetime
+    allowed-datatypes: ['string']
+  unix-time:
+    definition: Number of non-leap seconds which have passed since 00:00:00 UTC on Thursday, 1 January 1970
+    unit: UNIX Timestamp
+    quantity: datetime
+    allowed-datatypes: ['uint32','uint64','int64']
+  min:
+    definition: Duration measure in minutes
+    unit: minute
+    quantity: duration
+    allowed-datatypes: ['numeric']
+  percent:
+    definition: Relation expressed as percent
+    quantity: relation
+    allowed-datatypes: ['numeric']
+
+```
+
+## Defining custom units
+
+It is possible to define custom units in a unit file.
+Assume for instance you want to have a signal showing remaining range in [furlong](https://en.wikipedia.org/wiki/Furlong).
+Then you could add an additional unit `furlong`. No need to specify `unit` or `symbol` as they equals the default (i.e. "furlong").
+As this is unit not commonly used and not described in any standards it might be relevant to describe how it can be converted to other units.
+That is however only informative, as it a custom unit a downstream implementation supporting unit conversion may not support automatic conversion
+of furlong to other units.
+
+```
+units:
+  furlong:
+    definition: Length measured in furlong, 1 furlong equals 201.1680 m
+    quantity: length
+    allowed-datatypes: ['numeric']
+```