Endpoint

The Endpoint interface is responsible for communication with the AAS from the outside, e.g. users or external applications. An instance of FA³ST Service can serve multiple endpoints at the same time. Endpoints will be synchronized, meaning if a FA³ST Service offers multiple endpoint such as HTTP(S) and OPC UA at the same time, changes done via one of the endpoints like updating a value is reflected in the other.

The following is an example of the relevant part of the configuration part comprising both an HTTP(S) and OPC UA endpoint

Example configuration for running both an HTTP and OPC UA endpoint.

{
	"endpoints": [
		{
			"@class": "de.fraunhofer.iosb.ilt.faaast.service.endpoint.http.HttpEndpoint",
			"port": 443,
			"corsEnabled": true
		},
		{
			"@class": "de.fraunhofer.iosb.ilt.faaast.service.endpoint.opcua.OpcUaEndpoint",
			"tcpPort": 8081
		}
	],
	// ...
}

Generic Configuration

All endpoint implementations share the following common configuration properties.

Configuration properties of all Endpoint implementations.

Name	Allowed Value	Description	Default Value
profiles (optional)	List, allowed values: AAS_FULL AAS_READ AAS_REPOSITORY_FULL AAS_REPOSITORY_READ AASX_FILE_SERVER_FULL CONCEPT_DESCRIPTION_FULL DISCOVERY_FULL FAAAST_IMPORT FAAAST_RESET SUBMODEL_FULL SUBMODEL_READ SUBMODEL_VALUE SUBMODEL_REPOSITORY_FULL SUBMODEL_REPOSITORY_READ	The AAS Service Profiles that the endpoint should support.	(empty, meaning all profiles are supported)

HTTP

The HTTP Endpoint allows accessing data and execute operations within the FA³ST Service via REST-API. In accordance to the specification, only HTTPS is supported since AAS v3.0. The HTTP Endpoint is based on the document Details of the Asset Administration Shell - Part 2: Application Programming Interfaces v3.0 and the corresponding OpenAPI documentation v3.0.1.

Configuration

Configuration properties of HTTP Endpoint.

Name	Allowed Value	Description	Default Value
certificate (optional)	CertificateInfo	The HTTPS certificate to use.	self-signed certificate
corsAllowCredentials (optional)	Boolean	Sets the Access-Control-Allow-Credentials response header.	false
corsAllowedHeaders (optional)	String (comma-separated list)	Sets the Access-Control-Allow-Headers response header.	*
corsAllowedMethods (optional)	String (comma-separated list)	Sets the Access-Control-Allow-Methods response header.	GET, POST, HEAD
corsAllowedOrigin (optional)	String	Sets the Access-Control-Allow-Origin response header.	*
corsEnabled (optional)	Boolean	If Cross-Origin Resource Sharing (CORS) should be enabled. Typically required if you want to access the REST interface from any machine other than the one running FA³ST Service.	false
corsExposedHeaders (optional)	String (comma-separated list)	Sets the Access-Control-Expose-Headers response header.
corsMaxAge (optional)	Long	Sets the Access-Control-Max-Age response header.	3600
hostname (optional)	String	The hostname to be used for automatic registration with registry.	auto-detect (typically IP address)
includeErrorDetails (optional)	Boolean	If set, stack traceis added to the HTTP responses incase of error.	false
port (optional)	Integer	The port to use.	443
sniEnabled (optional)	Boolean	If Server Name Identification (SNI) should be enabled. This should only be disabled for testing purposes as it may present a security risk!	true
sslEnabled (optional)	Boolean	If SSL/HTTPS should be enabled. This should only be disabled for testing purposes as it may present a security risk!	true

Example configuration section for HTTP Endpoint.

{
	"endpoints": [ {
		"@class": "de.fraunhofer.iosb.ilt.faaast.service.endpoint.http.HttpEndpoint",
		"certificate": {
			"keyStoreType": "PKCS12",
			"keyStorePath": "C:\faaast\MyKeyStore.p12",
			"keyStorePassword": "changeit",
			"keyAlias": "server-key",
			"keyPassword": "changeit"
		},
		"corsAllowCredentials": false,
		"corsAllowedHeaders": "X-Custom-Header",
		"corsAllowedMethods": "GET, PUT, POST, PATCH, DELETE, HEAD",
		"corsAllowedOrigin": "localhost",
		"corsEnabled": true,
		"corsExposedHeaders": "X-Custom-Header",
		"corsMaxAge": 1000,
		"hostname": "localhost",
		"includeErrorDetails": true,
		"port": 443,
		"profiles": [ "AAS_REPOSITORY_FULL", "AAS_FULL", "SUBMODEL_REPOSITORY_FULL", "SUBMODEL_FULL" ],
		"sniEnabled": true,
		"sslEnabled": true
	} ],
	// ...
}

API

FA³ST Service supports the following APIs as defined by the OpenAPI documentation v3.0.1

• Asset Administration Shell API

• Submodel API

• Asset Administration Shell Repository API

• Submodel Repository API

• Concept Description API

