DWIS.Client.ReferenceImplementation 2.1.9

DWIS.Client.ReferenceImplementation

This is the main component of the DDHub .net SDK.

Installation

The simplest is to use nuget packages.

dotnet add package DWIS.Client.ReferenceImplementation --version 1.0.5

The package relies on the Unified Automation .Net SDK. This product is licensed: if you have a license, place it in the folder containing your executable. Otherwise, the client will only run for one hour.

Getting started

Creating a client

To instantiate a client, you need to pass some arguments.

• IDWISClientConfiguration clientConfiguration: contains the connection information to the DDHub server. A standard implementation of the interface is the class DefaultDWISConfiguration, in the same namespace. The interface exposes the following fields:
  • ServerAdress: the opc address to be used, including the port number
  • UseWebAPI: can be set to true if the server also exposes an http interface. If set to false the standard opc ua communication will be used for semantic interaction.
  • WebAPIUrl: the url of the web service. Only relevant if UseWebPI is true.
• IUAApplicationConfiguration uAApplicationConfiguration: for the management of opc ua communication. A standard implementation of the interface is DefaultUAApplicationConfiguration, in the same package. The interface exposes the following fields:
  • LicenseFilePath
  • ApplicationName
  • ProductName
  • CertificateStorePath
  • CertificateSubjectName
  • TrustedCertificateStore
  • IssuerCertificateStore
  • RejectedCertificatesStore
• ILogger<DWISClient>? logger, ILoggerFactory? loggerFactory
• IUALicenseManager? uALicenseManager. A standard implementation of the interface is DefaultLicenseManager, in the same package.

A client can be implemented by:

var client = new DWISClient(
    new DefaultDWISClientConfiguration() 
    { 
        ServerAddress = "opc.tcp://localhost:48030", 
        UseWebAPI = false 
    }, 
    new DefaultUAApplicationConfiguration(), 
    null, 
    null, 
    new DefaultLicenseManager());

Another example, based on dependency injection:

var hostBuilder = Host.CreateDefaultBuilder();
hostBuilder.ConfigureServices((hostContext, services) =>
{
    services
    .AddSingleton<IDWISClientConfiguration>(DefaultDWISClientConfiguration.LoadDefault())//standard method that will load from a JSON file at a predefined location, or construct a configuration with default parameters. 
    .AddSingleton<IUAApplicationConfiguration, DefaultUAApplicationConfiguration>()
    .AddSingleton<IUALicenseManager,DefaultLicenseManager>()
    .AddSingleton<IOPCUADWISClient, DWISClient>();
});

var host = hostBuilder.Build();
var client = host.Services.GetRequiredService<IOPCUADWISClient>();

Using the DDHub API

Inject a manifest

Manifest injection is done by calling the Inject method. The manifest class is in the DWIS.API.DTO namespace.

ManifestFile myManifest = new ManifestFile();
//populate your manifest

var result = client.Inject(myManifest);

If your manifest contains some provided variables, those can be updated on the server by calling the UpdateProvidedVariables method:

ManifestFile myManifest = new ManifestFile();
myManifest.ProvidedVariables = new List<ProvidedVariable>();
myManifest.ProvidedVariables.Add(new ProvidedVariable()
{
    DataType = "double",
    Rank = 0,
    VariableID = "mySPP"
});

var result = client.Inject(myManifest);//the client will maintain the mapping between the provided variable ID and the opc ua nodeID on the main server. 

client.UpdateProvidedVariables(new List<(string, object, DateTime)>() { ("mySPP", 1e5, DateTime.Now) });

Acquisition files

AcquisitionFile acquisitionFile = new AcquisitionFile();
AcquisitionItem acquisitionItem = new AcquisitionItem();
acquisitionItem.Name = "SPP";
acquisitionItem.Criterias.Add(new AcquisitionCriteria() { Classes = new List<string>() { Nouns.Measurement, Nouns.SPP }, CriteriaIndex = 0 });

acquisitionItem.Name = "SFT";
acquisitionItem.Criterias.Add(new AcquisitionCriteria() { Classes = new List<string>() { Nouns.Measurement, Nouns.SurfaceTorque }, CriteriaIndex = 0 });

var resolvedFile = client.Resolve(acquisitionFile);

string[] keys = { "SPP", "SFT" };

foreach (string key in keys)
{
    var results = resolvedFile.Resolutions.First(r => r.Name == key);

    foreach (var criteria in results.ITemResults)
    {
        Console.WriteLine($"Results for {key} criteria {criteria.Index}");
        foreach (var item in criteria.CriteriaResults)
        {
            Console.WriteLine($"Found a signal with ID {item.SignalID.ID} in the namespace with index {item.SignalID.NameSpaceIndex}");
        }
    }
}

You can also register an acquisition file to receive updates when new resolutions are available:

client.RegisterAcquisitionFile(acquisitionFile, Callback);

private void Callback(AcquisitionDiff acquisitionDiff)
{
    //manage your application's response here. 
    Console.WriteLine("Received new results for the acquisition file.");
}

Sparql queries

The client can be used to resolve sparql queries such as:

SELECT ?convA ?convB 
WHERE {			
        ?unit <http://ddhub.no/ConversionFactorA> ?convA .			
        ?unit <http://ddhub.no/ConversionFactorB> ?convB .		
 }

This query will return all the conversion factors of the units stored in the DDHub server. To get the result, just call the GetQueryResult method

string sparql;//write your sparql query in plain text here
var res = client.GetQueryResult(sparql);

You can also register a query to get notified when new solutions are found:

var res = client.RegisterQuery(sparql, Callback);

private void Callback(QueryResultsDiff resultsDiff)
{
    //manage your application's response here. 
    Console.WriteLine("Received new results for the query.");
}

Avanced

Query builder

The QueryBuilder class is a utility class to design SPARQL queries with a focus on the D-WIS vocabulary. Use the Build() method to generate the query. Special methods are included to specify that the query should return the signal or data point itself (or both), the units, or that the data point should be of a specific Noun.

The following code:

string sparql = new QueryBuilder()
    .SelectSignal()
    .SelectDataPoint()
    .AddMeasuredClass(DWIS.Vocabulary.Schemas.Nouns.HookLoad)
    .Build();

generates the following query:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX ddhub: <http://ddhub.no/>

SELECT ?signal ?dataPoint
WHERE {
                        ?dataPoint ddhub:HasDynamicValue ?signal .
                        ?dataPoint rdf:type ddhub:Measurement .
                        ?dataPoint rdf:type ddhub:HookLoad .
}

Acquired signals