How to Configure the OPC UA Collector (version 24)

Begin Logging OPC UA Data

Use the OPC Collector module within the Canary Admin to create and manage OPC UA data collection. 

Within the OPC Collector, tags are organized into Groups, and Groups are organized into Logging Sessions.

• A Group is a set of tags that will share common configuration properties.  Group properties include the sample interval, the ability to normalize timestamp precision, and the application of deadbanding.
• A Logging Session is a collection of Groups.  Logging Session properties dictate which Canary Historian(s) and DataSet the tags within the Groups will be archived within. A Logging Session can be Tag Based or Path Based.

When organizing tags into Groups and Groups into Logging Sessions, consider not just the properties that tags will have in common, but also the potential 'interruption' of data logging.  When editing Groups, the entire Logging Session will require a momentary stop and start to apply the changes.  This will result in a one or two second gap in the data record, showing 'NoData' values for all tags within the Logging Session.

Create a Logging Session (Tag Based)

1. Open the Canary Admin client and navigate to the OPC Collector tile>Configuration screen.
2. Select New Session and choose a Tag Based  session.
3. Name the session within the SESSION SETTINGS window at bottom left.
4. Select the Historian you wish to log data to by entering the machine name or IP address.  If the Canary Historian is on the local machine, use localhost as your entry.
   • To write data to multiple Canary Historians, enter multiple Historian machine names or IP addresses separated by a comma.
   • CanaryHistorian1, CanaryHistorian2
5. Browse for the DataSet to log tags to or enter the desired name of the DataSet if not yet created.
6. New File need only be checked if you wish to adjust the licensing of tags that are already being logged.  Checking this causes the system to audit the current session for any tag changes and releases the license of any previously logged tag no longer present.  This action does not erase the historical record but does release the consumed tag license for all missing tags and keeps client tools from being able to access the no longer licensed tags.

Establish OPC Server

1. Enter the machine name or IP address of the OPC server.
2. Add the port number for the OPC server. If unsure of the port number, consult your OPC server documentation.
3. If you would like to enable security, check the Use Security box. The Collector will attempt to connect to the UA server using the configured certificate from the Settings screen in the left menu bar. Additionally, the user can provide a username and password if credentials are required for connecting. If security is not necessary, leave the box unchecked.
4. Select Apply at the top of the page.

Edit Group Settings

1. Select the Group that has been created under your new Logging Session.  The Group name should be highlighted.
2. Edit the Group Name as desired.
3. Adjust the Sample Interval as desired.
4. Choose whether you would like to Normalize Times.  Choosing to do so will standardize all timestamps to either half the sample interval or to 1000 milliseconds, defaulting to the more precise of the two.
5. Choose Deadband Type, either Absolute or Percent.  Individual tag deadbands are then set when later configuring the tag Group.

Browse for Tags

1. Select Browse from the TAGS window to open the tag browser.
2. If you wish to prepend the tag names, use the Name Prefix window to enter the desired string and check the Prepend Browse Path box.  Once a tag has been selected, the tag path will appear in the Example box to show the transformed name.
3. Browse the Server Nodes window to find the tags you wish to select. Clicking on the node name or branch will highlight the name and display any available tags in the window to the right.
4. Highlight the tags you wish to log.  You may click on a tag individually as well as use the Shift or Control keys to multi-select tags.  Tag properties, if available, will display in the window to the right.
5. With tags selected, click Apply to add them to the tag Group and continue to browse for additional tags. 
6. Click OK when finished.

Configure the Tag Group

From the tag Group table (displayed in the TAGS window), users can edit tag names, OPC node mapping, data type, deadbands, perform data transformations, and add metadata properties. 

Editing the Tag Table

Making edits to the tag table can be done in large quantities by using additional tools like Excel or done tag-by-tag for smaller jobs. The Group displays all tags in a table format.  The table consists of columns, each with a header, and a individual row for each tag within the group.  Clicking on first cell of any row will select the tag contained within that row.

Mass Tag Editing

To allow for the removal or copying and pasting of tag records use the REMOVE, COPY, PASTE, or PASTE NEW buttons at the top of window.

