Add SAMM - Semantic Aspect Meta Model exporter

Signed-off-by: Kostadin Ivanov (BD/TBC-BG) <[email protected]>

docs/samm.md

@@ -0,0 +1,220 @@
+# Vspec - Semantic Aspect Meta Model (SAMM) exporter
+
+Helper exporter to convert VSS specification (.vspec) file(s) into [ESMF - Semantic Aspect Meta Model](https://eclipse-esmf.github.io/samm-specification/2.1.0/index.html) (.ttl) files,
+which then can be further used in the [Eclipse Semantic Modeling Framework (ESMF) - Aspect Model Editor (AME)](https://github.com/eclipse-esmf/esmf-aspect-model-editor#readme).
+<br />
+<br />
+
+## What is this script about?
+
+This script is built to provide functionalities to convert COVESA VSS specification (.vspec) files
+into ESMF Aspect Model (.ttl) formatted files and following the [Resource Description Format (RDF11)](https://www.w3.org/TR/rdf11-concepts/) and Terse [RDF Tripple Language](https://www.w3.org/TR/turtle/) syntax,
+which then can be loaded in [ESMF - AME](https://github.com/eclipse-esmf/esmf-aspect-model-editor#readme).
+
+The editor latest version, can be downloaded from [ESMF AME - releases](https://github.com/eclipse-esmf/esmf-aspect-model-editor/releases).
+Select the corresponding package, based on your operating system and follow the instructions.
+
+The ESMF - Aspect model Editor, provides a number of functions to design, edit and work with UML like diagrams,
+which then, can be used to generate example JSON loads, can be exported into OPEN API - JSON formatted specifications,
+which further can be loaded in tools like [SWAGGER](https://swagger.io/) or other API generating tools and so on an dso forth.
+<br/>
+<br/>
+
+## User Guide:
+</br>
+
+### Get Help:
+To get help information about this script, use:
+
+```bash
+vspec export samm --help
+```
+<br/>
+
+### Example Usage:
+
+This script is provided pre-configured, unless some other requirements like:
+
+1. where to store the converted ttl files?
+2. whether to have the full VSS converted into a single Aspect model or split into separate Aspect models?
+    - **Please Note:** if the full VSS is selected to be converted to a single aspect model (.ttl),
+                   this would lead to one pretty big Aspect model (.ttl) file.
+                   Very large aspect models can slow down the work with the ESMF AME or could lead to some unpredicted results.
+                   Therefore, it is recommended to use the **--split/--spl** option.
+
+are needed.
+<br/>
+
+#### Convert complete VSS to single ESMF ttl model:
+Below command will call this script with its default options.
+
+```bash
+vspec export samm -s PATH_TO_VSS/vehicle_signal_specification/spec/VehicleSignalSpecification.vspec
+```
+
+>**Please Note:**
+>
+> Above command will run the samm exporter with its default options.
+> The above mentioned **help** command will provide a full list of VSS Tools supported options
+> and the additional ones, listed below, which are handled by this script.
+>
+<br/>
+
+### Vspec - SAMM exporter dedicated options:
+
+Below are listed only the specific and handled by this exporter options, which can be used to further control its behavior.
+
+1. **--target-folder** or **-tf** - path to or name for the target folder, where generated aspect models (.ttl files) will be stored.
+
+    >**Please Note:**
+    > This folder will be created relatively to the folder from which this script is called.
+    >
+    > **DEFAULT:** vss_ttls/
+    >
+
+2. **--target-namespace** or **-tns** - Namespace for VSS library, located in specified **--target-folder**.
+    Will be used as name of the folder where VSS Aspect models (TTLs) are to be stored.
+    This folder will be created as subfolder of the specified **--target-folder** parameter.
+
+    > **DEFAULT:** com.covesa.vss.spec
+    >
+
+3. **--split** or **-spl** / **--no-split** - Boolean flag - used to indicate whether to convert VSS specifications in separate ESMF Aspect(s)
+    or the whole (selected) VSS specification(s) will be combined into single ESMF Aspect model.
+
+    >**Please Note:**
+    > Since the size of the VSS is pretty big, it is recommended to use the **DEFAULT** value of this option i.e.,
+    > **--split**. Otherwise the generated *Vehicle.ttl* will be very big and hard to work with it in the [ESMF - Aspect Model Editor (AME)](https://github.com/eclipse-esmf/esmf-aspect-model-editor#readme)
+    >
+    > **DEFAULT:** *--split* or *-spl*
+    >
+
+4. **--split-depth** or **-spld** - Number - used to define, up to which level, VSS branches will be converted into single aspect models.
+    Can be used in addition to the **--split, -spl** option.
+
+    > **DEFAULT:** 1
+    > Default value of 1 means that only 1st level VSS branches like Vehicle.Cabin, Vehicle.Chassis etc.,
+    > will be converted to separate aspect models i.e. **.ttl** files.
+    >
+
+5. **--signals-file**  or **-sigf** - Path to file with selected VSS signals to be converted.
+    Allows to convert just selected VSS signals into aspect model(s), when **--split, -spl** is enabled
+    or build one single *Vehicle.ttl* aspect model with selected VSS signals.
+
+    >**Please Note:**
+    > Each signal in the file should be on a new line and in the format of:
+    >
+    > ```
+    > PARENT_SIGNAL.PATH.TO.CHILD_SIGNAL
+    > ```
+    >
+    > as defined in VSS.
+    >
+<br/>
+
+### Convert selected VSS signals to ESMF ttl models:
+
+In order to convert just selected COVESA VSS signals, you can create a simple text file, where each selected signal is added on a new line.
+
+For example, this **selected-vss-signals-to-convert.txt** can look like:
+
+```
+Vehicle.Cabin.Door
+Vehicle.CurrentLocation.Accuracy
+Vehicle.CurrentLocation.Latitude
+Vehicle.CurrentLocation.Longitude
+Vehicle.Powertrain.FuelSystem.InstantConsumption
+```
+
+An example call would be:
+
+```bash
+vspec export samm \
+    -s PATH_TO_VSS/vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
+    -sigf PATH_TO_FILE/selected-vss-signals-to-convert.txt
+```
+
+>**Please Note:**
+> We used just the **--vspec, -s** and **--signals-file, -sigf** options,
+> leaving other ones to their default values.
+>
+
+As result, you will get the following folder with below listed contents, placed in the location, from which you called this exporter.
+
+```
+vss_ttls/
+    com.covesa.vss.spec/
+        5.0.0/
+            Cabin.ttl
+            CurrentLocation.ttl
+            Powertrain.ttl
+            Vehicle.ttl
+```
+
+>**Please Note:**
+> The version folder: **5.0.0/** is dynamically read from the COVESA VSS - *Vehicle.VersionVSS* node.
+>
+> In other words, if you happen to call an older VSS version, lets say *4.2.0* with same selected signals file,
+> then the result will be:
+>
+> ```
+> vss_ttls/
+>    com.covesa.vss.spec/
+>        4.2.0/
+>            Cabin.ttl
+>            CurrentLocation.ttl
+>            Powertrain.ttl
+>            Vehicle.ttl
+> ```
+>
+<br/>
+
+### Validation and verification of generated Aspect Models
+
+Once you have your generated VSS aspect models, you can do a simple validation in the context of [Eclipse Semantic Modeling Framework (ESMF)](https://github.com/eclipse-esmf)
+using either their UI tool, the [ESMF - Aspect Model Editor (AME)](https://github.com/eclipse-esmf/esmf-aspect-model-editor#readme) or their CLI one, the [ESMF - Command Line Interface (CLI)](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html).
+
+The validation with the [ESMF - Aspect Model Editor (AME)](https://github.com/eclipse-esmf/esmf-aspect-model-editor#readme) is relatively easy.
+First of all you need to have it installed on your machine, then move the generated **com.covesa.vss.spec/** folder under the AME workspace,
+which usually should be located in your User **Home** directory and be named: **aspect-model-editor**.
+
+All you will need to do is move the generated **com.covesa.vss.spec/** folder to: **YOUR HOME DIRECTORY/aspect-model-editor/models**,
+load the aspect in the editor and hit the validate button, as shown below:
+
+![Validate aspect model on the ESMF - AME](assets/Validate%20aspect%20model%20on%20ESMF-AME.png)<br/>
+*Example: How to validate aspect model on the Aspect Model Editor*
+
+
+The validation, using the [ESMF - Command Line Interface](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html)
+will save the extra steps to copy aspect models to the AME workspace, and will allow you to directly validate the generated VSS aspect model, using the below command.
+
+```bash
+samm aspect vss_ttls/com.covesa.vss.spec/5.0.0/Vehicle.ttl validate
+```
+
+>**Please Note:**
+> In order to be able to use the [ESMF - SAMM CLI](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html)
+> you will need to have it installed on your environment.
+>
+
+Both tools [ESMF - AME](https://github.com/eclipse-esmf/esmf-aspect-model-editor#readme) and [ESMF - SAMM CLI](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html)
+provide for validation of aspect models and generation of other documents like: OpenAPI specifications, HTML Documents, Sample JSON Payload and JSON Schemas.
+Also, please keep in mind that since the CLI tool also provides functionality to generate and SQL Schemas.
+<br/>
+
+### Running this exporter in DEBUG or other mode
+
+As per available functionality, provided by the [vspec](vspec.md), the DEFAULT mode of execution of this and other exporters is INFO.
+
+Other possible modes are: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL".
+
+In order to switch these when calling this exporter you can use the option: [--log-level](vspec.md#--log-level).
+Also there is an option to redirect the console output i.e. logged information to a text file. To do so, you can use the [--log-file](vspec.md#--log-file) option.
+
+A complete example, where you can call this exporter in DEBUG mode and store the logged information into a simple text file would be:
+
+```bash
+vspec --log-level DEBUG --log-file PATH_TO_LOGS/export_vss2samm.log export samm \
+    -s PATH_TO_VSS/vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
+    -sigf PATH_TO_FILE/selected-vss-signals-to-convert.txt
+```

docs/vspec.md

@@ -51,6 +51,7 @@ vspec export json --vspec spec/VehicleSignalSpecification.vspec --output vss.jso
 - [graphql](./graphql.md)
 - [id](./id.md)
 - [protobuf](./protobuf.md)
+- [samm](./samm.md)
 
 ## Argument Explanations
 

src/vss_tools/vspec/cli.py

@@ -47,6 +47,7 @@ def cli(ctx: click.Context, log_level: str, log_file: Path):
         "protobuf": "vss_tools.vspec.vssexporters.vss2protobuf:cli",
         "yaml": "vss_tools.vspec.vssexporters.vss2yaml:cli",
         "tree": "vss_tools.vspec.vssexporters.vss2tree:cli",
+        "samm": "vss_tools.vspec.vssexporters.vss2samm.vss2samm:cli",
     },
 )
 @click.pass_context

src/vss_tools/vspec/vssexporters/vss2samm/config/config.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2024 Contributors to COVESA
+#
+# This program and the accompanying materials are made available under the
+# terms of the Mozilla Public License 2.0 which is available at
+# https://www.mozilla.org/en-US/MPL/2.0/
+#
+# SPDX-License-Identifier: MPL-2.0
+
+# General CONFIG variables
+SAMM_TYPE = "samm"
+SAMM_VERSION = "2.1.0"
+# Custom string, which we use to escape " and ' characters in VSS node description/comments
+# Used in file_helper.write_graph_to_file to properly escape characters in filedata, before to write it to a file.
+CUSTOM_ESCAPE_CHAR = "#V2E-ESC-CHAR#"
+
+# CONFIG Variable defined at runtime as per user input and in available init function
+OUTPUT_NAMESPACE = None
+VSPEC_VERSION = None
+SPLIT_DEPTH = None
+
+
+def init(output_namespace: str, vspec_version: str, split_depth: int):
+    # Set user defined or OUTPUT_NAMESPACE
+    global OUTPUT_NAMESPACE
+    OUTPUT_NAMESPACE = output_namespace
+
+    # Set user defined or OUTPUT_NAMESPACE
+    global VSPEC_VERSION
+    VSPEC_VERSION = vspec_version
+
+    # Make sure that split_depth is in correct type and value, else set it to DEFAULT: 1
+    global SPLIT_DEPTH
+    SPLIT_DEPTH = split_depth if (type(split_depth) is int and split_depth > 0) else 1

src/vss_tools/vspec/vssexporters/vss2samm/helpers/data_types_and_units.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2024 Contributors to COVESA
+#
+# This program and the accompanying materials are made available under the
+# terms of the Mozilla Public License 2.0 which is available at
+# https://www.mozilla.org/en-US/MPL/2.0/
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from rdflib import XSD
+
+from .namespaces import get_unit_uri
+
+DataTypes = {
+    "uint8": XSD.unsignedByte,
+    "int8": XSD.byte,
+    "uint16": XSD.unsignedShort,
+    "int16": XSD.short,
+    "uint32": XSD.unsignedInt,
+    "int32": XSD.int,
+    "uint64": XSD.unsignedLong,
+    "int64": XSD.long,
+    "boolean": XSD.boolean,
+    "float": XSD.float,
+    "double": XSD.double,
+    "string": XSD.string,
+    "dateTime": XSD.dateTime,
+    "dateTimeStamp": XSD.dateTimeStamp,
+    "iso8601": XSD.dateTimeStamp,
+    "anyURI": XSD.anyURI,
+}
+
+DataUnits = {
+    "cm3": get_unit_uri("cubicCentimetre"),
+    "cm^3": get_unit_uri("cubicCentimetre"),
+    "kw": get_unit_uri("kilowatt"),
+    "kW": get_unit_uri("kilowatt"),
+    "kWh": get_unit_uri("kilowattHour"),
+    "l": get_unit_uri("litre"),
+    "l/100km": get_unit_uri("litrePerHour"),
+    "mm": get_unit_uri("millimetre"),
+    "kg": get_unit_uri("kilogram"),
+    "inch": get_unit_uri("inch"),
+    "A": get_unit_uri("ampere"),
+    "Ah": get_unit_uri("ampereHour"),
+    "Nm": get_unit_uri("newtonMetre"),
+    "N.m": get_unit_uri("newtonMetre"),
+    "V": get_unit_uri("volt"),
+    "celsius": get_unit_uri("degreeCelsius"),
+    "cm/s": get_unit_uri("centimetrePerSecond"),
+    "degree": get_unit_uri("degreeUnitOfAngle"),
+    "degrees": get_unit_uri("degreeUnitOfAngle"),
+    "degrees/s": get_unit_uri("degreePerSecond"),
+    "g/s": get_unit_uri("gramPerSecond"),
+    "kilometer": get_unit_uri("kilometre"),
+    "km": get_unit_uri("kilometre"),
+    "km/h": get_unit_uri("kilometrePerHour"),
+    "kpa": get_unit_uri("kilopascal"),
+    "kPa": get_unit_uri("kilopascal"),
+    "l/h": get_unit_uri("litrePerHour"),
+    "m": get_unit_uri("metre"),
+    "m/s": get_unit_uri("metrePerSecond"),
+    "m/s2": get_unit_uri("metrePerSecondSquared"),
+    "m/s^2": get_unit_uri("metrePerSecondSquared"),
+    "mbar": get_unit_uri("millibar"),
+    "min": get_unit_uri("minuteUnitOfTime"),
+    "ml": get_unit_uri("millilitre"),
+    "pa": get_unit_uri("pascal"),
+    "Pa": get_unit_uri("pascal"),
+    "percent": get_unit_uri("percent"),
+    "percentage": get_unit_uri("percent"),
+    "ratio": get_unit_uri("rate"),
+    "rpm": get_unit_uri("revolutionsPerMinute"),
+    "g/km": get_unit_uri("kilogramPerKilometre"),
+    "s": get_unit_uri("secondUnitOfTime"),
+    "h": get_unit_uri("secondUnitOfTime"),
+    "W": get_unit_uri("watt"),
+    "cpm": get_unit_uri("cycle"),
+    "bpm": get_unit_uri("cycle"),
+    "iso8601": get_unit_uri("secondUnitOfTime"),
+    "blank": get_unit_uri("blank"),
+}