OPC UA Specification - Amendment

OPC 10001-3

 

OPC Unified Architecture

Amendment 3: Method Metadata

 

 

Release 1.04

November 6, 2018

 

 

 

 

 

 

 


 

Specification Type:

Industry Standard Specification

Comments:

Report or view errata: http://www.opcfoundation.org/errata

 

 

 

 

Document
Number

10001-3

 

 

Title:

OPC Unified Architecture

Amendment 3: Method Metadata

Date:

November 6, 2018

 

 

 

 

Version:

Release 1.04

Software:

MS-Word

 

 

Source:

OPC 10001-3 - UA Specification 1.04 Amendment 3 - Method Metadata.docx

 

 

 

 

Author:

OPC Foundation

Status:

Release

 

 

 

 


 

 

OPC Foundation

____________

 

UNIFIED ARCHITECTURE –

FOREWORD

This specification is the specification for developers of OPC UA applications. The specification is a result of an analysis and design process to develop a standard interface to facilitate the development of applications by multiple vendors that shall inter-operate seamlessly together.

Copyright © 2006-2018, OPC Foundation, Inc.

AGREEMENT OF USE

COPYRIGHT RESTRICTIONS

Any unauthorized use of this specification may violate copyright laws, trademark laws, and communications regulations and statutes. This document contains information which is protected by copyright. All Rights Reserved. No part of this work covered by copyright herein may be reproduced or used in any form or by any means--graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems--without permission of the copyright owner.

OPC Foundation members and non-members are prohibited from copying and redistributing this specification. All copies must be obtained on an individual basis, directly from the OPC Foundation Web site https://opcfoundation.org/.

PATENTS

The attention of adopters is directed to the possibility that compliance with or adoption of OPC specifications may require use of an invention covered by patent rights. OPC shall not be responsible for identifying patents for which a license may be required by any OPC specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. OPC specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents.

WARRANTY AND LIABILITY DISCLAIMERS

WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OPC FOUDATION MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OPC FOUNDATION BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

The entire risk as to the quality and performance of software developed using this specification is borne by you.

RESTRICTED RIGHTS LEGEND

This Specification is provided with Restricted Rights. Use, duplication or disclosure by the U.S. government is subject to restrictions as set forth in (a) this Agreement pursuant to DFARs 227.7202-3(a); (b) subparagraph (c)(1)(i) of the Rights in Technical Data and Computer Software clause at DFARs 252.227-7013; or (c) the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 subdivision (c)(1) and (2), as applicable. Contractor / manufacturer are the OPC Foundation,. 16101 N. 82nd Street, Suite 3B, Scottsdale, AZ, 85260-1830

COMPLIANCE

The OPC Foundation shall at all times be the sole entity that may authorize developers, suppliers and sellers of hardware and software to use certification marks, trademarks or other special designations to indicate compliance with these materials. Products developed using this specification may claim compliance or conformance with this specification if and only if the software satisfactorily meets the certification requirements set by the OPC Foundation. Products that do not meet these requirements may claim only that the product was based on this specification and must not claim compliance or conformance with this specification.

Trademarks

Most computer and software brand names have trademarks or registered trademarks. The individual trademarks have not been listed here.

GENERAL PROVISIONS

Should any provision of this Agreement be held to be void, invalid, unenforceable or illegal by a court, the validity and enforceability of the other provisions shall not be affected thereby.

This Agreement shall be governed by and construed under the laws of the State of Minnesota, excluding its choice or law rules.

This Agreement embodies the entire understanding between the parties with respect to, and supersedes any prior understanding or agreement (oral or written) relating to, this specification.

ISSUE REPORTING

The OPC Foundation strives to maintain the highest quality standards for its published specifications, hence they undergo constant review and refinement. Readers are encouraged to report any issues and view any existing errata here: HTUhttp://www.opcfoundation.org/errataUTH

 


Revision 1.04 Amendment 3 Highlights

The following table includes the Mantis issues resolved by this Amendment.

Mantis ID

Summary

Resolution

2765

Support for optional method arguments or default parameters

Added HasArgumentDescription reference types to allow optional Metadata which can be used to identify optional arguments and default parameter values

3792

Support for additional information about method arguments

Added HasArgumentDescription reference types to allow optional additional Metadata to be included in the model

4175

ModelingRule for InputArguments, OutputArguments and Method Metadata

Added statements defining the use of Mandatory ModellingRule in Table 15

 

 


OPC Unified Architecture Specification

 

Amendment 3: Method Metadata

 

