9 PubSub configuration model ToC Previous Next

9.1 Common configuration model ToC Previous Next

9.1.3 Types for the PublishSubscribe Object ToC Previous Next

9.1.3.1 Overview ToC

Figure 40 depicts the PublishSubscribeType and the components used to represent the PublishSubscribe Object.

readme_files/image043.png Figure 40 – PublishSubscribe Object Types overview

The PublishSubscribe Object is the root node for all PubSub related configuration Objects. It is an instance of the PublishSubscribeType and a component of the Server Object.

The PublishSubscribeType contains the entry point for PublishedDataSet configuration, the entry point for PubSub connections. In addition, it provides Methods for connection management.

9.1.3.2 PublishSubscribeType ToC Model

An instance of this ObjectType represents the root Object for all PubSub related configuration and metadata Objects. The one instance of this ObjectType that represents the root Object is defined in 8.3.2. The ObjectType is formally defined in Table 177.

Table 177 – PublishSubscribeType definition

Attribute Value        
BrowseName PublishSubscribeType        
IsAbstract False        
References Node Class BrowseName DataType TypeDefinition Modelling Rule
Subtype of PubSubKeyServiceType defined in 8.2.          
           
HasPubSubConnection Object <ConnectionName>   PubSubConnectionType OptionalPlaceholder
HasComponent Method SetSecurityKeys Defined in 9.1.3.3. Optional  
HasComponent Method AddConnection Defined in 9.1.3.4. Optional  
HasComponent Method RemoveConnection Defined in 9.1.3.5. Optional  
HasComponent Object PublishedDataSets   DataSetFolderType Mandatory
HasComponent Object SubscribedDataSets   SubscribedDataSetFolderType Optional
HasComponent Object PubSubConfiguration   PubSubConfigurationType Optional
HasComponent Object Status   PubSubStatusType Mandatory
HasComponent Object Diagnostics   PubSubDiagnosticsRootType Optional
HasComponent Object PubSubCapablities   PubSubCapabilitiesType Optional
HasComponent Object DataSetClasses   FolderType Optional
HasProperty Variable SupportedTransportProfiles String[] PropertyType Mandatory
HasProperty Variable DefaultDatagramPublisherId UInt64 PropertyType Optional
HasProperty Variable ConfigurationVersion VersionTime PropertyType Optional
Conformance Units          
PubSub Model Base          

The PublishSubscribeType ObjectType is a concrete type and can be used directly.

The configured connection Objects are added as components to the instance of the PublishSubscribeType. Connection Objects may be configured with product-specific configuration tools or added and removed through the Methods AddConnection and RemoveConnection. The PubSubConnectionType is defined in 9.1.5.2. The HasPubSubConnection ReferenceType is defined in 9.1.3.6.

The PublishedDataSets Object contains the configured PublishedDataSets. The DataSetFolderType is defined in 9.1.4.5.1. The DataSetFolderType can be used to build a tree of DataSetFolders.

The SubscribedDataSets Object contains the configured SubscribedDataSets. The SubscribedDataSetFolderType is defined in 9.1.9.4. The SubscribedDataSetFolderType can be used to build a tree of SubscribedDataSetFolders.

The PubSubConfiguration Object provides read and write access to the PubSub configuration through a PubSubConfigurationType with is a subtype of FileType. The read access is to the complete configuration. The write access allows add, modify and delete operations to the existing PubSub configuration. The PubSubConfigurationType and the related DataTypes are defined in 9.1.3.7.

The Status Object provides the current operational status of the PublishSubscribe functionality. The PubSubStatusType is defined in 9.1.10. The state machine for the status and the relation to other PubSub Objects like PubSubConnection, PubSubGroup, DataSetWriter and DataSetReader are defined in 6.2.1.

The Diagnostics Object provides the current diagnostic information for the PublishSubscribe Object. The PubSubDiagnosticsRootType is defined in 9.1.11.7.

The SupportedTransportProfiles Property provides a list of TransportProfileUris supported by the Server. The TransportProfileUris are defined in OPC 10000-7.

The default unique PublisherId for datagram transport protocols is provided through the Property DefaultDatagramPublisherId. Further details for the PublisherId are defined in 6.2.7.1.

The ConfigurationVersion represents the time of the last configuration change.

The PubSubCapabilities Objects provides the PubSub capablitiy information. The PubSubCapabilitiesType ObjectType is defined in 9.1.12.

The DataSetClasses Folder allows a Server to expose DataSetClasses supported. These DataSetClasses can be used to create PublishedDataSets. The Folder would also be used by standard information models to include standardized DataSetClasses into their namespace.

The DataSetClasses Folder references a list of Variables where the Value of a Variable represents a DataSetClass. For each Variable, the Name field of the BrowseName equals the Name in the DataSetMetaData. The Object is formally defined in Table 178.

Table 178 – DataSetClass Object definition

Attribute Value        
BrowseName DataSetClasses        
References Node Class BrowseName DataType TypeDefinition Modelling Rule
HasComponent Variable <DataSetName> DataSetMetaDataType BaseDataVariableType OptionalPlaceholder

9.1.3.3 SetSecurityKeys ToC

This Method is used to push the security keys for a SecurityGroup into a Publisher or Subscriber. It is used if Publisher or Subscriber have no OPC UA Client functionality.

Encryption is required for this Method. The Method shall return Bad_SecurityModeInsufficient if the communication is not encrypted.

The OPC UA Client calling this Method shall be the SKS application with the ApplicationUri that matches the ApplicationUri in the SecurityKeyServices parameter of the WriterGroup, ReaderGroup or DataSetReader objects using the SecurityGroupId.

Signature

SetSecurityKeys (
[in]	String 		SecurityGroupId,
[in]	String 		SecurityPolicyUri,
[in]	IntegerId 		CurrentTokenId,
[in]	ByteString 		CurrentKey,
[in]	ByteString[]	FutureKeys,
[in]	Duration 		TimeToNextKey,
[in]	Duration 		KeyLifetime
);

Argument Description
SecurityGroupId The identifier for the SecurityGroup.
SecurityPolicyUri The URI for the set of algorithms and key lengths used to secure the messages. The SecurityPolicies are defined in OPC 10000-7.
CurrentTokenId    The SecurityTokenId that appears in the header of messages secured with the CurrentKey. It starts at 1 and is incremented by 1 each time the KeyLifetime elapses even if no keys are requested. If the CurrentTokenId increments past the maximum value of UInt32 it restarts at 1.   If the PubSub Object has key material from previous SetSecurityKeys Method calls, the CurrentTokenId is used to match the existing list with the fetched list and to eliminate duplicates.If the CurrentTokenId is unknown, the existing list shall be discarded and replaced.
CurrentKey The current key used to secure the messages. This key is not used directly since the protocol associated with the PubSubGroup(s) specifies an algorithm to generate distinct keys for different types of cryptography operations.
FutureKeys An ordered list of future keys that are used when the KeyLifetime elapses. The SecurityTokenId associated with the first key in the list is 1 more than the CurrentTokenId. All following keys have a SecurityTokenId that is incremented by 1 for every key returned.
TimeToNextKey    The time, in milliseconds, before the CurrentKey is expected to expire.    If a Publisher uses this Method to get the keys from an SKS, the TimeToNextKey and KeyLifetime are used to calculate the time the Publisher shall use the next key. The TimeToNextKey defines the time when to switch from CurrentKey to FutureKeys and the KeyLifetime defines when to switch from one future key to the next future key.   For a Subscriber the TimeToNextKey and KeyLifetime are used to calculate the time the Subscriber expects that the Publishers use the next key. Due to network latency, out of order delivery and the use of keys for several Publishers, a Subscriber needs to expect some overlap time where NetworkMessages are received that are using the previous or the next key.TimeToNextKey   and KeyLifetime are also used to calculate the time until Publisher and Subscriber shall fetch new keys.
KeyLifetime    The lifetime of a key in milliseconds.   The returned keys may expire earlier if the keys are discarded for some reason. An unplanned key rotation is indicated in the NetworkMessage header before the next key is used to give the Subscriber some time to fetch new keys.If the CurrentTokenId in the message is not recognized, the receiver shall call this Method again to get new keys.

Method Result Codes

ResultCode Description
Bad_NotFound The SecurityGroupId is unknown.
Bad_UserAccessDenied The caller is not allowed to set the keys for the SecurityGroup.
Bad_SecurityModeInsufficient The communication channel is not using encryption.

9.1.3.4 AddConnection Method ToC

This Method is used to add a new PubSubConnection Object to the PublishSubscribe Object.

The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.

Signature

AddConnection (
[in]	PubSubConnectionDataType	Configuration,
[out]	NodeId				ConnectionId
);

Argument Description
Configuration Configuration parameters for the PubSubConnection. The parameters and the PubSubConnectionDataType are defined in 6.2.7.
ConnectionId The NodeId of the new connection.

Method Result Codes

ResultCode Description
Bad_InvalidArgument The Server is not able to apply the name. The name may be too long or may contain invalid characters.
Bad_BrowseNameDuplicated An Object with the name already exists.
Bad_ResourceUnavailable The Server has not enough resources to add the PubSubConnection Object.
Bad_UserAccessDenied The Session user is not allowed to create a PubSubConnection Object.

9.1.3.5 RemoveConnection Method ToC

This Method is used to remove a PubSubConnection Object from the PublishSubscribe Object.

A successful removal of the PubSubConnection Object removes all associated groups, DataSetWriter and DataSetReader Objects. Before the Objects are removed, their state is set to Disabled.

The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.

Signature

RemoveConnection (
[in]	NodeId	ConnectionId
);

Argument Description
ConnectionId NodeId   of the PubSubConnection Object to remove from the Server

Method Result Codes

ResultCode Description
Bad_NodeIdUnknown The ConnectionId is unknown.
Bad_UserAccessDenied The Session user is not allowed to delete the PubSubConnection Object.

9.1.3.6 HasPubSubConnection ToC Model

The HasPubSubConnection ReferenceType is a concrete ReferenceType that can be used directly. It is a subtype of the HasComponent ReferenceType.

The SourceNode of References of this type shall be the PublishSubscribe Object defined in 8.3.2.

The TargetNode of this ReferenceType shall be an Object of type PubSubConnectionType defined in 9.1.5.2.

Servers shall provide the inverse Reference that relates a PubSubConnection Object back to the PublishSubscribe Object.

The representation of the HasPubSubConnection ReferenceType in the AddressSpace is specified in Table 179.

Table 179 – HasPubSubConnection ReferenceType

Attributes Value    
BrowseName HasPubSubConnection    
InverseName PubSubConnectionOf    
Symmetric False    
IsAbstract False    
References NodeClass BrowseName Comment
Subtype of HasComponent defined in OPC 10000-5.      
Conformance Units      
PubSub Model Base      

9.1.3.7 Modification of PubSub configuration ToC Model

9.1.3.7.1 PubSubConfigurationType ToC Model

This ObjectType represents a FileType the can be used to access a PubSub configuration. The PubSubConfigurationType is formally defined in Table 180.

The PubSubConfigurationType file is a UA Binary encoded stream containing an instance of UABinaryFileDataType that contains a PubSubConfiguration2DataType or subtype as Body. The UABinaryFileDataType is defined in OPC 10000-5. The PubSubConfiguration2DataType is defined in 6.2.12.4.

The FileType functionality is used instead of passing the PubSubConfiguration2DataType to read and write Methods to overcome potential limitations of communication buffers for OPC UA Service calls. It is expected that the PubSubConfiguration2DataType is used internally in Client and Server and that the FileType is only used to be able to transfer large configurations.

The Open Method shall not support modes other than Read (0x01) and the Write + EraseExisting (0x06).

When a Client opens the file for writing the Server will not actually update the PubSub configuration until the CloseAndUpdate Method is called. Simply calling Close will discard the updates.

Table 180 – PubSubConfigurationType definition

Attribute Value
BrowseName PubSubConfigurationType
IsAbstract False

Subtype of FileType defined in OPC 10000-20.

References NodeClass BrowseName DataType TypeDefinition ModellingRule
HasComponent Method ReserveIds Defined in 9.1.3.7.5. Mandatory  
HasComponent Method CloseAndUpdate Defined in 9.1.3.7.6. Mandatory  
           
Conformance Units          
PubSub Model Base          

9.1.3.7.2 PubSubConfigurationRefMask ToC

This OptionSet defines flags indicating the PubSubConfigurationRefDataType options. The value of the mask is null, if none of the bits is set.

The PubSubConfigurationRefDataType is used to reference a configuration element in a PubSubConfiguration2DataType structure. The PubSubConfigurationRefDataType indicates the element type referenced and defines the operation to be executed for the referenced configuration element. The possible element operations are ElementAdd, ElementMatch, ElementModify and ElementRemove.

Only one of the reference bits shall be set. If more than one of these bits are set, the operation shall fail.

The PubSubConfigurationRefMask values are formally defined in Table 181.

Table 181 – PubSubConfigurationRefMask values

Value Bit No. Description
ElementAdd 0    If this bit is set, the referenced elements is added to the PubSub configuration.   If the name of the element is null or empty a name is assigned.   If PublisherId, WriterGroupId or DataSetWriterId are null, unique IDs are assigned.If this bit is set, the ElementModify and ElementRemove bits shall be false. If more than one of these bits are set, the operation shall fail.
ElementMatch 1    If this bit is set, the Id and name shall be null and a matching element is searched. This is used to add children to an existing parent configuration object. This flag can be combined with the ElementAdd flag to either use an existing element or to add the element if it does not exist.   Match shall only be applied for ReferenceConnection, ReferenceWriterGroup and ReferenceReaderGroup. For all other references the match shall fail with Bad_InvalidArgument.   For the PubSubConnectionDataType, the following structure fields are used for the match, the others are ignored.   * TransportProfileUri   * Address   * TransportSettings   For the WriterGroupDataType, the following structure fields are used for the match, the others are ignored.   * SecurityMode   * SecurityGroupId   * SecurityKeyServices   * MaxNetworkMessageSize   * PublishingInterval   * KeepAliveTime   * Priority   * HeaderLayoutUri   * TransportSettings   * MessageSettings   For the ReaderGroupDataType, the following structure fields are used for the match, the others are ignored.   * SecurityMode   * SecurityGroupId   * SecurityKeyServices   * MaxNetworkMessageSize   * TransportSettings   * MessageSettingsFor the ConnectionProperties and GroupProperties only the entries are compared for the match that are provided in the element to match. Additional properties contained in the existing configuration are ignored.
ElementModify 2 If this bit is set, the referenced element will be modified. The related element in the current PubSub configuration is referenced with matching the name of the elements. If no matching name is found, the element operation shall fail.
ElementRemove 3 If this bit is set, the referenced element will be removed. The related element in the current PubSub configuration is referenced with matching the name of the elements. If no matching name is found, the element operation shall fail.
ReferenceWriter 4 The element operation is applied to the referenced DataSetWriter.
ReferenceReader 5 The element operation is applied to the referenced DataSetReader.
ReferenceWriterGroup 6 The element operation is applied to the referenced WriterGroup.
ReferenceReaderGroup 7 The element operation is applied to the referenced ReaderGroup.
ReferenceConnection 8 The element operation is applied to the referenced PubSubConnection.
ReferencePubDataset 9 The element operation is applied to the referenced PublishedDataSet.
ReferenceSubDataset 10 The element operation is applied to the referenced SubscribedDataSet.
ReferenceSecurityGroup 11    The element operation is applied to the referenced SecurityGroup.The access to the security groups may require different user credentials than access to the communication configuration elements.
ReferencePushTarget 12    The element operation is applied to the referenced PubSubKeyServerPushTarget.The access to the push target configuration may require different user credentials than access to the communication configuration elements.

The PubSubConfigurationRefMask representation in the AddressSpace is formally defined in Table 182.

Table 182 – PubSubConfigurationRefMask definition

Attribute Value
BrowseName PubSubConfigurationRefMask
IsAbstract False

Subtype of the UInt32 type defined in OPC 10000-5.

References NodeClass BrowseName DataType TypeDefinition ModellingRule
0:HasProperty Variable OptionSetValues LocalizedText[] PropertyType  
ConformanceUnits          
PubSub Model Base          

9.1.3.7.3 PubSubConfigurationRefDataType ToC Model

The PubSubConfigurationRefDataType allows to reference an element contained in the PubSubConfiguration2DataType Structure.

The PubSubConfigurationRefDataType is formally defined in Table 183.