1. Select the top left cell of the table. In doing so you should select all available cells.  Use the COPY button to add all table contents to the clipboard.  
2. Paste the clipboard into a program like Excel and make all necessary changes.
3. Remove the column headers from the new table and copy only the rows containing tag data.
4. With all rows selected within the OPC Collector, use the PASTE button to replace the existing contents with the freshly edited table.

COPY and PASTE NEW can also be used to select an existing tag row or rows and duplicate them in the table.  You will receive an error that a duplicate tag record exists.  Edit the tag name to resolve.

Renaming Tags

1. With a Group selected in the SESSIONS window, select a tag by clicking on the first cell in the row of that tag. The entire row should be highlighted. 
2. Under the TAG SETTINGS section, edit the Canary Tag Name field  to rename the tag as desired for the historical archive. 
3. Select APPLY. 

Tags can be aliased, or given a new name, without altering the way they appear in the OPC server.  

Adjusting OPC Node Mapping

The OPC Node ID field allows users to change the tag's OPC Node ID. The OPC Node ID indicates the location of the tag within the OPC server's folder structure.

1. With a Group selected in the SESSIONS window, select a tag by clicking on the first cell in the row of that tag. The entire row should be highlighted. 
2. Under the TAG SETTINGS section, edit the OPC Node ID field  to remap the tag to the proper OPC server node. 
3. Select APPLY. 

Changing the Data Type

Data types are "containers" that are assigned to tags that correspond with how much storage space a tag requires; however, sometimes data types get misidentified by the OPC Server and a tag with a small data footprint gets assigned a larger data type, wasting storage space. 

1. With a Group selected in the SESSIONS window, select a tag by clicking on the first cell in the row of that tag. The entire row should be highlighted. 
2. Under the TAG SETTINGS section, select the drop down menu in the Type field to change the Data Type of the tag. 
3. Select APPLY. 

By default, the data type is established by the OPC server. To maximize archive performance and minimize data footprint, adjust data types to use the minimum amount of resources. For example, do not use an R8 when an I2 would suffice. 

Deadbands

A deadband is the range that a tag value can vary until it is logged. Applying a deadband to a tag is useful for filtering out inconsequential data, which conserves network and machine resources while reducing the data footprint. Two kinds of deadbands are supported. 

• Absolute - the most recent value received must differ from the previously logged value by more than the specified amount. If the most recent value has not changed by more than the deadband value, the value is not logged and the previous value remains as the current value.

• Percent - applies only to analog items with an EURange property that defines a value range for the item. (This is configured in the OPC server.) The range is multiplied by the deadband value and then compared with the actual value change to determine if the OPC server should notify the collector of a change. DeadbandValues range from 0.0 to 100.0.

1. With a Group selected in the SESSIONS window, select a tag by clicking on the first cell in the row of that tag. The entire row should be highlighted. 
2. Under the TAG SETTINGS section, select the Deadband field and type a number to specify the deadband amount. If set to a Percent deadband, enter the percent on a 0 to 100 scale (i.e., to express a percentage deadband of a quarter of a percent enter 0.25).
3. Select APPLY. 

Data Transformations

Data transformations are calculations applied to single tag values and can be used for measurement conversions and other purposes. 

1. With a Group selected in the SESSIONS window, select a tag by clicking on the first cell in the row of that tag. The entire row should be highlighted. 
2. Under the TAG SETTINGS section, select the Transform field and enter the expression. Transformations of incoming values should use the string Value to represent the current value in the expression. Expressions can be built using NCalc operators and functions. Quality can also be adjusted by using the string Quality.
   • Example: Value*10 = the latest tag value multiplied by ten. 
   • Example: Round(Value,1) = the latest tag value rounded to the nearest tenth. 
   • Example: If(Value<0,Quality='Bad',Quality)= if the latest tag value is less than zero the Quality is overwritten and reported as 'Bad'. If the latest tag value is greater than or equal to zero, then the actual Quality is reported. 
3. Select APPLY. 