OPC 10000-3, OPC Unified Architecture - Part 3: Address Space Model

Replace 5.7 with the following:

5.7       Methods

5.7.1    Method NodeClass

Methods define callable functions. Methods are invoked using the Call Service defined in Part 4. Method invocations are not represented in the AddressSpace. Method invocations always run to completion and always return responses when complete. Methods are defined using the Method NodeClass, specified in Table 15.

Table 15 – Method NodeClass

Name

Use

Data Type

Description

Attributes

 

 

 

    Base NodeClass Attributes

M

--

Inherited from the Base NodeClass. See Clause 5.2.

    Executable

M

Boolean

The Executable Attribute indicates if the Method is currently executable (“False” means not executable, “True” means executable).

The Executable Attribute does not take any user access rights into account, i.e. although the Method is executable this may be restricted to a certain user / user group.

    UserExecutable

M

Boolean

The UserExecutable Attribute indicates if the Method is currently executable taking user access rights into account (“False” means not executable, “True” means executable).

References

 

 

 

    HasProperty

0..*

 

HasProperty References identify the Properties for the Method.

    HasModellingRule

0..1

 

Methods can point to at most one ModellingRule Object using a HasModellingRule Reference (see Clause 6.4.4 for details on ModellingRules).

    GeneratesEvent

0..*

 

GeneratesEvent References identify the type of Events that will be generated whenever the Method is called.

    AlwaysGeneratesEvent

0..*

 

AlwaysGeneratesEvent References identify the type of Events that shall be generated whenever the Method is called.

    HasArgumentDescription

0..*

 

The HasArgumentDescription References are used to specify argument Metadata. If the SourceNode of this Reference is defined on an InstanceDeclaration the TargetNode shall use the Mandatory ModellingRule.

    <other References>

0..*

 

Methods may contain other References.

Standard Properties

 

 

 

    NodeVersion

O

String

The NodeVersion Property is used to indicate the version of a Node.

The NodeVersion Property is updated each time a Reference is added or deleted to the Node the Property belongs to. Attribute value changes do not cause the NodeVersion to change. Clients may read the NodeVersion Property or subscribe to it to determine when the structure of a Node has changed.

    InputArguments

O

Argument[]

The InputArguments Property is used to specify the arguments that shall be used by a client when calling the Method. If this Property is defined on an InstanceDeclaration it shall use the Mandatory ModellingRule.

    OutputArguments

O

Argument[]

The OutputArguments Property specifies the result returned from the Method call. If this Property is defined on an InstanceDeclaration it shall use the Mandatory ModellingRule.

 

The Method NodeClass inherits the base Attributes from the Base NodeClass defined in Clause 5.2. The Method NodeClass defines no additional Attributes.

The Executable Attribute indicates whether the Method is executable, not taking user access rights into account. If the OPC UA Server cannot get the Executable information from the underlying system, it should state that it is executable. If a Method is called then the Server should transfer this request and return the corresponding StatusCode even if such a request is rejected. StatusCodes are defined in Part 4.

The UserExecutable Attribute indicates whether the Method is executable, taking user access rights into account. If the OPC UA Server cannot get any user rights related information from the underlying system, it should use the same value as used in the Executable Attribute. The UserExecutable Attribute can be set to “False”, even if the Executable Attribute is set to “True”, but it shall be set to “False” if the Executable Attribute is set to “False”. Clients cannot assume a Method can be executed based on the UserExecutable Attribute. It is possible that the Server may return an access denied error due to some Server specific change which was not reflected in the state of this Attribute at the time the Client accessed it.

Properties may be defined for Methods using HasProperty References. The Properties InputArguments and OutputArguments specify the input arguments and output arguments of the Method. Both contain an array of the DataType Argument as specified in 8.6. An empty array or a Property that is not provided indicates that there are no input arguments or output arguments for the Method.

The Property NodeVersion indicates the version of the Method. There are no additional Properties defined for Methods in this document. Additional parts of this series of standards may define additional Properties for Methods.

To specify its ModellingRule, a Method can use at most one HasModellingRule Reference pointing to a ModellingRule Object. ModellingRules are defined in Clause 6.4.4.

GeneratesEvent References identify that Methods may generate an Event of the specified EventType or one of its subtypes for every call of the Method. A Server may generate one Event for each referenced EventType when a Method is successfully called.

AlwaysGeneratesEvent References identify that Methods will generate an Event of the specified EventType or one of its subtypes for every call of the Method. A Server shall always generate one Event for each referenced EventType when a Method is successfully called.

Servers should make GeneratesEvent References bidirectional References. However, it is allowed to be unidirectional when the Server is not able to expose the inverse direction pointing from the EventType to each Method generating the EventType.

GeneratesEvent References are optional, i.e. the call of a Method may produce Events of an EventType that is not referenced with a GeneratesEvent Reference by the Method.

Methods may use additional References to define relationships to other Nodes. No restrictions are placed on the types of References used or on the NodeClasses of the Nodes that may be referenced. However, restrictions may be defined by the ReferenceType excluding its use for Methods. Standard ReferenceTypes are described in Clause 7.

A Method shall always be the TargetNode of at least one HasComponent Reference. The SourceNode of these HasComponent References shall be an Object or an ObjectType. If a Method is called then the NodeId of one of those Nodes shall be put into the Call Service defined in Part 4 as parameter to detect the context of the Method operation.

If the Method is used as InstanceDeclaration (see Clause 4.5) all Nodes referenced with forward hierarchical References shall have unique BrowseNames in the context of this Method.

The Variable referenced by a HasArgumentDescription ReferenceType shall use a BrowseName equal to the name of the Argument it describes. The NameSpace of the BrowseName shall be ignored by a Client when performing an equality check with an Argument name. For each Argument there shall be at most one Variable referenced by a HasArgumentDescription ReferenceType. The Variable referenced by the HasArgumentDescription ReferenceType shall have the same DataType as the Argument’s DataType.

Argument names shall be unique within the scope of the Method.

An example use of the HasArgumentDescription Reference is illustrated in Figure  8A. In this example an ObjectType defines a Method which illustrates the following:

·      Output1 as a discrete output argument with a HasArgumentDescription Reference to a TwoStateDescreteType Variable which provides descriptions of the states of the output argument.

·      Input1 as a numeric input argument with a HasArgumentDescription Reference to a DataVariable Variable which provides the default value 42.

·      Input2 as a numeric input argument with a HasArgumentDescription Reference to an AnalogItemType Variable which provides an engineering units range of 0 kPa to 100 kPa.

·      Input3 as an optional discrete input argument with a HasOptionalInputArgumentDescription Reference to a TwoStateDescreteType Variable which provides descriptions of the states of the input argument and a default value of true.

·      Object1 as an instance of MyObjectType with an instance specific HasArgumentDescription Reference to an instance specific AnalogItemType Variable which provides an instance specific engineering range of 0 kPa to 200 kPa and a default value of 75 kPa for the Input2 argument.

Figure 8A [RSA1] – Method Metadata Example

5.7.2    HasArgumentDescription ReferenceType

The HasArgumentDescription ReferenceType is a concrete ReferenceType that is a subtype of the HasComponent ReferenceType.

The semantic of the HasArgumentDescription ReferenceType – extends the semantic of the HasComponent ReferenceType to reference argument Metadata of a Method NodeClass.

The SourceNode of this ReferenceType shall be a Method and the TargetNode of this ReferenceType shall be a Variable.

5.7.3    HasOptionalInputArgumentDescription ReferenceType

The HasOptionalInputArgumentDescription ReferenceType is a concrete ReferenceType that can be used directly. It is a subtype of the HasArgumentDescription ReferenceType.

The semantic of the HasOptionalInputArgumentDescription ReferenceType – extends the semantic of the HasArgumentDescription ReferenceType to reference optional input arguments of a Method NodeClass. Optional input arguments shall always follow any non-optional input arguments in the InputArguments array. For example, if a method has 3 arguments with 1 being optional then the 3rd argument shall be the optional one.

There are no additional constraints defined for this ReferenceType.

OPC 10000-4, OPC Unified Architecture - Part 4: Services

Replace Clause 5.11.2.2 with the following:

5.11.2.2    Parameters

Table 65 defines the parameters for the Service.

Table – 65 Call Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    methodsToCall []

CallMethodRequest

List of Methods to call. This structure is defined in-line with the following indented items.

        objectId

NodeId

The NodeId shall be that of the Object or ObjectType on which the Method is invoked.

In case of an ObjectType the ObjectType or a super type of the ObjectType shall be the source of a HasComponent Reference (or subtype of HasComponent Reference) to the Method specified in methodId.

In case of an Object the Object or the ObjectType of the Object or a super type of that ObjectType shall be the source of a HasComponent Reference (or subtype of HasComponent Reference) to the Method specified in methodId.

See Part 3 for a description of Objects and their Methods.

        methodId

NodeId

NodeId of the Method to invoke.

If the objectId is the NodeId of an Object, it is allowed to use the NodeId of a Method that is the target of a HasComponent Reference from the ObjectType of the Object.

        inputArguments []

BaseDataType

List of input argument values. An empty list indicates that there are no input arguments. The size and order of this list matches the size and order of the input arguments defined by the input InputArguments Property of the Method.

The name, a description and the data type of each argument are defined by the Argument structure in each element of the method’s InputArguments Property.

If a Method has optional input arguments, these optional input arguments are indicated by the Method’s DefaultInputValues Property. In this case fewer arguments than the total number of input arguments defined may be passed by the Client. The InputArguments and DefaultInputValues Property are defined in Part 3.

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

CallMethodResult

Result for the Method calls. This structure is defined in-line with the following indented items.

        statusCode

StatusCode

StatusCode of the Method executed in the server. This StatusCode is set to the Bad_InvalidArgument StatusCode if at least one input argument broke a constraint (e.g. wrong data type, value out of range).

This StatusCode is set to a bad StatusCode if the Method execution failed in the server, e.g. based on an exception.

        inputArgumentResults []

StatusCode

List of StatusCodes corresponding to the inputArguments.

This list is empty unless the operation level result is Bad_InvalidArgument.

If this list is populated, it has the same length as the inputArguments list.

        inputArgumentDiagnosticInfos []

DiagnosticInfo

List of diagnostic information corresponding to the inputArguments. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

        outputArguments []

BaseDataType

List of output argument values. An empty list indicates that there are no output arguments. The size and order of this list matches the size and order of the output arguments defined by the OutputArguments Property of the Method.

The name, a description and the data type of each argument are defined by the Argument structure in each element of the methods OutputArguments Property.

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the statusCode of the results. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

OPC 10000-5, OPC Unified Architecture - Part 5: Information Model

Replace Clause 11.7 with the following:

11.7     HasComponent

This standard ReferenceType is defined in Part 3. Its representation in the AddressSpace is specified in Table 104.

Table 104 – HasComponent ReferenceType

Attributes

Value

BrowseName

HasComponent

InverseName

ComponentOf

Symmetric

False

IsAbstract

False

References

NodeClass

BrowseName

Comment

HasSubtype

ReferenceType

HasOrderedComponent

Defined in 11.8

HasSubtype

ReferenceType

HasArgumentDescription

Defined in 11.18

 

Add the following as Clause 11.18:

11.18   HasArgumentDescription

This standard ReferenceType is defined in Part 3. Its representation in the AddressSpace is specified in Table 114A.

Table 114A – HasArgumentDescription ReferenceType

Attributes

Value

BrowseName

HasArgumentDescription

InverseName

ArgumentDescriptionOf

Symmetric

False

IsAbstract

False

References

NodeClass

BrowseName

Comment

HasSubtype

ReferenceType

HasOptionalInputArgumentDescription

Defined in 11.19

 

Add the following as Clause 11.19:

11.19   HasOptionalInputArgumentDescription

This standard ReferenceType is defined in Part 3. Its representation in the AddressSpace is specified in Table 114B.

Table 114B – HasOptionalInputArgumentDescription ReferenceType

Attributes

Value

BrowseName

HasOptionalInputArgumentDescription

InverseName

OptionalInputArgumentDescriptionOf

Symmetric

False

IsAbstract

False

References

NodeClass

BrowseName

Comment

 

 

 

 

 

OPC 10000-7, OPC Unified Architecture - Part 7: Profiles

 

Add the following ConformanceUnits to section 5.2, Table 8 “Method Services”: 

Category 

Title 

Description 

Client 

Method Client Call with Optional Arguments

Use the Call Service to call one or several Methods having optional input arguments.

 

 

Add the following ConformanceUnits to section 5.4, Table 14 “Address Space Model”: 

Category 

Title 

Description 

Server 

Address Space Method Meta Data

Support Method Nodes that include meta data to describe the arguments using HasArgumentDescription References.

 

Add the following ConformanceUnits to section 6.6.39, Table 61 “Method Server Facet”: 

Group 

Conformance Unit / Profile Title 

Optional 

Address Space Model

Address Space Method Meta Data

True 

 

Add the following ConformanceUnits to section 6.6.109, Table 131 “Method Client Facet”: 

Group 

Conformance Unit / Profile Title 

Optional 

Method Services

Method Client Call with Optional Arguments

True 

 


 [RSA1]Needed a SEQ field