Table 183 – PubSubConfigurationRefDataType structure

Name Type Description
PubSubConfigurationRefDataType Structure  
ConfigurationMask PubSubConfigurationRefMask Specifies the add, match, modify or remove element operation and the type of configuration element that is referenced.
ElementIndex UInt16    Specifies the index into the DataSetWriters, DataSetReaders, PublishedDataSets, SubscribedDataSets, SecurityGroups or PubSubKeyPushTargets array of the PubSubConfiguration depending on the bits ReferenceWriter, ReferenceReader, ReferencePubDataset, ReferenceSubDataset, ReferenceSecurityGroup or ReferencePushTarget.If this index is not used for referencing, it shall be set to 0.
ConnectionIndex UInt16    Specifies the index within the Connections array of the PubSubConfiguration if the connection, group, reader or writer bits is set.   If ReferenceConnection is true, the add, modify or remove element operation is applied. If ReferenceConnection is false, the name of the connection is used to identify the matching connection in the current PubSub configuration.If this index is not used for referencing, it shall be set to 0.
GroupIndex UInt16    If the ReferenceReaderGroup and/or ReferenceReader bits are true, it speficies the index within the ReaderGroups array of the related connection.   If ReferenceReaderGroup is true, the add, modify or remove element operation is applied. If ReferenceReaderGroup is false, the name of the ReaderGroup is used to identify the matching group in the current PubSub configuration.   If the ReferenceWriterGroup and/or ReferenceWriter bits are true, it specifies the index within the WriterGroups array of the related connection.   If ReferenceWriterGroup is true, the add, modify or delete bit is applied. If ReferenceReaderGroup is false, the name of the ReaderGroup is used to identify the matching group in the current PubSub configuration.If this index is not used for referencing, it shall be set to 0.

The PubSubConfigurationRefDataType representation in the AddressSpace is formally defined in Table 184.

Table 184 – PubSubConfigurationRefDataType definition

Attribute Value
BrowseName PubSubConfigurationRefDataType
IsAbstract False

Subtype of Structure defined in OPC 10000-5.

References NodeClass BrowseName DataType TypeDefinition ModellingRule
ConformanceUnits          
PubSub Model Base          

9.1.3.7.4 PubSubConfigurationValueDataType ToC Model

The PubSubConfigurationValueDataType allows to indicate specific values contained in PubSubConfiguration elements.

The PubSubConfigurationValueDataType is formally defined in Table 185.

Table 185 – PubSubConfigurationValueDataType structure

Name Type Description
PubSubConfigurationValueDataType Structure  
ConfigurationElement PubSubConfigurationRefDataType Refers to a configuration element in the related PubSubConfiguration2DataType Structure.
Name String The name of the referenced PubSub configuration element.
Identifier BaseDataType    The identifier value used for the referenced element in the PubSub NetworkMessages.   The value is only provided if the element is a PubSubConneciton, WriterGroup or DataSetWriter. The value is null otherwise.   If ConfigurationElement references a PubSubConnection, Identifier will contain the value of the PublisherId.   If ConfigurationElement references a WriterGroup, Identifier will contain the value of the WriterGroupId.If ConfigurationElement references a DataSetWriter, Identifier will contain the value of the DataSetWriterId.

The PubSubConfigurationValueDataType representation in the AddressSpace is formally defined in Table 186.

Table 186 – PubSubConfigurationValueDataType definition

Attribute Value
BrowseName PubSubConfigurationValueDataType
IsAbstract False

Subtype of Structure defined in OPC 10000-5.

References NodeClass BrowseName DataType TypeDefinition ModellingRule
ConformanceUnits          
PubSub Model Base          

9.1.3.7.5 ReserveIds Method ToC

This Method reserves unique WriterGroupIds and DataSetWriterIds to allow PubSub configuration applications to apply unique Ids to new PubSub configuration elements when preparing a update to the PubSub configuration.

The ID shall be returned from the range 0x8000 - 0xFFFF for internal assignment. The Server shall ensure that the IDs returned are not used in the current PubSub configuration or are not reserved yet.

When a Client reserves IDs, these reservations are valid while the Session is open. The reserved IDs can only be used for configuration modifications through the same Session. The reservation is only valid until the ID is used in the configuration or until the Session is closed. The IDs can be re-used if a PubSub component that uses the ID is deleted.

