Skip to content

Semantic Models and the Asset Administration Shell (AAS)

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

Table of Contents

Topics

  1. Get yourself familiar with the APIs for registration and searching for digital twins/AAS
  2. Get yourself 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 installed.

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

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.

Digital Twin Registry Information

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

Live Demo

Following data is available in the provided digital twin registries:

Digital Twin Registry Available Shell Available Submodel Descriptors
Team OEM (provider-oem-dtr-1) Convertible Shell
shellId:c931c4ea-c552-470f-80a2-a4ea9e5364dc
idShort:model-b311-convertible		 Submodeldescriptor: BOM
model:bom_as_specified
id:d8b50cad-041a-4ec8-bd4b-3d79be00456b
idShort:bom-as-build
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 from1_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 oem-registry

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 2. 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 https://(provider-dtr-tier1a)/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"
}
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://provider-dtr-tier1B/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"
}
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 https://provider-dtr-tier1C/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"
}
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