From 2b583216fd9a0d3678c343cfecb6221851750735 Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Fri, 1 Nov 2024 14:23:09 +0100 Subject: [PATCH] Doc Update Signed-off-by: Erik Jaegervall --- CHANGELOG.md | 9 ++ docs-gen/README.md | 2 +- docs-gen/content/governance/_index.md | 16 +++- docs-gen/content/license/_index.md | 4 +- docs-gen/content/rule_set/branches.md | 60 ++++++-------- .../content/rule_set/data_entry/_index.md | 15 ++-- .../content/rule_set/data_entry/data_types.md | 54 +++++++++++- .../rule_set/data_entry/data_types_struct.md | 58 +++++++++++-- .../data_entry/{attributes.md => default.md} | 13 +-- .../rule_set/data_entry/sensor_actuator.md | 82 ++++++++++--------- 10 files changed, 210 insertions(+), 103 deletions(-) rename docs-gen/content/rule_set/data_entry/{attributes.md => default.md} (71%) diff --git a/CHANGELOG.md b/CHANGELOG.md index aa762e740..751a2ae6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,15 @@ It includes changes that are included in released version, but also changes plan The `Vehicle.OBD` branch is now removed. If needed there is an OBD overlay in the `overlays` directory. +### Support for new `pattern` keyword + +String types can now be restricted by a RegExp pattern. + +### Support for `default` for signals and properties using struct types. + +Previously the documentation stated that default values could not be given for struct types. +That is now supported. + ## VSS 5.0 ### Signal Updates diff --git a/docs-gen/README.md b/docs-gen/README.md index 157721da2..bebd73230 100644 --- a/docs-gen/README.md +++ b/docs-gen/README.md @@ -92,7 +92,7 @@ Within the repository hugo server -D -s ./docs-gen ``` -Optional ```-D:``` include draft pages as well. Afterwards, you can access the +Optional ```-D``` include draft pages as well. Afterwards, you can access the page under http://localhost:1313/vehicle_signal_specification. ## Contribute diff --git a/docs-gen/content/governance/_index.md b/docs-gen/content/governance/_index.md index 51c931669..836836bad 100644 --- a/docs-gen/content/governance/_index.md +++ b/docs-gen/content/governance/_index.md @@ -4,8 +4,6 @@ weight: 15 chapter: false --- -# Governance - The Vehicle Signal Specification (VSS) project is an initiative by [COVESA](https://covesa.global/) to define a syntax and a catalog for vehicle signals. The artifacts maintained by the VSS project consist of: @@ -63,6 +61,20 @@ VSS is however an evolving syntax and catalog and there are still areas where ch Changes that breaks backward compatibility are typically introduced only in major releases (e.g. `X.0`) and shall be documented in release notes. This concerns changes to syntax and signals, but also to tools. +Changes considered as backward incompatible include: + +* Signals have been deleted, renamed or change of datatype or unit. +* New data entry attributes have been added to standard VSS catalog, only accepted by an updated VSS-tools version. +* VSS-tools CLI changed, for example arguments renamed or new mandatory arguments added. +* Columns/fields removed from VSS-tools exporter output. + + +Changes NOT considered as backward incompatible include: + +* New signals, units or quanties added to VSS standard catalog. +* New VSS-tools exporters added. +* Columns/fields added to VSS-tools exporter output. + The VSS project has introduced a [deprecation concept]({{% ref "../rule_set/basics.md#deprecation-since-version-21" %}}). If possible, when e.g. renaming or moving a signal or changing tools the old signal or parameter set shall be kept but marked as deprecated. That allows the change to be introduced in a minor version (e.g. `X.Y`). The old signal shall be removed first in the next major release, or later if needed. diff --git a/docs-gen/content/license/_index.md b/docs-gen/content/license/_index.md index 029a639b5..993c25fe2 100644 --- a/docs-gen/content/license/_index.md +++ b/docs-gen/content/license/_index.md @@ -10,9 +10,9 @@ chapter: false {{% /notice %}} ## Which license applies -VSS as well as the VSS-tools are covered by the [Mozilla Public License 2.0 (MPL-2.0)](https://opensource.org/licenses/mpl-2.0). The MPL-2.0 is an OSI approved Open Source license that gives you a lot of freedom using VSS in your products, or for (academic) research. It also provides a solid legal framework if you choose to contribute to either the standards or the tools. +VSS as well as the VSS-tools are covered by the [Mozilla Public License 2.0 (MPL-2.0)](https://opensource.org/license/mpl-2.0). The MPL-2.0 is an OSI approved Open Source license that gives you a lot of freedom using VSS in your products, or for (academic) research. It also provides a solid legal framework if you choose to contribute to either the standards or the tools. -We will line out some answers to commonly asked questions, but keep in mind this page is informational. The legally binding clauses can be found in the [license](https://opensource.org/licenses/mpl-2.0) itself. If in doubt, consult your friendly neighborhood lawyer or IP department. +We will line out some answers to commonly asked questions, but keep in mind this page is informational. The legally binding clauses can be found in the [license](https://opensource.org/license/mpl-2.0) itself. If in doubt, consult your friendly neighborhood lawyer or IP department. ## Can I use VSS / VSS-tools in my commercial products Most definitely yes. You must inform your users that the product contains MPLed code and need to provide access to the source (e.g. by linking to this documentation or our [Github repository](https://github.com/covesa/vehicle_signal_specification)). diff --git a/docs-gen/content/rule_set/branches.md b/docs-gen/content/rule_set/branches.md index 94204d851..ceffede51 100644 --- a/docs-gen/content/rule_set/branches.md +++ b/docs-gen/content/rule_set/branches.md @@ -10,43 +10,33 @@ signals. A branch entry example is given below: ```yaml -Trunk: +Vehicle.Trunk: type: branch description: All signals related to the rear trunk aggregate: false ``` +Each data entry has a name, in the example above `Vehicle.Trunk`. +VSS use a dot-notated name style where the full path of a branch consists of all parent branches from the root node separated by dots and at the end the name of the current branch. In the standard VSS catalog the root node is called `Vehicle`. -The following elements are defined: - -**`Body.Trunk`** -The list element name defines the dot-notated signal name to the signal. -Please note that all parental branches included in the name must be defined as -well. - -**```type```** -The value ```branch``` specifies that this is a branch entry (as -opposed to a signal entry). This is the default, in case ```type``` is omitted. - -**```description```** -Describes the meaning and content of the branch. -Recommended to start with a capital letter and end with a dot (`.`). - -**```comment ```** *[optional]* `since version 3.0` -A comment can be used to provide additional informal information on a branch. -This could include background information on the rationale for the branch, -references to related branches, standards and similar. -Recommended to start with a capital letter and end with a dot (`.`). - -**```instances```** *[optional]* -For specifying that multiple instances of this branch exist, for more information see documentation on -[instances](/vehicle_signal_specification/rule_set/instances/). - -**```aggregate```** *[optional]* -Defines whether or not this branch is an aggregate. -If not defined, this defaults to ```false```. -An aggregate is a collection of signals that make sense to handle together in a system. -A typical example could be GNSS location, where latitude and longitude make sense to read -and write together. This is supposed to be deployment and tool specific, -and for that reason no branches are aggregates by default in VSS. -For branches that both have `instances` defined and `aggregate: true`, then aggregate refers to the signals for -individual instances, i.e. signals for different instances can be handled separately. +When using `*.vspec` files to define a VSS catalog it is not necessary to give the full dot-notated name for each branch as the +`*.vspec` format supports [includes](../includes/) that can be used to append entries to a specific branch. + +## Mandatory Branch Attributes + +This is the list of attributes that must be specified for every data entry. + +Attribute | Description | Comment +-------------|-----------------------------|-------- +`type` | Defines the type of the node. For a branch this must be `branch`. | The default for `type` is `branch`. +`description`| Describes the meaning and content of the branch. Recommended to start with a capital letter and end with a dot (`.`). + +## Optional Data Entry Attributes + +In additon to the mandatory attributes some optional attributes have been defined. +There may be additional constraints on their usage not specified in the table below. + +Attribute | Description | Comment +-------------|-----------------------------|-------- +`comment` | A comment can be used to provide additional informal information on a branch. This could include background information on the rationale for the branch, references to related branches, standards and similar. Recommended to start with a capital letter and end with a dot (`.`). | *since version 3.0* +`instances` | For specifying that multiple instances of this branch exist, for more information see documentation on [instances](/vehicle_signal_specification/rule_set/instances/). +`aggregate` | Defines whether or not this branch is an aggregate. If not defined, this defaults to ```false```. An aggregate is a collection of signals that make sense to handle together in a system. A typical example could be GNSS location, where latitude and longitude make sense to read and write together. This is supposed to be deployment and tool specific, and for that reason no branches are aggregates by default in VSS. For branches that both have `instances` defined and `aggregate: true`, then aggregate refers to the signals for individual instances, i.e. signals for different instances can be handled separately. diff --git a/docs-gen/content/rule_set/data_entry/_index.md b/docs-gen/content/rule_set/data_entry/_index.md index 5b7f32990..52dc68e83 100644 --- a/docs-gen/content/rule_set/data_entry/_index.md +++ b/docs-gen/content/rule_set/data_entry/_index.md @@ -6,14 +6,11 @@ weight: 2 --- Leaf nodes of the tree contain metadata describing the data associated to the node. -In order to help application developers, who are using the specification, it makes a distinction between three types of signals - -[```sensor```](/vehicle_signal_specification/rule_set/data_entry/sensor_actuator/), -[```actuator```](/vehicle_signal_specification/rule_set/data_entry/sensor_actuator/) - and -[```attribute```](/vehicle_signal_specification/rule_set/data_entry/attributes/). -The difference between sensors/actuators and attributes is that sensors/actuators typically have -a publisher (or producer) that updates the signal value continuously when a change occur while an -attribute has a set value that should typically not change more than once per ignition cycle. +In order to help application developers, who are using the specification, it makes a distinction between three types of signals: + +* sensor +* actuator +* attribute Examples and more information you'll find in the -[Sensors & Actuators chapter](/vehicle_signal_specification/rule_set/data_entry/sensor_actuator/) and -[Attributes chapter](/vehicle_signal_specification/rule_set/data_entry/attributes/). +[Sensors, Actuators and Attributes chapter](/vehicle_signal_specification/rule_set/data_entry/sensor_actuator/). diff --git a/docs-gen/content/rule_set/data_entry/data_types.md b/docs-gen/content/rule_set/data_entry/data_types.md index 0746ba958..a6738a0c8 100644 --- a/docs-gen/content/rule_set/data_entry/data_types.md +++ b/docs-gen/content/rule_set/data_entry/data_types.md @@ -4,8 +4,58 @@ date: 2019-08-04T11:11:48+02:00 weight: 10 --- -Each [data entry](/vehicle_signal_specification/rule_set/data_entry/) specifies a ```datatype``` from the following set (from Franca IDL). -Datatypes shall not be used for [branch entry](/vehicle_signal_specification/rule_set/branches/) +In VSS each [data entry](/vehicle_signal_specification/rule_set/data_entry/) (except branches and structs) must specify a ```datatype```. +It can be a primitive type, an array of a primitive type or a struct type. + +This is the default datatype for the given entry. +The VSS project typically selects datatype (and unit) so that values are easily understandable by humans, +can cover a reasonable range and supports reasonable precision. +An example is given below where `Vehicle.Speed` has been assigned the datatype `float` and the unit `km/h`. + +``` +Vehicle.Speed: + datatype: float + type: sensor + unit: km/h + description: Vehicle speed. +``` + +The meaning of this is that unless otherwise specified (by an API), the value is supposed to be given as a decimal number with km/h as unit. +An example from [VISS](https://github.com/COVESA/vehicle-information-service-specification) is given below, showing how the speed 123.45 km/h is returned As `"123.45"`. + +``` +HTTP/1.1 200 OK + Content-Type: application/json; charset=utf-8 + ... + { + “data”:{“path”:”Vehicle.Speed”, + “dp”:{“value”:”123.45”, “ts”:”2020-04-15T13:37:00Z”} + } + } +``` + +Another example is the [Kuksa Client](https://github.com/eclipse-kuksa/kuksa-python-sdk) where values are to be given in the unit and datatype specified by VSS. + +``` +Test Client> setValue Vehicle.Speed 43.2 +2024-10-18 16:12:54,307 INFO kuksa_client.grpc.aio: Using v2 +OK + +Test Client> getValue Vehicle.Speed +{ + "path": "Vehicle.Speed", + "value": { + "value": 43.20000076293945, + "timestamp": "2024-10-18T14:12:54.314814+00:00" + } +} +``` + +It is *not* mandatory for an implementation, protocol or an API to use the datatype and unit specified by the COVESA VSS catalog. +A VSS entity can in a customized or extended VSS catalog, be annotated with information specifying that the data entry shall be transmitted or stored using a different datatype, possibly involving scaling and offset. An API may in addition or as replacement to the default datatype and offset allow the entity to be read or written using alternative representations or alternative units. + +It is however recommended that the default method to read or write a dataentry shall be based on the datatype and unit definined in the standard VSS catalog for signals definied in the standard VSS catalog, as there otherwise is a risk that the client and the server interpret the value differently. + ## Supported datatypes diff --git a/docs-gen/content/rule_set/data_entry/data_types_struct.md b/docs-gen/content/rule_set/data_entry/data_types_struct.md index d30d24cb3..ea8632841 100644 --- a/docs-gen/content/rule_set/data_entry/data_types_struct.md +++ b/docs-gen/content/rule_set/data_entry/data_types_struct.md @@ -158,7 +158,7 @@ Structs in parent branches will not be visible, in those cases absolute path nee *The reference by leaf name is applicable only for structs referencing other structs!* -## Expectations on VSS implementations (e.g. VISS, KUKSA.val) +## Expectations on VSS implementations (e.g. VISS, KUKSA) It is expected of implementations to support atomic read/write/subscribe of complete signals defined with struct datatype. They may support read of parts of signal, e.g. `DeliveryList.Receiver` @@ -271,19 +271,63 @@ Inline/anonymous structs are not allowed! ## Default Values -VSS supports [default values](/vehicle_signal_specification/rule_set/data_entry/attributes/). +VSS supports [default values](/vehicle_signal_specification/rule_set/data_entry/default/). -Default values are not allowed for signals of struct datatype. -This also mean that VSS does not need to specify notation for struct values. -An exception is arrays of struct-datatypes, where "empty array", i.e. `[]` shall be supported as default value. +Default values are also allowed for signals of struct datatype. -It shall be possible to define default values for properties (unless the item is of struct datatype). +It is also possible to define default values for properties. If all items of a struct datatype have default values, then a signal (or item) using the struct datatype is also considered to have a default value. +Default values are given in Yaml syntax, two examples are given below + +```yaml +ReturnAddress: + datatype: Types.DeliveryInfo + type: attribute + description: Where to send returns + default: + Address: "221B Baker Street" + Receiver: "Sherlock Holmes" + Open: + Open: 9 + Close: 17 +``` + +```yaml +ReturnAddresses: + datatype: Types.DeliveryInfo[] + type: attribute + description: Where to send returns + default: + - Address: "221B Baker Street" + Receiver: "Sherlock Holmes" + Open: + Open: 9 + Close: 17 + - Address: "742 Evergreen Terrace" + Receiver: "Homer Simpson" + Open: + Open: 15 + Close: 16 + +``` + +As a special case, `[]` can be used as default value to denote an empty array. + +```yaml +DeliveryAddresses: + datatype: Types.DeliveryInfo[] + type: sensors + description: List of deliveries + default: [] +``` + +It is also possible to use JSON syntax to specify default values for structs. + ## Allowed Values VSS supports [specification of allowed values](/vehicle_signal_specification/rule_set/data_entry/allowed/). Using `allowed` for `type: property` is allowed (if `allowed` is supported for the used datatype). -Using `allowed` for signals and items of struct datatype or array of struct datatype is not allowed. +Using `allowed` for signals and items of struct datatype or array of struct datatype is allowed. diff --git a/docs-gen/content/rule_set/data_entry/attributes.md b/docs-gen/content/rule_set/data_entry/default.md similarity index 71% rename from docs-gen/content/rule_set/data_entry/attributes.md rename to docs-gen/content/rule_set/data_entry/default.md index f79b69fc7..da04a0a35 100644 --- a/docs-gen/content/rule_set/data_entry/attributes.md +++ b/docs-gen/content/rule_set/data_entry/default.md @@ -1,13 +1,16 @@ --- -title: "Attributes" +title: "Default Values" date: 2019-08-04T12:37:31+02:00 weight: 40 --- -An attribute is an entity that has a default value, specified by -its ```default``` member. +VSS supports default values by the `default` attribute. +The intention is to provide a mechanism to provide initial values for data entries already when loading a VSS catalog. +This could typically be useful for attributes that never or rarely change, like [vehicle VIN](https://en.wikipedia.org/wiki/Vehicle_identification_number) or vehicle color. + The standard Vehicle Signal Specification does not include default values for all attributes. -If a default value has not been specified then the OEM must define a default value matching the actual vehicle. +If a default value has not been specified then the OEM must define a default value matching the actual vehicle, +either by using the `default` concept, or by the same other mechanism. If the standard defines a default value but it does not fit the actual vehicle, then the OEM must override the standard default value. @@ -51,4 +54,4 @@ SeatPosCount: description: Number of seats across each row from the front to the rear ``` -Using default values for structs is not allowed! +Default values can also be defined for [structs](/vehicle_signal_specification/rule_set/data_entry/data_types_struct/). diff --git a/docs-gen/content/rule_set/data_entry/sensor_actuator.md b/docs-gen/content/rule_set/data_entry/sensor_actuator.md index 89251fdc5..17c261a73 100644 --- a/docs-gen/content/rule_set/data_entry/sensor_actuator.md +++ b/docs-gen/content/rule_set/data_entry/sensor_actuator.md @@ -1,5 +1,5 @@ --- -title: "Sensors & Actuators" +title: "Sensors, Actuators and Attributes" date: 2019-08-04T12:37:03+02:00 weight: 30 --- @@ -8,57 +8,59 @@ Sensors are signals to read values of properties in a vehicle. Values of sensors Actuators are used to control the desired value of a property. Some properties in a vehicle cannot change instantly. A typical example is position of a seat or a window. Reading a value of an actuator shall return the current actual value, e.g. the current position of the seat, rather than the wanted/desired position. A typical example could be if someone wants to change the position of a seat from 0 to 100. This can be changed by setting the corresponding actuator to 100. If the actuator is read directly after the set request it will still return 0 as it might take some seconds before the seat reaches the wanted position of 100. If the seat by some reason is blocked or cannot be moved due to safety reasons it might never reach the wanted position. It is up to the vehicle to decide how long time it shall try to reach the desired value and what to do if it needs to give up. -A data entry for a sensor or actuator defines its members. A data +Attributes are signals that have a default value, specified by +its ```default``` member. +The standard Vehicle Signal Specification does not include default values for all attributes. +If a default value has not been specified then the OEM must define a default value matching the actual vehicle. +If the standard defines a default value but it does not fit the actual vehicle, +then the OEM must override the standard default value. + +Attribute values can also change, similar to sensor values. +The latter can be useful for attribute values that are likely to change during the lifetime of the vehicle. +However, attribute values should typically not change more than once per ignition cycle, +or else it should be defined as a sensor instead. + +A data entry for a signal defines its members. A data entry example is given below: ```yaml -Speed: +Vehicle.Speed: type: sensor - description: The vehicle speed. - comment: For engine speed see Vehicle.Powertrain.CombustionEngine.Engine.Speed. datatype: float unit: km/h - min: 0 - max: 300 + description: Vehicle speed. ``` -**```Drivetrain.Transmission.Speed```** -Defines the dot-notated name of the data entry. Please note that -all parental branches included in the name must be defined as well. +Each data entry has a name, in the example above `Vehicle.Speed`. +VSS use a dot-notated name style where the full path of a data entry consists of all parent branches from the root node separated by dots and at the end the name of the data entry itself. In the standard VSS catalog the root node is called `Vehicle`. + +When using `*.vspec` files to define a VSS catalog it is not necessary to give the full dot-notated name for each data-entry, as the +`*.vspec` format supports [includes](../includes/) that can be used to append entries to a specific branch. -**```type```** -Defines the type of the node. This can be `branch`, -`sensor`, `actuator` or `attribute`. +In addition to `sensor`, `actuator`and `attribute` VSS also support entries to describe [struct data types](/vehicle_signal_specification/rule_set/data_entry/data_types_struct/). The information on data entry attributes below is partially valid also for structs. -**```datatype```** -The string value of the datatype specifies the scalar type of the data entry -value. See [datatype](/vehicle_signal_specification/rule_set/data_entry/data_types/) chapter for a list of available datatypes. +## Mandatory Data Entry Attributes -**```description```** -Describes the meaning and content of the signal. -The `description`shall together with other mandatory members like `datatype` and `unit` provide sufficient information -to understand what the signal contains and how signal values shall be constructed or interpreted. -Recommended to start with a capital letter and end with a dot (`.`). +This is the list of attributes that must be specified for every data entry. -**```comment ```** *[optional]* `since version 3.0` -A comment can be used to provide additional informal information on a signal. -This could include background information on the rationale for the signal design, -references to related signals, standards and similar. -Recommended to start with a capital letter and end with a dot (`.`). +Attribute | Description | Comment +-------------|-----------------------------|-------- +`type` | Defines the type of the node. This can be `branch`, `sensor`, `actuator` or `attribute`. +`datatype` | Specifies the scalar type of the data entry value. See [datatype](/vehicle_signal_specification/rule_set/data_entry/data_types/) chapter for a list of available datatypes. Shall not be used for `branch` entries.| +`description`| Describes the meaning and content of the signal. The `description`shall together with other members like `datatype` and `unit` provide sufficient information to understand what the signal contains and how signal values shall be constructed or interpreted. Recommended to start with a capital letter and end with a dot (`.`). -**```min```** *[optional]* -The minimum value, within the interval of the given ```datatype```, that the -data entry can be assigned. -If omitted, the minimum value will be the "Min" value for the given datatype. -Cannot be specified if ```allowed``` is defined for the same data entry. +## Optional Data Entry Attributes -**```max```** *[optional]* -The maximum value, within the interval of the given ```datatype```, that the -data entry can be assigned. -If omitted, the maximum value will be the "Max" value for the given datatype. -Cannot be specified if ```allowed``` is defined for the same data entry. +In additon to the mandatory attributes some optional attributes have been defined. +There may be additional constraints on their usage not specified in the table below. -**```unit```** *[optional]* -The unit of measurement that the data entry has. See [Data Units](/vehicle_signal_specification/rule_set/data_entry/data_unit_types/) -chapter for a list of available units. This -cannot be specified if ```allowed``` is defined for the same data entry. +Attribute | Description | Comment +-------------|-----------------------------|-------- +`comment` | A comment can be used to provide additional informal information on a signal. This could include background information on the rationale for the signal design, references to related signals, standards and similar. Recommended to start with a capital letter and end with a dot (`.`). | *since version 3.0* +`min` | The minimum value, within the interval of the given `datatype`, that the data entry can be assigned. If omitted, the minimum value will be the "Min" value for the given datatype. Cannot be specified if `allowed` is defined for the same data entry. +`max` | The maximum value, within the interval of the given `datatype`, that the data entry can be assigned. If omitted, the maximum value will be the "Max" value for the given datatype. Cannot be specified if `allowed` is defined for the same data entry. +`unit` | The unit of measurement that the data entry has. See [Data Units](/vehicle_signal_specification/rule_set/data_entry/data_units/) chapter for a list of available units. Cannot be specified if `allowed` is defined for the same data entry. +`pattern` | Can be used for datatype `string` to specify a regular expression that limits allowed values for the data entry. The expression must be supported by [Python Regular Expressions](https://docs.python.org/3/howto/regex.html) | *since version 6.0* +`default` | Default value for the data entry. See [Default Values](/vehicle_signal_specification/rule_set/data_entry/default/). +`allowed`| Allowed values for the data entry. See [Allowed Values](/vehicle_signal_specification/rule_set/data_entry/allowed/). +`arraysize`| If the `datatype`is an array, this atrribute can be used to specify the size of the array. See [datatype](/vehicle_signal_specification/rule_set/data_entry/data_types/)