0

How to Configure the OPC UA Collector (version 21)

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.

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.

  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 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 name 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 '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.
  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, then click on 'Settings' in the left menu bar and add your security certificate information.  If security is not necessary, leave the box empty.
  4. Select 'Apply' at the top of the page.
  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.
  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.

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. 

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.  

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'. 

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. 

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 previously logged 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 previously logged 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 are calculations applied to single tag value 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 to your tags offers context beyond timestamp, value, and quality score and can be used by additional Canary 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'.

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.
  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.

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

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.

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.

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>

 

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

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; available when the Secure or Username endpoint is enabled.

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

Member name Description
AddressBook The X.509 certificate store for other users.
AuthRoot The X.509 certificate store for third-party certificate authorities (CAs).
CertificateAuthority The X.509 certificate store for intermediate certificate authorities (CAs).
Disallowed The X.509 certificate store for revoked certificates.
My The X.509 certificate store for personal certificates.
Root The X.509 certificate store for trusted root certificate authorities (CAs).
TrustedPeople The X.509 certificate store for directly trusted people and resources.
TrustedPublisher The X.509 certificate store for directly trusted publishers.

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

Member name Description
FindByApplicationPolicy The findValue parameter for the Find method must be a string representing either the application policy friendly name or the object identifier (OID, or Oid) of the certificate. For example, "Encrypting File System" or "1.3.6.1.4.1.311.10.3.4" can be used. For an application that will be localized, the OID value must be used, because the friendly name is localized.
FindByCertificatePolicy The findValue parameter for the Find method must be a string representing either the friendly name or the object identifier (OID, or Oid) of the certificate policy. The best practice is to use the OID, such as "1.3.6.1.4.1.311.10.3.4". For an application that will be localized, the OID must be used, because the friendly name is localized.
FindByExtension The findValue parameter for the Find method must be a string describing the extension to find. The object identifier (OID) is most commonly used to direct the Find method to search for all certificates that have an extension matching that OID value.
FindByIssuerDistinguishedName The findValue parameter for the Find method must be a string representing the issuer distinguished name of the certificate. This is a more specific search than that provided by the FindByIssuerName enumeration value. Using the FindByIssuerDistinguishedName value, the Find method performs a case-insensitive string comparison for the entire distinguished name. Searching by issuer name is a less precise search.
FindByIssuerName The findValue parameter for the Find method must be a string representing the issuer name of the certificate. This is a less specific search than that provided by the FindByIssuerDistinguishedNameenumeration value. Using the FindByIssuerName value, the Find method performs a case-insensitive string comparison using the supplied value. For example, if you pass "MyCA" to the Find method, it will find all certificates with the issuer name containing that string, regardless of other issuer values.
FindByKeyUsage The findValue parameter for the Find method must be either a string representing the key usage or an integer representing a bit mask containing all the requested key usages. For the string value, only one key usage at a time can be specified, but the Find method can be used in a cascading sequence to get the intersection of the requested usages. For example, the findValue parameter can be set to "KeyEncipherment" or an integer (0x30 indicates "KeyEncipherment" and "DataEncipherment"). Values of the X509KeyUsageFlags enumeration can also be used.
FindBySerialNumber The findValue parameter for the Find method must be a string that represents the serial number of the certificate as displayed by the certificate dialog box, but without the spaces, or as returned by theGetSerialNumberString method.
FindBySubjectDistinguishedName The findValue parameter for the Find method must be a string representing the subject distinguished name of the certificate. This is a more specific search than that provided by the FindBySubjectNameenumeration value. Using the FindBySubjectDistinguishedName value, the Find method performs a case-insensitive string comparison for the entire distinguished name. Searching by subject name is a less precise search.
FindBySubjectKeyIdentifier The findValue parameter for the Find method must be a string representing the subject key identifier in hexadecimal, such as "F3E815D45E83B8477B9284113C64EF208E897112", as displayed in the UI.
FindBySubjectName The findValue parameter for the Find method must be a string representing the subject name of the certificate. This is a less specific search than that provided by the FindBySubjectDistinguishedNameenumeration value. Using the FindBySubjectName value, the Find method performs a case-insensitive string comparison using the supplied value. For example, if you pass "MyCert" to the Find method, it will find all certificates with the subject name containing that string, regardless of other subject values. Searching by distinguished name is a more precise search.
FindByTemplateName The findValue parameter for the Find method must be a string representing the template name of the certificate, such as "ClientAuth". A template name is an X509 version 3 extension that specifies the uses of the certificate.
FindByThumbprint The findValue parameter for the Find method must be a string representing the thumbprint of the certificate.
FindByTimeExpired The findValue parameter for the Find method must be a DateTime value in local time. For example, you can find all the certificates that will be valid until the end of the year by eliminating the results of a Findoperation for FindByTimeExpired of the last day of the year from the results of a Find operation forDateTime.Now.
FindByTimeNotYetValid The findValue parameter for the Find method must be a DateTime value in local time. The value does not have to be in the future. For example, you can use FindByTimeNotYetValid to find certificates that became valid in the current year by taking the intersection of the results of a Find operation forFindByTimeNotYetValid for the last day of last year with the results of a Find operation forFindByTimeValid of DateTime.Now.
FindByTimeValid The findValue parameter for the Find method must be a DateTime value in local time. You can useDateTime.Now to find all the currently valid certificates.

'Subject Name' is the name of the certificate subject.

Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular