From 387a246ea817154908f342f50de4a412f54b9e53 Mon Sep 17 00:00:00 2001 From: Sebastian Schleemilch Date: Thu, 29 Aug 2024 11:03:01 +0200 Subject: [PATCH] Adding concept of 'format' Signed-off-by: Sebastian Schleemilch --- .../rule_set/data_entry/data_formats.md | 48 +++++++++++++++++++ spec/Cabin/Infotainment.vspec | 2 +- spec/Powertrain/TractionBattery.vspec | 4 +- .../TractionBattery/BatteryConditioning.vspec | 4 +- spec/Vehicle/Vehicle.vspec | 12 ++--- spec/formats.yaml | 15 ++++++ spec/units.yaml | 13 ----- 7 files changed, 74 insertions(+), 24 deletions(-) create mode 100644 docs-gen/content/rule_set/data_entry/data_formats.md create mode 100644 spec/formats.yaml diff --git a/docs-gen/content/rule_set/data_entry/data_formats.md b/docs-gen/content/rule_set/data_entry/data_formats.md new file mode 100644 index 000000000..8a473784d --- /dev/null +++ b/docs-gen/content/rule_set/data_entry/data_formats.md @@ -0,0 +1,48 @@ +--- +title: "Data Formats" +date: 2024-08-29T12:36:12+02:00 +weight: 25 +--- + +## Data Formats + +For some data it is necessary to specify the format. +An example are dates. +Let's say we specify a leaf e.g. `Vehicle.ProductionDate` and give it +the datatype `string`. How would a consumer know what to expect in this string? +It could be ISO8601, it could be a unix-timestamp or it could be something totally different. +To provide that info, a `format` field can be used. + +A complete definition of a `ProductionDate` field could then look like this: + +```yaml +Vehicle.ProductionDate: + description: The production date of the car + datatype: string + format: iso8601 +``` + +All formats being used have to be specified in format definition files. + +## Format definitions file + +It has the following format: + +```yaml +unix-time: + description: Unix Timestamp + allowed-datatypes: ['uint32','uint64','int64'] +``` + +Both fields are required: +- `description`: Should specify how the format is specified +- `allowed-datatypes`: Datatypes allowed when using this format. The consistency will be enforced by `vss-tools` + +Please note that you can either specify `unit` or `format`. + + +## Supported Data Formats in VSS Standard Catalog + +The catalog defines common formats in the `formats.yaml` file similar to how units are handled. `vss-tools` provides an interface to pass one or more format files. +Like with unit files, `formats.yaml` will be loaded if it is present on the level +of the given entry point `vspec` file. diff --git a/spec/Cabin/Infotainment.vspec b/spec/Cabin/Infotainment.vspec index 9b1cd611e..30f32327e 100644 --- a/spec/Cabin/Infotainment.vspec +++ b/spec/Cabin/Infotainment.vspec @@ -234,7 +234,7 @@ HMI.IsScreenAlwaysOn: HMI.LastActionTime: datatype: string type: sensor - unit: iso8601 + format: 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 index 3ffa40e11..f59d69423 100644 --- a/spec/Powertrain/TractionBattery.vspec +++ b/spec/Powertrain/TractionBattery.vspec @@ -21,7 +21,7 @@ Id: ProductionDate: datatype: string type: attribute - unit: iso8601 + format: iso8601 description: Production date of battery in ISO8601 format, e.g. YYYY-MM-DD. ErrorCodes: @@ -634,7 +634,7 @@ Charging.Timer.Mode: Charging.Timer.Time: datatype: string type: actuator - unit: iso8601 + format: 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/Powertrain/TractionBattery/BatteryConditioning.vspec b/spec/Powertrain/TractionBattery/BatteryConditioning.vspec index 0167eace9..6163809fe 100644 --- a/spec/Powertrain/TractionBattery/BatteryConditioning.vspec +++ b/spec/Powertrain/TractionBattery/BatteryConditioning.vspec @@ -64,7 +64,7 @@ BatteryConditioning.StartTime: datatype: string description: Start time for battery conditioning, formatted according to ISO 8601 with UTC time zone. - unit: iso8601 + format: iso8601 comment: If the vehicle is asleep, this is the time the vehicle and the battery conditioning system must wake up and start monitoring the battery and if necessary start heating/cooling of the battery. @@ -72,7 +72,7 @@ BatteryConditioning.TargetTime: type: actuator datatype: string description: Target time when conditioning shall be finished, formatted according to ISO 8601 with UTC time zone. - unit: iso8601 + format: iso8601 comment: For FAST_CHARGING mode this is typically the time when charging is supposed to start. For DRIVING mode this is typically the expected departure time. Battery conditioning will be deactivated when this time has passed. diff --git a/spec/Vehicle/Vehicle.vspec b/spec/Vehicle/Vehicle.vspec index 54f54c987..146eccadd 100644 --- a/spec/Vehicle/Vehicle.vspec +++ b/spec/Vehicle/Vehicle.vspec @@ -97,7 +97,7 @@ VehicleIdentification.BodyType: VehicleIdentification.DateVehicleFirstRegistered: datatype: string type: attribute - unit: iso8601 + format: iso8601 description: The date in ISO 8601 format of the first registration of the vehicle with the respective public authorities. VehicleIdentification.LicensePlate: @@ -114,19 +114,19 @@ VehicleIdentification.MeetsEmissionStandard: VehicleIdentification.ProductionDate: datatype: string type: attribute - unit: iso8601 + format: iso8601 description: The date in ISO 8601 format of production of the item, e.g. vehicle. VehicleIdentification.PurchaseDate: datatype: string type: attribute - unit: iso8601 + format: 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 + format: 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: @@ -221,7 +221,7 @@ StartTime: datatype: string type: attribute default: '0000-01-01T00:00Z' - unit: iso8601 + format: 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). @@ -452,7 +452,7 @@ CurrentLocation: CurrentLocation.Timestamp: datatype: string type: sensor - unit: iso8601 + format: iso8601 description: Timestamp from GNSS system for current location, formatted according to ISO 8601 with UTC time zone. CurrentLocation.Latitude: diff --git a/spec/formats.yaml b/spec/formats.yaml new file mode 100644 index 000000000..55031b2f5 --- /dev/null +++ b/spec/formats.yaml @@ -0,0 +1,15 @@ +unix-time: + description: Unix time in seconds + allowed-datatypes: ['uint32','uint64','int64'] +unix-time-ms: + description: Unix time in milliseconds + allowed-datatypes: ['uint32','uint64','int64'] +iso8601: + description: Date and Time expressed as a string according to ISO 8601 + allowed-datatypes: ['string'] +ipv4: + description: Internet Protocol version 4 + allowed-datatypes: ['string'] +ipv6: + description: Internet Protocol version 6 + allowed-datatypes: ['string'] diff --git a/spec/units.yaml b/spec/units.yaml index ee0c9ab36..e88425a62 100644 --- a/spec/units.yaml +++ b/spec/units.yaml @@ -214,19 +214,6 @@ years: quantity: duration allowed-datatypes: ['numeric'] -# Datetime - -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'] -iso8601: - definition: Date and Time expressed as a string according to ISO 8601 - unit: ISO 8601 - quantity: datetime - allowed-datatypes: ['string'] - # Pressure mbar: