Skip to content

Semantic Models and the Asset Administration Shell (AAS)

Jump to bottom
tunacicek edited this page May 18, 2024 · 47 revisions

Table of Contents

Topics

  1. Get yourself familiar with the APIs for registration and searching for digital twins/AAS
  2. Get familiar with the APIs for the Access Management
  3. Practical excercise:
    1. search for digital twins providing information needed
    2. create a digital twin yourself
    3. grant permissions for access to the digital twins

Required for participant

For the workshop you need your own device with Postman or insomnia installed.

Postman

Follow the installation guide to install postman and import the postman-collection for DTR.

Insomnia

  1. Download and install insomnia Insomnia Download

  2. Open the application in scratch Pad Mode (this mode not required to create a user)

  3. Download the insomnia_collection_v1.json import it.

Name of Digital Twin Registry Instance URL Tier BPN Responsible Component
Team OEM (provider-oem-dtr-1) /registry Tier OEM BPN_PROVIDER_OEM Convertible (model-b811-convertible)
Team A (Provider-dtr-1A) /registry Tier 1A BPN_PROVIDER_1A Chassis, Spotlight
Team B (Provider-dtr-1B) /registry Tier 1B BPN_PROVIDER_1B Braking-system, Steering
Team C (Provider-dtr-1C) /registry Tier 1C BPN_PROVIDER_1C Convertible-top, Seat

Useful links

digital-twin-registry github repository
digital-twin-registry documentation
New Access management documentation
AAS 3 openAPI
Access Management openAPI
Access management tickets
Semantic models github repository

UseCase Creating shells (digital twins) for convertible car components

The scope of this workshop is to build digital twins that represent a convertible car (model-b311-convertible) and retrieve PCF (Product Carbon Footprint) Data from each individual component.

Technical requirements

Four environments exists and each environment includes one digital twin registry.

overview_usecases

Digital Twin Registry Information

Name of Digital Twin Registry Instance URL Tier BPN Responsible Component
Team OEM (provider-oem-dtr-1) /registry Tier OEM BPN_PROVIDER_OEM Convertible (model-b811-convertible)
Team A (Provider-dtr-1A) /registry Tier 1A BPN_PROVIDER_1A Chassis, Spotlight
Team B (Provider-dtr-1B) /registry Tier 1B BPN_PROVIDER_1B Braking-system, Steering
Team C (Provider-dtr-1C) /registry Tier 1C BPN_PROVIDER_1C Convertible-top, Seat

Attachements:

examples.zip

Live Demo

Following data is available in the provided digital twin registries:

Task_1_Overview

Digital Twin Registry Available Shell Available Submodel Descriptors
Team OEM (provider-oem-dtr-1)
Team A (Provider-dtr-1A) Chassis Shell
shellId:12411f9a-0d5b-4771-bd8f-018974d57da2
specificAssetId: partId=chassis-id-1
idShort:model-b311-convertible-chassis		 Submodeldescriptor: PCF
model:pcf
id:c38ad782-b56a-4f38-bcf5-8b7cfdaa1475
idShort:pcf
Team B (Provider-dtr-1B) Braking-system
shellId:ae4181e6-d23f-485b-aa53-aff20a1923a1
specificAssetId: partId=braking-id-1
idShort:model-b311-convertible-braking-system		 Submodeldescriptor: PCF
model:pcf
id:55a9d023-5d2a-471b-95cb-60fbe14c2f55
idShort:pcf
Team C (Provider-dtr-1C) Convertible-top
shellId:265be332-d266-4e43-b35f-d1604a5b9bc1
specificAssetId: partId=runner-id-1
idShort:model-b311-convertible-top		 Submodeldescriptor: PCF
model:pcf
id:f5d2aea0-c86e-4d25-8763-824399494cac
idShort:pcf

Following mock submodelserver are available:

