Configure an OPC UA Client worksheet

Use the OPC UA Client task/worksheet to communicate with any system that implements the OPC UA server standard for data access.

About OPC UA

The OPC UA Client task/worksheet uses the new OPC Unified Architecture standard introduced by the OPC Foundation. According to the foundation:
The existing OPC COM based specifications have served the OPC Community well over the past 10 years, but as technology moves on so must our interoperability standards. Here are the factors that influenced the decision to create a new architecture:
  • Microsoft has deemphasized COM in favor of cross-platform capable Web Services and SOA (Service Oriented Architecture)
  • OPC Vendors want a single set of services to expose the OPC data models (DA, A&E, HDA …)
  • OPC Vendors want to implement OPC on non-Microsoft systems, including embedded devices
  • Other collaborating organizations need a reliable, efficient way to move higher level structured data

In other words, OPC UA is intended to be a platform- and language-independent standard. For more information, go to http://www.opcfoundation.org/UA/.

Note: This feature includes cryptographic software written by Eric Young (eay@cryptsoft.com).

Configure a new OPC UA connection

To configure a new connection to an OPC UA server:
  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 Connection from the drop-down list; or
    • In the Comm tab of the Project Explorer, right-click OPC UA Connections, and then click Insert on the shortcut menu.
    The Server Configuration dialog box is displayed:
    Figure 1. Server Configuration dialog box
    Web Studio Help dialog opcua serverconfiguration OPC UA Client

  2. In the Connection Name box, type a name for the connection.

    This name will be displayed in the OPC UA Connections folder in the Project Explorer, and it is the name you will look for when you configure the OPC UA Client worksheet.

  3. In the End point box, type the URL of the OPC UA server to which you want to connect.
    Note: At this time, OPC UA in InduSoft Web Studio only supports end points using OPC.TCP (e.g., opc.tcp://host:8000/server). HTTP and HTTPS are not supported.
    If you do not know the URL, click the browse button to the right of the box. The UA Discovery dialog box is displayed:
    Figure 2. Discovery dialog box
    Web Studio Help dialog opcua discovery OPC UA Client

    Use this dialog box to find the discovery server, which publishes a list of OPC UA servers on the network, and then select the server to which you want to connect.

  4. In the User Name and Password boxes, type your login credentials for the OPC UA server.

    You may leave these boxes empty if you want to connect to the server anonymously and you are authorized to do so.

  5. If the OPC UA server is configured to require secure communication (also called a “SecureChannel” in the OPC UA specification), you must take extra steps to exchange certificates between that server and the OPC UA Client task in InduSoft Web Studio. IWS uses a file-based certificate store, which means that the certificates are saved as files in your project folder rather than as entries in a database or system registry.
    The steps to exchange certificates and configure the security settings differ somewhat depending on whether you are using self-signed certificates or certificates signed by a trusted Certificate Authority (CA):

    For more information, see “Certificate Management” in the document OPC Unified Architecture Specification, Part 2: Security Model. You can download the document from the OPC Foundation website (www.opcfoundation.org).

  6. In certain situations, you may need to tune the server connection by adjusting the various timeouts. To do so, click Advanced to open the following dialog box:
    Figure 3. Advanced dialog box
    Web Studio Help dialog opcua advanced OPC UA Client

    Review the settings and configure as needed:
    Session
    Session Timeout
    The session timeout (in milliseconds) for the server connection. If a session times out from inactivity, a new session must be started to resume communication.
    SecureChannel Lifetime
    The time (in milliseconds) after which the SecureChannel between the client and server is automatically renewed.

    For more information about the SecureChannel Services, please consult the OPC UA specification.

    Watchdog Time
    The time (in milliseconds) between watchdog checks.
    Watchdog Timeout
    The timeout (in milliseconds) for a specific watchdog check.
    Server Calls
    First Read Max Age
    The maximum acceptable age (in seconds) of item values when the client connects to the server and requests the values for the first time. If the age of a value in the server’s cache is less than the maximum age, the server will return that cached value to the client. In contrast, if the age of the value is greater than the maximum age, the server will refresh it from the field before returning it to the client.
    Besides an actual age in seconds, this box can accept two special values:
    Value Description
    -1 Set the maximum age to be equal to the maximum possible value of an integer, which is 2147483647 seconds or approxiamtely 68 years. This has the practical effect of accepting all cached values regardless of age.
    -2 Ignore the first read altogether and wait until the server normally refreshes the item values. Please note that the client cannot write to the server until it has read.
    Call Timeout
    The timeout (in milliseconds) for individual server calls.
    Verify time synchronization
    When this option is selected, the time stamp on each value received from the server is compared against the system time on the client, and if the difference between the times is equal to the specified number of hours (i.e., the number of time zones between the server and client), the server and client are deemed to be synchronized and the value is accepted. Otherwise, if the difference is not equal to the specified number of hours, the value is rejected and communication is interrupted.

    The default number of hours is 25, which is a special setting that means the hours portion of the time stamp should be disregarded and only the minutes and seconds should be compared. This enables the client to receive values from the server without knowing the server’s time zone.

    When this option is cleared, the time stamp on each value received from the server is ignored and the client’s system time is used instead to save the value in the project database.

    Browse
    Max nodes per call
    When browsing for a server item (see below), the maximum number of items/nodes to be returned per server call.
    Check item type
    When browsing for a server item (see below), check the item’s data type. In some situations, the OPC UA server may not be able to get data types from field devices, and that may cause browsing to become slow and unusable. If that happens, clear this option.
  7. Click OK. The connection is saved in the OPC UA Connections folder in the Project Explorer.

Configure a new OPC UA Client worksheet

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 OPC UA, and then click Insert on the shortcut menu.
    A new OPC UA Client worksheet is displayed:
    Figure 4. OPC UA Client worksheet
    Web Studio Help worksheet comm opcua OPC UA Client

  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 server connection that you configured earlier.
  4. For more connection options, click Advanced.
    The Advanced dialog box is displayed.
    Figure 5. Advanced dialog box
    Web Studio Help worksheet comm opcua advanced OPC UA Client

    Review the settings and configure as needed:
    Read actions
    Enable subscription
    When 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.
    Note: This is enabled by default. If it is disabled, you must use read triggers (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.
    Write actions
    Enable write on tag change
    When 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 occured 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.
    Note: This is enabled by default. If it is disabled, you must use write triggers (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.
    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. Tags in curly brackets (e.g., {tagname}) configured in the body of the worksheet are refreshed 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 refreshed from the specified paths every time the project is run.
    Note: Refreshing IDs like this may cause the project to take longer to start up, so if you select this option, you should also specify a root node (see below) to limit how much of the server’s list of items must scanned.
    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.
    Note: IWS‘s OPC client does not normally use the Triggering Mode that is defined the OPC protocol. 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.
  5. Click OK to close the Advanced dialog box and return to the worksheet.
  6. In the Status box, type the name of a project tag (Integer type) that will receive connection status codes during project runtime.
  7. In the Status Message box, type the name of a project tag (String type) that will receive the corresponding status messages.
  8. In the Publish Rate box, type the frequency (in milliseconds) at which the client will request updates from the server.
  9. In the Disable box, type a tag/expression. When the value is TRUE (non-zero), the worksheet will not be executed.
  10. In the Root node or view box, specify the server node that will serve as the root for all items in the worksheet body. Specifying a root node makes it easier to find items and improves runtime performance.
  11. For each row of the worksheet body, specify the following:
    • Tag Name: The name of a project tag.

      You may use tags in curly brackets (e.g., {tagname}), but if you do, make sure to configure the Reload trigger option above.

    • Item: The server item with which the project tag should be associated.

      To browse the server’s list of items, right-click in this field, and then click Browse on the shortcut menu.

      Note: If Enable bit notation is selected in the advanced settings, you can select a specific bit of a server node value by appending the bit number to the item name (e.g., nodepath.bit). Please note that 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.
    • Scan: If Always, the row is continuously scanned during runtime. If Screen, the row is scanned only when a project screen that uses the specified tag is open.
    • Div: For scaling — the value is divided by this number when reading from the server, and it is multiplied by this number when writing to the server.
    • Add: For scaling — this number is added to the value when reading from the server, and it is subtracted from the value when writing to the server.
    • Node ID: The node ID is automatically generated from the full path of the server item.
    Note:

    If the OPC server item is a single-dimension array, you can associate it with an array tag in IWS using a single worksheet row, without array indices. The elements of the OPC server item will be associated automatically, one-for-one, with the elements of the array tag.

    Please note that this capability only supports reading from the OPC server item.

  12. Save and close the worksheet.

Enable the OPC UA Client task

To enable the OPC UA Client task for runtime:
  1. On the Home tab of the ribbon, in either the Local Management or Remote Management group (depending on where the project server will be), click Tasks.

    The Execution Tasks dialog box is displayed.

  2. In the list of tasks, select OPC UA Client Runtime.
  3. Click Startup.

    The Startup dialog box is displayed.

  4. Select Automatic, and then click OK.
  5. Click OK again to close the Execution Tasks dialog box.

Troubleshooting

If you are having trouble with OPC UA Client operations, you can have the client generate a trace log with more detailed information. To do this, manually edit your project file (projectname.APP) and add the following settings:
  [OPC]  UaLogPath=file path and name  UaTraceLevel=level  

For UaLogPath, the file path is relative to your project folder.

For UaTraceLevel, select one of the following:
Level Description
0 NoTrace – Disables the trace.

This is the default if UaLogPath is not configured.

1 Errors – Internal system errors that require bug fixing.
2 Warnings – Internal system warnings and external errors.

This is the default if UaLogPath is configured.

3 Info – More detailed information about system events.
4 InterfaceCall – Information needed for debugging.
5 CtorDtor – Information needed for debugging.
6 Program – All message content.
7 FlowData – All messages.
Note: The levels are cumulative, so Level 2 includes Level 1, Level 3 includes Levels 1 and 2, and so on.

OPC UA Client