DATA INTERFACES. Installation & Configuration Guide

Transcription

1 DATA INTERFACES Installation & Configuration Guide

2

3 Copyright 2015 GP Strategies Corporation All rights reserved. This manual may not, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form without prior written permission from GP Strategies Corporation. Disclaimers Trademark Information All information referred to and/or included in this manual is current as of the original issue date of this manual. GP Strategies disclaims all warranties as to this software, whether express or implied, including without limitation any implied warranties of merchantability, fitness for a particular purpose, functionality, data integrity, or protection. This manual could include technical inaccuracies or typographical errors. Changes are made periodically to the information herein at the discretion of GP Strategies. These changes will be incorporated in new revisions of this manual. GP Strategies reserves the right to make improvements to the product(s) or program(s) described in this manual at any time and without notice. GP Strategies, GP Strategies and logo design, EtaPRO, VirtualPlant, EtaPRO APR, EtaPRO Predictor, EtaPRO ViPr, EPArchive, EPTrendSetter, EPReporter, EPLog, EPAlert, OPSCenter, Canalyzer, GPCALCS, GPSteam, GPiLEARN, and PerformancePlus+ are trademarks or registered trademarks of GP Strategies Corporation in the U.S. and other countries. All other names or products are trademarks or registered trademarks of their respective owners. Trademarks of other companies mentioned in this manual appear for identification purposes only and are the property of their respective companies. GP Strategies notes these trademarks where they occur in the text on only the first reference. Prepared by GP Strategies Corporation 25 Northpointe Parkway Suite 100 Amherst, New York, USA Technical Support: Phone: ( ) Support Website: EtaproSupport@gpstrategies.com Printed in the United States of America EPArch139.V2.1B0 Revised: April 2015 Issued: January 2012

4 Revision Sheet Release No. Date Revision Description Rev. 0 9/22/11 Issued for production. Rev 1. 1/16/12 Miscellaneous edits Rev 2 1/17/12 Miscellaneous edits Rev 3 6/1/12 Miscellaneous edits Rev 4 6/20/12 Added Modbus documentation Rev 5 7/18/12 Added an example connection string for OLEDB. Rev 6 7/18/12 Updated Modbus & OPC documentation Rev 7 5/8/13 Added PI-SDK documentation Rev 8 10/15/13 Update documentation to reflect to architecture Included entries for the following interfaces: Random Number, CSV, Network Statistics, IMAP, Microsoft Exchange, POP3 Included entries for the following transport interfaces: Microsoft Exchange, SMTP Rev 9 9/28/14 Miscellaneous edits Rev 10 10/31/14 Updated the installation instructions to reflect new installation wizard. Rev 11 4/15/2015 Miscellaneous edits Rev 12 10/30/2015 Added Predictor documentation Rev 13 5/4/2016 Added documentation for the following interfaces: EPArchive Subscription, Wonderware SDK, Wonderware Database, PI-AF-SDK

5 Table of Contents Getting Started Interface Installation Interface Configuration EtaPRO Data Interfaces EtaPRO Data Interfaces Installation & Configuration Guide v

6

7 Chapter 1 Getting Started Introduction Principles of Operation Structure Operation Overview Getting Help Introduction EtaPRO Data Interfaces collect data from various data sources for use and storage in an EtaPRO system. All communications between data interfaces and EtaPRO systems are one-way. Multiple interface instances can be hosted by a single windows service. Multiple interface host services can run simultaneously on different workstations for data collection to a single or multiple EtaPRO systems. The types of data interfaces provided are: EtaPRO OPC Text File Databases (OLE DB/ODBC/Native SQL) (Microsoft Exchange/POP3) Windows Performance Counter Yahoo! Finance Modbus OSIsoft PI-SDK CSV File Random Number Generator Refer to Chapter 4: EtaPRO Acquisition Data Interfaces for detailed descriptions of each interface type. Principles of Operation Structure EtaPRO Data Interfaces consist of dynamic link libraries (DLLs) that are hosted as a single Microsoft Windows service. This process is referred to as an Interface Host Service. Multiple interface host services can run simultaneously on different workstations. An interface has two components: Data Acquisition Object Acquires data from a data source such as an OPC Server, Modbus connection, etc. Acquisition Transport Interface Sends data directly to EtaPRO or through an intermediary. In the figure below, the items labeled Data Acquisition A and Data Acquisition B, refer generically to two different types of data sources. Each could be retrieving data from the same type of data source or two different types. Each interface operates completely independent of the other. EtaPRO Data Interfaces Installation & Configuration Guide 1-1

