Skip to content

Commit

Permalink
Updating doc and refactoring unit file
Browse files Browse the repository at this point in the history 
Signed-off-by: Erik Jaegervall <[email protected]>
  • Loading branch information
@erikbosch
erikbosch committed Nov 1, 2023
1 parent e243391 commit e9e7086
Show file tree
Hide file tree
Showing 2 changed files with 192 additions and 159 deletions.
183 changes: 120 additions & 63 deletions docs-gen/content/rule_set/data_entry/data_unit_types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -74,67 +74,124 @@ 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>]
[deprecated: [True|False]] # Default False
]*
]
[
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
[deprecated: [True|False]] # Default False
]*
```

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 `deprecated` keyword can be used to indicate that a specific quantity or unit will 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.

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']
```
Loading

0 comments on commit e9e7086

Please sign in to comment.