LIVE DATA INTERFACE USER GUIDE PUBLICATION HSELD-UM023A-EN-E–May 2012 Supersedes Publication HSELD-UM022A-EN-E
● ● ● Copyright ● ● Contact Rockwell Automation Customer Support Telephone — 1.440.646.3434 Online Support — http://www.rockwellautomation.com/support Copyright Notice © 2012 Rockwell Automation Technologies, Inc. All rights reserved. Printed in USA. © 2010 OSIsoft, Inc. All rights reserved. This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation Technologies, Inc.
Contents Introduction ............................................................ 1 Installation ........................................................................ 1 Features ........................................................................... 2 Related Documentation ......................................................... 3 Technical Support ................................................................ 3 Knowledgebase ...............................................................
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Point Configuration .................................................. 19 Point Attributes ................................................................. 19 Length ......................................................................... 20 Point Source .................................................................. 20 Point Type .................................................................... 20 PI 3 Server Nodes ..................
● ● Contents ● ● ● ● Performance Point Configuration ................................. 35 Startup Command File ............................................... 37 Command-line Parameters .................................................... 37 Sample FTLDInt.bat File ....................................................... 41 Setting File ....................................................................... 42 Interface Node Clock ................................................ 45 Security ..............
Chapter 1 Introduction The FactoryTalk Historian system uses the PI system as a back end to store tag data. The FactoryTalk Historian Live Data Interface (FTLD) allows FactoryTalk Historian to connect with Rockwell data sources. The FTLD interface provides buffering capability before the data is permanently stored in the Historian archive. The FTLD Interface is integrated with the FactoryTalk Live Data service provided by FactoryTalk Services Platform.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● The complete user documentation on FactoryTalk Historian SE is available in the Common Files > Rockwell > Help folder in your Program Files directory, and in the Redist > Docs folder on your FactoryTalk Historian SE installation DVD. Features The features of the FTLD Interface include: PI SDK The PI SDK and the PI API are bundled together and must be installed on each PI Interface node.
● 1 ● Introduction ● ● ● ● Related Documentation The following documentation provides additional information related to the FTLD Interface: FactoryTalk Historian SE Installation and Configuration Guide, FactoryTalk Historian SE Release Notes, both available from Start > Programs > Rockwell Software > FactoryTalk Historian SE > Help. FactoryTalk Help, available from Start > Programs > Rockwell Software > FactoryTalk Tools > FactoryTalk Help.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Subscribe to product and service e-mail notifications. Ask questions. Worldwide Support If you are not located in North America and want to contact Rockwell Automation Support, use the Worldwide Locator (http://www.rockwellautomation.com/locations/) for worldwide contact information.
● 1 ● Introduction ● ● ● ● technical resources. TechConnect service levels are provided at the TechConnect site (http://www.rockwellautomation.com/services/onlinephone/techconnect/). When you contact Rockwell Technical Support, please provide: Product name, version, and/or build numbers. Computer platform (CPU type, operating system, and version number). Exact wording of any messages that appeared on your screen. The message log(s) at that time.
● ● ● ● ● 6 FactoryTalk Historian Live Data Interface User Guide
Chapter 2 Principles of Operation The FactoryTalk Live Data (FTLD) Interface is a FactoryTalk Live Data client that enables process data to be passed between a FactoryTalk Live Data server (for example, RSLinx Enterprise) and a FactoryTalk Historian server. Each instance of the FTLD Interface can provide data to a single FactoryTalk Historian SE server or collective. Multiple instances of the interface may be configured, if required, if API buffering is used.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● The figure below shows the basic workflow of the FactoryTalk Historian Live Data Interface. Processing Loops At startup, the FTLD Interface tries to establish connection to both the FactoryTalk Live Data server and the FactoryTalk Historian server. Once startup is complete, the Interface enters the processing loop, which includes: 8 Servicing scheduled input points. Each Scan Class is processed in turn.
● 2 ● Principles of Operation ● ● ● ● Servicing output points as events arrive. Servicing triggered input points as events arrive. The Historian Point Database is checked every 2 minutes for points that are added, edited, and deleted. When point updates are detected, the points are loaded (or reloaded) by the Interface as appropriate. The 2-minute update interval can be adjusted with the /updateinterval command-line parameter discussed in the UniInt Interface User Manual.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● The count of points loaded by the interface. Error messages for points rejected by the interface because they are configured incorrectly. Error messages for points rejected by the FTLD server or error messages sent from the FTLD server. Because the FTLD Interface is based on the PI-UniInt framework, a few messages are sent to the PIPC log by the PI-UniInt.
Chapter 3 Configuring FactoryTalk Historian Live Data Interface To configure a FactoryTalk Historian Live Data Interface (FTLD), we recommend that you use FactoryTalk Administration Console. However, you must use the Interface Configuration Utility (ICU) to configure an FTLD Interface in the following cases: If you are configuring redundant FTLD Interfaces. For more information, refer to the 59932 article at the Rockwell Automation Knowledgebase (https://rockwellautomation.custhelp.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● To open the Interface Configuration Utility (ICU) online help, go to Start > All Programs > Rockwell Software > FactoryTalk Historian SE > Interface Configuration Utility, and select Help > Contents and Index from the main menu. If you create an FTLD Interface using the Interface Configuration Utility, it will not appear in the list of interfaces in the FactoryTalk Administration Console.
● 3 ● Configuring FactoryTalk Historian Live Data Interface ● ● ● ● If you configure an interface in the ICU, the batch file of the interface (FTLDInt.bat) will be maintained by the ICU, and all configuration changes will be kept in that file. To configure an FTLD Interface with the ICU: 1. Go to Start > All Programs > Rockwell Software > FactoryTalk Historian SE > Interface Configuration Utility. The Interface Configuration Utility dialog box appears. 2.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● The FTLD Interface configuration is displayed on the General page of the ICU. 6. From the Type drop-down list, select FTLDInt, if it has not been chosen automatically. 7. If necessary, edit the Scan Frequency and Scan Class values. 8. 14 Scan Frequency Indicates the frequency at which the interface reads values from the FactoryTalk Live Data server. Scan Class # Associated with the Scan Frequency value.
● 3 ● Configuring FactoryTalk Historian Live Data Interface ● ● ● ● Note that in this example the API Hostname is localhost, which means that the interface will be configured to communicate with the local FactoryTalk Historian SE server. If you want the interface to communicate with a remote FactoryTalk Historian server, you need to: 9. Add the remote server to the Connection Manager (page 16). 10. Define the remote server as the API host (page 16).
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Adding Remote Servers to Connection Manager To add a remote server to the Connection Manager: 1. In the ICU, select Interface > SDK Connections. 2. In the Connection Manager dialog box, select Server > Add Server. The Add Server dialog box appears. 3. In the Network Node text box, type the name of the remote server, and click OK. 4. In the Connection Manager dialog box, click Save.
Chapter 4 Point Source The FactoryTalk Historian Live Data Interface uses FTLD as the Point Source. A Point Source is a unique, single- or multi-character string that is used to identify a Historian point as a point that belongs to a particular interface. For example, the string Boiler1 may be used to identify points that belong to the MyInt Interface. To implement this, the Point Source attribute would be set to Boiler1 for every Historian Point that is configured for the MyInt interface.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Subsystem Point Source character RampSoak 9 Performance Equations C Do not use these Point Source characters or change the default Point Source characters for these applications. If a Point Source character is not explicitly defined when creating a PI point, the point is assigned a default Point Source character of Lab (PI 3). Therefore, do not use Lab as a Point Source character for an interface to avoid confusion.
Chapter 5 Point Configuration A FactoryTalk Historian point is the basic building block for controlling data flow to and from the FactoryTalk Historian SE server. A single point is configured for each measurement value that needs to be archived. Point Attributes Historian points (tags) have approximately 50 attributes. These attributes define how data is to be collected and stored for the point.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Length The Tag field allows a maximum of 1023 characters. Point Source The Point Source is a unique single or multiple character string that is used to identify the PI point as a point that belongs to a particular interface. The Point Source for FactoryTalk Historian Live Data Interface is FTLD. For additional information, see the /ps command-line parameter description in Command-line Parameters (page 37).
● ● 5 ● Point Configuration ● ● ● For more information on the individual point types, refer to the FT Historian SE Server Reference Guide, available in the Common Files > Rockwell > Help folder in your Program Files directory. Location1 Location1 indicates to which copy of the interface the point belongs. The value of this attribute must match the /id startup parameter. The default value for the FTLD Local Interface is 1. Location2 Location2 is not used for the FTLD Interface.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Location4 Location4 defines the scan class for the Historian point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f parameter in Commandline Parameters (page 37).
● ● 5 ● Point Configuration ● ● ● InstrumentTag InstrumentTag contains the ItemID of the tag. The format of this field depends on the FactoryTalk Live Data server: Type of the tag InstrumentTag syntax Device tags /::[] HMI tags /::\ The field must match the point defined on the FactoryTalk Live Data server, including punctuation, spaces, and case.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● SourceTag An output point is associated with a trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. For more information, see Output Points (page 25).
● ● 5 ● Point Configuration ● ● ● available in the Common Files > Rockwell > Help folder in your Program Files directory. Exception Reporting For each data point, you can set the following three attributes to configure its exception reporting specification: Exception Deviation (ExcDev): Specifies in engineering units how much a point's value must change before the interface considers it as a significant value, and sends it to the server.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Trigger Method 1 (Recommended) For Trigger Method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point.
● 5 ● Point Configuration ● ● ● ● Sample Tag Configurations See the following sample tag configurations: Scan Classes (page 27) Polled Tags (page 27) Advise Tags (page 28) Event Tags (page 28) Scan Classes Scan classes are defined in the startup file. Each /F= parameter defines a scan class, which is numbered in order. For example, if the .bat file reads /F=2 /F=1:00 /F=1:30:00 /F=00:00:05,00:00:01 then these scan classes have been defined: Scan Class 1 has a scan period of 2 seconds.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Tag InstrumentTag Loc1 Loc2 Loc3 Loc4 Loc5 OneMin.PV ItemID2 1 0 0 2 0 NinetyMin.PV ItemID3 1 0 0 3 0 Advise Tags For Advise tags, the interface asks the FTLD server to send data when it changes, and how often it should read the device to see if there is a new value. For example: Tag InstrumentTag Loc1 Loc2 Loc3 Loc4 Loc5 AdvFiveSecs.PV ItemID1 1 0 1 1 0 AdvOneMin.PV ItemID2 1 0 1 2 0 AdvNinetyMins.
● 5 ● Point Configuration ● ● ● ● If the event_condition is not specified then it defaults to Anychange. The update rate for event items groups is also related with the scan class, so the server will be asked to update its cache once every scan period for every event tag defined. That is probably faster or slower than necessary. You must set the Loc4 attribute to make event tags work well. The Location 5 attribute should have the value 1 for Event tags.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 30
Chapter 6 I/ORates Tag Configuration An I/ORates tag measures the throughput of an FTLD Interface. In particular, the value of an I/ORate point represents a 10-minute average of the total number of values per minute that the FTLD Interface sends to the FactoryTalk Historian server. Because values are averaged over a 10minute interval, the first calculated value is not written to the Historian server earlier than 10 minutes after the interface has started.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● To access the I/ORates tag data in ICU, select IO Rate from the left pane of the ICU dialog box. ICU currently allows for one I/ORates tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/ORates tags. The Input IORates Tag section contains the following elements: 32 Enable IORates for this interface Select the check box to enable I/ORates for the selected interface.
● ● 6 ● I/ORates Tag Configuration ● ● ● Suggest In the ICU dialog box, click it if you want the system to suggest Tagname Type the name of the I/ORates tag, or click the TagSearch icon to find the tag using the Tag Search dialog box. the next available Event Counter. The button is active if the Event Counter text box is empty or contains an illegal value. In the Rename IORates Tag dialog box, click it if you want the system to suggest a tag name. TagSearch.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 34
Chapter 7 Performance Point Configuration Performance Point tags document how long it takes to complete a scan. Due to the architecture of this interface, the performance point tags are not valid - the server's response is asynchronous, so the time to scan bears no relation to the amount of time it may take to get the data from the server.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 36
Chapter 8 Startup Command File In Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters. Command-line parameters should begin with a “/” character. For example, /ps=M.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Required parameters: Parameter Description /ps=Source The /ps parameter specifies the point source for the interface. The Source value is not case sensitive. The length of the Source value is limited to 100 characters by PI-UniInt. The value can contain any character except „*‟ and „?‟. The point source that is assigned with the /ps parameter corresponds to the Point Source attribute of the individual Historian point.
● 8 ● Startup Command File ● ● ● ● Parameter Description /f=SS Required for reading scanbased inputs. or The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds (ss). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Parameter Description /maxstoptime=stopti me Default = 120 seconds. /sio Default = send initial outputs. When an interface receives a signal from the operating system to shut down, it must perform a number of cleanup functions. If for some reason the execution of these functions takes longer time than the stop time, the interface will shut down without finishing these functions. The /sio parameter stands for suppress initial outputs.
● 8 ● Startup Command File ● ● ● ● Parameter Description /q Default = no queuing. When the /q parameter is present, Snapshots and exceptions are queued before they are sent to the PI Server node. The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is not filled. For an interface collecting unsolicited data, the queue is flushed four times a second if it is not filled.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Setting File For more flexibility, the FTLD interface can use an INI format file to configure interface information. This format file does not install with the FTLD interface, but you can create the file manually. It should be named FTLDInt.ini and it must be created in the same path as the FTLDInt.exe file and the FTLDIntCtl.dll file. The following is a sample setting file.
● 8 ● Startup Command File ● ● ● ● FTLDResponseInterval The FTLDResponseInterval key specifies the time interval during which the FTLD interface checks for data points that were marked „bad_quality‟ by the FTLD service.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 44
Chapter 9 Interface Node Clock Make sure that the time and time zone settings on the computer are correct. Check the settings in the Date and Time program of Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check Automatically adjust clock for Daylight Saving Time in Time Zone Settings. Make sure that the TZ environment variable is not defined on the computer. To check it, type set in the Command Prompt window.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 46
Chapter 10 Security The Trust Database must be configured so that the FTLD Interface is allowed to write data to the FactoryTalk Historian server. If the FTLD Interface cannot write data to the FactoryTalk Historian server because it has insufficient privileges, a 10401 error will be reported in the pipc.log file. The file is located in C:\Program Files\Rockwell Software\FactoryTalk Historian\Server\PIPC\DAT.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 48
Chapter 11 Starting and Stopping the Interface Once you have installed the FTLD interface as a service, you can start and stop it in two ways: Using the Interface Configuration Utility (ICU) (page 49). Using the Administrative Tools program of Control Panel (page 50). The FTLD interface service may terminate immediately after the startup for a variety of reasons. One of typical reasons is that the service is not able to find the command-line parameters in the associated .bat file.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 3. On the tool bar, click . 4. Wait, until the status on the status bar at the bottom of the dialog box changes to Running. To stop the FTLD interface: In the ICU, click on the tool bar. The service status on the status bar changes to Stopped. You may additionally check the status of the service in the Administrative Tools (page 50) program of Control Panel. Using the Administrative Tools To start the FTLD interface: 1.
Chapter 12 Error and Informational Messages The FTLD Interface is based on the PI-UniInt framework, therefore a few error messages are sent to the PIPC log by PI-UniInt. Other error messages are sent to the FactoryTalk Diagnostics system. When troubleshooting, we recommend that you check both FactoryTalk Diagnostics and the PIPC log. The following is the list of error messages sent to FactoryTalk Diagnostics. Severity Message text Error Failed to disconnect from FactoryTalk.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● Severity Message text Warning PI point <%s> is refused because of the invalid attribute of InstrumentTag. Warning PI point <%s> is refused because of the invalid attribute of Location [4]. Warning The value quality of PI point <%s (PointID: %d)> with FactoryTalk Live Data item <%s> is bad. Warning Failed to convert PIEvent to FTLD variant type of data. Warning Failed to write value to FactoryTalk Live Data item <%s>.
● ● 12 ● Error and Informational Messages ● ● ● Error Descriptions The descriptions of system and PI errors can be obtained with the pidiag utility. It is a command-line utility (pidiag.exe) located in the C:\Program Files\Rockwell Software\FactoryTalk Historian\Server\PI\Adm directory.
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● 54
Index Index A Adding Remote Servers to Connection Manager • 16 Advise and Polled Tags • 22 Advise Tags • 28 C Command-line Parameters • 37 Compression Testing • 24 Configuring FactoryTalk Historian Live Data Interface • 11 Configuring I/ORates Tag with ICU • 31 Configuring the FTLD Interface Using the FactoryTalk Administration Console • 12 Configuring the FTLD Interface Using the Interface Configuration Utility (ICU) • 12 Consulting Services • 4 D Features • 2 I I/ORates Tag Configuration • 31 Instal
● ● ● FactoryTalk Historian Live Data Interface User Guide ● ● PI 3 Server Node Reserved Point Sources • 17 PI 3 Server Nodes • 20 Point Attributes • 19 Point Configuration • 19 Point Source • 17, 20 Point Type • 20 Polled Tags • 27 Principles of Operation • 7 Processing Loops • 8 R Related Documentation • 3 S Sample FTLDInt.
