Create a new OPC UA Client worksheet

Create and configure an OPC UA Client worksheet to associate project tags with OPC server items.

Before you begin this task, you must have created at least one OPC UA server connection that the client worksheet can use. For more information, see Create a new OPC UA connection.

You should also be familiar with how to edit worksheets in the project development environment.

Tip: You can create multiple worksheets and then configure them to have different settings, so you do not need to make any single worksheet unnecessarily large or complicated.

OPC UA Client Refresh Watchdog Timer

There is an optional watchdog setting feature for the OPC UA client. If this feature is enabled, it will force a reload (unsubscribe and resubscribe) of an OPC UA Client worksheet if none of the group of tags in that worksheet receives an update from the OPC UA server within a timeout period. Each worksheet and its group of tags are evaluated independently, and one worksheet reloading has no effect on another worksheet.

This optional watchdog setting is disabled by default, but it can be enabled by adding the CheckGroupsWatchdog parameter to the project APP file, which is found in the project folder (<project folder>\<project>.app). Add the CheckGroupsWatchdog parameter to the APP file [OPC] group and specify the number of milliseconds in the timeout period. Here is an example with a timeout period of one minute (60,000 milliseconds). Setting the number of milliseconds to 0 disables the watchdog timer.

[OPC]

CheckGroupsWatchdog=60000

Note: This timeout applies to all OPC UA Client worksheets, so the value should be greater than the greatest Publish rate on any of the OPC UA Client worksheets (see Step 5, below). If the Publish rate for an OPC UA Client worksheet is greater than the CheckGroupsWatchdog value, that worksheet will reload before the tags in that group can receive new data. It is a recommended practice to set the CheckGroupsWatchdog value at least ten times higher than the Publish rate. For example, if the highest Publish rate of all OPC UA Client worksheets is 10,000 milliseconds, set the CheckGroupsWatchdog value no lower than 100,000 milliseconds.

To configure a new OPC UA Client worksheet:

1. Do one of the following:

   • On the Insert tab of the ribbon, in the Communication group, click OPC Client, and then select OPC UA Client from the drop-down list; or

   • In the Comm tab of the Project Explorer, right-click the OPC UA folder, and then on the shortcut menu, click Insert.

   A new OPC UA Client worksheet is displayed.

   

2. In the Description box, type a description of the worksheet.

   This is for documentation purposes only and does not affect the execution of the worksheet.

3. In the Connection list, select the connection or redundancy group that you created earlier.

4. In the Status box, type the name of a project tag (Integer type) that will receive connection status codes during project run time, and then in the Status Message box, type the name of a project tag (String type) that will receive the corresponding status messages.

5. In the Publish Rate box, type the frequency (in milliseconds) at which the client will request updates from the server.

6. In the Disable box, type a tag/expression.

   While this tag/expression evaluates as TRUE (non-zero), the worksheet will not be executed and it will not use the specified connection. If any other OPC UA Client worksheets share the same connection, however, the connection will remain open and active unless those worksheets are also disabled.

7. In the Root node or view box, specify a server node that will serve as the root for all browse paths in the worksheet body.

   Specifying a root node makes it easier to find items and improves runtime performance.

8. For each project tag that you want to associate with an OPC server item/node, complete a row in the worksheet body:

   1. In the Tag Name field, type the name of a project tag.

   2. In the Browse Path field, do one of the following: type the full path of the server item; or right-click in this field, and then on the shortcut menu, click Browse in order to browse the server's list of items.

      Note: If you have selected the Enable bit notation option in the advanced settings, you can select a specific bit of a server node value by appending the bit number to the item name, for example <node path>.<bit>. This is supported only for unsigned variables and 32-bit signed variables; if you try to do it with 16-bit or 8-bit signed variables, the most significant bit (MSB) will not work properly.

   3. In the Scan field, select either Always to have the row continuously scanned (that is, processed) during project run time or Screen to have the row scanned only when a project screen that uses the specified tag is open.

   4. In the Div field, type a number to be used for scaling during project run time. This is optional.

      When a value is read from the server, it is divided by this number. When a value is written to the server, it is multiplied by this number.

   5. In the Add field, type a number to be used for scaling during project run time. This is optional.

      When a value is read from the server, this number is added to it. When a value is written to the server, this number is subtracted from it.

   6. In the Node Id field, a node ID is automatically generated from the browse path.

      The node ID is the actual value that your project will use to subscribe to the item during run time. If your project runtime log contains errors indicating that

      This field accepts String expressions, for example {MyNodeId}. If you do, enable the Accept tag name in the Node Id column option and specify a Reload trigger in the Advanced settings.

   Both tag expansion and array distribution are enabled by default for all OPC UA Client worksheets. You can disable tag expansion for this worksheet by clearing the Enable Tag Expansion option in the advanced settings. You cannot disable array distribution.

9. When you are done, save and close the worksheet.

   The worksheet is saved in the OPC UA folder in the Project Explorer.

In order for your OPC UA Client worksheet(s) to be scanned during project run time, the OPC UA Client Runtime task in your project must be started. As such, the first time you configure and save a worksheet, the task's startup mode is set to Automatic. This is done for your convenience, and it means that when you run your project, the task will be started and the worksheet(s) will be scanned. You can set the task's startup mode back to Manual, however, if you want more control over how your project runs. For more information, see Runtime Tasks.

The worksheet is continuously scanned during project run time, so that the configured project tags and server items are updated as needed. Also, the project tags that you specified for the Status and Status Message settings in the worksheet header will receive the following possible values:

Tip: As long as the client is communicating normally with the server, the read/write status codes and messages (as configured in the advanced settings) will provide more information about each operation.

