From 23ccdc78e70ee8a355a592e5524a2c58e98fd351 Mon Sep 17 00:00:00 2001 From: Muhammad Saud Khan Date: Thu, 16 May 2024 13:40:06 +0200 Subject: [PATCH] chore: added digital-twin guide --- dpp-tutorial/data-provision.md | 191 ------------------ dpp-tutorial/digital-twin-provision.md | 153 ++++++++++++++ .../resources/digital-twins/example-dt.json | 106 ++-------- 3 files changed, 166 insertions(+), 284 deletions(-) delete mode 100644 dpp-tutorial/data-provision.md create mode 100644 dpp-tutorial/digital-twin-provision.md diff --git a/dpp-tutorial/data-provision.md b/dpp-tutorial/data-provision.md deleted file mode 100644 index 81e9c81ba..000000000 --- a/dpp-tutorial/data-provision.md +++ /dev/null @@ -1,191 +0,0 @@ - - -# Data Provision - ________EDC-Connector________ ________Registry________ ________Data Service________ - | | | | | | - | Controlplane <-> Dataplane | <---> | AAS DTR | <---> | A plain JSON Server | - |_____________________________| |________________________| |____________________________| - - -This guide provides the information needed to setup data provisioning services as a data provider. Additionally, it enables you to register data payloads into the data service and configure digital twins in digital twin registry component. - - -## Prerequisites - -You must have the following components up and running: - -- A Data Service (DS) to store passport payloads in a plain JSON format -- Digital Twin Registry (DTR) to store Digital Twins as Asset Administration Shells (AAS) -- A preconfigured EDC Conenctor (Data provider) -- Familiarity with the JSON structure -- Accessibility of components over the network - - -## Clone a Git repository - -Use the following command in your terminal to clone the digital product pass git repository - -```bash -git clone https://github.com/eclipse-tractusx/digital-product-pass.git -``` - -> [!Note] -> If you already cloned this repository, you can ignore this step - - -## Prepare DPP data - -The content of specific part assigned to each group is available in [resources](./resources/payloads/) directory. Please find your content corresponding to your assigned part. - - -## Add Data to the Submodel Server - -After preparation of the DPP data, its time to get your data registered into the data service. - -The content from each part of the car is stored in JSON format and can be manipulated via the unique identifier called **Submodel ID**. This *ID* is generated using the following format: - -```text -urn:: -``` - -```text -For example: urn:dpp01:0001 -``` - -> [!IMPORTANT] -> Please generate a unique identifier using given format prior to proceed to adding data -> Substitute the required placeholders with the provided values. - -Open a new terminal and run the following command to add your data into the data service: -```bash -curl --location '/data/urn::' \ ---header 'Content-Type: application/json' \ ---data "@resources/payloads/.json" -``` - -Check your data is registerd in the service -```bash -curl --location '/data/urn::' \ ---header 'Content-Type: application/json' \ -``` - -## Create DPP Aspect Model - -Use the following template and substitute the following parameters: - -```bash - -> it is your group number e.g., dpp01 - -> the part number is written on the datasheet from a part - -> edc provider controle plane url - -> edc provider data plane url - -> the name is the part assigned to you -``` - -```json -// Submodel Descriptor template - { - "endpoints": [ - { - "interface": "SUBMODEL-3.0", - "protocolInformation": { - "href": "/api/public/data/urn::", - "endpointProtocol": "HTTP", - "endpointProtocolVersion": [ - "1.1" - ], - "subprotocol": "DSP", - "subprotocolBody": "id=dpp-asset;dspEndpoint=", - "subprotocolBodyEncoding": "plain", - "securityAttributes": [ - { - "type": "NONE", - "key": "NONE", - "value": "NONE" - } - ] - } - } - ], - "idShort": "", - "id": "urn::", - "semanticId": { - "type": "ExternalReference", - "keys": [ - { - "type": "Submodel", - "value": "urn:bamm:io.catenax.generic.digital_product_passport:2.0.0#DigitalProductPassport" - } - ] - }, - "description": [ - { - "language": "en", - "text": "DPP Submodel Descriptor" - } - ] - } -``` - - -## Update Digital Twin - -After creation of the aspect model in previous step, its time to attach this model to submodel descriptors of an existing digital twin. - -> PUT /shell-descriptors//submodel-descriptors - -```bash -curl --location --request PUT '/semantics/registry/api/v3.0/shell-descriptors/DIGITAL_TWIN_ID_BASE64_ENCODED/submodel-descriptors/' \ ---header 'Content-Type: application/json' \ ---data '@resources/digital-twins/.json' -``` - -> [!Note] -> Every physical part of vehicle is represented by a Digital Twin object. A car is manufactured with a plenty of digital twins. - - -Check if your aspect model is added to the Digital twin. - -> GET /shell-descriptors//submodel-descriptors - -```bash -curl --location --request GET '/semantics/registry/api/v3.0/shell-descriptors//submodel-descriptors' \ ---header 'Content-Type: application/json' \ ---data '@resources/digital-twins/.json' -``` - -If everything works fine, then you have reached at the end of data provisioning guide. - -Congratulations, you have successfully setup the data provider. It is now available and ready to exchange data in the dataspace. - - -## NOTICE - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023, 2024 BMW AG -- SPDX-FileCopyrightText: 2023, 2024 CGI Deutschland B.V. & Co. KG -- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/digital-product-pass \ No newline at end of file diff --git a/dpp-tutorial/digital-twin-provision.md b/dpp-tutorial/digital-twin-provision.md new file mode 100644 index 000000000..05e173668 --- /dev/null +++ b/dpp-tutorial/digital-twin-provision.md @@ -0,0 +1,153 @@ + + +# Data Provision + ________EDC-Connector________ ________Registry________ ________Data Service________ + | | | | | | + | Controlplane <-> Dataplane | <---> | AAS DTR | <---> | A plain JSON Server | + |_____________________________| |________________________| |____________________________| + + +This guide provides the information needed to setup digital twin provisioning services as a data provider. Additionally, it enables you to create and register aspect models into the data service. + + +## Prerequisites + +You must have the following components up and running: + +- A Data Service (DS) to store passport payloads in a plain JSON format +- Digital Twin Registry (DTR) to store Digital Twins as Asset Administration Shells (AAS) +- A preconfigured EDC Conenctor (Data provider) +- Familiarity with the JSON structure +- Accessibility of components over the network + + +## Clone a Git repository + +Use the following command in your terminal to clone the digital product pass git repository + +```bash +git clone https://github.com/eclipse-tractusx/digital-product-pass.git +``` + +> [!Note] +> If you already cloned this repository, you can ignore this step + + +## Prepare Aspect Model + +In order to prepare aspect models, please follow the [aspect model guide](./aspect-model.md) + +## Add Aspect Model to the Submodel Server + +The data generated in previous step can be stored into the submode data service. + +The can be generated from here: https://www.uuidgenerator.net/ + +```bash +Example: uuid:urn:6fb9a71b-aee6-4063-a82e-957022aeaa7a +``` + +> [!IMPORTANT] +> Please substitute the <UUID> with the one generated above. + + +Open a new terminal and run the following command to add your data into the data service: +> POST /data/uuid:urn:<UUID> + +```bash +curl --location '/data/uuid:urn:' \ +--header 'Content-Type: application/json' \ +--data "@.json" +``` + +Verify your data is registerd in the service + +> GET /data/uuid:urn:<UUID> +```bash +curl --location '/data/uuid:urn:' \ +--header 'Content-Type: application/json' \ +``` + +## Create Digital Twin + +After preparing and registering aspect models, create a digital twin of a part assigned. +Create a new json and use the template in [resources/digital-twins/example-dt.json](./resources/digital-twins/example-dt.json) + +Replace the following placeholders: + +```bash + -> the value of part instance written on datasheet + -> the part number is written on the datasheet from a part + -> the UUID written on datasheet + -> the name is the part assigned +``` + +## Add Digital Twin into Digital Twin Registry (DTR) + +After creation of the digital twin in previous step, add the twin into Digital Twin Registry (DTR). + +> POST /shell-descriptors/ + +```bash +curl --location --request POST '/semantics/registry/api/v3.0/shell-descriptors/api/v3.0/shell-descriptors' \ +--header 'Content-Type: application/json' \ +--data '@resources/.json' +``` + +> [!Note] +> Every physical part of vehicle is represented by a Digital Twin object. A car is manufactured with a plenty of digital twins. + +The digital twin registered can be checked/verified from the following command: + +> [!Important] +> The should be encoded into base64. Use the following url for conversion: https://www.base64encode.org/ + +```bash +Example: +Digital Twin Id: urn:uuid:3f89d0d4-e11c-f83b-16fd-733c63d4e121 +Base64 Encoded: dXJuOnV1aWQ6M2Y4OWQwZDQtZTExYy1mODNiLTE2ZmQtNzMzYzYzZDRlMTIx +``` + +> GET /shell-descriptors/ + +```bash +curl --location --request GET '/semantics/registry/api/v3.0/shell-descriptors/' \ +--header 'Content-Type: application/json' +``` + +If everything works fine, then you have reached at the end of data provisioning guide. + +Congratulations, you have successfully setup the data provider. It is now available and ready to exchange data in the dataspace. + + +## NOTICE + +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023, 2024 BMW AG +- SPDX-FileCopyrightText: 2023, 2024 CGI Deutschland B.V. & Co. KG +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/digital-product-pass diff --git a/dpp-tutorial/resources/digital-twins/example-dt.json b/dpp-tutorial/resources/digital-twins/example-dt.json index 13a9a887c..184b8324c 100644 --- a/dpp-tutorial/resources/digital-twins/example-dt.json +++ b/dpp-tutorial/resources/digital-twins/example-dt.json @@ -7,31 +7,31 @@ ], "displayName": [], "globalAssetId": "urn:uuid:e5ab3398-bde1-4ef2-bb70-fd6dd1138e59", - "idShort": "LeftFrontDoor", - "id": "urn:dt-example-001", + "idShort": "", + "id": "", "specificAssetIds": [ { "name": "partInstanceId", - "value": "PRT-30002", + "value": "", "externalSubjectId": { "type": "ExternalReference", "keys": [ { "type": "GlobalReference", - "value": "BPNL00000000001" + "value": "BPNL0073928UJ879" } ] } }, { "name": "manufacturerPartId", - "value": "MFG024", + "value": "MPI0012", "externalSubjectId": { "type": "ExternalReference", "keys": [ { "type": "GlobalReference", - "value": "BPNL00000000001" + "value": "BPNL0073928UJ879" }, { "type": "GlobalReference", @@ -42,13 +42,13 @@ }, { "name": "manufacturerId", - "value": "BPNL00000000001", + "value": "BPNL0073928UJ879", "externalSubjectId": { "type": "ExternalReference", "keys": [ { "type": "GlobalReference", - "value": "BPNL00000000001" + "value": "BPNL0073928UJ879" } ] } @@ -61,7 +61,7 @@ "keys": [ { "type": "GlobalReference", - "value": "BPNL00000000001" + "value": "BPNL0073928UJ879" } ] } @@ -73,11 +73,11 @@ { "interface": "SUBMODEL-3.0", "protocolInformation": { - "href": "/api/public/data/urn:example-prtnumber", + "href": "https://dpp.int.demo.catena-x.net/BPNL000000000000/api/public/data/", "endpointProtocol": "HTTP", "endpointProtocolVersion": ["1.1"], "subprotocol": "DSP", - "subprotocolBody": "id=dpp-asset;dspEndpoint=", + "subprotocolBody": "id=urn:uuid:0c3d2db0-e5c6-27f9-5875-15a9a00e7a27;dspEndpoint=https://dpp.int.demo.catena-x.net/BPNL000000000000", "subprotocolBodyEncoding": "plain", "securityAttributes": [ { @@ -89,8 +89,8 @@ } } ], - "idShort": "digitalProductPass", - "id": "urn:example-prtnumber", + "idShort": "", + "id": "", "semanticId": { "type": "ExternalReference", "keys": [ @@ -107,86 +107,6 @@ } ], "displayName": [] - }, - { - "endpoints": [ - { - "interface": "SUBMODEL-3.0", - "protocolInformation": { - "href": "https://dpp.int.demo.catena-x.net/BPNL000000000000/api/public/data/urn:uuid:dea9dfe8-77a2-e7f9-ba78-e96ecc54528b", - "endpointProtocol": "HTTP", - "endpointProtocolVersion": ["1.1"], - "subprotocol": "DSP", - "subprotocolBody": "id=dpp-asset;dspEndpoint=https://dpp.int.demo.catena-x.net/BPNL000000000000", - "subprotocolBodyEncoding": "plain", - "securityAttributes": [ - { - "type": "NONE", - "key": "NONE", - "value": "NONE" - } - ] - } - } - ], - "idShort": "singleLevelBomAsBuilt", - "id": "urn:uuid:dea9dfe8-77a2-e7f9-ba78-e96ecc54528b", - "semanticId": { - "type": "ExternalReference", - "keys": [ - { - "type": "Submodel", - "value": "urn:bamm:io.catenax.single_level_bom_as_built:1.0.0#SingleLevelBomAsBuilt" - } - ] - }, - "description": [ - { - "language": "en", - "text": "Single level Bom As Built Submodel" - } - ], - "displayName": [] - }, - { - "endpoints": [ - { - "interface": "SUBMODEL-3.0", - "protocolInformation": { - "href": "https://dpp.int.demo.catena-x.net/BPNL000000000000/api/public/data/urn:uuid:58f2acd1-4c64-6fb1-7390-a340ef712334", - "endpointProtocol": "HTTP", - "endpointProtocolVersion": ["1.1"], - "subprotocol": "DSP", - "subprotocolBody": "id=dpp-asset;dspEndpoint=https://dpp.int.demo.catena-x.net/BPNL000000000000", - "subprotocolBodyEncoding": "plain", - "securityAttributes": [ - { - "type": "NONE", - "key": "NONE", - "value": "NONE" - } - ] - } - } - ], - "idShort": "SerialPart", - "id": "urn:uuid:58f2acd1-4c64-6fb1-7390-a340ef712334", - "semanticId": { - "type": "ExternalReference", - "keys": [ - { - "type": "Submodel", - "value": "urn:bamm:io.catenax.serial_part:1.0.1#SerialPart" - } - ] - }, - "description": [ - { - "language": "en", - "text": "DPP SerialPart Submodel" - } - ], - "displayName": [] } ] }