Type Submodel endpoint Response
BOM https://(base-url)/submodel/bom/d8b50cad-041a-4ec8-bd4b-3d79be00456b
PCF Chassis https://(base-url)/submodel/pcf/c38ad782-b56a-4f38-bcf5-8b7cfdaa1475
PCF Convertible-Top https://(base-url)/submodel/pcf/f5d2aea0-c86e-4d25-8763-824399494cac
PCF Braking-system https://(base-url)/submodel/pcf/55a9d023-5d2a-471b-95cb-60fbe14c2f55
PCF Spotlight https://(base-url)/submodel/pcf/02b8ea4d-7d21-4e15-9e4b-73cbd4a8eaf7
PCF Steering https://(base-url)/submodel/pcf/d871ca4d-4374-4b9a-9e19-3bfa4d6540c7
PCF Seat https://(base-url)/submodel/pcf/81a1f5cd-25c1-41e1-a680-d10543ab9e2a

Tasks

Task 1: Get familiar with the search DTR-APIs

1. Interact as OEM Provider

Create convertible Shell in Provider DTR provider-oem-dtr-1

  1. Call the POST API <provider-oem-dtr-1>/api/v3/shell-descriptors with the json fromProvider-OEM/shells/1_model-b311-convertible-oem.json to create the shell.

  2. Create access rules for participants with BPNs (BPN_PROVIDER_1A, BPN_PROVIDER_1B, BPN_PROVIDER_1C)

    1. Use the POST API <provider-oem-dtr-1>/api/v3/access-controls/rules with the jsons from folder Provider-OEM/access-rules

2. Interact as Consumer (BPN_PROVIDER_1B)

We assume that the consumer has only the following information:

  • BPN of Provider-oem-dtr (BPN_PROVIDER_OEM)
  • SpecificAssetId: oem=oem-000-001
Get Convertible Shell from provider-oem-dtr-1
  1. Call the lookup API with the specificAssetId (IMPORTANT: You need to encode the specificAssetId {"name":"oem","value":"oem-000-001"} : <Provider-oem-dtr>/api/v3/lookup/shells?assetIds=eyJuYW1lIjoib2VtIiwidmFsdWUiOiJvZW0tMDAwLTAwMSJ9
    1. If successful, the response includes the shellId of the oem shell.
  2. Or optional, call the new POST API shellsByAssetLink and add the specificAssetId in the body like: 
    [
 {
   "name": "oem",
   "value": "oem-000-001"
 }
]
  3. Call the <provider-oem-dtr-1>/api/v3/shell-descriptors/<encoded_shellId> to get the convertible-shell.
    1. Take a look into the submodel descriptors of the returned convertible-shell.
  4. Call the href of returned submodel descriptors to get BOM Data
    1. Take a look at the response. The response includes a list of partIds.
Get shell for chassis from Provider-dtr-1A
  1. Choose the partId of chassis from the previous call.
  2. Call the lookup API with the specificAssetId (IMPORTANT: You need to encoded the specificAssetId {"name":"partId","value":"chassis-id-1"} : <Provider-dtr-1A>/api/v3/lookup/shells?assetIds=eyJuYW1lIjoicGFydElkIiwidmFsdWUiOiJjaGFzc2lzLWlkLTEifQ
    1. If successful, the response includes the shellId of the chassis shell.
  3. Or optional, call the new POST API shellsByAssetLink and add the specificAssetId in the body like: 
    [
 {
   "name": "partId",
   "value": "chassis-id-1"
 }
]
  4. Call the <provider-dtr-1A>/api/v3/shell-descriptors/<encoded_shellId> to get the shell for the chassis.
    1. Take a look into the submodel descriptors of the returned shell.
  5. Call the href of returned submodel descriptors to get PCF Data
    1. Take a look at the response. The response includes the PCF data for the chassis.

Task 2: Get familiar with the create DTR-APIs

Team A

Team A interacts as provider-dtr-1A and delivers the following components:

  • Chassis (Shell already exists)
  • Spotlight (Shell needs to be created)
Digital Twin Registry URL BPN (add as Edc-Bpn Header)
Provider-dtr-1A /registry BPN_PROVIDER_1A
Create Shell for the component spotlight

Based on AAS 3, create a new shell in the digital twin registry for the component spotlight, including the following data. Use the provided Postman collection here.

  • Use the above BPN in the API header (Edc-Bpn) to act as the owner of the digital win registry. This header needs to be sent on every API call to the digital twin registry.
  • Use shellId: d86a3a11-3c3b-4995-88c1-aed697637681
  • To make the shell searchable for other participants, add at least the following specificAssetId in the specificAssetIds list:
{
  "name": "partId",
  "value": "spotlight-id-1"
}
  • includes following submodeldescriptor:
    • Use submodelDescriptors id: 02b8ea4d-7d21-4e15-9e4b-73cbd4a8eaf7
    • Use the value urn:bamm:io.catenax.pcf:4.0.1#Pcf in semanticId
    • The shell must include a submodelDescriptor. The URL for returning spotlight pcf data is: /submodel/pcf/02b8ea4d-7d21-4e15-9e4b-73cbd4a8eaf7
Search via defined specificAssetId the spotlight shell
  1. Call the lookup shell with the above defined specificAssetId (name=partId, value: spotlight-id-1)
    1. If successful, the response includes the shellId
  2. Call the shell-descriptors with the encoded shellId
    1. If successful, the response includes the created shell with submodelDescriptor from previous step
    2. Call the submodelserver (href)
      1. If successful, the response includes the pcf data for spotlight.

Team B

Team B interacts as provider-dtr-1B and delivers the following components:

  • Braking-system (Shell already exists)
  • Steering (Shell needs to be created)
Digital Twin Registry URL BPN (add as Edc-Bpn Header)
Provider-dtr-1B https:///registry BPN_PROVIDER_1B
Create Shell for the component steering

Based on AAS 3, create a new shell in the digital twin registry for the component steering, including the following data. Use the provided Postman collection here.

  • Use the above BPN in the API header (Edc-Bpn) to act as the owner of the digital twin registry. This header needs to be sent on every API call to the digital twin registry.
  • Use shellId: 5aaed5a5-e885-424d-9cfb-72479d93357a
  • To make the shell searchable for other participants, add at least the following specificAssetId in the specificAssetIds list:
{
  "name": "partId",
  "value": "steering-id-1"
}
  • includes following submodeldescriptor:
    • Use submodelDescriptors id: d871ca4d-4374-4b9a-9e19-3bfa4d6540c7
    • Use the value urn:bamm:io.catenax.pcf:4.0.1#Pcf in semanticId
    • The shell must include a submodelDescriptors. The URL for returning steering pcf data is: /submodel/pcf/d871ca4d-4374-4b9a-9e19-3bfa4d6540c7
Search via defined specificAssetId the steering shell
  1. Call the lookup shell with the above defined specificAssetId (name=partId, value: steering-id-1)
    1. If successful, the response includes the shellId
  2. Call the shell-descriptors with the encoded shellId
    1. If successful, the response includes the created shell with submodelDescriptor from previous step
    2. Call the submodelserver (href)
      1. If successful, the response includes the pcf data for steering.

Team C

Team C interacts as provider-dtr-1C and delivers the following components:

  • Convertible-Top (Shell already exists)
  • Seat (Shell needs to be created)
Digital Twin Registry URL BPN (add as Edc-Bpn Header)
Provider-dtr-1C /registry BPN_PROVIDER_1C
Create Shell for the component seat

Based on AAS 3, create a new shell in the digital twin registry for the component seat, including the following data. Use the provided Postman collection here.

  • Use the above BPN in the API header (Edc-Bpn) to act as the owner of the digital twin registry. This header needs to be sent on every API call to the digital twin registry.
  • Use shellId: b6e30ffc-b647-41e4-9724-69b5fff91485
  • To make the shell searchable for other participants, add at least the following specificAssetId in the specificAssetIds list:
{
  "name": "partId",
  "value": "seat-id-1"
}
  • includes following submodeldescriptor:
    • Use submodelDescriptors id: 81a1f5cd-25c1-41e1-a680-d10543ab9e2a
    • Use the value urn:bamm:io.catenax.pcf:4.0.1#Pcf in semanticId
    • The shell must include a submodelDescriptors. The URL for returning seat pcf data is:/submodel/pcf/81a1f5cd-25c1-41e1-a680-d10543ab9e2a
Search via defined specificAssetId the seat shell
  1. Call the lookup shell with the above defined specificAssetId (name=partId, value: seat-id-1)
    1. If successful, the response includes the shellId
  2. Call the shell-descriptors with the encoded shellId
    1. If successful, the response includes the created shell with submodelDescriptor from previous step
    2. Call the submodelserver (href)
      1. If successful, the response includes the pcf data for seat.
Clone this wiki locally