BaSyx Hack Docs

Getting Started

To get started with BaSyx, use the Web GUI.

> BaSyx GUI

You can set a new entry to the graph in the GUI or by making a call to the API:

fetch(
    'https://server.basyx.iese.de/aasServer/shells/exampleAAS/aas/submodels/graphExamples/submodel/submodelElements/singleGraph/value', {
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify("[4,7,1,1]")
})

You find other endpoints in the > REST API Reference.

Now you know how to read and write values in BaSyx!

Next, we show you how to set up your own Asset Administration Shells to build your project!


Work Flow

A typical workflow for using BaSyx is made up of four steps. First, you create a template for your Digital Twin (i.e., an Asset Administration Shell) (step 1), you upload it to the BaSyx server (step 2), you connect your (simulated) asset to an Asset Administration Shell (step 3) to be able to read properties and execute operations of the asset (step 4).

1) Create an Asset Administration Shell

An Asset Administration Shell has a standardized format with the following hierachy:

Asset Administration Shell

  • The Asset Administration Shell represents the topmost layer
  • It describes the asset that is digitized and holds submodels of the asset

Submodels

  • Represent modular units that define specific aspects of the Asset Administration Shell
  • Use submodels to split the asset in self-contained parts

Submodel Elements

  • Are the individual properties and operations a Submodel offers.
  • Can contain collections of other elements. Can be nested to split contents semantically.

AASX Package Explorer

This video shows you how to create an Asset Administration Shell with the > AASX Package Explorer.

Note: The AASX Package Explorer only exists for Windows. For Linux and Mac you can use the > AAS Manager. During the event we will help you create your Asset Administration Shells.

Wenn du das Video abspielst, werden Daten an YouTube und Google ├╝bermittelt. Einzelheiten in unseren Datenschutzhinweisen.

2) Upload an Asset Administration Shell

In a second step we upload the Asset Administration Shell we just created to the BaSyx server.

Upload your .aasx File here:

Alternatively, you can do this by posting to the API endpoint: https://server.basyx.iese.de/aasServer/shells/aasx

3) Connect an Asset

Now that we have uploaded the Asset Administration Shell to the server, we know what to expect when interacting with our asset. But we haven't connected any asset to the Asset Administration Shell yet, so there won't be much to interact with! So let's connect our first asset.

To connect an asset simply use the REST API as shown in the Getting Started section! Post the data your asset generates to the Asset Administration Shell server directly via:

fetch(
    'https://server.basyx.iese.de/aasServer/shells/exampleAAS/aas/submodels/graphExamples/submodel/submodelElements/singleGraph/value', {
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify("[4,7,1,1]")
})

Note: As this is a hackathon we encourage you to mock any kind of data you don't have!

4) Access Properties and Execute Operations

To access the assets properties again simply call the respective REST API endpoints of the submodel elements:

fetch('https://server.basyx.iese.de/aasServer/shells/exampleAAS/aas/submodels/graphExamples/submodel/submodelElements/singleGraph/value', {
  method: 'GET',
})
.then(response => response.json())
.then(data => console.log(data));

From here you on you know how to work with BaSyx and you can start thinking about the challenge!

You find more information on how to use BaSyx > here.


Basic Concepts

BaSyx builds on the following concepts:

Digital Twins

In Industry 4.0 a Digital Twin refers to a digital representation of an asset. An asset can be anything of value, e.g., a maschine, a product, a process, that we might want to monitor digitally.

A Digital Twin in Industry 4.0 represents an Asset (a machine, a product, a process).

Standardization

Standards help us use Digital Twins for Industry 4.0 more efficiently. With an agreed-upon set of properties and operations for an asset (e.g., which data it offers and what an asset can do) we can define a reusable, vendor-independent interface to the digital twin.

The Asset Administration Shell (AAS) provides such a > standard and is developed by many leading companies (such as Bosch, Festo, Siemens, Fraunhofer and many more).

An Asset Administration Shell is a standardized Digital Twin.

Middleware

The aspect of Standardization is implemented in the BaSyx architecture. BaSyx serves as a middleware for Industry 4.0 and abstracts from different communication protocolls.

BaSyx is an open-source middleware to work with Asset Administration Shells.


REST API Reference

Download the BaSyx Postman collection to try out the different endpoints.

Get all Asset Administration Shells:

GET /aasServer/shells

Get a specific Asset Administration Shell:

GET /aasServer/shells/<AAS URN>/aas

Upload an Asset Administration Shells as .aasx File:

POST /aasServer/shells/aasx

content type: multipart/form-data

body: <.aasx file>

Upload an Asset Administration Shells as JSON:

PUT /aasServer/shells/<AAS URN>

content type: raw

body: <JSON content>

Set a value for a submodel element

PUT /aasServer/shells/<AAS URN>/aas/submodels/<SubmodelElement IdShortPath>/submodel/submodelElements/<SubmodelElement IdShortPath>/value