The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.

Signature

ReserveIds (
[in]	String		TransportProfileUri,
[in]	UInt16		NumReqWriterGroupIds,
[in]	UInt16		NumReqDataSetWriterIds,
[out]	BaseDataType	DefaultPublisherId,
[out]	UInt16[]		WriterGroupIds,
[out]	UInt16[]		DataSetWriterIds
);

Argument Description
TransportProfileUri Transport protocol and message mapping profile scope for the ID request.
NumReqWriterGroupIds The number of requested Ids for WriterGroups.
NumReqDataSetWriterIds The number of requested Ids for DataSetWriters.
DefaultPublisherId The default PublisherId of the Server for the requested TransportProfileUri.
WriterGroupIds The reserved Ids for WriterGroups for the requested TransportProfileUri.
DataSetWriterIds The reserved Ids for DataSetWriters for the requested TransportProfileUri

Method Result Codes

ResultCode Description
Bad_UserAccessDenied The Session user is not allowed to modify the PubSub configuration.

9.1.3.7.6 CloseAndUpdate Method ToC

This Method closes the file and applies the changes to the PubSub configuration as defined in the ConfigurationReferences argument. It can only be called if the file was opened for writing. If the Close Method is called any cached data is discarded and the PubSub configuration is not changed.

The file content shall be a UABinaryFileDataType with a PubSubConfiguration2DataType as Body. The ConfigurationReferences argument specifies the configuration elements to add, modify or delete. Configuration elements in PubSubConfiguration2DataType that are not referenced by ConfigurationReferences may be used indirectly as parent elements for referencing. In this case only the name of the element is relevant and all other fields of the element are ignored. Configuration elements in PubSubConfiguration2DataType not referenced and not used as parent elements are ignored. The top-level Enable field in the PubSubConfiguration2DataType is ignored.

The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.

Signature

CloseAndUpdate (
[in]	UInt32					FileHandle,
[in]	Boolean					RequireCompleteUpdate,
[in]	PubSubConfigurationRefDataType[]	ConfigurationReferences,
[out]	Boolean					ChangesApplied,
[out]	StatusCode[]				ReferencesResults,
[out]	PubSubConfigurationValueDataType[]ConfigurationValues,
[out]	NodeId[]					ConfigurationObjects
);

Argument Description
FileHandle The handle of the previously opened file.
RequireCompleteUpdate If true, the modification is only applied if the all changes can be applied to all objects.
ConfigurationReferences References to the PubSub configuration elements in the written file that should be added, modified or removed.
ChangesApplied    If true, one or more changes were applied. If RequireCompleteUpdate was set to false, the ReferencesResults argument indicates if referenced configuration elements failed.If false, no changes were applied. The detailed errors are provided in the ReferencesResults argument.
ReferencesResults Results of the add, modify, match or remove operation for the referenced element. The length and order of the array shall match the ConfigurationReferences array.
ConfigurationValues The assigned names and identifiers for the elements where empty names or null identifiers where provided in the elements. The values are only provided for elements with the bits ElementAdd or ElementMatch set and where a name and identifier was assigned.
ConfigurationObjects    NodeIds of the related Objects to referenced    If NodeIds are returned, the length and order of the array shall match the ConfigurationReferences array.If the Server does not support the creation of NodeIds, the array is null or empty.

Method Result Codes

ResultCode Description
Bad_TypeMismatch The file content is not a UABinaryFileDataType with a PubSubConfiguration2DataType as Body.
Bad_InvalidArgument The file handle is not valid.
Bad_InvalidState The file was not opened for writer access.
Bad_UserAccessDenied The Session user is not allowed to modify the PubSub configuration.

Element Result Codes

ResultCode Description
Bad_BrowseNameDuplicated An element with the name already exists. The element cannot be added.
Bad_NoMatch An element with the name does not exist or there is no element with matching parameters. The element cannot be matched, modified or removed.
Bad_NotFound One of the parent elements does not exist or was not added or matched. The element cannot be processed.
Bad_InvalidArgument The element reference is invalid or has invalid index entries.
Bad_UserAccessDenied The user has not the rights to access the element.

Previous Next