BaSyx Python SDK

BaSyx Python SDK#

This documentation provides a comprehensive guide for working with the BaSyx Python SDK to create, host, and visualize Asset Administration Shells (AAS) and Submodels. The example runs in a VS Code Dev Container for a consistent development environment.

For more examples and detailed explanations, see:

Overview#

This example demonstrates three key aspects of working with BaSyx Python SDK:

Step 1: AAS & Submodel Creation#

Creates an Asset Administration Shell with a Submodel containing properties. The AAS represents a digital twin of an asset, while Submodels contain the actual data and functionality.

Key Features:

  • Define AAS identifiers and asset information

  • Create Submodels with typed properties

  • Add semantic references for standardization

  • Serialize to JSON format

Step 2: Hosting AAS via BaSyx Repository#

Reads AAS data from storage and serves it through a REST API using the BaSyx server infrastructure.

Endpoints:

  • AAS Repository: http://localhost:8080/api/v3.0/shells

  • Submodel Repository: http://localhost:8080/api/v3.0/submodels

Supported Formats:

  • JSON (.json)

  • XML (.xml)

  • AASX packages (.aasx)

Step 3: Visualization Dashboard#

Interactive web-based dashboard built with Dash that fetches and displays AAS and Submodel data from the BaSyx server.

Dashboard URL: http://127.0.0.1:8050

Download Example#

Download the complete Dev Container example: basyx-python-sdk-example.zip

Prerequisites#

Before running the example, ensure you have:

Quick Start#

  1. Download and Extract

    Download the example ZIP file and extract it to your desired location.

  2. Open in VS Code

    Open the extracted folder in Visual Studio Code.

  3. Start Dev Container

    When prompted, click “Reopen in Container” or press F1 and select “Dev Containers: Reopen in Container”. The container will automatically install all dependencies.

  4. Run the Example

    Open a terminal in VS Code and run:

    python main.py

    Select from the interactive menu:

    • 1 - Create AAS and Submodel

    • 2 - Start BaSyx Server

    • 3 - Start Visualization Dashboard

    • 4 - Run Server and Dashboard together

    • 5 - Run all steps sequentially

Step-by-Step Guide#

Step 1: Creating an AAS and Submodel#

The create_aas.py script demonstrates how to create an AAS with a Submodel programmatically.

Run:

python create_aas.py

Code Explanation:

Define AAS Identifiers#

from basyx.aas import model

aas_identifier = "https://example.com/AAS"
submodel_identifier = "https://example.com/Submodel"

Identifiers uniquely identify AAS and Submodels. Use URIs for global uniqueness.

Create Asset Information#

asset_info = model.AssetInformation(
    asset_kind=model.AssetKind.INSTANCE,
    global_asset_id="Asset1"
)

The AssetInformation describes the physical or logical asset that the AAS represents. AssetKind.INSTANCE indicates a specific asset instance (as opposed to a type).

Create the Asset Administration Shell#

aas = model.AssetAdministrationShell(
    asset_information=asset_info,
    id_=model.Identifier(aas_identifier)
)

The AAS is the digital representation of the asset. It contains references to Submodels but no data itself.

Define Properties#

prop1 = model.Property(
    id_short="Temperature",
    value_type=model.datatypes.Float,
    value=25.3,
    semantic_id=model.ExternalReference((
        model.Key(
            type_=model.KeyTypes.GLOBAL_REFERENCE,
            value='http://acplt.org/Properties/FirstSimpleProperty'
        ),
    ))
)

submodel.submodel_element.add(prop1)

Properties are the basic data elements. Each property has:

  • id_short: A human-readable identifier

  • value_type: The data type (Float, Integer, String, etc.)

  • value: The actual value

  • semantic_id: Optional reference to a standardized definition

Serialize to JSON#

from basyx.aas.adapter.json import write_aas_json_file

data = model.DictObjectStore()
data.add(aas)
data.add(submodel)

write_aas_json_file("storage/aas_data.json", data)

The DictObjectStore holds multiple AAS objects. The JSON adapter serializes them according to the AAS specification.

Step 2: Hosting the AAS via BaSyx Server#

The start_server.py script starts a BaSyx server that exposes AAS data via REST API.

Run:

python start_server.py

Keep this running in a separate terminal.

Code Explanation:

Load AAS Files#

from basyx.aas.adapter import load_directory

# Load AAS data from input directory
if os.path.isdir(env_input):
    object_store, file_store = load_directory(env_input)
    logger.info(
        "Loaded %d identifiable(s) and %d supplementary file(s)",
        len(list(object_store)), len(list(file_store))
    )

The server uses the load_directory function to recursively scan the input directory and load all AAS files (JSON, XML, or AASX) into an object store. The server supports both in-memory (read-only) and persistent storage modes.

Create WSGI Application#

from interfaces.repository import WSGIApp

