How to Configure the OPC UA Collector (version 23)

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' application and select the 'OPC Collector' tile.
2. Select the 'Configuration' tab at the bottom of the page.
3. Select 'New Session' and choose  a Tag Based  session.
4. Name the session within the 'SESSION SETTINGS' window at bottom left.
5. 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
6. Browse for the DataSet to log tags to or enter the desired name of the DataSet if not yet created.
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.
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 and network resources. 

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 as of Version 20. 

• Absolute Deadband - 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 Deadband - the most recent value received must differ from the previously logged value by more than the percentage specified. 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. 

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. 

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' application and select the 'OPC Collector' tile.
2. Select the 'Configuration' tab at the bottom of the page.
3. Select 'New Session' and choose  a Path Based  session.
4. Name the session within the 'SESSION SETTINGS' window at bottom left.
5. 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
6. Specify a 'DataSet Prefix'. This is the DataSet where data will be stored in the historian.
7. 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, ...)
8. '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 with in 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. Upgrade the Canary System and OPC Collector to version 20.3.4 or newer.
2. Each OPC UA Logging Session generates a separate OCF file.  The Logging Session that requires high speed polling will need to be modified using Notepad++ or a similar file editor.  The OCF file can be found by browsing C:\ProgramData\Canary Labs\OPC Collector\.
3. 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.
4. 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.  
5. 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

Delaying Service Startup

All OPC UA Logging Sessions run automatically as a Windows Service.  To delay the execution of this service, possibly to allow equipment to startup without recording their values, follow these steps:

1. Open the Canary Admin. Select the 'OPC Collector' tile. Select the 'Configuration' tab.
2. Select the 'Settings' tab on the left hand side.
3. Change the 'Startup Logging Delay'.
   • Time format is hh:mm:ss

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 Notepad++ or a similar file 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' module 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.