Refactoring unit file

Signed-off-by: Erik Jaegervall <[email protected]>
COVESA · Nov 22, 2023 · e9fbab9 · e9fbab9
1 parent f1bb863
commit e9fbab9
Show file tree

Hide file tree

Showing 7 changed files with 607 additions and 301 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 units (like [VISS](https://raw.g
 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. This concerns typically signals where datatype `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,133 @@ Vehicle.Powertrain.Transmission.ClutchWear:
 
 ## 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          | 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 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 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 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 of 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 follow the syntax defined below:
+
+```
+[
+ <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> # Quantity of the unit.
+    [allowed-datatypes] : ['numeric', 'string', uint8', ...]] # Allowed datatypes in VSS standard catalog
+    [deprecation: <reason>]
+]*
+```
+
+The VSS term `quantity` corresponds roughly to the term `quantity` as defined in for example ISO 80000.
+Typical example are `length`, `mass` and `velocity` that all can be expressed in SI-units.
+However, from a VSS perspective quantities do not need to correspond to physical quantities.
+It could be an arbitrary term, but it is generally expected that it is possible to convert between values
+using different units but defined with the same quantity.
+
+Example:
+
+```
+m:
+  definition: Length measured in meters
+  unit: meter
+  quantity: length
+  allowed-datatypes: ['numeric']
+
+mm:
+  definition: Length measured in millimeters
+  unit: millimeter
+  quantity: length
+  allowed-datatypes: ['numeric']
+```
+
+As `m` and `mm` are defined with the same quantity it is expected that you can convert a value from `m` to `mm`.
+
+The `allowed-datatypes` attributes can be used to specify which VSS datatypes 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 as a 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 unit may be removed in the future.
+Tooling shall preferably give a warning if a signal uses 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:
+    definition: Distance measured in inches
+    unit: inch
+    quantity: distance
+    deprecation: V5.0 replaced by 'in'
+  in:
+    definition: Distance measured in inches
+    unit: inch
+    quantity: distance
+```
+
+
+The unit syntax has recently been changed. To simplify transition to the new syntax it is recommended that
+tooling also supports unit files using the old syntax described below.
+
+```
+units:
+  [
+    <vss-unit-identifier>: # Typically unit abbreviation, like km/h or mm, but
+      label: <string> # Replaced with "unit"
+      description: <string> # Replaced with "definition"
+      quantity: <string>
+  ]*
+```
+
+## Quantity file syntax
+
+
+Defing quantities is recommended, but currently optional for backward compatibility reasons.
+If tooling supports quantity files it can verify that all units provided in unit files
+use defined quantities.
+
+``
+
+  [
+    <vss-quantity-identifier>: # Identifier preferably taken from a standard, like ISO 80000
+      definition: <string>
+      [remark: <string>] # remark as defined in for example ISO 80000
+      [comment: <string>]
+      [deprecation: <reason>]
+  ]*
+
+```
+
+
+The VSS list of quantitiess for the standard catalog exists in [quantities.yaml](https://github.com/COVESA/vehicle_signal_specification/blob/master/spec/quantities.yaml).
+
+## 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']
+```
diff --git a/spec/Cabin/Infotainment.vspec b/spec/Cabin/Infotainment.vspec
@@ -234,6 +234,7 @@ HMI.IsScreenAlwaysOn:
 HMI.LastActionTime:
   datatype: string
   type: sensor
+  unit: iso8601
   description: Time for last hmi action, formatted according to ISO 8601 with UTC time zone.
 
 HMI.DisplayOffDuration:

diff --git a/spec/Powertrain/TractionBattery.vspec b/spec/Powertrain/TractionBattery.vspec
@@ -21,6 +21,7 @@ Id:
 ProductionDate:
   datatype: string
   type: attribute
+  unit: iso8601
   description: Production date of battery in ISO8601 format, e.g. YYYY-MM-DD.
 
 ErrorCodes:
@@ -570,6 +571,7 @@ Charging.Timer.Mode:
 Charging.Timer.Time:
   datatype: string
   type: actuator
+  unit: iso8601
   description: Time for next charging-related action, formatted according to ISO 8601 with UTC time zone.
                Value has no significance if Charging.Timer.Mode is 'inactive'.
 

diff --git a/spec/Vehicle/Vehicle.vspec b/spec/Vehicle/Vehicle.vspec
@@ -97,6 +97,7 @@ VehicleIdentification.BodyType:
 VehicleIdentification.DateVehicleFirstRegistered:
   datatype: string
   type: attribute
+  unit: iso8601
   description: The date in ISO 8601 format of the first registration of the vehicle with the respective public authorities.
 
 VehicleIdentification.LicensePlate:
@@ -113,16 +114,19 @@ VehicleIdentification.MeetsEmissionStandard:
 VehicleIdentification.ProductionDate:
   datatype: string
   type: attribute
+  unit: iso8601
   description: The date in ISO 8601 format of production of the item, e.g. vehicle.
 
 VehicleIdentification.PurchaseDate:
   datatype: string
   type: attribute
+  unit: iso8601
   description: The date in ISO 8601 format of the item e.g. vehicle was purchased by the current owner.
 
 VehicleIdentification.VehicleModelDate:
   datatype: string
   type: attribute
+  unit: iso8601
   description: The release date in ISO 8601 format of a vehicle model (often used to differentiate versions of the same make and model).
 
 VehicleIdentification.VehicleConfiguration:
@@ -217,6 +221,7 @@ StartTime:
   datatype: string
   type: attribute
   default: '0000-01-01T00:00Z'
+  unit: iso8601
   description: Start time of current or latest trip, formatted according to ISO 8601 with UTC time zone.
   comment: This signal is supposed to be set whenever a new trip starts.
            A new trip is considered to start when engine gets enabled (e.g. LowVoltageSystemState in ON or START mode).
@@ -447,6 +452,7 @@ CurrentLocation:
 CurrentLocation.Timestamp:
   datatype: string
   type: sensor
+  unit: iso8601
   description: Timestamp from GNSS system for current location, formatted according to ISO 8601 with UTC time zone.
 
 CurrentLocation.Latitude:

diff --git a/spec/quantities.yaml b/spec/quantities.yaml
@@ -0,0 +1,80 @@
+# This file defines available quantities for the units defined for the VSS standard catalog in the file unit.yaml.
+# See VSS documentation for information on syntax and intended content
+
+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).
+velocity:
+  definition: Vector quantity giving the rate of change of a position vector (ISO 80000-3:2019)
+acceleration:
+  definition: Vector quantity giving the rate of change of velocity (ISO 80000-3:2019)
+volume:
+  definition: Extent of a three‑dimensional geometrical shape (ISO 80000-3:2019)
+temperature:
+  definition: Partial derivative of internal energy with respect to entropy at constant volume
+              and constant number of particles in the system (ISO 80000-3:2019)
+angle:
+  definition: TBD
+angular-speed:
+  definition: TBD
+power:
+  definition: Scalar product of force F acting to a body and its velocity (ISO 80000-4:2019)
+work:
+  definition: Process quantity describing the total action of a force F along a continuous curve
+              in three-dimensional space with infinitesimal displacement dr,
+              as a line integral of their scalar product (ISO 80000-4:2019)
+mass:
+  definition: Property of a body which expresses itself in terms of inertia
+              related to changes in its state of motion as well as
+              its gravitational attraction to other bodies (ISO 80000-4:2019)
+voltage:
+  definition: For a conductor, scalar quantity given by the
+              electric potential difference Vab (6-11.2) between
+              two points a and b respectively (IEC 80000-6:2022)
+electric-current:
+  definition: Scalar quantity equal to the quotient of the net
+              quasi-infinitesimal electric charge dQ
+              transferred through a surface during a quasiinfinitesimal
+              time interval and the duration dt of that interval (IEC 80000-6:2022)
+electric-charge:
+  definition: Additive scalar quantity attributed to any particle
+              and, generally, any system of them, to
+              characterize its electromagnetic interactions (IEC 80000-6:2022)
+duration:
+  definition: Measure of the time difference between two events (ISO 80000-3:2019)
+datetime:
+  definition: Specific point in time
+  remark: This quantity is not described in ISO 80000.
+  comment: Example usage of this quantity could be ISO 8601 string representation of date and time, or UNIX timestamp
+pressure:
+  definition: Quotient of the component of a force normal to a surface and its area (ISO 80000-4:2019)
+rating:
+  definition: TBD
+mass-per-time:
+  definition: TBD
+mass-per-distance:
+  definition: TBD
+energy-consumption-per-distance:
+  definition: TBD
+volume-per-distance:
+  definition: TBD
+volume-flow-rate:
+  definition: Scalar quantity characterizing the total flow through the two-dimensional domain A with
+              the normal vector en of a flowing fluid with velocity v as an integral (ISO 80000-4:2019)
+distance-per-volume:
+  definition: TBD
+force:
+  definition: Vector quantity describing interaction between bodies or particles (ISO 80000-4:2019)
+torque:
+  definition: quantity described by the scalar product M*eQ where M is moment of force and eQ is
+rotational-speed:
+  definition: TBD
+frequency:
+  definition: TBD
+relation:
+  definition: Dimensionsless quantity for relation between two values of the same quantity.
+  remark: This quantity is not described in ISO 80000.
+resistance:
+  definition: Property of a resistive element, equal to the scalar
+            quantity given by the quotient of voltage u and electric current i (IEC 80000-6:2022)