Add basic tutorials (#6)

We add tutorials regarding AAS creation and 
JSON / XML de-/serialization in the style of 
the Eclipse BaSyx Python SDK's tutorials.

sdk/basyx/tutorial/tutorial_create_simple_aas.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+# This work is licensed under a Creative Commons CCZero 1.0 Universal License.
+# See http://creativecommons.org/publicdomain/zero/1.0/ for more information.
+"""
+Tutorial for the creation of a simple Asset Administration Shell, containing an AssetInformation object and a Submodel
+reference using aas-core3.0-python
+"""
+
+# Import all type classes from the aas-core3.0-python SDK
+import aas_core3.types as aas_types
+
+# In this tutorial, you'll get a step-by-step guide on how to create an Asset Administration Shell (AAS) and all
+# required objects within. First, you need an AssetInformation object for which you want to create an AAS. After that,
+# an Asset Administration Shell can be created. Then, it's possible to add Submodels to the AAS. The Submodels can
+# contain SubmodelElements.
+
+# Step-by-Step Guide:
+# Step 1: create a simple Asset Administration Shell, containing AssetInformation object
+# Step 2: create a simple Submodel
+# Step 3: create a simple Property and add it to the Submodel
+
+
+############################################################################################
+# Step 1: Create a Simple Asset Administration Shell Containing an AssetInformation object #
+############################################################################################
+# Step 1.1: create the AssetInformation object
+asset_information = aas_types.AssetInformation(
+    asset_kind=aas_types.AssetKind.INSTANCE,
+    global_asset_id='http://acplt.org/Simple_Asset'
+)
+
+# Step 1.2: create the Asset Administration Shell
+identifier = 'https://acplt.org/Simple_AAS'
+aas = aas_types.AssetAdministrationShell(
+    id=identifier,  # set identifier
+    asset_information=asset_information,
+    submodels=[]
+)
+
+
+#############################################################
+# Step 2: Create a Simple Submodel Without SubmodelElements #
+#############################################################
+
+# Step 2.1: create the Submodel object
+identifier = 'https://acplt.org/Simple_Submodel'
+submodel = aas_types.Submodel(
+    id=identifier,
+    submodel_elements=[]
+)
+
+# Step 2.2: create a reference to that Submodel and add it to the Asset Administration Shell's `submodel` set
+submodel_reference = aas_types.Reference(
+    type=aas_types.ReferenceTypes.MODEL_REFERENCE,
+    keys=[aas_types.Key(
+        type=aas_types.KeyTypes.SUBMODEL,
+        value=identifier
+    )]
+)
+
+# Warning, this overwrites whatever is in the `aas.submodels` list.
+# In your production code, it might make sense to check for already existing content.
+aas.submodels = [submodel_reference]
+
+
+# ===============================================================
+# ALTERNATIVE: step 1 and 2 can alternatively be done in one step
+# In this version, the Submodel reference is passed to the Asset Administration Shell's constructor.
+submodel = aas_types.Submodel(
+    id='https://acplt.org/Simple_Submodel',
+    submodel_elements=[]
+)
+aas = aas_types.AssetAdministrationShell(
+    id='https://acplt.org/Simple_AAS',
+    asset_information=asset_information,
+    submodels=[aas_types.Reference(
+        type=aas_types.ReferenceTypes.MODEL_REFERENCE,
+        keys=[aas_types.Key(
+            type=aas_types.KeyTypes.SUBMODEL,
+            value='https://acplt.org/Simple_Submodel'
+        )]
+    )]
+)
+
+
+###############################################################
+# Step 3: Create a Simple Property and Add it to the Submodel #
+###############################################################
+
+# Step 3.1: create a global reference to a semantic description of the Property
+# A global reference consists of one key which points to the address where the semantic description is stored
+semantic_reference = aas_types.Reference(
+    type=aas_types.ReferenceTypes.MODEL_REFERENCE,
+    keys=[aas_types.Key(
+        type=aas_types.KeyTypes.GLOBAL_REFERENCE,
+        value='http://acplt.org/Properties/SimpleProperty'
+    )]
+)
+
+# Step 3.2: create the simple Property
+property_ = aas_types.Property(
+    id_short='ExampleProperty',  # Identifying string of the element within the Submodel namespace
+    value_type=aas_types.DataTypeDefXSD.STRING,  # Data type of the value
+    value='exampleValue',  # Value of the Property
+    semantic_id=semantic_reference  # set the semantic reference
+)
+
+# Step 3.3: add the Property to the Submodel
+
+# Warning, this overwrites whatever is in the `submodel_elements` list.
+# In your production code, it might make sense to check for already existing content.
+submodel.submodel_elements = [property_]
+
+
+# =====================================================================
+# ALTERNATIVE: step 2 and 3 can also be combined in a single statement:
+# Again, we pass the Property to the Submodel's constructor instead of adding it afterward.
+submodel = aas_types.Submodel(
+    id='https://acplt.org/Simple_Submodel',
+    submodel_elements=[
+        aas_types.Property(
+            id_short='ExampleProperty',
+            value_type=aas_types.DataTypeDefXSD.STRING,
+            value='exampleValue',
+            semantic_id=aas_types.Reference(
+                type=aas_types.ReferenceTypes.MODEL_REFERENCE,
+                keys=[aas_types.Key(
+                    type=aas_types.KeyTypes.GLOBAL_REFERENCE,
+                    value='http://acplt.org/Properties/SimpleProperty'
+                )]
+            )
+        )
+    ]
+)

sdk/basyx/tutorial/tutorial_serialization_deserialization.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+# This work is licensed under a Creative Commons CCZero 1.0 Universal License.
+# See http://creativecommons.org/publicdomain/zero/1.0/ for more information.
+"""
+Tutorial for the serialization and deserialization of Asset Administration Shells, Submodels and Assets into/from JSON
+and XML files.
+"""
+
+import json
+
+import aas_core3.types as aas_types
+import aas_core3.xmlization as xmlizaztion
+import aas_core3.jsonization as jsonization
+
+# 'Details of the Asset Administration Shell' specifies multiple official serialization formats for AAS data. In this
+# tutorial, we show how the Eclipse BaSyx Python library can be used to serialize AAS objects into JSON or XML and to
+# create JSON/XML files, according to the standardized format. It is also demonstrated how these files can be parsed to
+# restore the AAS objects as Python objects.
+#
+# Step-by-Step Guide:
+# Step 1: creating Submodel and Asset Administration Shell objects
+# Step 2: serializing single objects to JSON
+# Step 3: parsing single objects or custom data structures from JSON
+# Step 4: writing multiple identifiable objects to a (standard-compliant) JSON/XML file
+# Step 5: reading the serialized aas objects from JSON/XML files
+
+
+####################################################################
+# Step 1: Creating Submodel and Asset Administration Shell Objects #
+####################################################################
+
+# For more details, take a look at `tutorial_create_simple_aas.py`
+
+submodel = aas_types.Submodel(
+    id='https://acplt.org/Simple_Submodel',
+    submodel_elements=[
+        aas_types.Property(
+            id_short='ExampleProperty',
+            value_type=aas_types.DataTypeDefXSD.STRING,
+            value='exampleValue',
+            semantic_id=aas_types.Reference(
+                type=aas_types.ReferenceTypes.MODEL_REFERENCE,
+                keys=[aas_types.Key(
+                    type=aas_types.KeyTypes.GLOBAL_REFERENCE,
+                    value='http://acplt.org/Properties/SimpleProperty'
+                )]
+            )
+        )
+    ]
+)
+
+aashell = aas_types.AssetAdministrationShell(
+    id='https://acplt.org/Simple_AAS',
+    asset_information=aas_types.AssetInformation(asset_kind=aas_types.AssetKind.INSTANCE, global_asset_id="test"),
+    submodels=[aas_types.Reference(
+        type=aas_types.ReferenceTypes.MODEL_REFERENCE,
+        keys=[aas_types.Key(
+            type=aas_types.KeyTypes.SUBMODEL,
+            value=submodel.id
+        )]
+    )]
+)
+
+
+#######################################
+# Step 2: Serializing Objects to JSON #
+#######################################
+
+shell_jsonable = jsonization.to_jsonable(aashell)
+shell_string = json.dumps(shell_jsonable, indent=4)
+
+submodel_jsonable = jsonization.to_jsonable(submodel)
+submodel_string = json.dumps(submodel_jsonable, indent=4)
+
+
+######################################################################
+# Step 3: Parsing Single Objects or Custom Data Structures from JSON #
+######################################################################
+
+shell_jsonable_from_string = json.loads(shell_string)
+shell_from_jsonable = jsonization.asset_administration_shell_from_jsonable(shell_jsonable_from_string)
+
+submodel_jsonable_from_jsonable = json.loads(submodel_string)
+submodel_from_jsonable = jsonization.submodel_from_jsonable(submodel_jsonable_from_jsonable)
+
+
+######################################
+# Step 4: Serializing Objects to XML #
+######################################
+
+aashell_xml = xmlizaztion.to_str(aashell)
+submodel_xml = xmlizaztion.to_str(submodel)
+
+
+####################################
+# Step 5: Parsing Objects from XML #
+####################################
+
+aashell_from_xml = xmlizaztion.submodel_from_str(aashell_xml)
+submodel_from_xml = xmlizaztion.submodel_from_str(submodel_xml)