How to Configure the OPC DA Collector (version 24)

Begin Logging OPC DA Data

Run the Logger Administrator application to create and manage OPC DA data collection. Within the Logger Administrator, 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 update rate, the ability to normalize timestamp precision, and the option to trigger data logging based on another tag's value.
• 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.

It is a best practice to have a one-to-one ratio of logging sessions to DataSets. In other words, a logging session should NOT be configured to send data to multiple DataSets, nor should multiple logging sessions write to one single DataSet. This will mainly cause issues when trying to force the historian to create a new file when logging begins in order to update the current tag list.

If needing to write to multiple DataSets, another logging session should be created. Multiple logging sessions can run simultaneously from the same Logger Admin. Likewise, if multiple logging sessions are writing to the same DataSet, these sessions should be combined into one session and utilize the Group functionality stated above.

Create a Logging Session

1. Launch the Logger Administrator application. Typically, different computers in various locations are used to log data. The opening page, under the General Tab, allows the admin to see every device in the network that has a Logger Administrator application installed on it. From the General tab, a user can remotely monitor/administrate those sessions.
2. Optional: Right-click on a machine name and select 'Connect' to access that machine's Logger Administrator. Do not do this when creating a Logging Session on the local machine. 
3. Select 'File' then 'New Log Session' from the menu bar.
4. Enter a name for the Logging Session in the 'Name' field. 
5. In the 'Historian Computer' field, enter the machine name where the Canary Historian is installed. Leave this field blank if the historian is local.
   • To write data to multiple Canary Historians, enter multiple historian machine names or IP addresses, separated by a comma.
   • CanaryHistorian1, CanaryHistorian2
6. 'Create a new file when logging starts' need only be checked if you wish to adjust the licensing of tags that are already being logged.  Checking 'Create a new file when logging starts' 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. Under the Group tab, in the 'Computer' field, enter the machine name or IP address of the OPC DA server. If the OPC DA server is local, leave this field blank.
2. Use the ellipses to browse any available OPC servers on the computer specified. Select the desired OPC server and select 'OK'.

Edit Group Settings

1. The 'Group Name' field can be used to change the name of the Group. Additional Groups can be created by right-clicking on the exiting Group name tab or by selecting 'Add Group' from the 'Edit' menu.
2. Edit the 'Group Name' as desired.
3. Adjust the 'Update Rate' as desired. The 'Update Rate' field controls the frequency at which the Canary Collectors poll the OPC server for data. Change the update rate to conserve network and machine resources. 
4. Choose whether you would like to apply an 'OPC Deadband', expressed as a percentage (0 - 1.0) to all the tags within that Group. A deadband is the range a tag's value can vary before it is logged. The deadband field in the Group Settings pertains only to percent deadbanding and requires further configuration within the OPC server. This type of deadbanding is rarely implemented.
   • Percent Deadband - The OPC server deadbanding is defined as a percent deadbanding and covers the entire group level.  The definition of the OPC server deadbanding can be found in the OPC 2.0 specification at section 4.5.1.6.  At the group level in the Canary Logger, the deadband percent number (between 0.0 and 1.0) is passed to the OPC server. Not all OPC servers support percent deadbanding, since this is an optional behavior.  If available, this deadbanding is the most efficient because it reduces the amount of data that needs to be communicated to the Canary Logger; however, it does require further configuration within the OPC server to guarantee expected results. If not familiar with this type of deadbanding, it is recommended to use the 'Dead Band' column within the table itself. This is not percent-based, but rather, an absolute value deadband.
5. Decide if you wish to adjust 'Normalization Time'.
   • The 'Normalization Time' rounds the incoming timestamp from the OPC server to the specified number of milliseconds. Normalization Time is used in two scenarios:
     1. This provides a mechanism to adjust the timestamp to a consistent interval.  With some OPC servers, the incoming timestamp will fluctuate slightly between updates. 
     2. This can also reduce the data footprint. If timestamp normalization is set to 1000 milliseconds, expressed as '00:00:01.000', it will round the timestamp to the nearest second rather than retaining tenths, hundredths, or thousandths of a second precision. This can have a large impact on the overall storage requirements of the historian.
