twinsphere SDK Features

Asset Administration Shell Builder

Relevant specification: Specification of the Asset Administration Shell - Part 1: Metamodel - v3.0 ⧉

Code Example

AAS builder usage is simple:

using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Shells;
using AasCore.Aas3_0;

var shellBuilder = new AssetAdministrationShellBuilder("9A8F8B66-5AA7-4528-AA17-1CC128AF64C2",
        new AssetInformationBuilder(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<ILangStringTextType>
    {
        new LangStringTextType("en", "description"),
        new LangStringTextType("de", "Beschreibung")
    });

// add submodels here

var shell = shellBuilder.Build();

Remarks

Like with other builders, Construct enforces the truly mandatory properties, while the rest are kind of optional. Calling Build() performs internal validation, so expect exceptions if some property combinations are not properly set.

This builder essentially wraps what the aas-core-works ⧉ library already provides. However, its main purpose is the packaging of AASX files. A shell can contain a thumbnail, and we use the approach of providing the binary file directly to this builder. This is not possible or even specified in the AAS Metamodels, which only expect a file reference. By providing the binary file, we ensure that the file itself is properly serialized during packaging and that all references are correctly set on all expected places.

Submodel Builders

Contact Information Builder

---	Supported Submodel Template
Name	Contact Information
IDTA Number	02002
Version	1.0
Github	https://github.com/admin-shell-io/submodel-templates/tree/main/published/Contact%20Information/1 ⧉

Code Example

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Submodels.ContactInformations;

// prepare submodel

var builder = new ContactInformationBuilder()
        .WithRoleOfContactPerson("0173-1#07-AAS931#001")
        .WithNationalCode(new List<ILangStringTextType>() { new LangStringTextType("de", "DE") })
        .AddLanguage("de")
        .WithTimeZone("+2")
        .WithCityTown(new List<ILangStringTextType>() { new LangStringTextType("de", "Nürnberg") })
        .WithCompany(new List<ILangStringTextType>() { new LangStringTextType("de", "Conplement AG") })
        .WithDepartment(new List<ILangStringTextType>() { new LangStringTextType("de", "Vertrieb") })
        .WithPhone(new List<ILangStringTextType>() { new LangStringTextType("de", "01234512457") },
            TypeOfTelephone.Office,
            new List<ILangStringTextType>()
            {
                    new LangStringTextType("de", "Montag – Freitag 08:00 bis 16:00")
            })
        .WithFax(new List<ILangStringTextType>() { new LangStringTextType("de", "01234512400") },
            TypeOfFaxNumber.Office)
        .WithEmail("info@test.de", TypeOfEmail.Office)
        .AddIpCommunication("https://www.conplement.de/test/chat", "chat",
            new List<ILangStringTextType>()
            {
                    new LangStringTextType("de", "Montag – Freitag 08:00 bis 16:00")
            })
        .WithStreet(new List<ILangStringTextType>() { new LangStringTextType("de", "Südwestpark 92") })
        .WithZipCode(new List<ILangStringTextType>() { new LangStringTextType("de", "90449") })
        .WithPoBox(new List<ILangStringTextType>() { new LangStringTextType("de", "PF 90449") })
        .WithZipCodeOfPoBox(new List<ILangStringTextType>() { new LangStringTextType("de", "90449") })
        .WithStateCounty(new List<ILangStringTextType>() { new LangStringTextType("de", "Bayern") })
        .WithNameOfContact(new List<ILangStringTextType>() { new LangStringTextType("de", "Mustermann") })
        .WithFirstName(new List<ILangStringTextType>() { new LangStringTextType("de", "Max") })
        .WithMiddleNames(new List<ILangStringTextType>() { new LangStringTextType("de", "Michael") })
        .WithTitle(new List<ILangStringTextType>() { new LangStringTextType("de", "Herr") })
        .WithAcademicTitle(new List<ILangStringTextType>() { new LangStringTextType("de", "Dr") })
        .WithFurtherDetailsOfContact(new List<ILangStringTextType>() { new LangStringTextType("de", "1. Etage 2. Büro rechts") })
        .WithAddressOfAdditionalLink("https://www.conplement.de");

var contactInformationsBuilder = new ContactInformationsBuilder("ContactInformations").AddContactInformation(builder);

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Shells;

var thumbnail = new SphereFile("thumbnail.jpg", "image/jpg", Array.Empty<byte>());

var builder = new AssetAdministrationShellBuilder(Guid.NewGuid().ToString(),
        new AssetInformationBuilder(AssetKind.Instance)
            .WithGlobalAssetId("GlobalAssetTestId")
            .WithDefaultThumbnail(thumbnail))
    .WithIdShort("GlobalAssetTestIdShort")
    .WithDescription(new List<ILangStringTextType>
    {
        new LangStringTextType("en", "description"),
        new LangStringTextType("de", "Beschreibung")
    });
builder.WithContactInformations(contactInformationsBuilder); // see the example above

Remarks

Additional value of this builder is the Concept Descriptions management which occurs under the hood when this builder is used for packaging. Please pay attention to singular und plural versions of the builders - ContactInformationBuilder vs. ContactInformationsBuilder.

Digital Nameplate Builder

---	Supported Submodel Template
Name	Digital Nameplate for Industrial Equipment
IDTA Number	02006
Version	2.0
Github	https://github.com/admin-shell-io/submodel-templates/tree/main/published/Digital%20nameplate/2/0 ⧉

Code Example

// build submodel
using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Submodels.DigitalNameplate;

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

// add the markings
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<ILangStringTextType> { new LangStringTextType("en", "maximum") },
                "ACME", "maximum", "highly-flammable", "0", "75", "55", "normal")
            .WithProcessConditions("external", new List<ILangStringTextType> { new 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);

// add submodel to shell
shellBuilder.WithDigitalNameplate(digitalNameplateBuilder);

Remarks

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Shells;

var thumbnail = new SphereFile("thumbnail.jpg", "image/jpg", Array.Empty<byte>());

var builder = new AssetAdministrationShellBuilder(Guid.NewGuid().ToString(),
        new AssetInformationBuilder(AssetKind.Instance)
            .WithGlobalAssetId("GlobalAssetTestId")
            .WithDefaultThumbnail(thumbnail))
    .WithIdShort("GlobalAssetTestIdShort")
    .WithDescription(new List<ILangStringTextType>
    {
        new LangStringTextType("en", "description"),
        new LangStringTextType("de", "Beschreibung")
    });
builder.WithDigitalNameplate(digitalNameplateBuilder);

Additional value of this builder is the file management which occurs under the hood once you include the file, for example when creating a marking you need to provide a marking image itself. Same goes for necessary concept descriptions which are automatically included when this builder is used for packaging.

Handover Documentation Builder

---	Supported Submodel Template
Name	Handover Documentation
IDTA Number	02004
Version	1.2
Github	https://github.com/admin-shell-io/submodel-templates/tree/main/published/Handover%20Documentation/1/2 ⧉

Code Example

// build submodel
using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Submodels.HandoverDocumentation.DocumentClassifications;
using Conplement.Sphere.SDK.Submodels.HandoverDocumentation;

// prepare submodel

var handoverDocumentationBuilder = new HandoverDocumentationBuilder(
        "https://conplement-docs.de/operator-manual-1.0-9987736")
    .AddDocument(UserManualDocument())
    .AddDocument(...)

private DocumentBuilder UserManualDocument()
{
    // the version is the heart of the structure, because it contains the actual documents (and the image preview files)
    var documentVersion = new DocumentVersionBuilder(
            new List<string>() { "de", "en" },
            "1.0",
            new List<ILangStringTextType> { new LangStringTextType("en", "Operator Manual") },
            new List<ILangStringTextType>
            {
                new LangStringTextType("en", "The operator manual for the device")
            },
            new List<ILangStringTextType> { new LangStringTextType("en", "manual") },
            "2023-09-27",
            "Released",
            "conplement",
            "conplement AG",
            new List<SphereFile> { new("manual.pdf", "text/pdf", Array.Empty<byte>()) },
            idShort: "DocumentVersion01")
        .AddPreviewFile(new("preview-image.png", "image/png", Array.Empty<byte>()))
        .WithSubTitle(new List<ILangStringTextType> { new LangStringTextType("en", "Operations manual") });

    return new DocumentBuilder(
            new List<DocumentIdBuilder> { new("1213455566", "XF90-884", idShort: "DocumentId01") },
            // we classify the document as the Operational documentation according to VDI2770
            new List<DocumentClassification> { DocumentClassificationVDI2770.Operation },
            idShort: "Document01")
        .AddDocumentVersion(documentVersion);
}

// add submodel to shell
shellBuilder.AddHandoverDocumentation(handoverDocumentationBuilder);
shellBuilder.AddHandoverDocumentation(...);

Remarks

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Shells;

var thumbnail = new SphereFile("thumbnail.jpg", "image/jpg", Array.Empty<byte>());

var builder = new AssetAdministrationShellBuilder(Guid.NewGuid().ToString(),
        new AssetInformationBuilder(AssetKind.Instance)
            .WithGlobalAssetId("GlobalAssetTestId")
            .WithDefaultThumbnail(thumbnail))
    .WithIdShort("GlobalAssetTestIdShort")
    .WithDescription(new List<ILangStringTextType>
    {
        new LangStringTextType("en", "description"),
        new LangStringTextType("de", "Beschreibung")
    });
builder.AddHandoverDocumentation(handoverDocumentationBuilder);
builder.AddHandoverDocumentation(...);

Additional value of this builder is the file management which occurs under the hood once you include the file. Same goes for necessary concept descriptions which are automatically included when this builder is used for packaging.

Contraints ensured

• Document:DocumentClassification => at least one classification according to VDI 2770 shall be provided.
  • this is ensured due to Mandatory Constructor Fields
• DocumentId:IsPRimary => only one DocumentId in a collection may be marked as primary.
  • if more than one is marked as primary the validation will throw an according Exception
• DocumentClassification:ClassId => if ClassificationSystem is set to “VDI2770 Blatt 1:2020”, the given IDs of VDI2770 Blatt 1:2020 shall be used
  • this is ensured as only matching IDs can be used using the SDK
• DocumentClassification:ClassName => if ClassificationSystem is set to “VDI2770 Blatt 1:2020”, the given IDs of VDI2770 Blatt 1:2020 shall be used
  • this is ensured as only matching IDs can be used using the SDK
• DocumentVersion:Title => for each language-dependent Title, a Summary and at least one KeyWord shall exist for the given language.
  • this is validated while building and throws an according Exception
• DocumentVersion:Summary => for each language-dependent Title, a Summary and at least one KeyWord shall exist for the given language.
  • this is validated while building and throws an according Exception
• DocumentVersion:KeyWords => for each language-dependent Title, a Summary and at least one KeyWord shall exist for the given language.
  • this is validated while building and throws an according Exception
• DocumentVersion:DigitalFile => the MIME-Type needs to match the file type.
  • this is validated while building and throws an according Exception
• DocumentVersion:DigitalFile => at least one PDF/A file type shall be provided.
  • this is validated while building and throws an according Exception
• DocumentVersion:PreviewFile => the MIME-Type needs to match the file type.
  • this is validated while building and throws an according Exception
• DocumentVersion:PreviewFile => Allowed file types are JPG, PNG, BMP.
  • this is validated while building and throws an according Exception

Constraints not yet ensured

• Document:DocumentedEntity => reference targets an Entity within the Submodel “ManufacturerDocumentation”.
  • this constraint is not ensured currently due to uncertainty because of "ManufacturerDocumentation"
• DocumentClassification:ClassName => languages shall match at least the language specifications of the included DocumentVersions.
  • this is currently not supported as only english is used
• DocumentVersion:RefersTo => reference targets a SMC “Document” or a “DocumentVersion”.
  • this is currently not ensured as the SDK accepts all references
• DocumentVersion:BasedOn => reference targets a SMC “Document” or a “DocumentVersion”.
  • this is currently not ensured as the SDK accepts all references
• DocumentVersion:TranslationOf => reference targets a SMC “Document” or a “DocumentVersion”.
  • this is currently not ensured as the SDK accepts all references
• DocumentVersion:TranslationOf => the (language-independent) content must be identical in both Documents or DocumentVersions.
  • this is not ensured as the SDK cannot prove this

Technical Data Builder

---	Supported Submodel Template
Name	Generic Frame for Technical Data for Industrial Equipment in Manufacturing
IDTA Number	02003
Version	1.2
Github	https://github.com/admin-shell-io/submodel-templates/tree/main/published/Technical_Data/1/2 ⧉

Code Example

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Submodels.TechnicalData;

// prepare submodel

SubSectionBuilder subSectionBuilder = new SubSectionBuilder();
SubSectionBuilder dimensions = new SubSectionBuilder();
subSectionBuilder.AddSubmodelElement(new Property(DataTypeDefXsd.UnsignedInt)
{
    Value = "12",
    IdShort = "Weight",
    SemanticId = Conplement.Sphere.SDK.Submodels.SemanticReference.Create(
        "https://admin-shell.io/ZVEI/TechnicalData/TechnicalProperties/MainSection00/SubSection00/Weight")
});
dimensions.AddSubmodelElement(new Property(DataTypeDefXsd.UnsignedInt)
{
    Value = "1300",
    IdShort = "Length",
    SemanticId = Conplement.Sphere.SDK.Submodels.SemanticReference.Create(
        "https://admin-shell.io/ZVEI/TechnicalData/TechnicalProperties/MainSection00/SubSection01/Length")
});
dimensions.AddSubmodelElement(new Property(DataTypeDefXsd.UnsignedInt)
{
    Value = "1000",
    IdShort = "Width",
    SemanticId = Conplement.Sphere.SDK.Submodels.SemanticReference.Create(
        "https://admin-shell.io/ZVEI/TechnicalData/TechnicalProperties/MainSection00/SubSection01/Width")
});
dimensions.AddSubmodelElement(new Property(DataTypeDefXsd.UnsignedInt)
{
    Value = "900",
    IdShort = "Height",
    SemanticId = Conplement.Sphere.SDK.Submodels.SemanticReference.Create(
        "https://admin-shell.io/ZVEI/TechnicalData/TechnicalProperties/MainSection00/SubSection01/Height")
});

MainSectionBuilder main = new MainSectionBuilder();
main.AddSubSection(subSectionBuilder);
main.AddSubSection(dimensions);

GeneralInformationBuilder generalInformationBuilder = new GeneralInformationBuilder(
        "conplement AG",
        new List<ILangStringTextType> { new LangStringTextType("de", "A test product for test reasons!") },
        "08154711",
        "133742069"
    ).WithManufacturerLogo(new SphereFile("companyLogo.png", "image/png", Array.Empty<byte>()))
    .WithProductImage(new SphereFile("productImage.png", "image/png", Array.Empty<byte>()));

var madeIn = new List<ILangStringTextType>()
{
    new LangStringTextType("de", "Gefertigt in Deutschland"),
    new LangStringTextType("en", "Made in Germany"),
    new LangStringTextType("ru", "Сделано в Германии")
};

var factoryPlace = new List<ILangStringTextType>()
{
    new LangStringTextType("de", "Nürnberg"),
    new LangStringTextType("en", "Nuremberg"),
    new LangStringTextType("ru", "Нюрнберг")
};

FurtherInformationBuilder furtherInformationBuilder = new FurtherInformationBuilder("2023-09-09")
    .AddTextStatement(madeIn)
    .AddTextStatement(factoryPlace);

ProductClassificationsBuilder productClassificationsBuilder = new ProductClassificationsBuilder()
    .AddProductClassificationItem("ECLASS", "0173-1#01-AKN474#019", "13.0")
    .AddProductClassificationItem("IEC CDD", "0112/2///61987#ABJ740#002", "1.0");

TechnicalPropertiesBuilder technicalPropertiesBuilder = new TechnicalPropertiesBuilder();
technicalPropertiesBuilder.AddMainSection(main);

TechnicalDataBuilder technicalDataBuilder =
    new TechnicalDataBuilder("TechnicalData", generalInformationBuilder, technicalPropertiesBuilder)
        .WithFurtherInformation(furtherInformationBuilder)
        .WithProductClassifications(productClassificationsBuilder);

conceptDescriptions = GetConceptDescriptions();

foreach (var conceptDescription in conceptDescriptions)
{
    technicalDataBuilder.ConceptDescriptions.Add(conceptDescription);
}

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Shells;

var thumbnail = new SphereFile("thumbnail.jpg", "image/jpg", Array.Empty<byte>());

var builder = new AssetAdministrationShellBuilder(Guid.NewGuid().ToString(),
        new AssetInformationBuilder(AssetKind.Instance)
            .WithGlobalAssetId("GlobalAssetTestId")
            .WithDefaultThumbnail(thumbnail))
    .WithIdShort("GlobalAssetTestIdShort")
    .WithDescription(new List<ILangStringTextType>
    {
        new LangStringTextType("en", "description"),
        new LangStringTextType("de", "Beschreibung")
    });
builder.WithTechnicalData(technicalDataBuilder);

Remarks

Additional value of this builder is the file management which occures under the hood once you include the file, for example when creating a marking you need to provide a marking image itself. Same goes for necessary concept descriptions which are automatically included when this builder is used for packaging.

Time Series Data Builder

---	Supported Submodel Template
Name	Time Series Data
IDTA Number	02008
Version	1.1
Github	https://github.com/admin-shell-io/submodel-templates/tree/main/published/Time%20Series%20Data/1/1 ⧉

Code Example

Build submodel:

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Submodels.TimeSeriesData.Operations;
using Conplement.Sphere.SDK.Submodels.TimeSeriesData;

// prepare submodel

public static TimeSeriesBuilder ComplexTimeSeriesData()
{
    // linked segments
    var linkedSegment = new LinkedSegmentBuilder();
    linkedSegment
        .WithName(new List<ILangStringTextType> { new LangStringTextType("en", "example link segment") })
        .WithDescription(
            new List<ILangStringTextType> { new LangStringTextType("en", "An example for a link segment") })
        .WithEndpoint("https://example.com/time-series-data")
        .WithQuery("?deviceId=12345&start=987654678");

    var linkedSegment2 = new LinkedSegmentBuilder();
    linkedSegment2
        .WithName(new List<ILangStringTextType> { new LangStringTextType("en", "other example link segment") })
        .WithDescription(new List<ILangStringTextType>
            { new LangStringTextType("en", "An other example for a link segment") })
        .WithEndpoint("https://example.com/time-series-data")
        .WithQuery("?deviceId=12345&end=8729807345");

    // external segment

    var externalSegment = new ExternalSegmentBuilder();
    externalSegment
        .WithName(new List<ILangStringTextType> { new LangStringTextType("en", "example external segment") })
        .WithDescription(new List<ILangStringTextType>
            { new LangStringTextType("en", "An example for an external segment") })
        .WithFile(new SphereFile("time-data.csv", "text/csv", Array.Empty<byte>())); // A SphereFile

    // internal segment
    var records = new RecordsBuilder();

    var record1 = new RecordBuilder();

    record1
        .WithIdShort(0)
        .AddTAITime("1997-07-01T00:00:29")
        .AddUTCTime("1997-06-30T23:59:59")
        .AddRelativeTimeDuration("100000000000000000000000");

    var measure = new Property(DataTypeDefXsd.Decimal)
    {
        IdShort = "Temperature",
        Value = "10.5"
    };

    var record2 = new RecordBuilder();
    record2
        .WithIdShort(1)
        .AddTAITime("1997-07-01T00:00:20")
        .AddUTCTime("1997-06-30T23:59:50")
        .AddRelativeTimeDuration("99")
        .AddVariable(measure);

    records
        .AddRecord(record1)
        .AddRecord(record2);

    var internalSegment = new InternalSegmentBuilder(records);

    // required builder for metadata
    var metaDataRecordBuilder = new RecordBuilder();
    metaDataRecordBuilder.AddRelativePointInTime("5");

    // required builders for the time series submodel
    var segemnts = new SegmentsBuilder();
    segemnts
        .AddLinkedSegment(linkedSegment)
        .AddLinkedSegment(linkedSegment2)
        .AddExternalSegment(externalSegment)
        .AddInternalSegment(internalSegment);
    var metadata =
        new MetadataBuilder(new List<ILangStringTextType> { new LangStringTextType("en", "ExampleMetaData") },
            metaDataRecordBuilder);

    // operations
    var deriveSegmentOperation = new DeriveSegmentsBuilder("1997-06-30T23:59:59", "1997-07-30T23:59:59");
    deriveSegmentOperation.WithAggregationMethod("Max");
    var readSegmentsOperation = new ReadSegmentsBuilder("1997-06-30T23:59:59", "1997-07-30T23:59:59");
    var readRecordsOperation = new ReadRecordsBuilder("1997-06-30T23:59:59", "1997-07-30T23:59:59");

    var builder = new TimeSeriesBuilder("ExampleTimeSeriesSubmodel", metadata, segemnts)
        .WithDeriveSegmentsOperation(deriveSegmentOperation)
        .WithReadRecordsOperation(readRecordsOperation)
        .WithReadSegmentsOperation(readSegmentsOperation);

    return builder;
}

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Shells;

var thumbnail = new SphereFile("thumbnail.jpg", "image/jpg", Array.Empty<byte>());

var builder = new AssetAdministrationShellBuilder(Guid.NewGuid().ToString(),
        new AssetInformationBuilder(AssetKind.Instance)
            .WithGlobalAssetId("GlobalAssetTestId")
            .WithDefaultThumbnail(thumbnail))
    .WithIdShort("GlobalAssetTestIdShort")
    .WithDescription(new List<ILangStringTextType>
    {
        new LangStringTextType("en", "description"),
        new LangStringTextType("de", "Beschreibung")
    });
builder.WithTimeSeriesData(ComplexTimeSeriesData());

Remarks

Additional value of this builder is the file management which occures under the hood once you include the file, for example when creating a marking you need to provide a marking image itself. Same goes for necessary concept descriptions which are automatically included when this builder is used for packaging.

Carbon Footprint Builder

---	Supported Submodel Template
Name	Carbon Footprint
IDTA Number	02023
Version	0.9
Github	https://github.com/admin-shell-io/submodel-templates/tree/main/published/Carbon%20Footprint/0/9 ⧉

Code Example

Build submodel:

using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Submodels.ProductCarbonFootprint;

// prepare submodel

public static CarbonFootprintBuilder ComplexCarbonFootprint()
{
    var pcfAddress = new TCFGoodsTransportAddressTakeoverHandoverBuilder()
        .WithHouseNumber("18a")
        .WithStreet("Musterstraße")
        .WithCityTown("Musterstadt")
        .WithCountry("Musterland")
        .WithPCFGoodsIds();
    var tcfAddressHandover = new TCFGoodsTransportAddressTakeoverHandoverBuilder()
        .WithHouseNumber("18a")
        .WithStreet("Musterstraße")
        .WithCityTown("Musterstadt")
        .WithCountry("Musterland")
        .WithHandoverIds();
    var tcfAddressTakeover = new TCFGoodsTransportAddressTakeoverHandoverBuilder()
        .WithHouseNumber("18a")
        .WithStreet("Musterstraße")
        .WithCityTown("Musterstadt")
        .WithCountry("Musterland")
        .WithTakeoverIds();

    var productCarbonFootprintBuilder = new ProductCarbonFootprintBuilder(
        "GHG Protocol",
        "17.2",
        "g",
        "A1 - raw material supply (and upstream production)",
        "5.0",
        "2024-02-16",
        pcfAddress
    );

    var productCarbonFootprintBuilder2 = new ProductCarbonFootprintBuilder(
            "ISO 14067",
            "17.2",
            "kg",
            "B2 - maintenance",
            "5.0",
            "2024-02-16",
            pcfAddress
        ).WithExpirationDate("2025-01-01")
        .WithExplanatoryStatement(new SphereFile("Example.pdf", "application/pdf", Array.Empty<byte>()));

    var transportCarbonFootprintBuilder = new TransportCarbonFootprintBuilder(
        "5.3",
        "t",
        "4.0",
        "WTT - Well-to-Tank",
        tcfAddressTakeover,
        tcfAddressHandover,
        "2024-02-16"
    ).WithExpirationDate("2025-01-01");

    var carbonFootprintBuilder = new CarbonFootprintBuilder("carbonFootprintExample")
        .AddTransportCarbonFootprint(transportCarbonFootprintBuilder)
        .AddProductCarbonFootprint(productCarbonFootprintBuilder2)
        .AddProductCarbonFootprint(productCarbonFootprintBuilder);
    return carbonFootprintBuilder;
}

using AasCore.Aas3_0;
using Conplement.Sphere.SDK.Packaging;
using Conplement.Sphere.SDK.Shells;

var thumbnail = new SphereFile("thumbnail.jpg", "image/jpg", Array.Empty<byte>());

var builder = new AssetAdministrationShellBuilder(Guid.NewGuid().ToString(),
        new AssetInformationBuilder(AssetKind.Instance)
            .WithGlobalAssetId("GlobalAssetTestId")
            .WithDefaultThumbnail(thumbnail))
    .WithIdShort("GlobalAssetTestIdShort")
    .WithDescription(new List<ILangStringTextType>
    {
        new LangStringTextType("en", "description"),
        new LangStringTextType("de", "Beschreibung")
    });
builder.WithCarbonFootprint(ComplexCarbonFootprint());

Remarks

Additional value of this builder is the file management which occures under the hood once you include the file, for example when creating a marking you need to provide a marking image itself. Same goes for necessary concept descriptions which are automatically included when this builder is used for packaging.

Sphere Package Builder

Relevant specification: Specification of the Asset Administration Shell - Part 5: Package File Format (AASX) - v3.0 ⧉

Sphere Package Builder produces so-called "Sphere Packages," which are essentially equivalent to AASX packages as defined by the AAS. The reason for the special naming is that we introduce some constraints to the packaging when using our builder. For example, while the standard specification defines packaging of shells in so-called environments with no limit on the number of shells included, Sphere packages limit the number of shells per package to a single shell.

Sphere packages automatically contain all files and concept descriptions of the shell/submodels included through the builders.

Code Example

var spherePackage = new SpherePackageBuilder(shellBuilder).Build();

// you can save the package to disk, e.g. 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);

Sphere Upload

The Sphere Upload can be used to upload an SDK-built Sphere Package to a Sphere API in one go.

It requires the host address of the API, the username and password, and the complete package.

Each twinsphere Tenant has its own host.

Code Example

private TestConfiguration _configuration = new TestConfiguration();

var apiResult = await SphereUpload.Upload(spherePackage, new SphereUploadOptions(_configuration.ApiPassword, _configuration.ApiUsername, _configuration.ApiHostAddress));
if(apiResult.Success){
    LogMessage("Upload Complete");    
} else {
    LogMessage(apiResult.ErrorMessage);    
}

It returns a result that indicates if the upload was a success and an error message if not.

Helper Functions

The twinsphere SDK comes with useful helper functions to support developers in building shells and submodels.

Helper Extensions

Class Conplement.Sphere.SDK.HelperExtensions

ToLangString

• Transform a string to a Langstring

Core.ILangStringTextType ToLangString(this string data, string countryCode = "de")

var manufacturerName = "MeinHersteller".ToLangString();
var manufacturerNameEn = "MyManufacturer".ToLangString("en");

ToSingleList

• Transform an item to List with only the item as values

List<T> ToSingleList<T>(this T data)

List<LangString> manufacturer = manufacturerName.ToSingleList(); 

Property Helper

Class Conplement.Sphere.SDK.Submodels.PropertyHelper

CreateMultiLanguage

• Create MultiLanguageProperties where you can use the method with the most fitting signature for your data (value, dictionary, params, IEnumerable)

var classNameProperty = PropertyHelper.CreateMultiLanguage(
        "ClassName",
        MyIds.ClassName,
        "MyClassName".ToLangString("en"));

var manufacturerName = PropertyHelper.CreateMultiLanguage(
        "ManufacturerName",
        MyIds.ManufacturerName,
        manufacturerName); 

Create Properties

• Create Properties with different overloadings and predefined types

var timeZone = PropertyHelper.Create("TimeZone", MyIds.TimeZone, Core.DataTypeDefXsd.String, timeZone);

var serialNumber = PropertyHelper.CreateString("SerialNumber",MyIds.SerialNumber, serialNumber);

var issueDateProp = PropertyHelper.CreateDate("IssueDate", MyIds.IssueDate, issueDate);

Semantic Reference Helper

Class Conplement.Sphere.SDK.Submodels.SemanticReference

• Create Semantic References with default values

SemanticId = SemanticReference.Create(MyIds.DigitalNameplate);
SemanticId = SemanticReference.Create(MyIds.DigitalNameplate, Core.KeyTypes.GlobalReference);
SemanticId = SemanticReference.Create(MyIds.DigitalNameplate, Core.KeyTypes.GlobalReference, Core.ReferenceTypes.ExternalReference);

Helpers

Class Conplement.Sphere.SDK.Submodels.Helpers

SetUniqueIdShort

• Transform an IEnumerable of IReferable to only have unique IdShorts
  • groups all elements of the same IdShort and then adds a count to it
  • from (myid, myid, testid, myid) to (myid, myid1, testid, myid2)

    var myElementsWithUniqueIds = mergedElementsWithNonUniqueIds.SetUniqueIdShort();