Understanding all of the functionality of the data transformation using Value and Quality can provide for more powerful data logging. Quality can be set to keywords in single quotes or numerical values: 'Good' (192), 'Bad' (0), 'NoData' (32768), etc. 

Adding Metadata Properties

Adding Metadata to your tags offers context beyond timestamp, value, and quality score and can be used by additional Canary services and third party components for data contextualization and reporting. Properties can be "hard-coded" by entering a static value or logged from the OPC server using its Node ID. If logging the property from the OPC server, the Node ID needs encapsulated in [square brackets].

1. Select the TAG PROPERTIES button to open the Tag Properties window. 
2. Choose a metadata category or create a new one by typing the name of the desired category in the drop down box. Select ADD.
3. Select APPLY after adding the desired metadata categories. 
4. With a Group selected in the SESSIONS window, select a tag by clicking on the first cell in the row of that tag. The entire row should be highlighted. 
5. Under the TAG SETTINGS section, select the metadata category and enter the desired value. 
6. Select APPLY.

Create a Logging Session (Path Based)

1. Open the Canary Admin client and navigate to the OPC Collector tile>Configuration screen.
2. Select New Session and choose a Path Based session.
3. Name the session within the SESSION SETTINGS window at bottom left.
4. Select the Historian you wish to log data to by entering the machine name or IP address.  If the Canary Historian is on the local machine, use localhost as your entry.
   • To write data to multiple Canary Historians, enter multiple Historian machine names or IP addresses separated by a comma.
   • CanaryHistorian1, CanaryHistorian2
5. Specify a DataSet Prefix. This is the DataSet where data will be stored in the Historian.
6. Set the Tags Per DataSet limit. This is the max amount of tags that will be stored in a single DataSet from this session. Once this limit is exceeded a new DataSet will be created with the same prefix and incremented by 1. (i.e. DataSet, DataSet2, DataSet3, ...)
7. New File need only be checked if you wish to adjust the licensing of tags that are already being logged.  Checking New File causes the system to audit the current session for any tag changes and releases the license of any previously logged tag no longer present.  This action does not erase the historical record but does release the consumed tag license for all missing tags and keeps client tools from being able to access the no longer licensed tags.

Establish OPC Server

1. Enter the machine name or IP address of the OPC server.
2. Add the port number for the OPC server. If unsure of the port number, consult your OPC server documentation.
3. If you would like to enable security, check the Use Security box. The collector will attempt to connect to the UA server using the configured certificate from the Settings screen in the left menu bar. Additionally, the user can provide a username and password if credentials are required for connecting. If security is not necessary, leave the box unchecked.
4. Select Apply at the top of the page.

Edit Group Settings

1. Select the Group that has been created under your new Logging Session.  The Group name should be highlighted.
2. Edit the Group Name as desired.
3. Adjust the Sample Interval as desired.

Browse Paths

1. Select Browse from the Browse Paths window to open the tag browser.
2. Browse the Server Nodes window to find the node you wish to select. Clicking on the node name or branch will highlight the name and preview any available tags in the window to the right.
3. With the node selected, click Apply to add it to the Group and continue to browse for additional nodes, if needed. 
4. Click OK when finished.

Applying Filters

Once a node is selected, filters can be applied to further include or exclude a subset of tags under that node. Canary uses Regular Expressions to match upon string patterns within that tag path. *These expressions apply only to the path beneath the selected node, NOT the node itself.

1. Select a path from the Browse Paths window.
2. Add an expression in the Filters bar and click ADD. An expression can be as simple as a keyword which you want to include or exclude. Some common expressions are ^StartsWith and EndsWith$.
3. Once added, check the INCLUDE box to include the tags that this filter applies to or leave unchecked if wishing to exclude them. (For more information on Browse Path and filters, see here.)

High Speed Polling

By default, the Canary OPC Collector requests a new series of tag values once per second from the OPC server. For sub-second polling, the OPC UA server must be capable of buffering tag values between requests from the Canary OPC UA Collector. Configuration may be necessary.

