In order to perform an operation like UA_Read, UA_Write, UA_ReadList, UA_WriteList or UA_MethodCall one has to prepare the communication following the sequence of calls as decribed hereunder, after which one has to stop the communication and clean up.
UA_Connect is used to create an (optional secure) transport connection of an OPC UA session. UA_Connect is to be performed once for each connection. The UA_NamespaceGetIndexList is to be performed once for each namespace. The NodeHdl for a specific node is to be retrieved once. Read and write can be performed as frequent as necessary and permitted by the system. Once the communication is done, the node handle is not required anymore and shall be released via the use of UA_NodeReleaseHandleList for all relevant handles. The connection handle shall be released using UA_Disconnect.
A list is handled as an array of the related base type (e.g. UANodeID or UANodeAdditionalInfo). Additionally, there is a length specified which holds the number of elements in the array. Although several arrays can be connected to the function block (e.g. node handles and variables in case of UA_ReadList) there is only one length because all arrays have the same number of elements to be processed.
The UA_NodeGetHandleList will return an UANodeHdl array. This call will not verify that the given UANodeID is valid. It will just be checked if it is structurally right (e.g. it’s not one by UAIdentifierType mentioned values) – otherwise an error in the corresponding error element (NodeErrorIDs) will be returned. The output array of UA_NodeGetHandleList can be used unchanged for subsequent calls to function blocks UA_ReadList, UA_WriteList, but the control implementation shall check always the corresponding error element (NodeErrorIDs). In case of any general error no outputs shall be changed from the underlying implementation.
The following function blocks are used to create subscriptions and to add monitored items to this subscription.
To create a subscription, a valid connection handle is required. The connection handle is to be acquired using UA_Connect once. UA_SubscriptionCreate will create a subscription, and needs to be called for every subscription needed. The applicable SubscriptionHdl will be returned on successful execution of the function block UA_SubscriptionCreate. In order to monitor an item, a NodeHdl for that specific node is required. In other words, both the applicable UA_SubscriptionCreate and UA_NodeGetHandleList are to be called before calling the related UA_MonitoredItemAddList. UA_MonitoredItemAddList is used to add items to a subscription identified by a SubscriptionHdl. The items to be monitored are to be assigned to this FB in form of NodeHdl. UA_MonitoredItemModifyList can be used to modify monitoring settings like sampling interval, deadband type, and deadband value and hence it can be called optionally.
Take note to delete the subscription. Release the NodeHdl before you disconnect. Unless UA_SubscriptionDelete is called the Subscription will continue working, even if UA_NodeReleaseHandleList is called.
Figure 3: Subscription and MonitoredItem sequence
Monitoring of nodes does invert the communication interaction: The control program is initiating the communication but as a consequence the values will be pushed from the OPC UA Server to the control program.
Like shown in the block diagram above, a subscription and monitored items have to be set up.
There are two modes to actually retrieve latest values within the control program:
- Controller-sync: Using the UA_MonitoredItemAddList function block with UAMonitoringSyncMode “UAMS_ControllerSync” – updated values shall be retrieved after the call UA_MonitoredItemOperateList is finished. This means the control program can decide when values are updated. If this block is not called no updates to the control program will be delivered. The currently specified handling of monitored items and subscriptions is based on linking one UA node (identified by NodeHdl) to one PLC variable (defined in the PLC program). By calling the function block UA_MonitoredItemOperateList values delivered from the UA server are transfered into the PLC variables.Please see more detailed explanations in vendor specific documentation in particular in cases of QueueSize > 1.
- FW-sync: The firmware could internally update the values of the memory of the controller.After adding monitored items, the control program might call UA_SubscriptionProcessed to know that any values have been changed, but it might be that the control program has no control about when updates are deployed to the control program memory.
In general, a QueueSize bigger than the PLC variable array size will return an error shown in the corresponding NodeErrorIDs in UA_MonitoredItemAddList directly after the call returns, an overflow (values lost) will be shown in the corresponding NodeQualityIDs and the minimum lost values will be shown in the corresponding MinLostValueCount.
The vendor has to decide which mode to provide. Vendor documentation should describe the selected behavior. Especially for the FW-sync way a detailed documentation should state when (i.e., beginning of control program cycle) updates are available to the control program.
A vendor may provide both modes (Controller-sync and FW-sync). The parameter QueueSize defined in structure UAMonitoringParameter indicates the mode: With configuration of QueueSize > 1 for the intention not to lose data changes it also becomes the user’s responsibility to fetch those values one at a time thus QueueSize is used to determine the mode of operation as follows:
- QueueSize > 0 with a sample queue of that size. If ‘0’ the QueueSize ‘1’ will be applied. This means for a monitored item both, locally and on the server side as many as QueueSize data changes can be stored. The server discards data changes if the publish interval is too large. The client discards data changes if the UA_MonitoredItemOperateList cycle is not sufficient. Discard oldest policy is implied.
The mode of operation is configured independently for each monitored item (input parameter SyncMode of FB UA_MonitoredItemAddList).
Note: For vendors who support both Controller- and FW-sync: If NodeHdls are registered to a subscription with Controller-sync and afterwards UA_SubscriptionProcessed FB for this subscription will be called will result in an error shown in the corresponding NodeErrorIDs and the UA_SubscriptionProcessed FB call will fail.
The appropriate sequence for initiating a method call is shown below. A valid method handle is necessary to call a method. Successful call of UA_MethodGetHandleList will deliver a valid MethodHdls.
One shall release the method handle list before you disconnect.
Figure 4: Method call sequence
This procedure is to check if the connection is still alive. The function block UA_Connect will deliver the ConnectionHdl. UA_ConnectionGetStatus requires this ConnectionHdl as input to deliver the connection status. In case the connection is lost after receiving the handle and while calling the UA_ConnectionGetStatus, ServerState Unknown will be returned.
NOTE: It is recommended to call UA_ConnectionGetStatus periodically but for performance reasons not in every control program cycle.
Figure 5: Connection diagnostics
Browsing is used by a client to navigate through the Address Space of an OPC UA Server. By passing a starting node the server returns a list of nodes by references.
To be able to browse a valid connection handle is required. Function block UA_Connect will deliver the ConnectionHdl. UA_Browse takes a structure for starting Node description and filter criteria. The result is an array of structures for references and target Nodes.
If the ContinuationPointOut output is connected to the ContinuationPointIn input of a consecutive UA_Browse instance, a browse next service can be performed.
This function block is used to request that the Server translates one or more UABrowsePaths to UANodeIDs. Each UA_BrowsePath is constructed of a starting UANodeID and a UARelativePath. The specified starting UANodeID identifies the UANodeID from which the UARelativePath is based. The UARelativePath contains a sequence of UARelativePathElement and UAQualifiedName.
One purpose of this function block is to allow programming against type definitions. Since UAQualifiedName shall be unique in the context of type definitions, a user program may create a UABrowsePath that is valid for a type definition and use this path on instances of the type. For example, an ObjectType “Boiler” may have a “HeatSensor” Variable as InstanceDeclaration. A graphical element programmed against the “Boiler” may need to display the Value of the “HeatSensor”. If the graphical element would be called on “Boiler1”, an instance of “Boiler”, it would need to call this Service specifying the UANodeID of “Boiler1” as starting UANodeID and the UABrowsePaths of the “HeatSensor” as browse path. The function block would return the UANodeID of the “HeatSensor” of “Boiler1” and the graphical element could subscribe to its value.
If an OPC UA Node has multiple targets with the same UABrowsePaths, the underlying server will return a list of UANodeIDs. However, since one of the main purposes of this function block is to support programming against type definitions, the UANodeID of the OPC UA Node based on the type definition of the starting OPC UA Node is returned as the first UANodeID in the list.
Figure 7: TranslatePath sequence
A typical OPC UA Server can be configured to fire Events to a Client. OPC UA specifies a wide range of different Events. OPC UA Clients can receive Events when subscribing to an Event Notifier.
In order to monitor an item, a NodeHdl for that specific node is required. Both UA_SubscriptionCreate and UA_NodeGetHandle are to be called before calling UA_EventItemAdd. UA_EventItemAdd is used to add an event item to a subscription mentioned by the SubscriptionHdl. The node of which events are monitored is to be assigned to this FB in form of NodeHdl. UA_EventItemOperate can be used to get information about the incoming events occurred.
Take note to delete the subscription. Release the NodeHdl before you disconnect. If UA_NodeReleaseHandle is called before UA_SubscriptionDelete the Subscription will continue working.
Figure 8: Monitor Events sequence