6. Decide if you wish to apply a Trigger Item ID or Trigger Expression.
   • The Trigger Item ID and the Trigger Expression allows the user to log a group of tags based on a configurable tag expression. The most common use of this feature is start or stop logging sessions based on a specific tag's value.  This feature allows you only to capture data from within a tag Group when a process is running, a condition is met, or the data has value.
   • The Trigger Item ID field references a single OPC tag whose value, or an expression using that value, will determine whether all tags in the current Logging Group should be logged and historized.
   • The Trigger Expression is a configurable expression where "x" represents the Trigger Item ID. When the Trigger Expression evaluates as TRUE, the tag group will begin to log data. A FALSE value will stop logging for the entire group.
     • An example of this could be as simple as x=1 where x represents a 'Trigger Item ID' set to a Boolean and the Group will only log when that Boolean is in state TRUE.

Browse For Tags

1. Select 'Browse OPC Server' by right clicking in the dark grey section of the Trends Grid or from 'Edit' on the menu bar. A window with the OPC Server Nodes appears.
2. At the top of the window, use the drop down menu in the 'Name Prefix' to select a DataSet to log data to. DataSets must already be created from within the Canary Admin application using the 'Historian' panel and the 'Configuration' submenu at the bottom of the application. (See Creating, Deleting, and Renaming DataSets.)
3. 'Prepend browser path' will include the OPC server node path on the front of the tag name.
4. Browse the OPC Server Nodes and expand them to make tags visible in the window on the right.
5. Click and drag to select all the desired tags or Shift+Click. Select 'Apply' to add them to the logging session and continue to browse other nodes without closing the window. Select 'OK' to add all selected tags and close the window.
6. Select 'Apply'. Select 'Save'. Store the LCF in a public directory so that the Local System Account has permission to read it.
7. Select 'Start' to begin the logging session.

Configure the Trends Grid

Editing the Trends Grid

The Logger Administrator's data table, known as the Trends Grid, functions similarly to an Excel spreadsheet. Columns and cells within the Trends Grid can be edited, cut, copied, and pasted with the same functionally that one would find in any spreadsheet application, such as Excel. 

Mass Tag Editing

Microsoft Excel offers functionality not available in the Trends Grid, such as conditional formatting or print optimization. Some users may be more comfortable using Excel as opposed to the Trends Grid.

1. Select all the tags in the grid by selecting the cell in the topmost and leftmost corner of the grid. The traditional click and drag technique can be used to select all of the tags as well.
2. Copy and paste into the Microsoft Excel spreadsheet.

   Notice a header row is created in Excel that did not exist in the trends grid. The header row must be copied and pasted when importing the spreadsheet back into the Logger Administrator. 

After the appropriate edits have been made to the spreadsheet, import the spreadsheet into the Trends Grid within the Logger Administrator.

1. Copy only cells that are being imported into the Trends Grid (including the header). Do not copy the entire spreadsheet or any blank cells, doing so results in errors when cells are pasted into the Trends Grid.
2. When pasting the spreadsheet, right-click on the Trends Grid and select 'Paste New Trends'. Do not use the hotkey Ctrl-V or select the usual paste option, doing so replaces the copied cells with the existing cells.

Find and Replace

1. Select 'Replace' in the 'Edit Menu' (or use Ctrl+H)
2. Enter the text or expression in the 'Find what' field before entering the new text or expression in the 'Replace' field.

• 'Look In' can be switched to 'Selection' or 'Current Group'
  • 'Selection' applies find and replace only to the cells that are selected.
  • 'Current Group' applies find and replace to everything.

Adjusting OPC Server Item ID

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

1. With a Group Tab selected, choose a cell in the Item ID column. The Item Id can be edited to remap the tag to the proper OPC server node. 
2. 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. 

• The data type of a tag can be changed on a tag by tag basis, by selecting the drop down menu of a tag's cell in the 'Type' column. 

By default, the data type is established by the OPC server. To maximize archive performance and minimize the 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

The 'Deadband' column allows the user to enter an Absolute Deadband. An Absolute Deadband means the most recent value received must differ from the previously logged value by more than the amount specified in the cell. If the most recent value has not changed by more than the deadband value, the previously logged value remains as the current value. The Absolute deadband is configured on a tag by tag basis in the trends grid, as opposed to the Group Settings. The Group Settings supports a Percent deadband. 

1. Enter a value in the 'Deadband' field. 
2. Select 'Apply'. 

Data Transformations

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

