twinsphere SDK Documentation

Introduction

The twinsphere SDK is built with the following concepts in mind:

  • Compatibility with the latest Asset Administration Shell (AAS) specification, as specified by the Industrial Digital Twin Association, currently in version 3.0.
  • Convenience for developers to reduce the necessary study of the AAS metamodel specifications. For example, XML code documentation is heavily used to describe AAS semantics on the builders.
  • Definition of metamodels for selected submodels, such as Digital Nameplate.
  • Extension rather than abstraction or replacement of aas-core-works ⧉ metamodels. Our SDK often uses aas-core objects as return values or method parameters, and aas-core validation rules are reused.
  • Offering packaging functionality based on the AASX format.
  • Comfortable upload functionality of created AASX packages to the twinsphere platform via its API.

Download

The SDK is available as a NuGet package, hosted on the private twinsphere Nuget package feed ⧉. You can add the feed to your project with dotnet nuget:

dotnet nuget add source https://pkgs.dev.azure.com/conplementag/AASphere/_packaging/AASphere/nuget/v3/index.json -n AASphere -u aasphere-package-reader -p api_key

Remarks:

  • The username in the command above can be set to any value.
  • An additional parameter --store-password-in-clear-text might be necessary on Linux clients.

The twinsphere SDK is included in any twinsphere subscription. Please ask us for the access credentials (api_key).

Example

This code example provides a first impresion on the usage of our SDK:

using Conplement.Sphere.SDK.Building;
using Conplement.Sphere.SDK.Packaging;
// ...

// 1. we build a digital nameplate for our product
var digitalNameplateBuilder = new DigitalNameplateBuilder(
    "nameplate-C4022",
    "https://conplement.de/test",
    new List<Core.ILangStringTextType> { new Core.LangStringTextType("de-DE", "conplement AG") },
    new List<Core.ILangStringTextType> { new Core.LangStringTextType("de-DE", "internal-product") },
    "2023",
        new ContactInformationForDigitalNameplateBuilder(
        new List<Core.ILangStringTextType> { new Core.LangStringTextType("de-DE", "Südwestpark 92G") },
        new List<Core.ILangStringTextType> { new Core.LangStringTextType("de-DE", "90449") },
        new List<Core.ILangStringTextType> { new Core.LangStringTextType("de-DE", "Nürnberg") },
        new List<Core.ILangStringTextType> { new Core.LangStringTextType("de-DE", "DE") }
    ));

// 1.1 digital nameplate makes little sense without markings
// note about Array.Empty<byte> - no real image is passed here, but you would normally load and pass the image contents, 
// so that it is available for functionality like packaging below
var mainMarking = new MarkingBuilder("Marking01", "main-image", new SphereFile("main-marking.png", "image/png", Array.Empty<byte>()))
    .WithExplosionSafeties(new ExplosionSafetiesBuilder()
        .AddExplosionSafety(explosionSafety => explosionSafety
            .WithAmbientConditions("external",new List<Core.ILangStringTextType> { new Core.LangStringTextType("en", "maximum") },
                "ACME", "maximum", "highly-flammable", "0", "75", "55", "normal")
            .WithProcessConditions("external",new List<Core.ILangStringTextType> { new Core.LangStringTextType("en", "maximum") },
                "ACME", "maximum", "highly-flammable", "0", "75", "55", "normal")));

var secondMarking = new MarkingBuilder("Marking02", "second-image", new SphereFile("second-marking.png", "image/png", Array.Empty<byte>()));

var markingsCollection = new MarkingsBuilder()
    .AddMarking(mainMarking)
    .AddMarking(secondMarking);

digitalNameplateBuilder
    .WithIdShort("Nameplate")
    .WithCompanyLogo(new SphereFile("conplement-logo.png", "image/png", Array.Empty<byte>()))
    .WithFirmwareVersion("1.0.0")
    .WithSerialNumber("09383-sf8843j4-4")
    .WithCountryOfOrigin("Germany")
    .WithDateOfManufacture("2023-12-25")
    .WithMarkings(markingsCollection);

// 2. we need a shell for our product too
var shellBuilder = new AssetAdministrationShellBuilder("9A8F8B66-5AA7-4528-AA17-1CC128AF64C2",
        new AssetInformationBuilder(Core.AssetKind.Instance)
            .WithGlobalAssetId("urn:conplement:aas:type:7689239_f0b4f6ff-6951-4614-b733-6da43db7af9a")
            .WithDefaultThumbnail(new SphereFile("conplement-product-thumbnail.png", "image/png", Array.Empty<byte>())))
    .WithIdShort("myshellidshort")
    .WithDescription(new List<Core.ILangStringTextType>
    {
        new Core.LangStringTextType("en-EN", "description"),
        new Core.LangStringTextType("de-DE", "Beschreibung")
    })
    .WithDigitalNameplate(digitalNameplateBuilder); // the nameplate is added to the shell

// 3. we can now create an AASX package out of all of this
var spherePackage = new SpherePackageBuilder(shellBuilder).Build();

// 4. you can save the package to disk for analysis with the https://github.com/admin-shell-io/aasx-package-explorer
packageFilePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "my-package.aasx");
await spherePackage.SaveToFile(packageFilePath);

General Usage

Builder methods are separated into three groups:

  • With*() methods for normal properties, which can be called multiple times, and will simply overwrite the previous value

  • Add*() methods for collection properties, which add a new item every time when called

  • With*(SphereFile file, ...) methods accepting the SphereFile argument can be called only once at the moment, to simplify the packaging logic at the moment. This behavior might change in the future.

Build() can be called directly, to produce a valid metamodel object

new AssetInformationBuilder(Core.AssetKind.Instance)
    .WithGlobalAssetId("my-id")
    .Build(); // produces a aas-core-works AssetInformation object instance

Builders carry extra functionality and data, they are not simply there to populate object properties. For example, every builder supports AASX packaging functionality which enables you to add files to the semantically proper place, and not worry about all the references which have to be set for the packaging in the background. 

new AssetInformationBuilder(Core.AssetKind.Instance)
    .WithDefaultThumbnail(new SphereFile("my-company.png", "image/png", binaryContents))
    .Build();

In the example above, the builder collects the actual file for the thumbnail, but abstracts away many implementation details required for packaging later down the road.

Due to the extra functionality feature, nested builders are implemented in a way that you should normally not call the Build() method yourself - the builders are direct dependencies in constructors or in the With*() or Add*() methods.

var assetInformationBuilder = new AssetInformationBuilder(Core.AssetKind.Instance)
    .WithGlobalAssetId("urn:conplement:aas:type:7689239_f0b4f6ff-6951-4614-b733-6da43db7af9a");

new AssetAdministrationShellBuilder("9A8F8B66-5AA7-4528-AA17-1CC128AF64C2", assetInformationBuilder); // builder expected, not the product of the Build() method!

Note This SDK heavily uses the XML code documentation in which all methods and classes are explained in detail.