In certain situations, if the worksheet does not behave as expected during project run time — and especially if you see OPC communication errors in the runtime log — you might need to adjust the worksheet's advanced settings: in the worksheet header, click Advanced, and then in the Advanced dialog box, review and configure the settings.

Read actions

Advanced settings that control how values are read from the OPC UA server.

Enable subscription

While this value is TRUE (non-zero), the client will subscribe to the server nodes so that it can receive notifications when the node values change.

This setting has a default value of 1, which indicates it is always enabled. If it is disabled, or if you type a tag/expression that will cause it to be disabled during project run time, you might need to use read triggers instead (see below).

Maximum group size

The maximum number of server nodes that may be read in a single read operation.

For example, if you have 1000 items/rows configured in the worksheet and Maximum group size is set to 100, 10 read operations will be performed when a read is triggered.

Synchronous read trigger

When the value of this tag/expression changes, the client reads all of the node values from the server. The read operation is performed synchronously, which means all other client operations are blocked until the read operation is finished. When the read operation is finished, the client increments the tag configured in Read count.

Asynchronous read trigger

The same as Synchronous read trigger except that the read operation is performed asynchronously, which means that other client operations may continue while the read operation is being performed.

Read count

The name of a project tag (Integer type) that will receive a count of the number of read operations performed since the project was run.

Status

The name of a project tag (Integer type) that will receive a status code for the last read operation performed by a trigger. If the status code is 0, the read operation finished successfully. For all other status codes, see List of read/write status codes and messages for OPC UA.

Status message

The name of a project tag (String type) that will receive the corresponding status message.

Maximum aging

The maximum age (in milliseconds) of values that will be accepted from the server's cache. If a value is older than this, the server will be forced to get the latest value from the field device.

Sampling rate

When this option is selected, you can change the rate (in milliseconds) at which the OPC server reads from field devices. By default, the sampling rate is half the publishing rate.

Queue size

This is the requested size of the OPC UA specification MonitoredItem queue. The default value is 1, which returns the minimum queue size the OPC UA Server requires for Event Notifications as revisedQueueSize for data monitored items. A value of 0 returns the default queue size for Event Notifications as revisedQueueSize. Other integer values are possible; for more information, see the OPC Foundation documentation (https://reference.opcfoundation.org/).

Write actions

Advanced settings that control how values are written to the OPC UA server.

Enable write on tag change

While this value is TRUE (non-zero), an asynchronous write operation will be performed automatically whenever the value of a project tag changes. All tag changes that occurred since the last scan of the worksheet will be written in a single write operation, or in multiple write operations if the number of tag changes exceeds the maximum group size.

This setting has a default value of 1, which indicates it is always enabled. If it is disabled, or if you type a tag/expression that will cause it to be disabled during project run time, you might need to use write triggers instead (see below).

Maximum group size

The maximum number of tag changes that may be written in a single write operation.

For example, if you have 1000 items/rows configured in the worksheet and Maximum group size is set to 100, 10 write operations will be performed during each scan of the worksheet.

Synchronous write trigger

When the value of this tag/expression changes, the client writes all of the tag values to the server. The write operation is performed synchronously, which means all other client operations are blocked until the write operation is finished. When the write operation is finished, the client increments the tag configured in Write count.

Asynchronous write trigger

The same as Synchronous write trigger except that the write operation is performed asynchronously, which means that other client operations may continue while the write operation is being performed.

Write count

The name of a project tag (Integer type) that will receive a count of the number of write operations performed since the project was run.

Status

The name of a project tag (Integer type) that will receive a status code for the last write operation performed by a trigger. If the status code is 0, the write operation finished successfully. For all other status codes, see List of read/write status codes and messages for OPC UA.

Status message

The name of a project tag (String type) that will receive the corresponding status message.

Other

Other settings that control how this worksheet communicates with the OPC UA server.

Reload trigger

The name of a project tag (Boolean, Integer, or Real type) that can be used as a trigger. When the value of this tag changes, the worksheet is reloaded. String expressions configured in the body of the worksheet are reevaluated only when the worksheet is reloaded. After the worksheet is reloaded, the value of this tag will be reset to 0.

Refresh IDs on startup

When this option is selected, the node IDs in the worksheet will be automatically refreshed from the specified browse paths every time the project is run. This might resolve any node IDs that are missing or invalid.

Refreshing IDs like this can cause the project to take longer to run, however, so if you select this option, you should also specify a root node (that is, in the Root node or view box in the worksheet header) to restrict the list of server items that must scanned.

The OPC server software might not support this option, depending on how it has implemented the OPC standard. For more information, see the documentation for that software.

Ensure cache synchronization

When this option is selected, the client will wait after each write operation for confirmation from the server that the node values actually changed. If the client does not receive confirmation, it will restore the previous tag values.

Enable bit notation

When this option is selected, bit notation is allowed in the Item column of the worksheet body.

Accept tag name in the Node Id column

When this option is selected, you can type string expressions in the Node Id column of the worksheet, but if you do, make sure you have also configured the Reload trigger setting (see above).

Enable Tag Expansion

When this option is selected, tag expansion is enabled for this worksheet. You can disable it for this worksheet without affecting any other OPC client worksheets, and you may choose to do so if you want more control over how OPC server items are associated with your project tags.

Note: This software does not normally use the Triggering Mode that is defined the OPC standard. Instead, it allows any change in any tag/expression to be used as a trigger. If you want to use Triggering Mode, configure one worksheet to read the trigger values, and then configure another worksheet that specifies the read values as triggers.