application = WSGIApp(object_store, file_store, base_path="/api/v3.0")

The custom WSGIApp (from the interfaces module) creates a REST API that exposes the AAS data according to the official AAS API specification. This implementation provides full control over the API endpoints and behavior.

Start the Server#

from waitress import serve

serve(application, host="0.0.0.0", port=8080)

Waitress is a production-ready WSGI server that serves the BaSyx application on port 8080.

API Endpoints:

  • GET /api/v3.0/shells - List all AAS

  • GET /api/v3.0/shells/{aasIdentifier} - Get specific AAS by Base64URL-encoded ID

  • GET /api/v3.0/submodels - List all Submodels

  • GET /api/v3.0/submodels/{submodelIdentifier} - Get specific Submodel by Base64URL-encoded ID

  • GET / - Root endpoint with service information

Note: Identifiers in URLs must be Base64URL-encoded. The server automatically handles encoding/decoding.

Step 3: Visualizing AAS Data#

The visualization.py script creates an interactive dashboard using Dash.

Run:

python visualization.py

Access the dashboard at http://localhost:8050

Code Explanation:

Fetch Data from BaSyx Server#

import requests

def fetch_aas_data():
    response = requests.get("http://localhost:8080/api/v3.0/shells")
    return response.json()

Uses the requests library to fetch AAS data from the running BaSyx server.

Create Dash Application#

import dash
from dash import html, Input, Output

app = dash.Dash(__name__)

Dash is a Python framework for building web applications. It’s built on top of Flask, Plotly.js, and React.

Define Layout#

app.layout = html.Div([
    html.H1("BaSyx AAS Viewer"),
    html.Button("🔄 Refresh Data", id="refresh-btn", n_clicks=0),
    html.Div(id="aas-output"),
    html.Div(id="submodels-output")
])

The layout defines the structure of the web page using HTML components.

Add Callbacks#

@app.callback(
    [Output("aas-output", "children"),
     Output("submodels-output", "children")],
    [Input("refresh-btn", "n_clicks")]
)
def update_view(n_clicks):
    aas_data = fetch_aas_data()
    submodel_data = fetch_submodel_data()
    return html.Pre(str(aas_data)), html.Pre(str(submodel_data))

Callbacks make the app interactive. When the refresh button is clicked, the callback fetches fresh data and updates the display.

Run the Server#

app.run_server(debug=True, port=8050)

Starts the Dash development server on port 8050.

Project Structure#

resources/
├── .devcontainer/
│   └── devcontainer.json      # Dev container configuration
├── interfaces/                # Custom repository interfaces
│   ├── __init__.py
│   ├── base.py               # Base WSGI application
│   └── repository.py         # AAS API implementation
├── util/                      # Utility modules
│   ├── __init__.py
│   └── converters.py         # URL converters for identifiers
├── storage/                   # AAS data storage directory
│   └── .gitkeep              # Placeholder for empty directory
├── requirements.txt           # Python dependencies
├── main.py                    # Main script with interactive menu
├── create_aas.py             # Step 1: Create AAS and Submodel
├── start_server.py           # Step 2: Start BaSyx server
├── visualization.py          # Step 3: Dash visualization
└── README.md                 # Example documentation

Configuration#

Environment Variables#

Configure the BaSyx server behavior using environment variables:

  • INPUT (default: storage)

    • Directory path to load AAS data from at startup

  • STORAGE (default: storage)

    • Directory path for persistent storage (used when STORAGE_PERSISTENCY is enabled)

  • STORAGE_PERSISTENCY (default: false)

    • true: Enable persistent storage backend (changes are saved to disk)

    • false: Use in-memory storage (read-only mode)

  • STORAGE_OVERWRITE (default: false)

    • true: Overwrite existing files when syncing INPUT to STORAGE

    • false: Skip existing files during sync

  • API_BASE_PATH (optional, default: /api/v3.0)

    • Custom base path for the API endpoints

Example:

# Start with persistent storage
export STORAGE_PERSISTENCY=true
python start_server.py

# Start with custom input directory
export INPUT=my_data
export STORAGE=persistent_storage
export STORAGE_PERSISTENCY=true
python start_server.py

Troubleshooting#

Port Already in Use#

If you encounter port conflicts:

# Kill process on port 8080
lsof -ti:8080 | xargs kill -9

# Kill process on port 8050
lsof -ti:8050 | xargs kill -9

Server Connection Failed#

If the visualization cannot connect:

  1. Ensure the BaSyx server is running (python start_server.py)

  2. Verify server accessibility: http://localhost:8080/api/v3.0/shells

  3. Check that storage/aas_data.json exists

No AAS Data Found#

If the server reports no data:

  1. Run python create_aas.py to generate example data

  2. Verify storage/aas_data.json exists and is valid JSON

Additional Resources#

Additional Resources BaSyx Python SDK#

Asset Administration Shell#