From e9e70868cb3075c2c53019e12402202c166e9d81 Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Wed, 18 Oct 2023 15:43:38 +0200 Subject: [PATCH] Updating doc and refactoring unit file Signed-off-by: Erik Jaegervall --- .../rule_set/data_entry/data_unit_types.md | 183 ++++++++++++------ spec/units.yaml | 168 +++++++--------- 2 files changed, 192 insertions(+), 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 index 7a7f83ac2..e3ce38dd4 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 @@ -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,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: + [ + : # Identifier preferably taken from a standard, like ISO 80000 + definition: + [remark: ] + [comment: ] + [deprecated: [True|False]] # Default False + ]* +] +[ + units: + [ + : # Typically unit abbreviation, like km/h or mm, but + definition: + [unit: ] # Full name of unit, optional, if not given assumed to be equal to vss-unit-identifier + quantity: # 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'] +``` diff --git a/spec/units.yaml b/spec/units.yaml index 5289284b4..b575f2674 100644 --- a/spec/units.yaml +++ b/spec/units.yaml @@ -1,272 +1,248 @@ # This file defines units supported in the VSS standard catalog -# Ambition: Two units belongs to same domain if it is possible to convert -# between them, either with multiplier/denominator or by custom -# (hard-coded) function -# -# (However, conversion may result in out of range if target unit/datatype cannot -# represent the value) -# -# Ambition when defining domains: -# -# A domain shall have a default unit. -# Other units in the same name domain shall specify how to convert to default unit. -# Either by explicitly or implicitly stating multiplier/denominator -# or identifying that custom (hard-coded) conversion is needed -# multiplier: x (default: 1) -# denominator: Y (default: 1) -# custom-conversion: true | false (default: false) -# -# The default unit does not need to specify any of them (i.e. use default = 1:1 mapping) -# -# For backward compatibility reasons defining domains should for now be optional -# I.e. tooling shall not give an error if a domain has not been defined -# TODO: Agree on long term standpoint of whether domains shall be required -# Alt 1: Required for all VSS-based models, i.e. give warning today that it may become mandatory if not not defined -# Alt 2: Required only for standard catalog (i.e. this file), i.e for now give warning if using "--strict" mode -# Alt 3: Always keep it optional, potentially give info if using --strict mode - - -domains: - distance: - description: Length traveled or length between two objects - # Default unit specifies the base for conversion - # Other units needs to specify how conversion to default unit can happen - default-unit: m - speed: - description: Change in distance per time unit - default-unit: km/h - point in time: - description: Specific moment in time - default-unit: iso8061 - time: - description: Time between two events - default-unit: s - pressure: - description: Force applied perpendicular to the surface of an object per unit area - default-unit: Pa - # More domains to be added in similar way. units: mm: + label: millimeter description: Distance measured in millimeters + # Shall we call the field "quantity" (as in ISO 80000) rather than "domain"? domain: distance - # Multiply this value by 1000 to get default unit (meters) - multiplier: 1000 - # List of allowed datatypes. Numeric is short-cut for all int/uint types - allowed-datatypes: ['numeric'] cm: + label: centimeter description: Distance measured in centimeters + # Shall we use the quantity "length" rather than "distance"?, different meaning in ISO 80000, "length" is more generic domain: distance - multiplier: 100 - allowed-datatypes: ['numeric'] m: + # As of today we have an implicit identifier (here "m"), label and description + # Could this possibly be improved? + label: meter description: Distance measured in meters domain: distance - # No explicit multiplier/denominator as default, implies 1 - allowed-datatypes: ['numeric'] km: + label: kilometer + # Would it be an idea to migrate from description to definition? description: Distance measured in kilometers domain: distance - # Divide this value by 1000 to get default unit - denominator: 1000 - allowed-datatypes: ['numeric'] + # Here we have "inch" in multiple places, for other units we typically use the abbreviation as identifier + # So shall we possibly change to "in" as identifier? inch: + label: inch description: Distance measured in inches domain: distance - # Maybe support only integers for multiplier/denominator, if we prefer that over 0.0254 - multiplier: 254 - denominator: 10000 - allowed-datatypes: ['numeric'] km/h: + label: kilometer per hour description: Speed measured in kilometers per hours domain: speed - allowed-datatypes: ['numeric'] m/s: + label: meters per second description: Speed measured in meters per second domain: speed - multiplier: 36 - denominator: 10 - allowed-datatypes: ['numeric'] m/s^2: + label: meters per second squared description: Acceleration measured in meters per second squared domain: acceleration cm/s^2: + label: centimeters per second squared description: Acceleration measured in centimeters per second squared domain: acceleration ml: + label: milliliter description: Volume measured in milliliters domain: volume l: + label: liter description: Volume measured in liters domain: volume cm^3: + label: cubic centimeters description: Volume measured in cubic centimeters domain: volume celsius: + label: degree celsius description: Temperature measured in degree celsius domain: temperature degrees: + label: degree description: Angle measured in degrees domain: angle degrees/s: + label: degree per second description: Angular speed measured in degrees per second domain: angular speed W: + label: watt description: Power measured in watts domain: power kW: + label: kilowatt description: Power measured in kilowatts domain: power PS: + label: horsepower description: Power measured in horsepower domain: power kWh: + label: kilowatt hours description: Energy consumption measured in kilowatt hours domain: energy consumption g: + label: gram description: Mass measured in grams domain: mass kg: + label: kilogram description: Mass measured in kilograms domain: mass lbs: + label: pound description: Mass measured in pounds domain: mass V: + label: volt description: Electric potential measured in volts domain: electric potential A: + label: ampere description: Electric current measured in amperes domain: electric current Ah: + label: ampere hours description: Electric charge measured in ampere hours domain: electric charge ms: + label: millisecond description: Time measured in milliseconds domain: time - denominator: 1000 - allowed-datatypes: ['numeric'] s: + label: second description: Time measured in seconds + # The ISO 80000 quantity is "duration", not "time" domain: time - allowed-datatypes: ['numeric'] min: + label: minute description: Time measured in minutes domain: time - multiplier: 60 - allowed-datatypes: ['numeric'] h: + label: hour description: Time measured in hours domain: time - multiplier: 3600 - allowed-datatypes: ['numeric'] day: + label: days description: Time measured in days domain: time - multiplier: 86400 - allowed-datatypes: ['numeric'] weeks: + label: weeks description: Time measured in weeks domain: time - multiplier: 604800 - allowed-datatypes: ['numeric'] months: + label: months description: Time measured in months domain: time - # Multiplier based on 30 day month - multiplier: 2592000 - allowed-datatypes: ['numeric'] years: + label: years description: Time measured in years domain: time - # Multiplier based on 365 day year - multiplier: 31536000 - allowed-datatypes: ['numeric'] - iso8061: - description: Point in time expressed as string according to ISO 8601 - domain: point in time - allowed-datatypes: ['string'] - # Special conversion method 1so8601 -> timestamp needed + # Do we see a generic problem having blanks in identifier, we could use something else like "unix-time" UNIX Timestamp: + label: UNIX Timestamp description: 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. + # Point in time is not an ISO 80000 quantity, maybe it cannot be considered as a quantity at all domain: point in time - # Conversion custom , i.e this file does not specify how conversion to iso8061 happens - conversion: custom - allowed-datatypes: ['uint32','uint64','int64'] mbar: + label: millibar description: Pressure measured in millibars domain: pressure - multiplier: 100 Pa: + label: pascal description: Pressure measured in pascal domain: pressure kPa: + label: kilopascal description: Pressure measured in kilopascal domain: pressure - multiplier: 1000 - psi: - description: Pressure measured in pounds per square inch - domain: pressure - multiplier: 6894.7572931783 stars: + label: stars description: Rating measured in stars domain: rating g/s: + label: grams per second description: Mass per time measured in grams per second domain: mass per time g/km: + label: grams per kilometer description: Mass per distance measured in grams per kilometers domain: mass per distance kWh/100km: + label: kilowatt hours per 100 kilometers description: Energy consumption per distance measured in kilowatt hours per 100 kilometers domain: energy consumption per distance ml/100km: + label: milliliter per 100 kilometers description: Volume per distance measured in milliliters per 100 kilometers domain: volume per distance l/100km: + label: liter per 100 kilometers description: Volume per distance measured in liters per 100 kilometers domain: volume per distance l/h: + label: liter per hour description: Flow measured in liters per hour domain: flow mpg: + label: miles per gallon description: Distance per volume measured in miles per gallon domain: distance per volume N: + label: newton description: Force measured in newton domain: force Nm: + label: newton meter description: Torque measured in newton meters domain: torque rpm: + label: revolutions per minute description: Rotational speed measured in revolutions per minute domain: rotational speed Hz: + label: frequency description: Frequency measured in hertz domain: frequency ratio: + label: ratio description: Relation measured as ratio domain: relation percent: + label: percent description: Relation measured in percent domain: relation nm/km: + label: nano meter per kilometer description: nm/km domain: nm/km dBm: + label: decibel milliwatt description: Power level expressed in decibels with reference to one milliwatt domain: relation kN: + label: kilo newton description: Force measured in kilo newton domain: force cpm: + label: cycles per minute description: Number of cycles per minute domain: frequency bpm: + label: beats per minute description: Number of human heart beats per minute domain: frequency Ohm: + label: resistance description: Electrical resistance measured in ohms domain: electric resistance Wh/km: description: Energy consumption per distance measured in watt hours per kilometer + label: watt hour per km domain: energy consumption per distance + psi: + description: Pressure measured in pounds per square inch + label: pounds per square inch + domain: pressure