1. Under the 'Data Transform' column in the Trends Grid,  enter an expression. Transformations of incoming values should use the variable, x, to represent the current value in the expression. Expressions can be built using NCalc operators and functions.
   • Example: x*10 = the latest tag value multiplied by ten. 
   • Example: Floor(x) = the latest tag value rounded down to the nearest integer.
2. 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 and third party components for data contextualization and reporting. Metadata columns and cells can be cut, copied, and pasted with the same functionally that one would find in all spreadsheet applications. 

Additional Administrative Duties

AutoStart for the OPC DA Collector

The Logger can be set to automatically re-establish the current session in the event of a temporary OPC Server shutdown or a machine restart.

1. Open the Canary Admin application. Select the 'Logger' tile.
2. Ensure that the Logger is running as a 'Service'.
3. Type in the entire filepath of the Logger Configuration File (.lcf) into the 'Arguments' field. Use double quotations if the filepath contains a space. Multiple file's can be specified by separating the file names with a space. The entire path does not need repeated if the lcf files resides in the same directory. For example,
   • "C:\Program Files\Canary\Log Session1.lcf" LogSession2.lcf
4. A delay (in seconds) can be added to allow more time for the OPC server to come available. Type /delay:30 before typing in the file's save path. Select 'Apply'.
   • /delay:30 "C:\Program Files\Canary\Log Session1.lcf"

A delay is recommended to prevent the logger service from running before other Canary / OPC Server services run.

When the CLILogger is registered as a service it will check the following registry entry for command line arguments during startup:

• x32 bit computer - HKEY_LOCAL_MACHINE\SOFTWARE\Canary Labs\Logger\StartUpCommandLine.
• x64 bit computer - HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Canary Labs\Logger\StartUpCommandLine.

How to Repurpose an LCF (Logging Configuration File)

Logging Configuration Files (LCF) can be edited and re-used, keeping the user from manually re-building them when creating new or similar logging sessions. A new Logging Session can be made by re-purposing an existing LCF instead of building it from scratch. 

1. Launch Logger Administrator application
2. Select 'File', then 'Open'.
3. Browse the directory for the LCF. LCFs can be stored in any location in the machine's file directory. 
4. Choose the file that must be re-purposed. Select 'Open', then 'Yes'. 
5. Edit the file accordingly. Ensure that the new LCF is writing to the appropriate DataSet. 
6. Select 'File', then 'Save As'. Rename the LCF. Ensure the new LCF does not retain the name of the original. If no new name is given, then the original LCF will be overwritten. 
7. Select 'Start'. 

Add Tags without Using the Logger Admin UI 

When adding a few tags to a large LCF, you may wish to avoid having to browse through large tag counts in deep folder structure using the Logger Administrator UI.

1. Open the LCF using Notepad++. LCF files can be located anywhere in the machine's file directory. Right-click the LCF from within the file directory and select 'Edit with Notepad++'.
2. Add the tags manually.  The tag names must match the format of the rest of the file, including metadata, data transformations, and deadbands, for the logging session to operate correctly. 
3. An example of the file structure is below. Be sure to delimit each column of the Trends Grid using commas. 

[Canary Labs Logger]
Destination = Historian
Destination = Computer=
File Version=430
NewFileWhenStartLogging=Yes
Number of Groups=4
Session Name=Log Training
[Group 1]
Computer=
Deadband=0.000000
Log Trigger Expression=
Log Trigger Item Id=
Name= Group 1
Normalization Time=0
Number of Trends=21
OPC Server=CanaryLabs.SimDataServer
Trend 1=Test.Random.Tag0001,Random.Tag0001,,Boiler Temperature,,4,100,0,100,0,0,10000000,(x+32)*5/9
ENTER= NEW, TAG, INFO, HERE
Trend 10=Test.Random.Tag0010,Random.Tag0010,,Random.Tag0010,,4,100,0,100,0,0,10000000
Trend 11=Test.Random.Tag0011,Random.Tag0011,,Random.Tag0011,,4,100,0,100,0,0,10000000
Trend 12=Test.Random.Tag0012,Random.Tag0012,,Random.Tag0012,,4,100,0,100,0,0,10000000
Trend 13=Test.Random.Tag0013,Random.Tag0013,,Random.Tag0013,,4,100,0,100,0,0,10000000
Trend 14=Test.Random.Tag0014,Random.Tag0014,,Random.Tag0014,,4,100,0,100,0,0,10000000

• Stop and Start the Logging Session after modifying the LCF to pick up the changes.