Merge pull request #28 from boschglobal/waltersve/bamm-template

Provide a template to generate a BAMM Aspect Model based on a VSC service

model/vsc_parser.py

@@ -120,6 +120,8 @@ class Namespace(AST):
 class Service(AST):
  name: str
  description: str
+ major_version: int
+ minor_version: int
  namespaces: list[Namespace]
 
 # ----------------------------------------------------------------------------
@@ -226,7 +228,7 @@ def require_list(yaml, parent_name : str):
  ASTNodeError(f"Expected a list of command objects under {parent_name}, not just a single. If there is only one, specify a list, but with one object only")
 
 def ast_Structs(parent, yamltree) -> Structs:
- 
+
  subtrees = get_optional_yaml_value(yamltree, 'structs')
 
  if subtrees is None:
@@ -244,7 +246,7 @@ def ast_Structs(parent, yamltree) -> Structs:
 
 
 def ast_Typedefs(parent, yamltree) -> Typedefs:
- 
+
  subtrees = get_optional_yaml_value(yamltree, 'typedefs')
 
  if subtrees is None:
@@ -263,7 +265,7 @@ def ast_Typedefs(parent, yamltree) -> Typedefs:
 
 
 def ast_Enums(parent, yamltree) -> Enums:
- 
+
  subtrees = get_optional_yaml_value(yamltree, 'enumerations')
 
  if subtrees is None:
@@ -392,7 +394,7 @@ def ast_Namespaces(parent, yamltree) -> list[Namespace]:
  node.methods = ast_Methods(node, st)
  node.events = ast_Events(node, st)
  node.properties = ast_Properties(node, st)
- 
+
  nodes.append(node)
 
  return nodes
@@ -416,6 +418,10 @@ def ast_Service(parent, yamltree) -> Service:
  # that are expected in a valid file
  # So for a service we expect datatypes and interfaces as children:
  node.description = get_yaml_value(yamltree, 'description')
+
+ node.major_version = get_yaml_value(yamltree, 'major-version')
+ node.minor_version = get_yaml_value(yamltree, 'minor-version')
+
  node.namespaces = ast_Namespaces(node, yamltree)
 
  return node

templates/sds-bamm-aspect-model.md

@@ -0,0 +1,78 @@
+# BAMM Aspect Model Generator
+
+(C) 2022 Robert Bosch GmbH
+
+## Introduction
+
+The BAMM Aspect Model Generator converts VSC services to a valid BAMM Aspect Model according to the [BAMM Aspect Meta Model](https://github.com/OpenManufacturingPlatform/sds-bamm-aspect-meta-model), 
+keeping as much as possible of the information from the VSC definition. It consists of a template ([sds-bamm-aspect-model](sds-bamm-aspect-model.j2) and [sds-bamm-macros](sds-bamm-macros.j2)) 
+using the template framework of the vsc-tools project to parse and transform VSC services.
+
+## BAMM Aspect Meta Model
+The BAMM Aspect Meta Model (BAMM) allows the creation of models to describe the semantics of digital twins by defining
+their domain specific aspects. In this context, digital twins are the digital representation of a physical or virtual
+object that bundles and combines several aspects. The BAMM Aspect Meta Model (BAMM) provides a set of predefined objects
+(as depicted below) that allow a domain expert to define aspect models and complement a digital twin with a semantic
+foundation. In case you were wondering what the B in BAMM refers to: BAMM is recursively defined and thus the B refers
+to BAMM itself.
+
+## Known Limitations
+
+*The Generator has been developed as proof-of-concept and does not currently have product quality!*
+
+Known limitations of the implementation:
+* Handling of whitespaces between the model elements are not optimal
+* No support for namespaces of arbitrary depth. Currently, everything expected to be within the same namespace.
+* No support for including other files or referencing types in other namespaces
+* No support for deployment files defined in VSC.
+
+In general all data in the example VSC service can be converted.
+
+## Using the BAMM Aspect Model Generator
+
+### Generating a Seat Aspect Model 
+
+The tool can be used like below:
+
+```
+# go to vsc-tools if not already there
+cd vsc-tools
+# make sure that vsc has been cloned
+git clone https://github.com/COVESA/vehicle_service_catalog/
+python model/vsc_generator.py vehicle_service_catalog/comfort-service.yml sds-bamm-aspect-model.tpl > comfort/2.0.1/seat.ttl
+```
+
+### Mapping of the different concepts
+* [VSC Structs](https://github.com/COVESA/vehicle_service_catalog#namespace-list-object-structs) is represented as [Entity](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/entities.html).
+* [VSC Typedefs](https://github.com/COVESA/vehicle_service_catalog#namespace-list-object-typedefs) is represented as [Characteristic](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/characteristics.html).
+* [VSC Enumerations](https://github.com/COVESA/vehicle_service_catalog#namespace-list-object-enumerations) is represented as [Characteristic](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/characteristics.html).
+* [VSC Methods](https://github.com/COVESA/vehicle_service_catalog#namespace-list-object-methods) is represented as [Operation](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/v1.0.0/meta-model-elements.html).
+* [VSC Events](https://github.com/COVESA/vehicle_service_catalog#namespace-list-object-events) is represented as [Event](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/v1.0.0/meta-model-elements.html).
+
+### Validating the generated Aspect Model
+
+To validate the generated Aspect Model the open source [Java SDK]() can be used.
+The SDK can be downloaded from the official project page [here](https://github.com/OpenManufacturingPlatform/sds-sdk/releases).
+Install and use the SDK: 
+- Install Java
+- Download the latest SDK release (bamm-cli-x.x.x-x.jar)
+- Create the following directory structure 'comfort/2.0.1' and copy seat.ttl into the directory '2.0.1' 
+- Run in the project root folder `java -jar bamm-cli-x.x.x-x.jar -i comfort/2.0.1/seat.ttl -v`
+
+Example of successful validation:
+
+``` bat 
+java -jar bamm-cli-1.1.0-M3.jar -i comfort/2.1.0/seat.ttl -v
+Validation report: Input model is valid
+```
+
+Besides the CLI, the Aspect Model Editor application can be used to visualize and validate the generated Aspect Model. The editor
+is freely available for Windows, Linux and MAC and can be downloaded [here](https://www.bosch-connected-industry.com/de/de/downloads/aspect-model-editor/index.html).
+The editor is offered currently as freeware and will be open source this year within the OMP.
+
+### Further usage of an Aspect Model
+
+Based on the Aspect Model and the SDK the following additional topics can be generated:
+* JSON-Schema, running `java -jar bamm-cli-x.x.x-x.jar -i comfort/2.0.1/seat.ttl -schema`
+* HTML Documentation, running `java -jar bamm-cli-x.x.x-x.jar -i comfort/2.0.1/seat.ttl -html`
+* OpenAPI Spec, running `java -jar bamm-cli-x.x.x-x.jar -i comfort/2.0.1/seat.ttl -oapi-yaml -base-url 'http://<base-url>'`

templates/sds-bamm-aspect-model.tpl

@@ -0,0 +1,93 @@
+{% import 'sds-bamm-macros.tpl' as bamm %}
+
+{% set aspectModelURN = item.children[0].name %}
+{% set aspectModelVersion = item.children[0].major_version ~ '.' ~ item.children[0].minor_version ~ '.0' %}
+
+@prefix: <urn:bamm:{{ aspectModelURN }}:{{ aspectModelVersion }}#>.
+@prefix bamm: <urn:bamm:io.openmanufacturing:meta-model:1.0.0#> .
+@prefix bamm-c: <urn:bamm:io.openmanufacturing:characteristic:1.0.0#> .
+@prefix bamm-e: <urn:bamm:io.openmanufacturing:entity:1.0.0#> .
+@prefix unit: <urn:bamm:io.openmanufacturing:unit:1.0.0#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+{%for s in item.children %}
+
+ {# --- Aspect --- #}
+
+ {% for n in s.namespaces -%}
+ {{ bamm.render_aspect(n) }}
+
+ {# --- Operations --- #}
+
+ {% for method in n.methods -%}
+ {{ bamm.render_operation(method) }}
+ {% endfor %}
+
+ {# --- Events --- #}
+
+ {%- for event in n.events -%}
+ {{ bamm.render_event(event) }}
+ {% endfor %}
+
+ {# --- Entities --- #}
+
+ {%- for struct in n.structs -%}
+ {{ bamm.render_entity(struct) }}
+ {% endfor %}
+
+ {# --- Properties --- #}
+
+ {%- for struct in n.structs -%}
+ {%- for member in struct.members -%}
+ {{ bamm.render_property(member) }}
+ {% endfor %}
+ {% endfor %}
+
+ {%- for event in n.events -%}
+ {%- for in_arg in event.in_arguments -%}
+ {{ bamm.render_property(in_arg) }}
+ {% endfor %}
+ {% endfor %}
+
+ {%- for method in n.methods -%}
+ {%- for inProp in method.in_arguments -%}
+ {{ bamm.render_property(inProp) }}
+ {% endfor %}
+ {%- for outProp in method.out_arguments -%}
+ {{ bamm.render_property(outProp) }}
+ {% endfor %}
+ {% endfor %}
+
+ {# --- Characteristics --- #}
+
+ {%- for typedef in n.typedefs -%}
+ {{ bamm.render_characteristic(typedef) }}
+ {% endfor %}
+
+ {%- for enum in n.enums -%}
+ {{ bamm.render_enumeration(enum) }}
+ {% endfor %}
+
+ {%- for struct in n.structs -%}
+ {%- for member in struct.members -%}
+ {{ bamm.render_characteristic(member) }}
+ {% endfor %}
+ {% endfor %}
+
+ {%- for event in n.events -%}
+ {%- for in_arg in event.in_arguments -%}
+ {{ bamm.render_characteristic(in_arg) }}
+ {% endfor %}
+ {% endfor %}
+
+ {%- for method in n.methods -%}
+ {%- for inProp in method.in_arguments -%}
+ {{ bamm.render_characteristic(inProp) }}
+ {% endfor %}
+ {%- for outProp in method.out_arguments -%}
+ {{ bamm.render_characteristic(outProp) }}
+ {% endfor %}
+ {% endfor %}
+
+ {% endfor %}
+{% endfor %}