Before deploying this architecture, it is necessary to identify the caching capabilities of the OPC UA server as these can vary greatly from one vendor to another. Even servers with high message buffering capabilities, 100 or more messages per update, may not be able to maintain speeds faster than 50 milliseconds as the Windows OS may take two or three operating system intervals to process the request. Server specifications will likely need adjusted as well.

The Canary Historian is capable of writing continuous values at a rate of 10 milliseconds, but most OPC UA architectures will not support this rate of change.

How to Configure the OPC UA Collector for High Speed Polling

1. Each OPC UA Logging Session generates a separate OCF file.  The Logging Session that requires high speed polling will need to be modified using a text editor.  The OCF file can be found by browsing C:\ProgramData\Canary Labs\OPC Collector\.
2. Within the OCF file, set the sample_interval to the desired update rate in milliseconds. This setting determines how often the OPC server samples and buffers a tag value.
3. Next, set the opcua_publish_interval for the desired publish rate in milliseconds.  This setting will reflect how often you desire the OPC server to publish buffered messages to the OPC Collector.  
4. Save the OCF file and then stop and start the OPC UA Collector service within the Services tile of the Canary Admin in order for the changes to take effect.

When editing a Logging Session that was built prior to version 20.3.4, the 'publish_interval' setting will need to be added into the OCF file manually. Formatting is <opcua_publish_interval>100</opcua_publish_interval> where '100' represents the value in milliseconds and is customizable.

• Example: For a poll rate of 20ms you would need the OPC server to buffer 50 messages based on a the defaulted publish interval of 1000 milliseconds.  Assuming the OPC server can only buffer 10 messages, it would need to be published 5 times every 1000 milliseconds resulting in a publish interval setting of 200 milliseconds.

Additional Administrative Duties

Backing Up Logging Configurations

When a logging session is saved, a new OCF file is created for that logging configuration.  OCF files can be found by browsing the following directory:

C:\ProgramData\Canary Labs\OPC Collector

Additionally, each time changes are applied to an existing OCF file, the previous version of the OCF is backed up, archived as a BAK file.  During this process, the OCF file has the date and time prepended to its file name and the OCF extension is replaced with a BAK extension.

Should a previous configuration need to be restored, change the current OCF file extension to avoid naming conflicts (OCFtemp could be used) and rename the last BAK file with the standard OCF file name.

You will need to restart the OPC Collector service.

If your session is Tag Based, all of the logging session configuration including tags will be contained within the OCF file. If it is Path Based, only session and group configuration will reside in the OCF file. Tag mapping for ALL Path Based sessions are contained within the OpcCollector.sqlite file.

Canary keeps a minimum of 3 BAK files for each OCF.  Beyond the most recent 3 BAK files, Canary also archives all BAK files created within the last 14 days.

Add Tags Without Using the Canary Admin UI

To bypass the OPC Collector UI you may edit the Logging Session OCF files that are generated by the UI directly.

• Edit the Logging Session OCF file using a text editor. The file can be found by browsing C:\ProgramData\Canary Labs\OPC Collector\.
• Once edit is complete, save the OCF file and restart the OPC Collector in the Canary Admin Services tile to pick up the changes.
• An example of the file structure is below.

<tag>
<historian_name>TagNameGoesHere</historian_name>
<opc_itemid>OPCNodePathGoesHere</opc_itemid>
<datetype>DataTypeGoesHere</datatype>
<deadband>DeadbandValue</deadband>
<transform>ExpressionGoesHere</transform>
<property name="EnterPropertyName">PropertyValue</property name>
</tag>

OPC UA Security Information

With Logging Session security enabled, a security certificate can be added within the Canary Admin.

Security Certificate Settings

Access the security certificate in a few simple steps. Note, security must be enabled by checking the Security box within the Logging Session itself.

1. Open the Canary Admin, select the OPC Collector tile.
2. Select the Configuration tab at the bottom.
3. Select the Settings tab.

INFO... Launches the Certificate properties dialog.

Store Name

The chart below gives a description of all available options in the Store Name drop down menu.

Find Type

The chart below gives a description of all the available options in the Find Type drop down menu.

Subject Name

This is the value of the specified Type as selected from the Find Type drop-down menu.