The OPC UA Binding for WoT provides a standard guideline on how to design a WoT TD to describe an OPC UA interface. The example below illustrates a basic TD instance outlining an interface of an OPC UA Server, which provides access to a single datapoint (UA Variable) pumpSpeed.
This example shows a minimal version of metadata that would be enough that a client can initiate a connection to an OPC UA server (opc.tcp://opcuademo.com:4840), selects a preferred security mode that the OPC UA server offers (auto_sc), and is able to execute a read or monitor service of the pumpSpeed datapoint via the provided NodeId in href (nsu=http://example.nsu.com/demo/pump;s=PumpSpeed).
As an alternative a Thing Description can provide additional semantic metadata as specified in the specification to give a richer context of information. The following example extends the previous TD with potential terms:
The @context includes all namespaces that are used in the Thing Description. The http://opcfoundation.org/UA/WoT-Binding/ namespace points to the OPC UA WoT Binding ontology and http://example.namespace.com/demo/pump to an application class that is used in the OPC UA server. Terms such as uav:browseName specify the origin browse name (1:Pump and 1:PumpSpeed) of a corresponding UA Object marked with uav:object or of a UA Attribute marked with uav:variable in the Thing Description @type. The uav:browsePath provides the origin browse path in the OPC UA tree to the UA Variable that is associated with this property.
The following BNF format shows the structure of an URI of the OPC UA Client / Server protocol that have to be followed in a WoT Thing Description:
opc.tcp://<address>:<port>[/<resourcePath>]/?id=<nodeId>
Where is:
- {address} OPC UA server endpoint (IP) address
- {port} OPC UA server port number
- {resourcePath} If used by the OPC UA server, an added resource path at the endpoint address.
- {nodeId} OPC UA nodeId which should apply the following requirements: To prevent conflicts with reserved characters and to allow for deconstruction as specified by RFC 3986, two specific characters in the nodeId must be percent-encoded when used
If this URI is extracted from the Thing Description and is transmitted (e.g., via a network), all non-ASCII characters must first be encoded into bytes using the UTF-8 character encoding, and then each resulting byte must be percent-encoded in accordance with RFC 3986.
Note that the URL can be used as a whole in href within a forms definition or divided into the global base term (for sever location only) and href term (relative to the base that provides only the nodeId information).
Examples:
- "href": "/?id=nsu=http://example.nsu.com/demo/pump;s=PumpSpeed"
- "href":"/?id=nsu=http://example.com/hello%23;s=temperature"
- "href":"opc.tcp://192.168.120.237:4840/?id=nsu=http://widgets.com/schemas/hello;s=水 World"
If the namespace is resolved in the @context (see 6.5.5), its index value can be used in the nodeId:
- "href":"/?id=ns=10;i=12345"
- "href":"opc.tcp://192.168.120.237:4840/UA/Factory/?id=ns=10;i=12345"
- "href":"opc.tcp://192.168.120.237:4840/?id=ns=10;i=12345"
The standard definitions of the WoT Thing Description specification can be used to implicitly specify the endpoint security settings supported by the OPC UA server. Alternatively, an OPC UA specific scheme can be used to exchange explicit security knowledge.
Can be used when the OPC UA server only supports one endpoint that is set up without security options (securityMode=None, securityPolicy=None). Typical use cases include demo setups of an OPC UA server or an OPC UA server that provides public and read-only UA attributes, e.g., for monitoring purposes for a dashboard.
In that case WoT Thing Description should specify the NoSecurityScheme by the vocabulary term nosec (i.e., "scheme": "nosec").
Recommended to be used to show implicit knowledge that a OPC UA server supports multiple endpoints with different configuration for the security mode (e.g., None, Sign, or SignAndEncrypt), security policy (e.g., Basic256Sha256, Aes256_Sha256_RsaPss), and supported user identity tokens (e.g., Anonymous, UserName, Certificate).
This reflects the default use case of an OPC UA Client-Server interaction during the OPC UA Session Establishment phase. The client must execute the OPC UA GetEndpoints service in order to select the desired (secured) endpoint to open the session with the OPC UA server. To indicate this, in the WoT Thing Description, the AutoSecurityScheme should be used with the term auto (i.e., "scheme": "auto").
Please note that login credentials such as passwords or certificates are not shared in WoT Thing Descriptions and must be provided separately, e.g., through a separate credential store or by an explicit prompt to the client to enter the credentials for the session.
Recommended to be used to show explicit knowledge in the WoT Thing Description that a OPC UA server supports one or multiple endpoints with different security configuration settings.
This reflects the use case where an OPC UA server specifies which security option(s) should be used by specific client(s) via the WoT Thing Description.
To indicate this, in the WoT Thing Description, you should use OPCUASecurityChannelScheme by using the term uav:channelsec (i.e., "scheme": "uav:channelsec") and OPCUASecurityAuthenticationScheme by using the term uav: authentication (i.e., "scheme": "uav:authentication"). The ComboSecurityScheme from the WoT Thing Description 1.1 specification should be used to combine the schemes with allOf.
OPCUASecurityChannelScheme vocabulary terms:
|
Vocabulary term |
Description |
Assignment |
Type |
|
uav:securityMode |
Provides information about which modes are available from the supported endpoints of the OPC UA server:
|
required |
string |
|
uav:securityPolicy |
Provides information about which policy options are available from the supported endpoints of the OPC UA server:
Outdated (not recommended policies):
|
required |
string |
OPCUASecurityAuthenticationScheme vocabulary terms:
|
Vocabulary term |
Description |
Assignment |
Type |
|
uav:userIdentityToken |
Provides information about which policy options are available from the supported endpoints of the OPC UA server:
Similar for the AutoSecurityScheme, the login credentials such as user name and passwords or certificates are not shared in WoT Thing Descriptions and must be provided separately, e.g., through a separate credential store or by an explicit prompt to the client to enter the credentials for the session.
In the case of IssuedToken there may additional security schemes defined in the WoT Thing Description to describe an external authorization service such as OAuth2 (OAuth2SecurityScheme). To declare the combination of such a specific scheme with the OPCUASecurityScheme, the ComboSecurityScheme can be used with the term allOff (see WoT Thing Description 1.1 specification for more details). |
required |
String |
|
uav:issueToken |
Express a reference to a security scheme definition within the WoT Thing Description which should be applied to (e.g., OAuth2). |
optional |
String |
Examples:
Example usage of OPCUASecurityScheme in combination with an external OAuth2 authorization service:
Note that the terms of the OAuth2 and combo schemes are defined in the W3C WoT Thing Description 1.1 specifications.
To specify that a UA variable is readable (CurrentRead) in the TD, the term op must be assigned the value readproperty (as array entry). If the UA Variable is read only (you cannot write), the corresponding readOnly term of the DataSchema class in the TD should be set to true.
Since a readable UA Variable can be also subscribed by a Client, the term op must be supplemented by the value observeproperty and the observable term of the PropertyAffordance class in the TD should be set to true.
To specify that a UA variable is writable (CurrentWrite) in the TD, the op term must be assigned the value writeproperty (or has it as array entry). If the UA Variable is write only (you cannot read), the corresponding writeOnly term of the DataSchema class in the TD should be set to true.
The presented additional terms for the WoT Thing Description of this Companion Specification is identified by the following URI:
http://opcfoundation.org/UA/WoT-Binding/
In this specification, the prefix uav is used and associated to this namespace.
|
|
|
|
|
||||
|
Vocabulary term |
Description |
Assignment |
Type |
||||
|
uav:id |
NodeId value as defined in OPC 10000-6: UA Part 6: Mappings (5.1.12 QualifiedName, NodeId and ExpandedNodeId String Encoding). |
required |
string |
||||
The OPC UA binding does not need mandatory UA specific forms terms, the default forms terms from WoT Thing Description can be reused. Associated NodeId information for an interaction affordance (properties or actions) are reflected by the corresponding href as specified in 6.2..
The UA services are expressed by the TD op term and its corresponding values. In the following, the op values will correspond the following OPC UA Services:
|
readproperty |
UA Service Read |
|
writeproperty |
UA Service Write |
|
observeproperty |
UA Service Monitor |
|
invokeaction |
UA Service Call |
If the default serialization of the OPC UA server is used, the contentType should be assigned with the value "application/octet-stream".
Optional, following term can be used within the WoT TD forms container:
|
Vocabulary term |
Description |
Assignment |
Type |
|
uav:browsePath |
Provides information about the path of a UA node as string, following the guideline of OPC UA Part 4 (v104) in Chapter A.2, starting from the root node of an OPC UA address space. E.g., "/Root/Object/1:Machine/1:Pressure" |
optional |
String |
The following table gives an overview of the additional terms that can be used within a WoT Thing Description.
|
Vocabulary term |
Description |
Assignment |
Type |
|
uav:object |
Semantic annotation for @type of the TD root level to express that this TD instance represent a UA Object from the top level. |
optional |
- |
|
uav:objectType |
Semantic annotation for @type at root level to express that this instance represent a UA ObjectType (in TD context, this is called Thing Model (TM))Note: This annotation is only applicable in a Thing Model definition. |
optional |
- |
|
uav:variable |
Semantic annotation for @type of a TD property to associate a UA Variable. |
optional |
- |
|
uav:variableType |
Semantic annotation for @type of a Thing Model property to associate a UA Variable Type.Note: This annotation is only applicable in a Thing Model definition. |
optional |
- |
|
uav:method |
Semantic annotation for @type of a TD action to associate a UA Method. |
optional |
- |
|
uav:hasComponent |
Term to express there is one or more has-child relationship. The value entry is a nodeId of the child node. Note: uav:hasComponent is equivalent to <Reference ReferenceType="HasComponent" IsForward="true"> |
optional |
Array of String |
|
uav:componentOf |
Term to express there is one or more is-child-of relationship. The value entry is a nodeId of the parent node. Note: uav:componentOf is equivalent to <Reference ReferenceType="HasComponent" IsForward="false"> |
optional |
Array of String |
|
uav:browseName |
Provides the origin browse name of the UA node. The uav:browseName can be used at the top level to provide the browse name of the UA Object or UA ObjectType, and within the property or action level to give the browse name of the UA variable or UA method respectively. |
optional |
String |
|
uav:mapToNodeId |
This term can be used within a property definition to express that the associated runtime datapoint can be mapped to a (external) target OPC UA node (e.g. UA variable) with the corresponding NodeId.This term can be not used at the forms level. See Section 8.2 for example usage. |
optional |
string |
|
uav:mapToType |
This term can be used within a property definition to express that the associated runtime datapoint can be mapped to a (external) target OPC UA type with the corresponding NodeId.This term can be not used at the forms level. See Section 8.2 for example usage. |
optional |
string |
|
uav:mapByFieldPath |
This term can be only used with the uav:mapToType term. In the case that the target type of uav:mapToType is complex (e.g. based on BaseType 0:Structure), a specific field name can be addressed within this complex type definition to which the runtime data can be mapped to. See Section 8.2 for example usage. |
optional |
string |
Typically, OPC UA server uses namespaces from the OCP UA core, Companion Specifications and application specific namespaces. If it should be evident in the TD that different namepaces are used (e.g., visible by the uav:browseName or uav:browsePath terms), then these should be specified in the @context of the TD. The associated namespace index id should be associated as prefix value in the TD.
Example:
Lets assume there are namespaces used in a OPC UA server as described in the following nodeset:
If the Thing Description (TD) utilizes definitions from these namespaces, they should be specified within the TD @context with the corresponding namespace index as a prefix, as illustrated here:
