Doc Update

Signed-off-by: Erik Jaegervall <[email protected]>

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

docs-gen/content/governance/_index.md

@@ -63,6 +63,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.

docs-gen/content/rule_set/branches.md

@@ -10,32 +10,16 @@ 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 (`.`).
+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.
 
 **```instances```** *[optional]*
 For specifying that multiple instances of this branch exist, for more information see documentation on
@@ -50,3 +34,23 @@ 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.
+
+## 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.

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/).

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
 

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.

docs-gen/content/rule_set/data_entry/attributes.md → 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/).