8 1-2 Getting Started Interface Host Service Interface (Instance A ) Interface (Instance B ) Additional Interface Instances Data Acquisition A Acquisition Transport Data Acquisition B Acquisition Transport Operation Overview The EtaPRO Data Interface requires an EtaPRO Server running with a current configuration. Acquired points are configured using the EtaPRO Client connected to the EtaPRO Server. The EtaPRO Data Interfaces work by lining up a series of properties between the acquired points and the interfaces. Interface (Instance = OPC.SRV.1 Computer A EtaPRO Data Interface Interface (Instance = OPC.SRV.2 EtaPRO Server Source Tag 1 (Instance = OPC.SRV.1) Source Tag 2 (Instance = OPC.SRV.1) Computer B EPArchive Interface Interface (Instance = ModbusSrv) OPC Server OPC.SRV.1 OPC Server OPC.SRV.2 Source Tag 3 (Instance = OPC.SRV.2) Modbus Serial Connection Source Tag 4 (Instance = OPC.SRV.2) Source Tag 5 (Instance = ModbusSrv) The Interface Host Service holds multiple instances of interfaces, all running simultaneously. Each interface instance is configured separately, and can be configured to connect to the same or different data sources and sent to the same or different EtaPRO Server. Each acquired point in EtaPRO corresponds to a Source Tag in EPArchive. Source tags not only hold the historical data, they also hold the configuration information required for acquisition of that given piece of information. Information required for connection to an individual data source is configured in the EtaPRO Data Interface, while information regarding specific process inputs are set on an individual Source Tag in the EtaPRO Client. Each source tag can be linked with one interface instance using the Instance property for the source tag. When the Interface Host Service starts, it will read the configuration file and use the Acquisition Transport Interface to load its tag configuration. An EtaPRO Server can have collections of source tags coming from one or multiple Interface Instances. Interface Host Service Instance A Instance B EtaPRO Server Source Tag A Source Tag B Source Tag C Source Tag D

9 Getting Started 1-3 Multiple interfaces run simultaneously using the same Interface Host Service. Each Interface Instance is configured separately but all interface settings are saved to a single configuration file associated with the Interface Host Service. When the service starts, it reads the configuration file and creates the corresponding interface instances to handle data retrieval. If the configuration file is not available or is invalid, the service will fail to start and corresponding messages will be written to a log file. Log files are stored in the logging subdirectory for the interface installation. When each interface loads, it requests its corresponding tags as defined by the source tag Instance property. Tags are loaded by the Acquisition Transport Interface, and then passed to the Data Acquisition Object for tag validation. Tag Validation is when the Data Acquisition Object filters out incorrectly configured tags by checking the required property fields against available options. Tags that do not meet the data acquisition object s requirements are noted in the log files stored on the EtaPRO Data Interface Server, along with a description of each invalid item. Once an interface is started, the Data Acquisition Objects begin collecting data based on the specified refresh rates. Again, each interface instance is responsible for its own refresh rates. Therefore, when a time corresponds to a listed refresh rate, it instructs the Data Acquisition Object to read from the data source. The Data Acquisition Object reads only the tags that have been assigned to that refresh rate. Source Tag A Source Tag B Source Tag C Source Tag D Source Tag E Refresh Rate 1 (00:01:00) Refresh Rate 2 (00:00:30; 00:00:10) After the necessary tags are read from the data source, the results/values are passed back to the interface via events. After passing though exception reporting, values are then passed to the Acquisition Transport Interface. The Acquisition Transport Interface has the responsibility of sending the values away from the interface, most commonly directly to the EtaPRO Server. When the EtaPRO Data Interface is not installed on the same computer as the data source, the interfaces are able to report and recover from a loss of connectivity between the interface and the data source. In this scenario, when the data acquisition object is asked to read a refresh rate, the data acquisition object will pass back a list of points all marked as Bad Quality Data Acquisition Failure. When connectivity is reestablished, the data acquisition object will begin acquiring data. When the EtaPRO Data Interface is not installed on the EtaPRO Server and the connection between the Acquisition Transport Interface and the destination (usually the EtaPRO Server) goes down, the acquisition transport interface will notify the EtaPRO Data Interface via events that it will need to begin buffering data. Data buffering will continue until the connectivity is reestablished. Interface (Instance A ) Data Acquisition A Events Acquisition Transport Destination (usually EtaPRO Server) Read Only Data Source A

10 1-4 Getting Started Getting Help If you have any problems or questions, please do not hesitate to contact GP Strategies for assistance. GP Strategies Corporation 25 Northpointe Parkway Suite 100 Amherst, NY USA Phone: ( ) Fax: Support Website: Visit our EtaPRO website! Join our EtaPRO Group to start networking with your EtaPRO peers!

11 Chapter 2 Interface Installation Installation Checklist Prerequisties Interface Installation Interface Licensing Installation Checklist Prerequisties Download the latest EtaPRO Data Interface Setup software (EtaPRO Data Interface.msi) from and transfer it to the hardware on which the interfaces will be installed. It is recommended that the interface be installed on the same workstation as the data source. EtaPRO Server software installed on running on the EtaPRO server. Obtain an EtaPRO Product Key for the EtaPRO Data Interface(s) that will be used with the data source(s) by ing GP Strategies at EtaproSupport@gpstrategies.com. If you are upgrading the current version of the EtaPRO Data Interface software, go to Control Panel All Control Panel Items Programs and Features (Add/Remove Programs) and remove the current version of the EtaPRO Data Interface software. Interface Installation The EtaPRO Data Interface software is installed on the EtaPRO Server with the full installation of EtaPRO 10.2 or later. Follow these instructions to install the interfaces on another computer or update the software to the latest version on the current computer. 1. Browse to the download directory and select the EtaPRO Data Interface.msi file. 2. The EtaPRO Data Interface Setup Wizard will display. 3. Click Next to continue and display the End-User License Agreement (EULA). After reading the EULA, enable the I accept the terms in the license agreement check box. EtaPRO Data Interfaces Installation & Configuration Guide 2-1

12 2-2 Interface Installation 4. Click Next to continue and display the Custom Setup step. 5. By default all of these interfaces will be installed: EtaPRO Data Interface/Transport Option Native SQL Data Interface OPC Data Interface Data Interfaces /Transport Options Modbus Interface Windows Performance Counter Interface PI-SDK Interface Random Number Generator Interface Text File Interface Network Statistics Interface CSV File Interface Odbc Data Interface OLE DB Data Interface 6. To choose not to install a given interface, click the drop-down box for that interface and then select Entire feature will be unavailable.

13 Interface Installation Verify the installation path or select another directory using the Browse button. Keep in mind, this is the directory where logging and buffer files will be placed. You can check the available disk space using the Disk Usage button. The Reset button will reselect all the interfaces for installation. 8. Click Next to continue and then Install to begin the installation. 9. If your computer has User Account Control turned on, it will display an additional message asking you to confirm your choice to install. Click Yes to proceeded with the install.

14 2-4 Interface Installation 10. Click Finish to close ithe wiard and complete the installation. Interface Licensing The licensing methodology for the EtaPRO Data Interfaces requires the use of a Product Key. A Product Key is a set of 30 alpha-numeric characters similar to product keys used with other software products. Licensing enables the interfaces, and registers the software to the computer. Obtain an EtaPRO Product Key for the EtaPRO Data Interface(s) that will be used with the data source(s) by ing GP Strategies at EtaproSupport@gpstrategies.com. Follow these instructions to enter the Product Key: 1. Click the EtaPRO Data Interface Service Manager icon in the Start All Programs Files EtaPRO 10 menu.

15 Interface Installation Click the Licensing button to open the EtaPRO Data Interface Licensing dialog. 3. Enter the Product Key and then click Activate. If the activation is successful, a message will display on the EtaPRO Data Interface Licensing dialog indicating that the license validation was successful and further action is not required. Click Close to complete the licensing process. 4. If you do not have internet access, you will see a message indicating that activation failed. 5. Click OK and the Manual Activation field will display on the EtaPRO Data Interface Licensing dialog. 6. Click Copy to copy the Manual Registration Identifier to the clipboard or click To File... to save it to a file. 7. Open this website on a computer with internet access: to display EtaPRO Manual Activation website. Enter your Product Key and the Manual Registration Identifier in the fields provided along with your address. 8. Click Submit. 9. An containing your Product Manual Activation Identifier will be sent to your address. If you do not receive the or encounter difficulties during activation, please contact GP Strategies by at EtaPROSupport@gpstrategies.com. Include your Product Key and the file with the Manual Registration Identifier. 10. Open the EtaPRO Data Interface Licensing dialog again and enter the Manual Activation Identifier provided in the Click Activate and a message will display on the EtaPRO Data Interface Licensing dialog indicating that the features are now enabled. Click Close to complete the licensing process.

16

17 Chapter 3 Interface Configuration EtaPRO Data Interface Service Manager EtaPRO Data Interface Configurator Interface Host Service Configuration Options General Interface Configuration Options Data Buffering Logging Refresh Rates Data Source Interface Configuration Options Data Transport Interface Configuration Options Tag Configuration File Generator Acquisition Transport Interfaces Interface Testing Start or Stop Interface Service EtaPRO Data Interface Service Manager The EtaPRO Data Interface Service Manager is used to license and configure the interface(s) that will collect data from a data source(s) for use and storage in an EtaPRO system. This tool is also used to start and stop the EtaPRO Data Interface service. To launch this tool, click the EtaPRO Data Interface Service Manager icon in the Start All Programs Files EtaPRO 10 menu. EtaPRO Data Interface Configurator 1. Click the Configurator button to start the interface configuration process. The first time the EtaPRO Data Interface Configurator runs, the Interface Selection dialog will display. 2. Use the Source drop-down box to select the installed EtaPRO Data Interface. EtaPRO Data Interfaces Installation & Configuration Guide 3-1

18 3-2 Interface Configuration 3. Use the Transport drop-down box to select the Acquisition Transport Interface. 4. Click OK to display the EtaPRO Data Interface Configurator. Each field on the EtaPRO Data Interface Configurator is explained in the following sections. The settings for the interface are configured on the Interface tab. The interface is given a number for internal use. Each tab contains its own set of tabs: General: Options that are common to all interfaces are contained in this tab. Data Source: Options that pertain to the specific Data Acquisition Interface are contained in this tab Data Transport: These are options associated with an interface s connection to the Acquisition Transport method Any additional interfaces will appear in separate tabs along the top.

19 Interface Configuration 3-3 The New and Remove buttons are provided to add additional interfaces or remove the currently displayed interface. The Apply button saves any changes made to the form without closing the form. The OK button saves any changes and closes the form. Interface Service Configuration Options The Interface Configuration field is used to set the options for the Interface Host Service. Logging Allow Log Purge Days of Logs Logging Level Timeouts Max Disconnect Wait Start Delay TRUE/FALSE Allow or disallow log files to be deleted. If Allow Log Purge is set to TRUE, this is the number of days, including the current day s log that will be kept. All other log files will be deleted. The EtaPRO Data Interface supports three levels of logging. Higher level logging means more verbose messages are written to the log. A HIGH logging level is often useful during installation. However, it is recommended to be retuned back to LOW after setup has been completed. Maximum amount of time in seconds the host will wait for all of the interfaces to shut down. After which, the interface will attempt to kill off the process. Number of seconds the interface host will wait before it attempts to begin data collection.

20 3-4 Interface Configuration General Interface Configuration Options Options on the General tab for the interfaces are common to all interfaces Buffer Buffer Buffer File Count Buffer Size General Instance Quality Conversion Write Shutdown Data Write Timeout Data High Level Logging Log Live Data Log Live Data Count Time Stamping Source Time Setting Time Stamp Location Timeouts Tag Update Check Rate TRUE Enable buffering if the connection to the EtaPRO Server is lost. Number of buffer files to keep. Size in MB each buffer file should be allowed to grow. The upper limit is 500 MB. Characters that describe the interface instance. This field will correspond to the Instance field of EtaPRO Source tags. Tags with the same instance will be returned to the interface and given to the Data Acquisition Object for data acquisition from the data source. Collection used for converting qualities from source type to OPC types. TRUE Send shutdown value and quality if the interface is shut down. TRUE Send I/O value and quality if connection to the data source is lost. TRUE Logs real time data on every update only if the Logging Level is set to High. Number of real time data points to log on every update, only if the Logging Level is set to High. LOCAL Timestamp data coming from the data source is in local time. UTC - Timestamp data coming from the data source is in UTC (Coordinated Universal Time). This setting is only used if timestamps are provided by the data source. DATA_SOURCE Use the timestamp data provided by the data source. LOCAL_MACHINE Timestamp data is provided by the local machine clock. Interval in minutes to check if EtaPRO has been reconfigured and if tags have been added, edited, or removed. Data Buffering In the event that connectivity between the Acquisition Transport Interface and its destination is lost, the EtaPRO Data Interface will continue to acquire data from the data source. It will store the acquired process data in a series of buffer files as specified by each Interface Instance. These buffer

21 Interface Configuration 3-5 files will typically be stored in a folder titled Buffer in the installation (C:\Program Files (x86)\general Physics Corporation\EtaPRO Data Interface\Buffer) path or folder. Interface (Instance A ) Interface (Instance B ) Instance A Buffer File 1 (100 MB) Instance A Buffer File 2 (100 MB) Instance A Buffer File 3 (100 MB) Instance A Buffer File 1 (200 MB) Instance A Buffer File 2 (200 MB) Each Interface Instance has the option to allow/disallow data buffering to occur, as well as how much data it will store. Each instance stores its data into its own set of buffer files, and this is configured by setting the Buffer File Count and the Buffer Size. By default, each Interface Instance will buffer to three buffer files with a size of 100 MB per file. Interface Instance A Buffer: 3 Files 100 MB Instance A Buffer File 1 100% Full (100 MB) Instance A Buffer File 2 20% Full (20 MB) Take the image above as an example. The interface is configured for a Buffer File Count of three and a Buffer Size of 100 MB each. At the start of buffer operations, the Interface Instance will create the Buffer File 1 and begin buffering data into the file. If connection between the Acquisition Transport Interface and its destination is not reestablished, the Interface Instance will continue writing into that file until it has reached 100 MB in size. At that point it will create Buffer File 2 and continue buffering to that file. This process will continue until the Buffer File Count has been reached. Interface Instance A Buffer: 3 Files 100 MB Instance A Buffer File 1 100% Full (100 MB) Instance A Buffer File 2 100% Full (100 MB) Instance A Buffer File 3 100% Full (100 MB) Once the Buffer File Count has been reached, the Interface Instance will delete the oldest of the buffer files. In this example, it will delete Buffer File 1, and create Buffer File 4 and continue buffering into that file.

22 3-6 Interface Configuration Interface Instance A Buffer: 3 Files 100 MB Instance A Buffer File 4 0% Full (0 MB) Instance A Buffer File 2 100% Full (100 MB) Instance A Buffer File 3 100% Full (100 MB) To prevent filling up hard disk space, the EtaPRO Data Interface implements this buffer file recycling design. By multiplying the Buffer File Count by the Buffer Size we can determine the maximum size of our buffer. In this example, we have three buffer files at 100 MB each. Therefore, we have a capacity to buffer 300 MB worth of data. The Buffer Size is capped at 500 MB per file. However, the Buffer File Count does not have a high limit. Therefore, the total buffer capacity can be set to any capacity you wish. Interface Instance A Buffer: 3 Files 100 MB Interface Instance B Buffer: 2 Files 200 MB Instance A Buffer File 1 (100 MB) Instance A Buffer File 2 (100 MB) Instance A Buffer File 3 (100 MB) Instance A Buffer File 1 (200 MB) Instance A Buffer File 2 (200 MB) It is important to note that each Interface Instance has its own set of buffer files. Therefore, you could have two separate interfaces buffering to two separate sets of files. As shown in the example above, Interface Instance A has a total buffer capacity of 300 MB and Interface Instance B has a total buffer capacity of 400 MB. Therefore, the computer where both instances are hosted must have the necessary hard disk space to hold an additional 700 MB of potential data. Since it is not a good idea to fill up a hard drive with buffer data, it is important to know exactly how much or how many values can be put in a buffer file of a given size. Knowing this you can determine how many hours or days you can buffer data without recycling that first buffer file. Each data value that is buffered is comprised of four properties: Property Size (Bytes)* Tag Index 4 Timestamp 8 Quality 2 Value* 4* Total 18 * The size of the value property is variable on a tag by tag basis and is set by the Data Type property on the tag itself. However, the default and most common type is SinglePrecision which has a size of 4 Bytes. The total size of a single data value is 18 Bytes. Therefore, it simply becomes simple math to determine how many points will fit into a single buffer file. For example, for an Interface Instance with a Buffer File Count of three and a Buffer Size of 100 MB, the number of values that can be stored in a single file as shown below:

23 Interface Configuration 3-7 The total buffer capacity is: 100 MB 1024 kb 18 B 1 MB 1024 B 1 kb values file values 1 file 3 Files values So with three buffer files at 100 MB each, it is possible to store over 17 million values. You will need to examine your EtaPRO system and determine how many points are being acquired through this Interface Instance. For example, if the EtaPRO Server has 220 acquired points per unit and is running three units with 20 points come from a separate data source, the total number of points would be: (220 Total Points 20 Another Source) 3 Units = 600 points EtaPRO commonly acquires data on one minute intervals. Therefore, Refresh Rates are usually set to reflect that update rate. For this example, each unit is set into its own Refresh Rate, each offset ten (10) seconds from the previous with a period of one minute. So within a one minute period, the Interface Instance would acquire 600 points values 600 values update 1 min 1 update 1 hour 60 min 1 day 20 days 24 hour Based on the above example, you can store 20 days of data for 600 points with a Buffer File Count of three and a Buffer Size of 100 MB. However, if the Refresh Rates were changed to a period 30 seconds, the total number of days would drop to 10 days. Logging Logs for the Interfaces are kept in in a Logging directory within the install location on the host computer. New log files are created at the start of every day. To force log files to be deleted after a given number of days, set Allow Log Purge to True, and set Days of Logs to the desired days of logs to keep. Every day, when a new log file is created, it will delete the log files older than the specified Days of Logs. Refresh Rates The Refresh Rate sets the rate at which the interface will attempt to read the data from the data source and refresh the current values. Each Refresh Rate consists of an identifier number, a period, and an offset. Each interface is given a default Refresh Rate of 1-00:01:00. This is read as Refresh Rate number 1 (one) with a period of one minute and no offset. If an offset is present, the offset will be shown in-line with the period after a semicolon. For example 2-00:00:30; 00:00:15 would represent Refresh Rate number 2 (two) with a period of 30 seconds offset by 15 seconds. The period for a Refresh Rate works in relationship with the clock, meaning that a refresh rate of 00:01:00 will begin refreshing data every minute at the top of the minute, and a refresh rate of 00:00:15 will update at 0 seconds, 15 seconds, 30 seconds and 45 seconds past the minute. To offset refresh times, use an offset. An offset will adjust the time the interface refreshes. For example, for a Refresh Rate of 00:01:00; 00:00:05, the interface will refresh every minute at five seconds after the top of the minute. Refresh Rates can be added, modified or deleted, by clicking the appropriate button next to the Refresh Rate list box. Add New Refresh Rate 1. Click the Add New button to create a new Refresh Rate.

24 3-8 Interface Configuration 2. The Refresh Rate dialog displays. Enter the new period values in the Period group box, and, if appropriate, new offset values in the Offset group box. Click OK to close the dialog and add the refresh rate. The OK button is only enabled when the period entered is greater than zero seconds. Edit Refresh Rate 1. To edit a Refresh Rates, highlight the refresh rate in the list and click Edit. 2. The Refresh Rate dialog will display with the values for that Refresh Rate.

25 Interface Configuration Enter new values for the period and/or offset and click OK. 4. The new refresh rate will be reflected in the Refresh Rate list. Remove Refresh Rate To remove a refresh rate, highlight the refresh rate in the list and click Remove.

26 3-10 Interface Configuration Data Source Interface Configuration Options Refer to Chapter 4: EtaPRO Data Interfaces for an explanation of how to configure each of the interfaces. Data Transport Interface Configuration Options EtaPRO is still the only destination for data collected by the EtaPRO Data Interfaces. However, the EtaPRO Data Interfaces support the transportation of data through intermediaries. The Data Transport Interface handles the transportation of the data from the EtaPRO Data Interface service. EtaPRO Data Interface Computer Interface (Instance A ) EtaPRO Server Computer Data Acquisition A Events Acquisition Transport Interface EtaPRO Server Read Only Data Source A The above diagram illustrates a traditional schematic for two separate computers, one running the EtaPRO Server software and the other running EtaPRO Data Interface(s). While this configuration is very common, it relies on two way (bi-directional) communication between the EtaPRO Data Interface(s) and the EtaPRO Server. While communication or commands are always initiated on the by the EtaPRO Data interface, the EtaPRO Server must respond to these requests, this is the nature of TCP/IP communication. Nothing that uses TCP/IP communication can ever be truly one-directional.

27 Interface Configuration 3-11 In situations where due to security, infrastructure, or networking constraints, direct communication between the Acquisition Transport Interface and the EtaPRO Server is not allowed, it is necessary to go through an intermediary. EtaPRO Data Interface Computer Interface (Instance A ) EtaPRO Server Computer Interface (Instance A ) Data Acquisition A Read Only Events Acquisition Transport Interface B Data Acquisition B Events Acquisition Transport Interface C Data Source A Write Only Intermediary Read Only EtaPRO Server As shown in the diagram above, the EtaPRO Data Interface computer is not in direct communication with the EtaPRO Server computer. Instead, all the data is passed through an intermediary object. When an intermediary is added, you are required to install and configure another Interface Instance on the EtaPRO Server computer. Also, the Acquisition Transport Interface B needs to correspond with Data Acquisition B. Acquisition Transport SMTP Microsoft Exchange Mail Server Data Acquisition IMAP Microsoft Exchange POP3 The EtaPRO Data Interfaces can use an system as an Intermediary, where direct connection between two machines is not possible, but connectivity to a mail server is available. If this is the case then the corresponding protocols must be selected. Not all mail server implement every type of communication protocol, so it is important to know which ones are supported. Placing an intermediary between the EtaPRO Server and the EtaPRO Data Interface poses an issue with the configuration. Each source tag or acquired point is configured on the EtaPRO Server using the EtaPRO Client. Normally, an Interface Instance is configured to use an EtaPRO Acquisition Transport Interface. Therefore, during startup, the Interface Instance can ask the EtaPRO Server, via the EtaPRO Acquisition Transport Interface for the EtaPRO configuration. On a scheduled basis, the EtaPRO Acquisition Transport Interface requests a new EtaPRO configuration. The EtaPRO Acquisition Transport Interface will only get the new configuration if it sees that changes have been made to the system. When this occurs, the EtaPRO Server passes back a list of source tags specific to the Interface Instance. Interface (Instance A ) Data Acquisition A Events EtaPRO Acquisition Transport Give me the configuration for Instance A EtaPRO Server Read Only Data Source A Configuration for Instance A

28 3-12 Interface Configuration When an intermediary is introduced, the Acquisition Transport Interface is no longer an EtaPRO Acquisition Transport Interface, but perhaps an SMTP Acquisition Transport Interface. Therefore, the configuration for the Interface Instance cannot be obtained automatically. To obtain the configuration for an Interface Instance when using an intermediary, you will have to use the Tag Configuration File Generator. The file generated by the Tag Configuration File Generator will need to be copied manually from the EtaPRO Server computer to the EtaPRO Data Interface Computer. An important thing to note is that any time you add, remove, edit an acquired point s source tag information, you must run the Tag Configuration File Generator again, stop the EtaPRO Data Interface services, replace the file on the EtaPRO Data Interface computer, and then restart the EtaPRO Data Interface services. Tag Configuration File Generator The Tag Configuration File Generator creates a file of the current configuration of every source tag in an EtaPRO Server. To launch this tool, click the Tag Configuration File Generator icon in the Start All Programs Files EtaPRO 10 menu on the destination EtaPRO Server. 1. To generate the file required by an Acquisition Transport Interface communicating through an intermediary, enter the connection information for the EtaPRO Server. Connection Archive Database The name of the EPArchive database in SQL Password The password corresponding to a SQL user that has the rights to read data from the EPArchive database. If using Windows Authentication, leave blank. Server Name The name of the SQL Server where the EPArchive database is hosted. Use Windows Authentication TRUE Use the Windows credentials of the user currently running the utility. FALSE Use the specified SQL username/password. Username The username of a SQL user that has the rights to read data from the EPArchive database. If using Windows Authentication, leave blank. 2. Click the Test Connection button and edit the connection information, if necessary. 3. Specify the file path where the tag configuration information will be saved. Use the Browse button to locate the appropriate file path destination. 4. Click Generate to create the tag configuration file. 5. Click Close to complete the file transfer and close the Tag Configuration File Generator.

29 Interface Configuration 3-13 Advanced Send One On Failure Connection Domain Acquisition Transport Interfaces EtaPRO Acquisition Transport Interface Transporting acquired data directly to EtaPRO is the most common of the Acquisition Transport Interfaces. It communicates directly with the EtaPRO Transfer Service. If a non-connectivity error occurs while sending data to EtaPRO, the interface will try again to send each point one by one. Use this method only after discussion with EtaPRO Support. If the EtaPRO Server is using Windows authentication, it may be necessary to specify an authorized Windows user for connection to EtaPRO. If the domain, username and password are left blank, the credentials associated with the account used to run the Interface Hosting Service will be used. Computer name or IP Address of the target EtaPRO Server. Corresponding password for the entered user. EtaPRO Server Password Port Number Port used to connect to the EtaPRO Port, default port number is Security Mode EtaPRO Server authentication mode. User Username to use to connect to the EtaPRO Server. Time Stamping Adjust to EtaPRO Time Timeouts Reconnection Time TRUE Current UTC time on the local machine is compared to the current UTC time on the EtaPRO Server. Timestamps in the values coming from the interface are then adjusted to reflect the difference between the EtaPRO Server computer s UTC time and the EtaPRO Data Interface computer s UTC time. Number of seconds to wait between connection attempts if connection to the EtaPRO Server is lost. Microsoft Exchange Acquisition Transport Interface If the intermediary between the EtaPRO Data Interface computer and the EtaPRO Server computer is an server that uses Microsoft Exchange, there is a native Acquisition Transport Interface that supports Microsoft Exchange. This Acquisition Transport Interface will set the data as an attachment in the . The data will be first converted to binary format and then compressed to save space and facilitate transportation. A corresponding Data Acquisition Interface is required to convert the attachment back to values. It is highly recommended that a unique address be created only for this purpose.

30 3-14 Interface Configuration Authentication Authentication Mode Domain Password Username General Tag Configuration File Mail Message Destination Subject User Address Mail Server Auto Discover Host Exchange Server Version Hostname Method to use to authenticate to the Exchange Server: NONE No authentication is required, therefore, username and password can be left blank. USERNAME_PASSWORD A username and password will be supplied for the authentication. DEFAULT The Windows credentials of the user currently running the application will be used. Note that the credentials of the user account running the Windows Service will be used when the service is started. Optional domain of the username. Corresponding password for the username. Username to use to authenticate to the mail server. Path of the tag configuration *.XML file generated by the Tag Configuration File Generator. Address of the intended recipient of the . Subject of the mail message. This is important because the corresponding Data Acquisition Interface will search for a specific subject. address corresponding to the username or sender. TRUE Automatically discover the name of the Microsoft Exchange server using the User Address. Note that this feature may be very slow. However, it is only used one-time during startup. FALSE Use the Hostname supplied. Version of the Microsoft Exchange Server. Address of the Microsoft Exchange Server. SMTP Acquisition Transport Interface If the intermediary between the EtaPRO Data Interface computer and the EtaPRO Server is an server that supports Simple Mail Transfer Protocol (SMTP), there is a native Acquisition Transport Interface. This Acquisition Transport Interface will set the data as an attachment in the . The data will be first converted to binary format and then compressed to save space and facilitate transportation. A corresponding Data Acquisition Interface is required to convert the attachment back to values. It is highly recommended that a unique address be created only for this purpose.

31 Interface Configuration 3-15 Authentication Authentication Mode Domain Password Username Connection Use SSL Use TLS General Tag Configuration File Mail Message Method to use to authenticate to the Exchange Server: NONE No authentication is required, therefore, username and password can be left blank. USERNAME_PASSWORD A username and password will be supplied for the authentication. DEFAULT The Windows credentials of the user currently running the application will be used. Note that the credentials of the user account running the Windows Service will be used when the service is started. Optional domain of the username. Corresponding password for the username. Username to use to authenticate to the mail server. True Use SSL while connecting to the mail server. True Use TLS while connecting to the mail server. Path of the tag configuration *.XML file generated by the Tag Configuration File Generator. Destination Address of the intended recipient of the . Sender Address that will be set as the sender or From. Subject Subject of the mail message. This is important because the corresponding Data Acquisition Interface will search for a specific subject. Mail Server Hostname Address of the mail server. Port Number Port to use to connect to the mail server (Default 25). Interface Testing The EtaPRO Data Interface Configurator provides tools for testing connectivity to data sources and EtaPRO Servers. Before you start testing, you should verify that you have completed the following tasks: The EtaPRO Server is running with a current configuration. The Interface Instance General, Data Source, and Data Transport settings have been configured. The acquired point source tags are configured for the appropriate Interface Instance. If using an intermediary, the Tag Configuration Generator has been run and the configuration file placed in the directory that will be used by the Interface Host Service. Once the tasks have been completed, it is a good idea to test connectivity to both the data source and the data transport destination.

32 3-16 Interface Configuration 1. To test the connectivity to both the Data Source and the Data Transport, click the Test Connect buttons on each tab. 2. If the connection is unsuccessful, check the settings and try again. 3. Once the connection tests to the Data Source and the data transport destination are successful, click the Test Interface button to test the data acquisition process. 4. The Test Data Interface dialog displays.

33 Interface Configuration The Test Interface feature will do the following things: The interface will request the source tags based on the Instance, and then pass those tags to the Data Retriever. The Data Retriever will validate, and then connect (where applicable) to the data source. Once connection to the data source has been established, the interface will execute a refresh for each Refresh Rate. The Data Retriever will refresh the data for each tag that has been assigned to a Refresh Rate. Those values are returned in raw form to the grid, as shown below. Timestamps are the local versions of those that would be sent to EtaPRO 6. Each time the Refresh button is clicked, the interface will refresh of all the tags assigned to it. This test process will NOT send data to EtaPRO. It simply tests whether there are tags available for that instance, and if data can be acquired for those tags from the appropriate data source. 7. If connectivity is successful, click Close to return to the EtaPRO Interface Configurator. Start or Stop Interface Service Once the interface has been tested, the interface must be marked as active and the Interface Host Service started. 1. Enable the Interface Active checkbox and click OK to save the configuration data and close the configuration form.

34 3-18 Interface Configuration 2. Click OK to save the configuration data and close the EtaPRO Interface Configurator and display the EtaPRO Data Interface Service Manager. 3. To start the Interface Host Service and all of the active interface instances, click the Start button. 4. When the Interface Host Service is running, configuration changes are not permitted. Changes to the interface can only be made when the service is stopped. To stop the Interface Service, click the Stop button.

35 Chapter 4 EtaPRO Acquisition Data Interfaces EtaPRO-to-EtaPRO Data Interface OPC to EtaPRO Data Interface Text File-to-EtaPRO Data Interface Database (OLE DB/ODBC/SQL) to EtaPRO Data Interface Windows Performance Counter-to-EtaPRO Data Interface Yahoo! Finance-to-EtaPRO Data Interface Modbus-to-EtaPRO Data Interface PI-SDK-to-EtaPRO Data Interface Network Statistics Data Interface Random Number Generator Data Interface CSV File Data Interface IMAP Data Interface POP3 Data Interface Microsoft Exchange EtaPRO Data Interface EtaPRO-to-EtaPRO Data Interface Overview The EtaPRO-to-EtaPRO interface allows data to be acquired from another active EtaPRO Server. Tag Configuration The following properties must be set for source tags that use the EtaPRO-to-EtaPRO Interface: External Acquisition Item Instance The default for an EtaPRO Interface is EP. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID Either Initialization Index, Point ID, or Archive Offset to correspond to the selected Instrument ID Type. Item 1: The refresh rate ID corresponds to the number associated with the update rate defined when Refresh Rate ID setting up the data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Item 2: Unit designation of the source EtaPRO Point Unit Designation Item 3: Value Selection Item 4: Instrument ID Type Value Selection: 1 Acquired the numeric value displayed by EtaPRO. 2 Acquire the non-numeric extended value for an EtaPRO point (i.e. text). 3 Acquire the numeric raw value as acquired from the historian without alarm defaults applied. Instrument ID Type: 1 Indicates that the source point will be identified by its Initialization Index [Number] 2 Indicates that source point will be identified by its Point ID [Text] 3 Indicates that the source point will be identified using it Offset. The offset is defined in the EtaPRO database point table. EtaPRO Data Interfaces Installation & Configuration Guide 4-1

36 4-2 EtaPRO Acquisition Data Interfaces Interface Options When setting up an EtaPRO to EtaPRO Interface, there are very few Data Source options available for customization. The Data Source options for EtaPRO are the same as the options for connecting to an EtaPRO Acquisition Transport Interface. For additional information, read the section on Acquisition Transport Interfaces. EPArchive Subscription Data Interface Overview The EPArchive Subscription Interface allows data to be acquired from an active EtaPRO System with EPArchive. The EPArchive Subscription Interface must be run on the same machine as the source EtaPRO System.

37 EtaPRO Acquisition Data Interfaces 4-3 Tag Configuration The following properties must be set for source tags that use the EPArchive Subscription Interface: External Acquisition Item Instance The default for an EPArchive Subscription Interface is EPS. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID The Archive Tag Id Interface Options When setting up an EPArchive Subscription Interface, there are very few Data Source options available for customization. Connection Heartbeat Rate This is the rate in minutes to check to verify that the connection between the Interface and the Source EtaPRO System is still connected.

38 4-4 EtaPRO Acquisition Data Interfaces OPC-to-EtaPRO Data Interface Overview The OPC-to-EtaPRO Interface acquires data from an OPC DA Server. It is strongly recommended that the interface be placed on the same machine as the OPC Server or that a 3 rd party tunneller product be used. OPC Groups When reading OPC Items from an OPC DA Server, OPC Items are placed in groups. This ensures speedy and efficient data retrieval. An OPC Group is created for each refresh rate. OPC Groups should contain no more than 800 items, and only one group should be read at a time. Therefore, consideration should be given when assigning and creating Refresh Rates. It is recommended that an appropriate number of refresh rates be created to support this recommendation. Advice points, however, are grouped automatically, by a common Deadband, and then by an Advise Update Rate. OPC Group Types Some OPC servers support Advise points. Advise points will automatically report a change of data when that data moves outside a given Deadband. The OPC server will check for changes of the data based on the Advise Update Rate. Therefore, a group of points with a Deadband of 0.1 and an Advise Update Rate of milliseconds will report absolute changes of greater than.1 at a frequency of 10 seconds. The OPC Interface supports the creation of groups of Advise tags. Tags which are read when requested by a Refresh Rate are called Polled tags. The Interface supports the creation of groups of Polled tags as well. Tag Configuration The following properties must be set for source tags that use the OPC-to-EtaPRO Interface. External Acquisition Item Instance The default for an OPC Interface is OPC. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID OPC Item name. Item 1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up the Refresh Rate ID data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Item 2: Point Type Item 3: Deadband Item 4: Array Index Item 5: Advise Update Rate (ms) Point Type: 1 Advise 2 - Polled For an Advise point type, enter a deadband in the form of a float32. If the item entered is not in the form of a float32, then data will not be acquired for the tag. For a Polled point type, this should be left blank. If the OPC data type is an array, set the item to the base 0 index of the array. If the data type is an array, and no item is entered, the point will read as a data acquisition failure. If the point is not an array, this field should be left blank. For an Advise point type enter the update rate in milliseconds. For a Polled point type, this should be left blank.

39 EtaPRO Acquisition Data Interfaces 4-5 Interface Options When setting up an OPC to EtaPRO Interface, the following Data Source options are set. General Add Multiple Advise Update Rate Browse Validation Groups Active Ignore First Max Group Count OPC Read Location OPC Server Timeouts Connection Timeout Read Timeout Tags can be added to OPC Groups in bulk or one at a time. Adding OPC Items one at a time can help to troubleshoot problematic OPC Items. However, it takes considerably longer to create groups. TRUE - Add OPC Items in bulk to OPC Groups. FALSE Add OPC Items one at a time. Default Advise group update rate in milliseconds. The Advise Update Rate can be set on a tag-by-tag basis, or else set globally here Tags that contain InstrumentIDs corresponding to OPC Items that do not exist can sometimes cause issues on OPC Servers. This check cross references InstrumentIDs with all of the items found in the OPC Server and does not include tags with bad OPC Items. TRUE Performs a secondary validation using a flat OPC browse. FALSE Bypass secondary browse validation. OPC Advise Groups must be set to active before they will begin reporting changes. The OPC Group can be set active when it is being built or after all of the groups have been created. It is beneficial from a performance standpoint to wait until all the groups have been created before setting them active. TRUE OPC Groups are active when built. FALSE Groups set active after all groups are build. When first connecting to an OPC Server, the first data read from each point may contain extraneous or non-process data that refers to the connection and not the underlying data. Therefore, it is important to ignore that first data value sent from each point the first time the point is read after making the connection. TRUE Ignore the first point. FALSE Use the first point. In the OPC Interface, each tag is placed into an OPC Group. When using Polled type points, it is up to you to distribute the load of points. However, Advise type points are automatically grouped based on Deadband and Advise Update Rate. There are performance implications to having groups of very large numbers. The maximum number of OPC Items allowed in an Advise group is set here. The default setting is 800. An OPC Server can read a data value from memory (cache) or from the original data source (device). Data read from the OPC Server s memory takes considerably less time. OPC_DS_CACHE Data will be read from the OPC Server s memory or cache. OPC_DS_DEVICE Data will be read directly from the original data source and ignore the value stored in the OPC Server s cache. Name of the OPC Server. If the OPC Server is on a different computer than the interface, then this field must be in the form ComputerName OPCServerName. Length of time in seconds to wait for a connection request to return from the OPC Server. If nothing is returned in that time, it is assumed that the OPC Server is unavailable and will terminate the connection attempt. Length of time in seconds to wait for a Read request to return from the OPC Server. If nothing is returned in that time, it is assumed that the connection to the OPC Server has been lost.

40 4-6 EtaPRO Acquisition Data Interfaces Startup Wait Length of time in seconds to wait for an OPC Server to start after successful connection. Depending on the size and type of OPC Server, it may take some time for the OPC Server to build all the appropriate items and groups in memory. Text File-to-EtaPRO Data Interface Overview The Text File-to-EtaPRO Data Interface acquires data from text files. Text files can be generated by a variety of data sources. The Text File Interface watches a directory on the local machine for a new text file. Once it finds a new file, it parses the file and sends its data to an EtaPRO Server. Text File Format For the Text File Interface to work, the text file must be in the correct format and use an approved delimiter. NOTE A delimiter is a sequence of one or more characters used to specify the boundary between separate, independent regions in a plain text file. An example of a delimiter is the comma character, which acts as a field delimiter in a sequence of comma-separated values. The correct order for the text file is in the table below. Order Item Description 1 InstrumentID For data to be acquired accurately, the value for this item must correspond directly to the InstrumentID property of a source tag associated with the corresponding interface instance. 2 Value This corresponding value must match the values type selected in EtaPRO. For example, if the value type of value is set as an integer, the value cannot be a single precision or double precision data type or the data will not be converted correctly. 2 OPC Quality This quality field is optional. If quality is not included, all data will be considered goodand timestamps should not be included. The quality must be an OPC compliant quality, which can be converted to a 16-bit signed integer. 4 Timestamp The timestamp is optional. Text files are not required to place timestamp values in-line with the other three items. However, if a timestamp data is required, it must be in the form of a 64-bit integer that represents the number of ticks of the timestamp. Tag Configuration The following properties must be set for source tags that use the Text File-to-EtaPRO Interface. External Acquisition Item Instance The default instance for the Text File Interface is TXT. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance.

41 EtaPRO Acquisition Data Interfaces 4-7 InstrumentID The InstrumentID corresponds to the first item in one of the rows in the text file. The InstrumentID can be any alphanumeric string. Interface Options When setting up a Text File-to-EtaPRO Interface, the following Data Source options are set. Delimiters Comma Custom Delimiter Multiple Delimiters Semicolon Tab Text Qualifier General File Name File Wait Watch Directory TRUE Commas will be used as delimiters FALSE Commas will not be used as delimiters A single character that will be treated as another delimiter. TRUE Treat consecutive delimiters as one single delimiter TRUE Semicolon will be used as delimiters FALSE Semicolon will not be used as delimiters TRUE Tab will be used as delimiters FALSE Tab will not be used as delimiters Text Qualifiers are characters used to indicate that everything in between them should be interpreted exactly as it appears. DoubleQuotes Double quotes ( ) will be used as a text qualifier. Single Quote Single quotes ( ) will be used as a text qualifier. Name of the file, excluding the file extension, the Text File Interface should watch for. The default value is 100. Do not change this value without contacting GP Strategies Support first. Because large text files may take time to copy or write, the Text File Interface will wait until changes to the file have finished before parsing. The File Wait controls how many ticks the Interface will wait between checking the file to see if it is finished being written. Changing this value without the support of GP Strategies could cause extreme performance issues as well as a loss in data. Directory path where the Text File Interface should watch for the text file. NOTE Unlike other interfaces, the Text File Interface does not require refresh rates. Data is not read from a device based on a given timespan or time on a clock. The Text File Interface will acquire data each time a text file with the correct filename is placed in the Watch Directory.

42 4-8 EtaPRO Acquisition Data Interfaces Database (OLE DB/ODBC/SQL)-to-EtaPRO Data Interfaces Overview Three interfaces are provided for reading data from generic databases. These interfaces are the OLE DB (Object Linking and Embedding, Database), ODBC (Open Database Connectivity), and Native SQL Server-to-EtaPRO Data Interface. The settings and tag properties for these three interfaces are mostly identical with the exception of the connection string and instance property. Internally, each of the three interfaces uses different Microsoft libraries for communication. The database interfaces use queries stored in text files. These query files can be used to acquire data from different tables in the same database. Each historian source tag in EtaPRO specifies how to filter the results of a query based on the fields acquired from a database. Multiple tags can use data from the same query filtering on a unique piece of data such as an ID. It is desirable to have multiple tags retrieving data from the same query at the same time to decrease the total number of calls against the data source. Tag Configuration The following properties must be set for source tags that use the Database (OLE DB, ODBS, SQL)- to-etapro Interface. External Acquisition Item Instance The default Instance Name for the database interfaces are: OLEDB OLEDB-to-EtaPRO Interface ODBC ODBC-to-EtaPRO Interface SQL Native SQL Server-to-EtaPRO Data Interface The instance can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID Specifies the name of the query file, including file extension, that the tag receives its data from. Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up Refresh Rate the data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Item2: Specifies the time stamp field name in the results of the query that the tag receives its value from. Time Stamp Field Name Item3: Specifies the value field name in the results of the query that the tag receives its value from. Value Field Name

43 EtaPRO Acquisition Data Interfaces 4-9 Item4: Quality Field Name Item5: Filter String Name Specifies the quality field name in the results of the query that the tag receives its value from. Specifies the filter string used to retrieve a row from the query results. (Example: Use ID= PT101 to select the data in a row of a table with a field called ID that contains a value equal to PT101 ). NOTE: Refer to for more information about filter expressions. Name Connection String Query File Directory Interface Options When setting up a Database (OLE DB, ODBS, SQL)-to-EtaPRO Interface, the following Data Source options are set. Description Specifies the connection string used to establish communication with a desired data source. Connection strings contain unique information that is dependent on the data source you are connecting to. Please refer to data source s vendor documentation for the proper format and structure of the connection string. (Example: Provider=SQLOLEDB.1;Integrated Security=SSPI;Initial Catalog=Demo_Archive;Data Source= is the connection string used to establish an OLE DB connection to a SQL Server database called Demo_Archive running on a computer with an IP address of using Windows Authentication) Specifies the path to the directory that contains the query files used to retrieve data from the data source. NOTE: Refer to the following websites for information on connection strings for each database interface: OLE DB ODBC Native SQL Server

44 4-10 EtaPRO Acquisition Data Interfaces Windows Performance Counter-to-EtaPRO Data Interface Overview The Windows Performance Counter Interface is used to provide information related to the performance of the operating system and applications. Counter data can help determine system bottlenecks and fine-tune system and application performance. 1 This interface acquires performance counter data for usage in EtaPRO, and only works with counters on the local computer. It can be used to collect all types of information regarding the local machine, including, but not limited to: Hard Drive Space Memory usage (Total or Specific Applications) Network usage To view available Performance Counters on the local machine, go to Start Run and then type in perfmon.msc in the Open box. 1 Microsoft. (2011, January 20). Performance Counters. Retrieved June 29, 2011, from MSDN:

45 EtaPRO Acquisition Data Interfaces 4-11 Tag Configuration The following properties must be set for source tags that use the Windows Performance Counterto-EtaPRO Interface. External Acquisition Item Instance The default instance for the Counter Interface is WIN. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID Windows performance counters consist of three pieces of information: category name, a counter name, and an optional instance name. These three elements are put together, and separated by a pipe to form the InstrumentID. It should be in this form: CategoryName CounterName or CategoryName CounterName InstanceName. Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up the Refresh Rate ID data interface. If an invalid refresh rate is provided, data will not be acquired for the tag.

46 4-12 EtaPRO Acquisition Data Interfaces Interface Options Currently there are no Source Data options for the Windows Performance Counter- Interface. Yahoo! Finance-to-EtaPRO Data Interface Overview The Yahoo Finance-to-EtaPRO Data Interface acquires financial stock data from the search engine company Yahoo! Information on financial exchanges around the world. This data is acquired in real-time, directly from Yahoo! and sent to EtaPRO. NOTE Yahoo! delays all of their stock prices by 20 minutes. Also, exchanges are not open 24 hours a day. Therefore, depending on which value property is selected, it is possible to see values cut out when a given exchange is closed.

47 EtaPRO Acquisition Data Interfaces 4-13 Tag Configuration The following properties must be set for source tags that use the Yahoo! Finance-to-EtaPRO Data Interface. External Acquisition Item Instance The default Instance name for the Yahoo! Finance-to-EtaPRO Data Interface is YHOO. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID The InstrumentID needs to be a valid stock symbol that is recognized by Yahoo!. Item1: If the entered refresh rate is invalid, it will be filtered out during the Tag Validation process. Refresh Rate ID Item2: There are many different properties for each financial symbol. Values properties are shown in the next section. Value Property Value Properties Yahoo! provides numerous properties for each stock, however EtaPRO does not recognize every option. An approved list of options is shown below. A Ask A2 Average Daily Volume A5 Ask size B Bid B2 Ask (Real-time) B3 Bid (Real-time) B4 Book Value C1 Change C6 Change (Real-time) D Dividend/Share E Earnings/Share E7 EPS Estimate Current Year E8 EPS Estimate Next Year E9 EPS Estimate Next G Day s Low Quarter H Day s High J 52-Week Low K 52-Week High G3 Annualized Gain G4 Holdings Gain G6 Holdings Gain (Real-time) I5 Order Book (Real-time) J1 Market Capitalization J3 Market Cap (Real-time) J5 Change from 52-week Low J6 Percent Change From 52- K3 Last Trade Size week Low K4 Change From 52-week High K5 Percent Change From 52- L1 Last Trade (Price Only) week High L2 High Limit L3 Low Limit M3 50-day Moving Average M4 200-day Moving Average M5 Change From 200-day Moving Average M6 Percent Change From 200-day Moving Average M7 Change From 50-day Moving M8 Percent Change From 50- O Open Average day Moving Average P Previous Close P1 Price Paid P2 Change in Percent P5 Price/Sales P6 Price/Book R P/E Ratio R2 P/E Ratio (Real-time) R5 PEG Ratio R6 Price/Book R7 Price/EPS Estimate Next Year S1 Shares Owned S7 Short Ratio T8 1 yr Target Price V Volume V1 Holdings Value V7 Holdings Value (Real-time) Y Dividend Yield

48 4-14 EtaPRO Acquisition Data Interfaces Interface Options When setting up a Yahoo! Finance-to-EtaPRO Data Interface-to-EtaPRO Interface, the following Data Source options are set. Misc Server Yahoo! has servers all over the world, select the country or region closest to ensure faster data acquisition speeds. Modbus-to-EtaPRO Data Interface Overview The Modbus-to-EtaPRO Data Interface acquires data from devices using the Modbus communications protocol. This interface is compatible with the following Modbus protocol versions: Modbus RTU Modbus ASCII Modbus TCP/IP

49 Modbus UDP/IP Modbus RTU over TCP/IP Modbus RTU over UDP/IP EtaPRO Acquisition Data Interfaces 4-15 Multiple Modbus slaves can be connected together on one connection. The Modbus-to-EtaPRO Interface allows for this behavior. Using one connection, multiple slaves with unique IDs can be defined in the interface to allow for this situation. Tag Configuration The following properties must be set for source tags that use the Modbus-to-EtaPRO Interface. External Acquisition Item Instance The default instance for the Modbus-to-EtaPRO is MOD. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID Modbus Memory Address Numeric address of the Coil or Register, if the value extends to multiple registers, the address is the first register. This number should be between 0 and 65,535. Item1: The refresh rate ID corresponds to the number associated with the update rate defined when setting up Refresh Rate ID the data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Item2: Numeric ID that corresponds to the slaves identifier. This number should be between 1 and 255. Slave ID Item3: The Modbus-to-EtaPRO Interface supports only the first four function codes: Function Code 1 Coil Status 2 Input Status 3 Holding Registers 4 Input Registers Item4: Display Mode Specify the data type of the Modbus slave, and how the bytes are arranged. 1 Signed 9 Float AB CD 2 Unsigned 10 Float CD BA 3 Hex 11 Float BA DC 4 Binary 12 Float DC BA 5 Long AB CD 13 Double AB CD EF GH 6 Long CD AB 14 Double GH EF CD AB 7 Long BA DC 15 Double BA DC FE HG 8 Long DC BA 16 Double HG FE DC BA I

50 4-16 EtaPRO Acquisition Data Interfaces Interface Options When setting up a Modbus Data Interface-to-EtaPRO Interface, the following Data Source options are set. General Connection Select the connection method and protocol version from the provided list. IP Settings IP Address When using TCP or UDP communication protocols, specify the IP Address of the slave. Port When using TCP or UDP communication protocols, specify the TCP or UDP communication port of the slave. Serial Settings Baud Rate When using a serial connection, specify the communication transmission rate. Data Bits When using a serial connection, specify the number of data bits. This number should be 7 or 8. Parity Mode When using a serial connection, specify the mode of parity checking. Serial COM Port Number Specify which serial/com port the interface should read from. Serial Mode When using a serial connection, specify which serial communication mode should be used. Stop Bits When using a serial connection, specify how many stop bits are included in the message. PI-SDK-to-EtaPRO Data Interface Overview The PI-SDK-to-EtaPRO Data Interface acquires data from the OSIsoft PI System using their SDK. The PI-SDK must be installed and correctly configured prior to the use of this interface. Tag Configuration The following properties must be set for source tags that use the PI-SDK-to-EtaPRO Interface. External Acquisition Item Instance The default instance for the PI SDK Interface is PI. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID The PI source tag name. Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up the Refresh Rate ID data interface. If an invalid refresh rate is provided, data will not be acquired for the tag.

51 EtaPRO Acquisition Data Interfaces 4-17 Interface Options When setting up a PI-SDK Data Interface-to-EtaPRO Interface, the following Data Source options are set. General PI Server Specify the IP Address or server name of the PI Server. The name must be the same as is entered in the connection form of the PI SDK. PI-AF-SDK-to-EtaPRO Data Interface Overview The PI-AF-SDK-to-EtaPRO Data Interface acquires data from the OSIsoft PI System using their AF-SDK. The PI-AF-SDK must be installed and correctly configured prior to the use of this interface.

52 4-18 EtaPRO Acquisition Data Interfaces Tag Configuration The following properties must be set for source tags that use the PI-AF-SDK-to-EtaPRO Interface. External Acquisition Item Instance The default instance for the PI AF SDK Interface is PI. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID The PI source tag name. Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up the Refresh Rate ID data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Interface Options When setting up a PI-AF-SDK Data Interface-to-EtaPRO Interface, the following Data Source options are set. General PI Server Specify the IP Address or server name of the PI Server. The name must be the same as is entered in the connection form of the PI AF SDK.

53 EtaPRO Acquisition Data Interfaces 4-19 Network Statistics The EtaPRO Data Interfaces can also be used to collect network statistics data. This is useful to monitor the statistics between the EtaPRO Data Interface machine and any other machine visible on a network over time. Tag Configuration The following properties must be set for source tags that use the Network Statistics Interface. External Acquisition Item Instance The default instance for the interface is NET. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID Hostname or IP Address of the destination computer. Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up Refresh Rate ID the data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Item 2: Number corresponding to a valid network statistic tool Tool ID 1 - Ping Round Trip Time Gets the number of milliseconds take to send an Internet Control Message Protocol (ICMP) echo request and receive the corresponding ICMP echo reply message 2 - Buffer Size Gets the length of the buffer of data received in an ICMP echo reply message 3 - TTL Gets the number of routing nodes that can forward the Ping data before it is discarded Item 3: Optionally used to set the length of the buffer of data to send in an ICMP message. Only valid when Optional Arguments Item 2 is set to 1-3. Item 4: Optionally used to set a timeout in milliseconds for the ICMP/Ping message. Only valid when Item 2 Optional Arguments is set to 1-3. Item 5: Optional Arguments Optionally sets when the data can be sent in multiple packets. Only valid when Item2 is set to 1-3. True to send the data in multiple packets False to send the data in one packet

54 4-20 EtaPRO Acquisition Data Interfaces Interface Options Currently there are no Source Data options for the Network Statistics Interface. Random Number Generator The EtaPRO Data Interface also includes a Data Acquisition Interface for random number generation. This interface will send random data values to your EtaPRO Server, which could be useful in testing. Tag Configuration The following properties must be set for source tags that use the Random Number Generator Interface. External Acquisition Item Instance The default instance for the interface is RND. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance.

55 EtaPRO Acquisition Data Interfaces 4-21 InstrumentID Item1: Refresh Rate ID Item2: Minimum Value Item3: Maximum Value None required. The refresh rate ID corresponds to a number associated with an update rate defined when setting up the data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Optional minimum value for the random number. Optional maximum value for the random number. Interface Options When setting up a Random Number Generator Interface-to-EtaPRO Interface, the following Data Source options are set. General Maximum Value Minimum Value Global maximum value for the random numbers Global minimum value for the random numbers

56 4-22 EtaPRO Acquisition Data Interfaces CSV File Data Interface For testing, or training purposes, data can be acquired from a Comma Separated Variable (CSV) File. This interface requires a CSV file setup in a specific way as shown below: InstrumentID1 InstrumentID2 InstrumentID3 InstrumentID4 Value1 Value1 Value1 Value1 Value2\Quality Value2\Quality Value2\Quality Value2\Quality More Values More Values More Values More Values The CSV File Data Interface will look at the top row of items and attempt to match InstrumentIDs from the source tags to specific columns. Then using the period set in the first Refresh Rate the interface will read one line each period. The interface will read line by line each period until it gets to the end, at which point it will go back up to the first line of data again providing a constant loop of data. The values that correspond to an InstrumentID are found in the columns below that InstrumentID. By default any value found will be considered to be Good Quality (OPC Quality = 192). However, if you wish to pass in a specific quality, use a forward or backward slash ( \ or / ) to specify a specific quality. For example, a data value with the value of 20 and good quality can be written as 20 or 20\192 (without the double quotes). To write a data value that has the value of 20 with a bad quality of 0, write 20\0. Tag Configuration The following properties must be set for source tags that use the CSV File Data Interface. Instance The default instance for the interface is CSV. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID Corresponds to an item found in the first row of the CSV file Interface Options When setting up a CSV File Data Interface -to-etapro Interface, the following Data Source options are set. General File Path An explicit path to the.csv file

57 Predictor-to-EtaPRO Data Interface Overview EtaPRO Acquisition Data Interfaces 4-23 The Predictor-to-EtaPRO Data Interface acquires data from the GP Strategies Predictor System Tag Configuration The following properties must be set for source tags that use the Predictor-to-EtaPRO Interface. External Acquisition Item Instance The default instance for the Predictor Interface is PRE. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique Instance. InstrumentID The TDX number associated with the measurement Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up the Refresh Rate ID data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Item 2: Value Index Interface Options When setting up a Predictor Interface-to-EtaPRO Interface, the following Data Source options are set. General Predictor Server Name Specify the IP Address or server name of the Predictor

58 4-24 EtaPRO Acquisition Data Interfaces Wonderware SDK Interface Overview The Wonderware SDK-to-EtaPRO Data Interface acquires data from the Schneider Electric Wonderware Historian through their SDK. Tag Configuration The following properties must be set for source tags that use the Wonderware SDK-to-EtaPRO Data Interface. External Acquisition Item Instance The default instance name for the Wonderware SDK Interface is WWSDK. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique instance name. InstrumentID The Wonderware tag name Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up the Refresh Rate ID data interface. If an invalid refresh rate is provided, data will not be acquired for the tag. Interface Options When setting up a Wonderware SDK Interface-to-EtaPRO Interface, the following Data Source options are set.

59 EtaPRO Acquisition Data Interfaces 4-25 General Domain Password Servername Username The domain of the user, if necessary, that has authorization to read data from Wonderware Corresponding password for the entered user Computer name or IP Address of the source Wonderware Server Username to use to connect to the Wonderware server that is authorized to read data Wonderware Database Interface Overview The Wonderware Database-to-EtaPRO Data Interface acquires data from the Schneider Electric Wonderware Historian through their Oledb driver. This interface works by connecting directly to the Wonderware Historian Database and querying for the information directly. Tag Configuration The following properties must be set for source tags that use the Wonderware Database-to-EtaPRO Data Interface. External Acquisition Item Instance The default instance name for the Wonderware Database Interface is WWDB. It can be changed to any alphanumeric string of less than 512 characters when setting up the interface. Each interface associated with an EtaPRO server must have a unique instance name. InstrumentID The Wonderware tag name Item1: The refresh rate ID corresponds to a number associated with an update rate defined when setting up the Refresh Rate ID data interface. If an invalid refresh rate is provided, data will not be acquired for the tag.

60 4-26 EtaPRO Acquisition Data Interfaces Interface Options When setting up a Wonderware Database Interface-to-EtaPRO Interface, the following Data Source options are set. General Password Servername Use Windows Authentication Username Corresponding password for the entered user Computer name or IP Address of the source Wonderware Server Database True Use the Windows credentials of the user running the service to connect to the Wonderware Server Database. False Use the inputted credentials Username to use to connect to the Wonderware Server Database that is authorized to read data IMAP Data Interface This is one of the interfaces you can use when using an system as an intermediary between your EtaPRO Data Interface computer and the EtaPRO Server computer. If the server you select as your intermediary supports Internet Message Access Protocol (IMAP), this interface will communicate natively with the server. This will convert the attachment created by one of the Acquisition Transport Interfaces back to data values. Tag Configuration There is no tag configuration for the IMAP Data Interface. The Acquired Point source tags should be configured for the underlying data source. If the actual source data is coming from an OPC server, the tags should be configured as per the OPC Data Interface. Interface Options When setting up an IMAP Data Interface, the following Data Source options are set. Authentication Domain Password Username Optional domain of the username. Corresponding password for the username. Name of the user to use to authenticate to the mail server.

61 EtaPRO Acquisition Data Interfaces 4-27 Connection Use SSL Use TLS Mail Message Subject TRUE Use SSL while connecting to the mail server. TRUE Use TLS while connecting to the mail server. Subject of the mail message to search for in the inbox. This should correspond to the subject of the mail message on the Acquisition Transport Interface. Mail Server Hostname Name or address of the IMAP Server. Port Number Port number to use to connect to the IMAP Server (Default 143). POP3 Data Interface This is one of the interfaces you can use when using an system as an intermediary between your EtaPRO Data Interface computer and EtaPRO Server computer. If the server you select as your intermediary supports Post Office Protocol Version 3 (POP3), this interface will communicate natively with the server. This will convert the attachment created by one of the Acquisition Transport Interfaces back to data values. Tag Configuration There is no tag configuration for the POP3 Data Interface. The Acquired Point source tags should be configured for the underlying data source. If the actual source data is coming from an OPC server, the tags should be configured as per the OPC Data Interface. Interface Options When setting up a POP3 Data Interface, the following Data Source options are set. Authentication Domain Password Username Connection Use SSL Mail Message Subject Optional domain of the username Corresponding password for the username Name of the user to use to authenticate to the mail server True Use SSL while connecting to the mail server Subject of the mail message to search for in the inbox. This should correspond to the subject of the mail message on the Acquisition Transport Interface

62 4-28 EtaPRO Acquisition Data Interfaces Mail Server Hostname Name or address of the POP3 Server Port Number Port number to use to connect to the POP3 Server (Default 110) Microsoft Exchange Data Interface This is one of the interfaces you can use when using an system as an Intermediary between your EtaPRO Data Interface Computer and EtaPRO Server Computer. If the server you select as your Intermediary, supports Microsoft Exchange 2007 SP1 or newer this interface will communicate natively with the server. This will convert the attachment created by one of the Acquisition Transport Interfaces back to data values. Tag Configuration There is no tag configuration for the Microsoft Exchange Data Interface. The Acquired Point Source Tags should be configured for the underlying data source. If the actual source data is coming from an OPC server, the tags should be configured as per the OPC Data Interface. Interface Options When setting up a POP3 Data Interface, the following Data Source options are set. Authentication Authentication Mode Domain Password Username Mail Message Subject User Address Mail Server Method to use to authenticate to the Exchange Server. None No authentication is required, therefore, username and password can be left blank. Username_Password A username and password will be supplied for the authentication. Default The Windows credentials of the user currently running the application will be used. Note that the credentials of the user account running the Windows Service will be used when the service is started. Optional domain of the username. Corresponding password for the username. Name of the user to use to authenticate to the mail server. Subject of the mail message to search for in the inbox. This should correspond to the subject of the mail message on the Acquisition Transport Interface. address corresponding to the username or sender.