• Asset Administration Shell Basic Discovery API

• Serialization API

• Description API

Additionally, FA³ST Service offers the following proprietary API calls:

HTTP Method	URL Path	Description	Payload	Response
GET	/reset	Resets the server which includes deleting all AASs, submodels, concept descriptions, files, asset connections, and pending operations.	-	204 No Content
POST	/import	Imports an AAS files in any supported data format. Set the Content-Type header accordingly so that the server can parse the document.	The file to upload.	200 Ok with body containing list of errors that happend during import.

Using HTTP PATCH

As the AAS specification is currently does not properly specify show HTTP PATCH requests are expected to work, FA³ST Service follows the well-established RFC 7386 JSON Merge Patch. In short, this means that as payload you can send a JSON document that only contains the properties of the original document you want to update. To delete elements set the value explicitely to null.

As a consequence, URLs for all different content modifiers, i.e. /$metadata, /$value, as well as the call without any modifiers, are redundant and provide exactly the same functionality in FA³ST Service.

Caution

Arrays in JSON objects can only be replaced, i.e. if you want to update a single element within an array you first need to get the current value of the array, modify the element to be updated and then send the whole array as part of the PATCH payload.

Invoking Operations

To invoke an operation, make a POST request according to this URL example: /submodels/{submodelId (base64-URL-encoded)}/submodel-elements/{idShortPath to operation}/invoke.

Tip

You can invoke operations asynchronuously by calling .../invoke-async instead of .../invoke in which case you get back a handleId instead of the result. To monitor the execution state call .../operation-status/{handleId} and once finished you can get the result calling .../operation-results/{handleId} or .../operation-results/{handleId}/$value for the ValueOnly serialization.

Depending on the in & inoutput arguments, the payload should look like this.

Example payload for invoking operations synchronously

{
	"inputArguments": [ {
		"value": {
			"modelType": "Property",
			"value": "4",
			"valueType": "xs:int",
			"idShort": "in"
		},
		// additional input arguments
	} ],
	"inoutputArguments": [ {
		"value": {
			"modelType": "Property",
			"value": "original value",
			"valueType": "xs:string",
			"idShort": "note"
		},
		// additional inoutput arguments
	} ],
	"clientTimeoutDuration": "PT10S"   // ISO8601 duration, here: 10 seconds
}

An easier, or at least less verbose way, of invoking operations is by using the ValueOnly serialization. For this, add /$value to the end of the URL, i.e. resulting in either .../invoke/$value or .../invoke-async/$value. The payload will be simplified and look similar to this

Example payload for invoking operations with ValueOnly

{
	"inputArguments": {
		"in": 4
	},
	"inoutputArguments": {
		"note": "original value"
	},
	"clientTimeoutDuration": "PT10S"
}

OPC UA

The OPC UA Endpoint allows accessing data and execute operations within the FA³ST Service via OPC UA.

Unfortunately, there is currently no official mapping of the AAS API to OPC UA for AAS v3.0. Nevertheless, FA³ST Service decided to still provide an OPC UA endpoint even though it is not (yet) standard-compliant. This implementation is based on the OPC UA Companion Specification OPC UA for Asset Administration Shell (AAS) which defines a mapping between AAS and OPC UA for AAS v2.0 enriched with some custom adjustments and extensions to be used with AAS v3.0.

The OPC UA Endpoint is built with the Prosys OPC UA SDK for Java which means in case you want to compile the OPC UA Endpoint yourself, you need a valid license for the SDK (which you can buy here. For evaluation purposes, you also have the possibility to request an evaluation license. However, this is not necessary for using the OPC UA Endpoint we already provide a pre-compiled version that is used by default when building FA³ST Service from code. The developers of the Prosys OPC UA SDK have been so kind to allow us to publish that pre-compiled version as part of this open-source project under the condition that all classes related to their SDK are obfuscated.

Configuration Parameters

OPC UA Endpoint configuration supports the following configuration parameters

Name	Allowed Value	Description	Default Value
discoveryServerUrl (optional)	String	URL of the discovery server. If empty, discovery server registration is disabled.
secondsTillShutdown (optional)	Integer	The number of seconds the server waits for clients to disconnect	2
serverCertificateBasePath (optional)	String	Path where the server application certificates are stored	PKI/CA
supportedAuthentications (optional)	Anonymous UserName Certificate	List of supported authentication types	Anonymous
supportedSecurityPolicies (optional)	NONE BASIC128RSA15 BASIC256 BASIC256SHA256 AES128_SHA256_RSAOAEP AES256_SHA256_RSAPSS	List of supported security policies	NONE, BASIC256SHA256, AES128_SHA256_RSAOAEP, AES256_SHA256_RSAPSS
tcpPort (optional)	Integer	The port to use for TCP	4840
userMap (optional)	Map<String, String>	A map containing usernames and password. If UserName is not included in supportedAuthentications, this property is ignored.	empty
userCertificateBasePath (optional)	String	Path where the certificates for user authentication are saved	USERS_PKI/CA

Certificate Management

The path provided with the serverCertificateBasePath configuration property stores the server and client application certificates and contains the following subdirectories

• /certs: trusted client certificates

• /crl: certificate revocation list for client certificates

• /issuers/certs: certificates of trusted CAs

• /issuers/crl: certificate revocation list for CA certificates

• /issuers/rejected: rejected CA certificates

• /private: certificates for the OPC UA server

• /rejected: unkown/rejected client certificates

To provision the OPC UA Endpoint to use an existing certificate for the server, save the certificate file as {serverCertificateBasePath}/private/Fraunhofer IOSB AAS OPC UA Server@{hostname}_2048.der and the private key as {serverCertificateBasePath}/private/Fraunhofer IOSB AAS OPC UA Server@{hostname}_2048.pem where {hostname} is the host name of your machine.

When an unkown client connects to the OPC UA Endpoint, the connection will be rejected and its client certificate will be stored in /rejected. To trust the certificate of a client and allow the connection, move the file to /certs.

The path provided with the userCertificateBasePath configuration property stores the user certificates and contains the following subdirectories

• /certs: trusted user certificates

• /crl: certificate revocation list for user certificates

• /issuers/certs: certificates of trusted CAs

• /issuers/crl: certificate revocation list for CA certificates

• /issuers/rejected: rejected CA certificates

• /rejected: unkown/rejected client certificates

Similar to the client certificates, unknown user certificates are stored in /rejected the first time a new certificate is encountered. To trust this certificate, simply move it to /certs.

and userCertificateBasePath point to directories where the corresponding certificates are stored. These directories contain the following subdirectories:

Example configuration for OPC UA Endpoint.

{
	"endpoints": [ {
			"@class": "de.fraunhofer.iosb.ilt.faaast.service.endpoint.opcua.OpcUaEndpoint",			
			"discoveryServerUrl" : "opc.tcp://localhost:4840",
			"profiles": [ "AAS_REPOSITORY_FULL", "AAS_FULL", "SUBMODEL_REPOSITORY_FULL", "SUBMODEL_FULL" ],
			"userMap" : {
			  "user1" : "secret"
			},
			"secondsTillShutdown" : 5,
			"serverCertificateBasePath" : "PKI/CA",
			"supportedSecurityPolicies" : [ "NONE", "BASIC256SHA256", "AES128_SHA256_RSAOAEP" ],
			"supportedAuthentications" : [ "Anonymous", "UserName" ]
			"tcpPort" : 18123,
			"userCertificateBasePath" : "USERS_PKI/CA",			
	} ],
	//...
}

OPC UA Client Libraries

To connect to the OPC UA Endpoint, you need an OPC UA Client. Here are some example libraries and tools you can use:

• Eclipse Milo: Open Source SDK for Java.

• Unified Automation UaExpert: Free OPC UA test client (registration on website required for download).

• Prosys OPC UA Browser: Free OPC UA test client (registration on website required for download).

• Official Samples from the OPC Foundation: C#-based sample code from the OPC Foundation.

Screenshot showing UaExpert connected to a FA³ST Service via OPC UA Endpoint.

Datatype mapping

It’s necessary to map the AAS datatypes to OPC UA datatypes. In some cases, no corresponding datatype is available in OPC UA. These datatypes are mapped to String.

The mapping is as follows

AAS datatype	OPC UA datatype	Comment
xs:string	String
xs:boolean	Boolean
xs:decimal	String
xs:integer	String
xs:double	Double	No distinction between +0.0 and -0.0
xs:float	Float	No distinction between +0.0 and -0.0
xs:date	String
xs:dateTime	DateTime	Converted to UTC, TZ offset is lost.
xs:time	String
xs:gYear	String
xs:gMonth	String
xs:gDay	String
xs:gYearMonth	String
xs:gMonthDay	String
xs:duration	String
xs:byte	SByte
xs:short	Int16
xs:int	Int32
xs:long	Int64
xs:unsignedByte	Byte
xs:unsignedShort	UInt16
xs:unsignedInt	UInt32
xs:unsignedLong	UInt64
xs:positiveInteger	String
xs:nonNegativeInteger	String
xs:negativeInteger	String
xs:nonPositiveInteger	String
xs:hexBinary	ByteString
xs:base64Binary	ByteString
xs:anyURI	String

API

As stated, there is currently no official mapping of the AAS API to OPC UA for AAS v3.0 but FA³ST Service implements its proprietary adaption of the mapping for AAS v2.0.

Supported Functionality

• Writing values for the following types

  • Property

  • Range

  • Blob

  • MultiLanguageProperty

  • ReferenceElement

  • RelationshipElement

  • Entity

• Operations (OPC UA method calls). Exception: Inoutput-Variables are not supported in OPC UA.

Not (yet) Supported Functionality

• Updating the model, i.e., adding new elements at runtime is not possible

• Writing values for the following types

  • DataSpecifications

  • Qualifier

  • Category

  • ModelingKind

• AASDataTypeDefXsd

  • Base64Binary

  • UnsignedInt

  • UnsignedLong

  • UnsignedShort

  • UnsignedByte