PI Event Frame Generator (PIEFGen) Version User Guide

Transcription

1 PI Event Frame Generator (PIEFGen) Version User Guide

2 OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA USA Tel: (01) Fax: (01) Web: PI Event Frame Generator (PIEFGen) User Guide 2015 by OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PI Web API, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners. U.S. GOVERNMENT RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, LLC. Version: Published: January 2015

3 Contents Introduction to PI EFGen... 1 PI BaGen and PI EFGen feature comparison...3 Related manuals... 4 Supported features... 4 Supported platforms... 5 How PI EFGen works... 7 Configure PI EFGen... 7 Generate event frames...8 Event start and end detection...10 Hierarchical events Top-down hierarchical configuration Bottom-up hierarchical configuration (PIBaGen compatibility mode) Installation of PI EFGen System requirements...17 Install PI EFGen Configuration of PI EFGen...21 Interface Selection tab...21 Create a new instance of the PI EFGen interface File Selection tab Server Information tab Event Frame Structure tab PI BaGen compatibility mode Other settings Templates tab Define attribute templates Time Settings tab Operational Settings tab Test Configuration tab...30 View File tab Service tab...31 Converter tab Backfill event history PI EFGen modes of operation Recovery examples...34 Diagnostics and monitoring...38 Health monitoring points...38 Performance counter points Timer points PI EFGen advanced topics Configuration tutorial for PI EFGen...45 Set up PI data Configure scan classes for PI Performance Equation Scheduler PI Event Frame Generator (PIEFGen) User Guide iii

4 Contents Create digital state set for phases Create simulation PI points Import the PI AF data structure Configure event frames for the example...50 Configure downtime events Configure temperature excursion events Configure batch events...54 Configure batch events that span multiple reactors Configure daily and hourly time events for Factory Configure time events for Factory Generate event frames for the example View event frames in PI System Explorer...59 PI ProcessBook example Error and informational messages for PI EFGen Technical support and other resources iv PI Event Frame Generator (PIEFGen) User Guide

5 Introduction to PI EFGen PI Event Frames Generator (PI EFGen) generates events (event frames) in the PI AF database based on values from trigger points in the PI Server. Using event frame templates in PI AF, PI EFGen populates event frame attributes from point data, handles complex hierarchical events like batches, and migrates existing PI Batch Generator (PIBaGen) configurations to event frames so you can continue using your current batch structure. The following are notable features of PI Event Frames Generator: Generate events Easily configure event generation and automatically generate your events from the trigger points that are already collecting data in the PI Server. The screen shot below shows an example of downtime events being created using PI EFGen: Handle multiple event types Generate all your different event types, such as downtime, excursions, batches, and other events, on the same asset with no restrictions on overlapping events. Standardize using event frame templates and populate event attributes Different event types have different attributes and information that are important for analysis. Standardize your events using event frame templates, and use PIEFGen to automatically populate event s attributes with data from PI points. Generate complex event hierarchies like batches Create and relate complex events such as batch processes, which have levels of events like procedures, unit procedures, operations, and phases, while maintaining the parent/child relationships. Recover history and backfill events If PIEFGen loses its connection to the PI Server, your events are recovered upon reconnection, using built in history recovery. You never lose events when you have the PI Event Frame Generator (PIEFGen) User Guide 1

6 Introduction to PI EFGen underlying PI System data. Unlike the legacy PI Batch Generator (PIBaGen), you can recover events without manually deleting records before recovery. PIEFGen enables you to define your history recovery time window, then it recovers the events from previous time periods automatically. High availability and failover If you have a primary and secondary PI Server (HA PI Server Collective), PIEFGen can be configured to retrieve the trigger point information from the secondary PI Server automatically upon failure. To ensure continuous creation of events, you can run multiple instances of PIEFGen using interface-level failover. Finally, if you have a high-availability PI AF server, your events are stored redundantly, so the data is always available. Flexible deployment Unlike PIBaGen, PIEFGen can be run anywhere in your PI System architecture. OSIsoft recommends that you install it on your PI AF Server or on a PI interface node. Easy migration from PI Batch Generator Using the PIBaGen Converter tool, existing PIBaGen configurations that write to PI Batch can easily be migrated to PIEFGen to create the same events using event frames. After migrating, you can enhance your configuration to take advantage of features like event frame templates and attributes. Configuration tool Event Frames Interface Manager enables you to configure all event frame interfaces using a graphical user interface, rather than manually editing text files. PI Event Frames Generator does not have the following capabilities at this time: Using PI AF element attributes as event triggers or event attribute values Events are triggered using PI points. Configure using PI AF element templates You cannot use PI AF element templates during configuration. If the same event (such as downtime) needs to be created on the same type of asset (such as boilers), you must configure a trigger for each boiler. However, configurations can be easily copied, pasted, and edited to aid in configuring large numbers of assets. The following table compares the terminologies used by OSIsoft batch technologies: ISA S88 PI Batch PI Event Frame Level PIEFGen Event Frame Templates Procedure PIBatch 1 Procedure Unit Procedure PIUnitBatch 2 UnitProcedure Operation PISubBatch 3 Operation Phase PISubBatch 4 Phase PISubBatch 5 PhaseState PISubBatch 6 PhaseStep A PISubBatch can be a child of another PISubBatch, as can SubBatches in PIEFGen. 2 PI Event Frame Generator (PIEFGen) User Guide

7 Introduction to PI EFGen Topics in this section PI BaGen and PI EFGen feature comparison Related manuals Supported features Supported platforms PI BaGen and PI EFGen feature comparison Feature PI Batch Generator (PIBaGen) PI Event Frames Generator (PIEFGen) Where are the events stored? PI Batch Database PI AF Event Frames Database (SQL Server) Event Database scalability Thousands of events Millions of events Event Trigger method PI tags PI tags Supports sub-second time stamps on active point tags Supports overlapping events on same asset? Generates complex hierarchical events (such as Batch) Automatically populates event attributes? Supports evaluation delay on event attribute population? Consecutive event / batch merging Yes No. Follows ISA S88 limitations of only 1 batch in a unit at a time Yes Very limited. Limited to the fixed fields available in PI Batch Database (BatchID, Product, Recipe, Procedure, etc.). Yes Yes Yes Yes. Multiple overlapping events can be written to the same equipment. Yes Yes. Very flexible. You can define Event Frame templates to customize different attributes for different types of events. Interface deployment options PI Server only Anywhere (recommend PI AF Server or interface node) Multiple interface instances on same server No Yes Yes Yes. Multiple interface instances can be configured on the same server. Interface-level failover No Yes. Multiple interfaces can be configured as failover pairs. History recovery Yes, automatic Yes, automatic Event backfilling HA reads: Supports HA PI Server reads for trigger tags Yes, but limited. Only since the time the last batch was written. You are required to manually delete batch records in some recovery scenarios before backfilling data. No Yes, during any time period without manual record deletion Yes. PIEFGen automatically retrieves trigger tag data from a secondary PI Server in an HA PI Server Collective. PI Event Frame Generator (PIEFGen) User Guide 3

8 Introduction to PI EFGen Feature PI Batch Generator (PIBaGen) PI Event Frames Generator (PIEFGen) HA writes: Supports HA writes to database No. Data written to local PI Server only (typically primary PI Server) Yes. Supports a HA event frames database if PI AF is configured for HA writes. Related manuals The following OSIsoft manuals can be useful when configuring different aspects of this interface. PI Server System Management Guide PI SDK User Manual PI Server Installation and Upgrade Guide Introduction to PI Server System Management PI System Explorer User Guide for details about creating event frame templates PI System Management Tools (PI SMT) online help OSIsoft manuals and help files are available from the OSIsoft Download Center. Supported features Feature APS connector Point Builder utility ICU control PI point types Sub-second time stamps Sub-second scan classes Automatically incorporates PI point attribute changes? Exception reporting Outputs from PI Inputs to PI: scan-based/unsolicited/event tags Supports questionable bit Supports multi-character point source Maximum point count Uses PI SDK PINet string support Source of time stamps History recovery Support No No No (has own configuration tool) Populates one string type PI point Yes Not applicable Not applicable Not applicable No Event-based Batch Data Generation No Not applicable Not applicable Yes: PI SDK, PI AF SDK and the PI API are installed with PIEFGen Not applicable PI event time stamp Yes 4 PI Event Frame Generator (PIEFGen) User Guide

9 Introduction to PI EFGen Feature UniInt-based Disconnected startup SetDeviceStatus Failover Vendor software required on PI interface node/ PINet node Vendor software required on foreign device Vendor hardware required Additional PI software included with interface Device point types Serial-based interface Support No Not applicable Yes Yes No Not applicable Not applicable Yes. PI System Explorer is required to configure event frame templates in PI AF. Not applicable No Supported platforms PIEFGen runs on the following Windows platforms (32-bit or 64-bit in emulation mode): Windows 2008 and Windows 2008 R2 Windows 7 Windows 8 Windows 2012 No native 64-bit builds of the interface are available. PI Event Frame Generator (PIEFGen) User Guide 5

10 Introduction to PI EFGen 6 PI Event Frame Generator (PIEFGen) User Guide

11 How PI EFGen works In addition to triggering an event frame start and end time, PI EFGen can also populate attributes to record data that accompanies the event frame (such as its name). Event frame templates can be used to represent different types of events such as downtime, startups and shutdowns, process excursions, or batch data. PI EFGen includes a graphical configuration tool, the PI Event Frames Interface Manager. You can migrate PIBaGen configurations to PI EFGen using this tool. At startup, Pi EFgen creates any required event frame templates. During operation, PI EFGen scans the PI Server data archive for changes to specified active points. When an active point indicates that an event or one of its child events has begun, PI EFGen generates an event frame, populating its attributes. If the event frame requires an asset (such as a unit) that does not exist in the AF database, PI EFGen creates the asset. When the active point indicates that the event has concluded, PI EFGen records the end time in the event frame. The following diagram shows how PI EFGen interacts with the PI Server and PI AF Server. For best performance and to minimize competition for system resources, install PI EFGen on a dedicated interface node. Ensure that it can access port 5450 on the PI Server node and port 5457 on the PI AF Server node. If you cannot run PI EFGen on a dedicated node, it is preferable to install it on the PI AF Server node rather than the PI Server node, to minimize contention. Topics in this section Configure PI EFGen Generate event frames Event start and end detection Hierarchical events Configure PI EFGen The PI Event Frames Interface Manager is a graphical user interface for configuring PI EFGen. The PI Event Frames Interface Manager is installed with PI EFGen. By default, the PI Event Frames Interface Manager is installed in the %PIPC%\ICU\Bifconfig folder. The executable name is BIFConfig.exe. PI EFGen uses the following configuration files used to store configuration settings. By default, these files reside in the %PIPC%\Interfaces\PIEFGEN directory. PI Event Frame Generator (PIEFGen) User Guide 7

12 How PI EFGen works Configuration File Interface startup batch file Interface settings file Event frame structure file Description Windows batch file that invokes the PI EFGen executable, specifying runtime settings (.bat file) Specifies the interface configuration settings (.ini file) Defines the event frame hierarchy (.xml file) Generate event frames To generate event frames, perform the following steps: Procedure 1. Determine active points and event name points. Active points contain values that indicate when events start and stop. Event name points contain values that can be assigned as meaningful names to events during generation. Active point example values: 0 (start) / 1 (end) Inactive / Active Inactive / Step 1 / Step 2 / Step 3 Event name point example value: DT :33 2. Optional but recommended: Using PI System Explorer, create AF element templates for the assets for which you want to generate events. 3. In PI System Explorer, use the AF element templates to create a hierarchy of the assets for which you want to generate events. 8 PI Event Frame Generator (PIEFGen) User Guide

13 How PI EFGen works 4. In PI System Explorer, create event frame templates for the types of events you intend to generate. The templates can include attributes, which are placeholders that are populated when events are generated. Attributes can include references to process-related data. 5. Using PI Event Frames Interface Manager, configure PIEFGen to generate event frames and populate event frame attributes. 6. Using PI System Explorer, verify events are created and attributes are populated correctly. PI Event Frame Generator (PIEFGen) User Guide 9

14 How PI EFGen works Event start and end detection There are three approaches to determining event start and end based on point value: Step Pulse Include zero-th state (Continuous): All transitions end the current event frame and start a new one. Available only for Step. The following diagram compares step and pulse active point behavior. Given the transitions shown, step configuration generates three events, while pulse generates one event. 10 PI Event Frame Generator (PIEFGen) User Guide

15 How PI EFGen works Step Any change in value ends one event and starts the next, except when the value changes to the zero-th state, which ends the current event but does not start a new event. To generate events when the active point changes to its zero-th state, enable Include zeroth state. For example, the following figure shows a set of digital values recorded by a point that is tracking phases. The zero-th state is indicated by the value Inactive. PI Event Frame Generator (PIEFGen) User Guide 11

16 How PI EFGen works Events are generated (started) for all transitions except the transition from "XFER_OUT" to"inactive". Pulse A transition from the zero-th state to any other value starts an event, and a transition to the zero-th state ends the event. The following example shows data suitable for using pulse behavior. 12 PI Event Frame Generator (PIEFGen) User Guide

17 How PI EFGen works Hierarchical events PIEFGen is capable of generating complex hierarchies of events, such as batches that contain unit procedures, operations, and phases. The screen shot below shows an example of a batch with multiple phases. PI Event Frame Generator (PIEFGen) User Guide 13

18 How PI EFGen works There are two different approaches to configuring hierarchical events with PIEFGen: top-down configuration and PIBaGen compatibility mode, which is bottom-up. The differences result from the way that PIEFGen relates different events, as described in the following sections. Topics in this section Top-down hierarchical configuration Bottom-up hierarchical configuration (PIBaGen compatibility mode) Top-down hierarchical configuration The start time and end time transitions of the level 1 event frame (/Procedure/PIBatch) is driven by the level 1 active point configuration. If a level 2 event frame (Unit Procedure/PIUnitBatch) changes to an active state while its parent level 1 event frame is active, the level 2 event frame is created as a child. If the level 1 event frame trigger changes to an inactive state, it ends the level 1 event frame and all its child event frames. The following figure shows events occurring at levels one and two and the event frames that are generated as a result. The following table lists event frames resulting from the events depicted in the figure. Event Frame Name Start Time End Time Duration Element EF1 T1 T A1 T2 T4 2 A ----B1 T3 T6 3 B EF2 T11 T A2 T11 T15 4 A ----B2 T16 T18 2 B EF3 T22 T A3 T24 T26 2 A ----B3 T26 T28 2 B 14 PI Event Frame Generator (PIEFGen) User Guide

19 How PI EFGen works Bottom-up hierarchical configuration (PIBaGen compatibility mode) In PIBaGen compatibility mode, the start and end of the level 1 event frame (Procedure/ PIBatch) is triggered by the level 2 active point and a procedure name tag that associates multiple level 2 event frames. The procedure name tag corresponds to the PIBatch index point from the legacy PI Batch Generator (PI BaGen) interface. The procedure name tag specifies the PI point containing the name of the parent level 1 event frame. A valid PI Point for this attribute provides the name of the level 1 event frame. However, the point is not the active point for level 1 event frame. In other words, transitions in this PI point do not trigger the start and end of level 1 events. A level 1 event frame is started only when a level 2 event is started and ends when all the level 2 events within the level 1 event frame end. If a new level 2 event frame is added after the level 1 event frame ends, its end time is updated with the new end time. When a level 2 event starts, the value of the procedure name tag is used as name of the level 1 event frame and as one of the search criteria that the interface uses to determine if a new level 1 event needs to be created. If there are no matching level 1 event frames within the interface s cache time, a new level 1 event is created. If a valid PI point is not specified for this attribute, the level 2 event frame does not belong to any level 1 event frame. The following figure illustrates the relationship between level 1 and level 2 events. The following table lists the events generated as a result of the preceding set of value changes. Event Frame Name Start Time End Time Duration Element EF1 T2 T A1 T2 T4 2 A ----B1 T3 T6 3 B EF2 T11 T A2 T11 T15 4 A ----B2 T16 T18 2 B EF3 T24 T A3 T24 T26 2 A PI Event Frame Generator (PIEFGen) User Guide 15

20 How PI EFGen works Event Frame Name Start Time End Time Duration Element ----B3 T26 T28 2 B 16 PI Event Frame Generator (PIEFGen) User Guide

21 Installation of PI EFGen Topics in this section System requirements Install PI EFGen System requirements To run PIEFGen, your PI AF Server must be version 2010 R3 (2.4) or higher. No specific version of PI Server is required: for best performance and highest stability, use the most recent version. Version of the PI SDK and the PI AF SDK must be installed on the PIEFGen interface node. For best performance and to minimize competition for system resources, install PIEFGen on a dedicated interface node. Ensure that it can access port 5450 on the PI Server node and port 5457 on the PI AF Server node. If you cannot run PIEFGen on a dedicated node, it is preferable to install it on the PI AF Server node rather than the PI Server node, to minimize contention. To create health points and to read the active points that trigger the start and end times of event frames, PIEFGen requires read/write access to the PI Server. To create event frames and write data to elements and attributes, the interface must be able to connect to the PI AF server. The user account under which the Event Frames Interface Manager runs must be in the local Administrators group. Set the following permissions for the user that runs the interface and all users who need to run the Event Frames Interface Manager: PI Server permissions (PI SMT: Browse to Security > Database Security) Database security: Enable read/write access for the PIPOINT table Point Database security: Set both PtSecurity and DataSecurity to read/write Enable read access to the active points PI AF Server permissions Database: read/write Categories: read Element: read/write Element templates: read Event frames: read/write If you are running PI Server or later, you can take advantage of its support for Windows Integrated Security by running the PIEFGen interface service using a Windows account that has the required permissions on the PI Server. To use Windows Integrated Security, use PI SMT to define a mapping that assigns the Windows user (or group) a PI identity that has the required permissions. For pre versions of the PI Server, you must create a PI trust for the user that runs the interface and configuration tool. Limit the trust to the hostname or IP address of the PI Event Frame Generator (PIEFGen) User Guide 17

22 Installation of PI EFGen interface node and the application name (PIEFGEN.exe for PIEFGen and BIFConfig.exe for the Event Frames Interface Manager). Installation directories PIHOME directory To configure the [PIHOME] directory, edit the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory. For 32-bit operating systems, the recommended setting is as follows: [PIPC] PIHOME=C:\Program Files\PIPC For 64-bit operating systems, the recommended setting is as follows: [PIPC] PIHOME=C:\Program Files (x86)\pipc Although the preceding examples define the root of the PIHOME directory on the C: drive, the PIHOME directory does not need to be on the C: drive. Interface installation directory By default, the interface is installed in the following directory: %PIHOME%\Interfaces\EFGEN\ Install PI EFGen This checklist summarizes the steps for installing this interface. If you are familiar with running PI data collection interface programs, this checklist helps you get the interface running. Procedure 1. Confirm that you can use PI SMT to configure the PI Server. You need not run PI SMT on the same computer on which you install the interface. 2. If you are running the interface on computer other than the server node, create a PI trust that permits the interface to write data. 3. Download and run the PIEFGen interface installation kit. 4. If you are running the interface on an interface node, verify that the system time and time zone are set correctly. 5. Run the PI Event Frames Interface Manager and configure a new instance of this interface. Essential startup parameters for this interface are as follows: Point source (/PS=x) Interface ID (/ID=#) PI Server (/Host=<node name>:<port>) PI AF server (/AFHost=<AF node name>) and database (/ AFDatabase=<databasename>) Event frame definitions 18 PI Event Frame Generator (PIEFGen) User Guide

23 Installation of PI EFGen 6. Start the interface interactively in statistics mode by specifying the command line parameter /mode=stat. Confirm that the interface can connect to the PI Server and data sources and collect data successfully. 7. Configure the interface to run as a Window service and confirm that it runs properly. 8. Restart the interface node and confirm that the interface service restarts. PI Event Frame Generator (PIEFGen) User Guide 19

24 Installation of PI EFGen 20 PI Event Frame Generator (PIEFGen) User Guide

25 Configuration of PI EFGen The following sections describe the settings required to configure event frame generation. The command line parameters that are generated in the interface batch startup file are listed where appropriate, to help you verify that you have created the desired configuration. Topics in this section Interface Selection tab File Selection tab Server Information tab Event Frame Structure tab Templates tab Time Settings tab Operational Settings tab Test Configuration tab View File tab Service tab Converter tab Interface Selection tab The PI Event Frames Interface Manager can be used to manage multiple instances of the PI EFGen interface. Use the Interface Selection tab to select the instance to configure. Create a new instance of the PI EFGen interface Procedure 1. Click Add Interface. A browse window appears. 2. Browse to the %PIPC%\Interfaces\PIEFGEN directory, select PIEFGen.exe, and click Open to dismiss the browse window. 3. Click OK. The Interface field displays the name of the PIEFGEN instance you created. File Selection tab The File Selection tab is used to select the files that store settings and the configuration for the interface instance. Files are as follows: PI Event Frame Generator (PIEFGen) User Guide 21

26 Configuration of PI EFGen Interface Settings File (.INI) Contains the interface startup parameters and configuration settings. Be sure to specify the.ini extension. Event Frames Structure File (.XML) Contains the event frame hierarchy and configuration that specifies the event triggers, the name tags, and event attribute population settings. Be sure to specify the.xml extension. Server Information tab PIEFGen reads event trigger data from PI points from a PI Server and generates event frames on a PI AF Server. PI Server Settings PI Server (/HOST) Specifies the PI Server node from which PIEFGen reads the event trigger data. Host is the IP address of the PI Server node or the fully qualified domain name of the PI Server node. If the PI Server you want to use is not in the drop-down list, you must add it to the known servers table using the AboutPI-SDK application. PI ServerUser and PI Server Password For PI Servers version and higher, use Windows Integrated Security for authentication. Omit the user name and password from these fields, and ensure that the Windows account that runs the interface has Read and Write permission for the AF Server. For PI Servers prior to version , configure a trust on the PI Server that permits access for the user running the interface or interface service. PI ServerPort The port number for TCP/IP communication. The default port (recommended) is PI AF System Settings PI AF Host and Database (/AFHOST and /AFDATABASE) The destination PI AF server node and database where you want PIEFGen to create event frames. PI AFUser and Password If you are not using Windows Integrated Security for authentication, enter the user name and password for the Windows user account that you intend to use to connect to PI AF. Event Frame Structure tab On this tab, you define the event frames to be generated for each level of your event frame hierarchy. For each level, you define the active point that triggers the start and end of the event, the method for assigning a name to the event frame, and any additional data (attributes) that you want to populate when the event starts. 22 PI Event Frame Generator (PIEFGen) User Guide

27 Configuration of PI EFGen Configuration Name Descriptive name for the event frame level that you are defining. Event Frame Template Specify the template that defines the structure of the event frames to be created for this level of the hierarchy. To define event frame templates, launch PI System Explorer and browse to the Library tab. When you define the event frame template, you can define attributes that are populated when the event frame is created. Ensure that the data type of the attributes is string. When you select an event frame template, the attribute table is populated with its attributes. Topics in this section PI BaGen compatibility mode Other settings PI BaGen compatibility mode By default, the interface uses a top-down hierarchy for creating level 1 event frames. If PIBaGen compatibility is enabled, PIEFGen creates level 1 event frames using the specified procedure name point from the level 2 event frame configuration to create the level 1 event frame. This configuration uses the same logic that the legacy PI BaGen interface uses with the batch index point. Active Point Specifies the point that triggers generation of the event frame. Name The name of the PI point (tag) that triggers the start and end of the event frame. Behavior Specifies how the values of the active point are evaluated to determine when to start and end event frames. For more information refer to How PI EFGen works. Pulse A transition from zero-th state to any other state starts an event frame, and transition to the zero-th state ends the event frame. Step All transitions end any currently-running event frame and start a new event frame unless the transition is to a zero-th state. To include transitions to the zero-th state, check Include Zeroth state (Continuous). Step + Include Zeroth State (Continuous) All transitions end any currently-running event frame and start a new event frame upon the transition including transitions to a zeroth state. An event is always running. PI Event Frame Generator (PIEFGen) User Guide 23

28 Configuration of PI EFGen Strings indicating zeroth state If you are using a string point as the active point, specify the value that indicates the zero-th state. Note that the value is case sensitive. If multiple values indicate the zero-th state, specify them as a comma-separated list (for example, "Inactive, Off"). If you omit this setting, pulse or step behavior for a string type active point is the same as continuous. Event Frame Name This section configures how the event frame name is assigned when it is generated. Use Active Point value Assign the name of the event using the value of the active point. Typical setting for step active point behavior. Use Static Name Specifies static text to be used for the name. Typical setting for an active point that represents a single sub-event (phase) starting and stopping. Use this PIPoint value Use the value of the specified point as the event frame name, which is evaluated according to the evaluation delay setting. For use when you have another point that represents the name for your event frame, typically with a pulse active point behavior. Attributes Lists string attributes from the event frame template. This table provides a mapping for PIEFGen to populate event frame attributes. To define attributes that are not included in the event frame template, add rows to the table. (The event frame template must have its Allow Extensions option enabled in PI System Explorer.) To add attributes, define them as follows: Attribute Name The name of the event frame attribute to be populated. Configuration Specifies how the attribute is populated by PIEFGen: Not Included Do not populate the event frame attribute. Choose this option if the attribute is resolved using a PI AF data reference. Static Name Specifies static text to be used for the name. PIPoint Use the value of the specified point as the attribute value, evaluated according to the evaluation delay setting. 24 PI Event Frame Generator (PIEFGen) User Guide

29 Value The setting you choose for this field depends on the option you specify for the Configuration field, as follows: Configuration of PI EFGen Configuration option Not Included Static Name PIPoint Value Blank The text to be stored in the attribute Name of the PI point from which the value is to be read Other settings Referenced Elements Specifies the PI AF elements (equipment /assets /units) associated with the event. If there are multiple elements, the first element in the list must be the primary referenced element for the event frame. Enable Activate/deactivate the PIEFGen configuration node, for testing and troubleshooting. Debug Messages Activate/deactivate debugging output. Merge Consecutive Merges consecutive event frames if they have the same name, occur within the cache time period configured, and belong to the same PIEFGen configuration. If PIBaGen compatibility mode is enabled, event frames must also have the same product and recipe event frame attributes at the top level. If the name is identical and product and recipe event frame attributes are omitted, the events are merged. When event frames are merged, the start time is taken from the first event and the end time is taken from the second event. Event frame attributes are assigned the values from the second source event frame. The following figure shows two source events and the resulting merged event. PI Event Frame Generator (PIEFGen) User Guide 25

30 Configuration of PI EFGen Recovery Time Specifies the period for which events are to be recovered. At startup, the interface checks archived values for active points for the specified period and generates or corrects event frames accordingly. If no recovery time is specified or recovery time is less than cache time, the interface recovers events for the cache time that is configured. Events that start before the recovery period and end after it are not recovered. Evaluation Delay Specifies the time that the interface waits before evaluating PI point values to populate the event frame name and event frame attributes. Does not affect event start or end time. By default, values are read at the event start time (delay is 0). To read values at the end of the event, specify -1. If the event ends before the evaluation delay elapses, values are read at the event s end time. Templates tab To override the default way that batch data is stored in the PI System, you define templates. Attribute templates enable you to record batch data in PI AF event frame attributes. To specify how the data is to be formatted, you use placeholders. For example, if you specify the following template (note the placeholders in square brackets): Sample [Time] [Descript]-[BatchID]:[Event] pvalue:[pval][eu]... resulting data is formatted like the following example: Sample 2007/12/11 05:19:12:184 Product Code:Recipe Header pvalue:undefined To enable you to precisely extract the desired data from incoming fields, batch interfaces support advanced parsing features. For detailed information about placeholders and advanced parsing, refer to the user guide for your batch interface. Define attribute templates To define attribute templates using the PI Event Frames Interface Manager: Procedure 1. On the Templates tab, right-click Attribute Templates and choose Add The Configuration pane is displayed. 2. On the Configuration pane, enter the following settings: Index: Assigns a unique numeric index for the template. Name: Specifies how the target attribute is named. To use incoming data from the data source to define how the attribute or property is to be named, click Add Placeholder Within each hierarchy, property names must be unique. By default, properties are named Event_1, Event_2, and so on. Value: Specifies the value to be recorded. Use placeholders to derive values from the data emitted by the data source. Data type: PI data type of the value. 26 PI Event Frame Generator (PIEFGen) User Guide

31 Configuration of PI EFGen Translate: If required, specifies how any English language values are to be translated before being stored in the PI System. UOM: (AF only) Unit of measure to be used to store value, if different from unit provided by data source. Advanced Features Description: (AF only) Populates the attribute's Description field. Engineering units: Unit of measurement. Category: Specifies the PI AF category to be assigned to the attribute. Level: Assign the recipe level to which the attribute is assigned, as follows: -1: Same level as data source 1: Procedure 2: Unit Procedure 3: Operation 4: Phase 5: Phase State 6: Phase Step Time Settings tab General Settings Scan (/SCAN=<seconds>) Specifies how frequently the interface scans active points. Cache time (/CACHETIME=<days>) Specifies how long completed events are retained in memory. Default is one day. Specify the maximum duration expected between event frames that need to be merged, plus any desired margin of safety. The value can be specified as whole day or fraction of a day. For example, to release completed batches when their end time is less than 7 days and 12 hours from current time, specify the following cache time setting: CACHETIME=7.5 days Abandoned batch timeout (/ABTO=<days>) Specifies how long event frames can remain open before being considered abandoned. When this period (plus cache time) elapses, the interface writes an end time to the event to close it. Specify the maximum duration expected for events, plus any desired margin of safety. For example, if you set abandoned batch timeout to 50.5 days and cache time is seven days, events open for 57.5 days are automatically closed. The following figure illustrates timeout logic. PI Event Frame Generator (PIEFGen) User Guide 27

32 Configuration of PI EFGen Maximum query time frame (/MAXQTF=<days>) To help manage workload and memory usage, defines the maximum time frame for queries. For example, if you specify 30 days and the interface queries for one year s worth of data, the interface issues 12 one-month queries rather than one (large) one-year query. Maximum stop time (/MAXSTOPTIME=<seconds>) Specifies the maximum time allowed for the interface to properly shutdown. If the shutdown process takes longer than the specified time, the interface is forced to terminate immediately. The default value is 120 seconds. Use local time stamps to process incoming events (/TS) Applies the time on the local machine to the event frame start and end, overriding the time stamp read from the active point in the PI Server. By default, time stamps are recorded using GMT. PI Connection Settings PI connection timeout (/PICONNTO=<seconds>) Override the default PI SDK Connection TimeOut property. PI data access timeout (/PIDATO=<seconds>) Override the default PI SDK Data Access TimeOut property. Retry (/RETRY=<seconds>) Specifies how long to wait before retrying a failed SDK attempt to write data to PI Server. The default is 60 seconds. Retry timeout (/RETRYTO=<seconds>) Specifies timeout for failed SDK attempts to write data to PI Server. To avoid data loss, set to 0 (default, no timeout). PI Event Frames Generator Settings Event analysis delay time Specifies how long the interface waits before analyzing incoming event triggers and creating event frames. Intended for situations where the arrival of source data required to create events is often delayed. This setting is applied to all PIEFGen configurations for an interface instance. The following figure shows how this window of time is applied to incoming data. 28 PI Event Frame Generator (PIEFGen) User Guide

33 Configuration of PI EFGen Max events in event pipe Sets the maximum number of events an event pipe can hold. It is used by PIEFGen to calculate memory allocation for processing events. The interface creates an event pipe for snapshot updates to active points. (Default is 10,000.) If you have a large PIEFGen configuration or the PIPC.log file has messages indicating that the number of events is approaching the maximum, increase this value. Operational Settings tab Runtime mode (/MODE=<mode>) Interface modes are as follows: Mode /MODE flag Description Realtime (default) REALTIME Scan active points and generate event frames according to the configuration. Recovery REALTIME with /RST specified Scan active point history and generate or correct events accordingly. PIEFGen always starts in recovery mode, then switches to realtime mode. Statistics STAT Compare active point history against events and report results without updating any data. Delete DELETE with /RST and /RET specified Perform one scan then stop (/SINGLERUN) The interface performs one scan of active points, then exits. Print result of first scan to file (/PRINT=<file name>) Delete events for a specified period. The name of the text file to which the results of the first scan are printed. The results include the event frame hierarchy tree, the point list, and the equipment tree. This parameter is designed primarily for troubleshooting and configuration testing when the interface is run in statistics mode. PI Event Frame Generator (PIEFGen) User Guide 29

34 Configuration of PI EFGen Debug level (/DB=<#>) Specifies level of detail for logging as follows: 0: Log errors and warnings (default) 1: Log errors, warnings and major successes 2: Verbose logging Numeric settings (/NS=<lang>) Configures how numeric values are formatted by the interface, to enable the interface to properly interpret numeric values based on the machine s regional setting or a user-specified language. Default is "English_UnitedStates". Interface ID (/ID=<#>) Specifies the numeric interface instance identifier (maximum nine digits) To detect PI points maintained by the interface instance, the interface matches this setting against the value in the points Location1 attribute. Point source (/PS=<x>) Point source for the interface instance. Point source is not case sensitive. Corresponds to the PointSource attribute of individual PI Points. The interface loads PI points with the same point source. The default point source is PIEFGEN. Test Configuration tab To test your configuration, specify test settings, click Run Test, then check the output file for results. Test settings are as follows: Field BAT File Output File Start Time End Time Description The path to the interface.bat file to run during the test execution The path to the text file where the test results are written Start time for scanning End time for scanning View File tab Enables you to view the contents of the Interface Configuration Settings (.INI) file. Useful for troubleshooting. 30 PI Event Frame Generator (PIEFGen) User Guide

35 Configuration of PI EFGen Service tab Setting Display Name Logon as Password Startup Type Dependencies Description The name of service as displayed in the Services control Panel. To indicate that the service is part of the OSIsoft suite of products, prefix the name with "PI". The Windows user account used to run the interface service Password for the Windows user account used to run the interface service Configures whether the service starts automatically when the interface node is rebooted Configures other services that PIEFGen requires in order to run Converter tab The conversion process creates a PI AF event frame hierarchy configuration that corresponds to the PIBaGen configuration. At startup, PI EFGen creates any required event frame templates. During operation, PI EFGen creates any required assets for units that are associated with the event frame. Conversion Process Specify conversion settings as described in the following table, then click Convert. Setting Event Frame Structure File PI Server PI AF Server and database PI Server Element in AF Description The location and name for the XML file where the Event Frame hierarchy configuration is to be stored. The PI Server name whose PIBaGen configuration is to be migrated. The PI AF Server and database to which the configuration write event frames. The PI AF Element that corresponds to the source PI Module Database root containing the PIUnits to be migrated. Backfilling Events from Migrated Configuration After completing the conversion process, you can backfill events with the migrated configuration by running PIEFGen in recovery mode. In recovery mode, PIEFGen scans archived PI data, looking for changes to active points and using the corresponding event frame templates to generate event frames and populate any event attributes. Note: To preview the results of recovery without generating event frames, choose statistics mode and specify an output file. PI Event Frame Generator (PIEFGen) User Guide 31

36 Configuration of PI EFGen Backfill event history Procedure 1. Launch the PI Event Frame Manager and browse to the Operational Settings tab. 2. From the drop-down list, choose Recovery and specify the start and end times for the desired period. 3. Browse to the Save Settings tab and click Save. 4. Run the interface. After you finish To verify that event frames have been generated correctly, use PI System Explorer to examine the results in the Event Frames tab. 32 PI Event Frame Generator (PIEFGen) User Guide

37 PI EFGen modes of operation PI EFGen can be run in the following modes: Realtime (default) Recovery Statistics Delete To set the mode, go to the Operational Settings tab in the PI Event Frames Interface Manager. The interface can be started or stopped using the PI Event Frames Interface Manager Service tab or by using the Windows Services applet. Realtime mode In realtime mode, the interface monitors active points in the PI server for changes in value that indicate the beginning or end of an event. When it detects such a change, PIEFGen creates or updates event frames in the PI AF database. During startup, the interface performs recovery for each PIEFGen configuration, based on the setting for recovery time or the global interface cache time (whichever is greater), then begins scanning active points in real time. Recovery mode Recovery mode corrects history or recovers missing data for existing AF elements, element attributes, event frames and PI points, based on the history of active points. You can specify the start and end time for the period to be recovered. If you omit end time, the interface performs recovery and then switches to realtime mode. Statistics mode In statistics mode, the interface verifies existing event frames against active point data in the PI Server for a specified time period, and reports results. If you omit the time period, results are reported from the recovery start time until the current time. Delete mode In delete mode, the interface deletes event frames from the PI AF server for a specified period. If you intend to restore history using recovery mode, ensure a correct recovery by first deleting events for the period that you intend to recover. Topics in this section Recovery examples Diagnostics and monitoring PI Event Frame Generator (PIEFGen) User Guide 33

38 PI EFGen modes of operation Recovery examples Example 1: Realtime mode with zero-day recovery time The figure below depicts a scenario in which the interface has been shut down for eight days. Recovery time is set to zero days, the interface cache time is two days, and recovery start time is not set. With these settings, the interface recovers events for the past two days (the duration of the cache time parameter, which is larger than the recovery time parameter). As a result of downtime, three event frames are not created, and must be backfilled using recovery mode. Example 2: Realtime mode with four-day recovery time In the scenario below, the interface has been shut down for eight days, recovery time is set to four days, the interface cache time is two days, and recovery start time has not been set. 34 PI Event Frame Generator (PIEFGen) User Guide

39 PI EFGen modes of operation In this example, the interface recovers events for the past four days (the duration of the cache time parameter, which is larger than the recovery time parameter). As a result of downtime, two event frames are not created, and the event spanning into the recovery time is not created. To backfill the missing history, you must use recovery mode. Example 3: Realtime mode with four-day recovery time, in-progress batch with ABTO In the scenario pictured below, the interface has been shut down for nine days. Recovery time is set to four days, the interface cache time is two days, abandoned batch timeout is set to two days, and recovery start time has not been set, so the interface is running in realtime mode. PI Event Frame Generator (PIEFGen) User Guide 35

40 PI EFGen modes of operation In this example, the interface recovers events for the past four days, the duration of the recovery time parameter (which is larger than the cache time parameter). Two event frames were not created, due to the interface downtime. Additionally, the event that was in progress when the interface was shut down has been closed with an incorrect end time, because the two-day abandoned batch timeout expired. To fix the end time based on the active point data and create the two missing events, run the interface in recovery mode and specify an end time that includes the ABTO Closed event. Example 4: Realtime mode with ten-day recovery time In the scenario below, the interface has been shut down for eight days. Recovery time is set to ten days, the interface cache time is two days, and recovery start time has not been set, so the interface is running in realtime mode. In this example, the interface recovers events for the past ten days, the duration of the recovery time parameter (which is larger than the cache time parameter). All events that occurred during the downtime are recovered, because the recovery time spans the interface downtime. Example 5: Recovery mode, recovery time = 4 days, recovery start time = 9 days ago In the scenario below, the interface has been shut down for eight days. Recovery time is set to four days, the interface cache time is two days, and recovery start time has been set to include the preceding nine days. 36 PI Event Frame Generator (PIEFGen) User Guide

41 PI EFGen modes of operation The interface recovers events for the past nine days, recovering all events that occurred during the downtime, then starts active data collection. Example 6: Recovery mode, historical recovery backfilling Given the nine events pictured in the following diagram, recovering data from 8/15/ :00:00 through 08/17/ :00:00 recovers batch 5 excursion E2, but omits the following events: Excursion E1 [outside] Excursion E3 [outside] Batch 2 [outside] Batch 4 [outside] Batch 1 [border] Downtime D1 [border] Downtime D2 PI Event Frame Generator (PIEFGen) User Guide 37

42 PI EFGen modes of operation If you omit end time, all events are recovered. Diagnostics and monitoring The following types of diagnostic points are created: Health monitoring points Performance counter points Timer points All diagnostic point names are prefixed by the interface name and the interface ID, for example: PIEFGen_1_DeviceStatus. Topics in this section Health monitoring points Performance counter points Timer points Health monitoring points The heartbeat point value is a cycle of integers from 1 to 15, updated according to the frequency defined by the /scan command-line parameter or every minute, whichever is less. The device status point is a string reflecting the interface status as follows: Good: The interface is communicating properly with the PI Server and the AF Server. 1 Starting: The interface is initializing. 4 Shutdown: The interface is shutting down. Location1 contains the interface instance ID, and the point source is the value you specify when configuring the interface instance (/PS flag). The following table lists essential attributes of the health monitoring points. 38 PI Event Frame Generator (PIEFGen) User Guide

43 PI EFGen modes of operation Point name PointType Location3 ExDesc DeviceStatus Int32 0 [UI_DEVSTAT] HeartBeat Int32 1 [UI_HEARTBEAT] Performance counter points These points are created by the interface the first time it starts. The archiving flag for these points is turned off. The following table describes the performance counter flags. All counters are reset each time the interface starts up. Point name Location3 ExDesc Description EventReadCount 2 [UI_EVENTREADCOUNT ] Number of events read since last startup. ErrorCount 3 [UI_ERRORCOUNT] Number of errors since last startup. SourceUnitCount 4 [UI_SOURCEUNITCOUN T] Number of assets found since startup. PIUnitCount 5 [UI_PIUNITCOUNT] Number of assets found and added on the PI Server since startup. SourcePhaseModCount 6 [UI_SOURCEPHASEMOD COUNT] PIPhaseModCount 7 [UI_PIPHASEMODCOUN T] SourceBatchCount 8 [UI_SOURCEBATCHCOU NT] Number of phase modules found on the data source since startup. Number of phase modules found and added on the PI Server since startup. Number of top-level event frames found since startup. PIBatchCount 9 [UI_PIBATCHCOUNT] Number of top-level event frames found and added on the PI server since startup. SourceUnitBatchCount 10 [UI_SOURCEUNITBATC HCOUNT] PIUnitBatchCount 11 [UI_PIUNITBATCHCOUN T] SourceSubBatchCount 12 [UI_SOURCESUBBATCH COUNT] Number of level 2 events (unit batches) found on the data sources since startup. Number of level 2 events (unit batches) found and added on the PI server since startup. Total number of operations + phases + phase states found on the data source since startup. PI Event Frame Generator (PIEFGen) User Guide 39

44 PI EFGen modes of operation Point name Location3 ExDesc Description PISubBatchCount 13 [UI_PISUBBATCHCOUN T] SourcePropertyNodeCo unt 14 [UI_SOURCEPROPNODE COUNT] PIPropertyNodeCount 15 [UI_PIPROPNODECOUN T] SourcePropertyEventCo unt 16 [UI_SOURCEPROPEVEN TCOUNT] PIPropertyEventCount 17 [UI_PIPROPEVENTCOU NT] SourceTagCount 18 [UI_SOURCETAGCOUNT ] Total number of child events (subbatches) found and added to the PI server since last startup. Number of property nodes found in data source since last startup Number of property nodes found and added to the PI server since last startup. Number of events to be written to the batch properties found on the data source since last startup. Number of PIProperties (events) found and added to the PI server since last startup. Number of points found on the data source since last startup PITagCount 19 [UI_PITAGCOUNT] Number of points found and added to the PI server since last startup. SourceTagEventCount 20 [UI_SOURCETAGEVENT COUNT] PITagEventCount 21 [UI_PITAGEVENTCOUN T] SourceTagAliasCount 22 [UI_SOURCETAGALIASC OUNT] Number of events to be written into points found on the data sources(s) since last startup. Number of events written into points on the PI server since last startup. Number of point aliases to be created based on the data source(s) since last startup. PITagAliasCount 23 [UI_PITAGALIASCOUNT] Number of point aliases found and added to the PI server since last startup. CachedBatchCount 24 [UI_CACHEDBATCHCOU NT] OpenBatchCount 25 [UI_OPENBATCHCOUNT ] Number of batch objects cached in the local memory. Subset of cached objects that have no end time set. 40 PI Event Frame Generator (PIEFGen) User Guide

45 PI EFGen modes of operation Point name Location3 ExDesc Description WaitingForEquipmentU B 34 [UI_UBWAITFOREQUIP] Number of unit batches that do not have equipment allocated yet. The allocation is checked by the PI Server synchronization routine. Timer points Three tasks are tracked and per-scan readings are recorded for the following: Reading the data source Caching local data Synchronizing cached data with PI server The following table lists essential attributes for the timer flags. The prefix for the point name is PIEFGen_<InterfaceID>. All counters are reset every time the interface starts. Point name Location3 ExDesc Task timed SourceReadTime 26 [UI_SOURCEREADTIME] Read data from data source (PI Server). TagCacheTime 27 [UI_TAGCACHETIME] Populate the local point cache. BatchCacheTime 28 [UI_BATCHCACHETIME] Populate the local batch cache. EquipmentCacheTime 29 [UI_EQUIPCACHETIME] Populate the local equipment (module) cache. BatchSyncTime 30 [UI_BATCHSYNCTIME] Synchronize local batch cache with the AF server. TagSyncTime 31 [UI_TAGSYNCTIME] Synchronize local point cache with the PI server. EquipmentSyncTime 32 [UI_EQUIPSYNCTIME] Synchronize local equipment cache with the AF server. TotalTime 33 [UI_TOTALTIME] Read data, cache it in the local memory and synchronize local cache with AF server. PI Event Frame Generator (PIEFGen) User Guide 41

46 PI EFGen modes of operation 42 PI Event Frame Generator (PIEFGen) User Guide

47 PI EFGen advanced topics Running multiple interface instances To run multiple instances of PIEFGen, assign each instance a unique ID and point source and configure points accordingly. PI Event Frames Interface Manager enables you to configure multiple instances. Failover To configure failover, you create multiple identically-configured instances of the interface. In addition, you must configure a unique failover ID for each instance (/ failoverid=<identifier>), the failover point that is used to coordinate failover (/ failovertag=<tagname>), and the amount of time that the current primary interface must be unavailable before failover occurs (/swaptime=<time in seconds>). When the interfaces are configured for failover, the current primary interface writes events to the failover point using the following format: FailoverID Last-processed timestamp in UTC For example: interface Backup instances read the failover point. If the swap time is exceeded, indicating that the primary interface has become unavailable, the backup instance verifies the data and events in the cache time prior to the latest processed time stamp, then takes over data collection. History recovery: backfilling data You can use history recovery to fill gaps in your event frame history, for example, gaps caused by computer downtime. To ensure data integrity, do not change the structure of your event frame templates or PIEFGen configuration hierarchy when recovering data. If you need to change the structure, first delete all event frames using delete mode, then run the interface in recovery mode. High Availability PI Server and AF Server If the primary PI Server goes down, PIEFGen switches to the secondary. However, if the primary AF Server goes down, PIEFGen cannot write to the secondary AF Server. Running PIBaGen and PIEFGen simultaneously You can run both the legacy PIBaGen interface and PIEFGen simultaneously against the same PI Server. The PI Event Frames Interface Manager can convert your PIBaGen configuration to PIEFGen. If both interfaces are running simultaneously, they monitor the same active points and generate the same events. PIBaGen writes the events to the PI Batch Database while PIEFGen write the events to the PI Event Frames Database in PI AF. PI Event Frame Generator (PIEFGen) User Guide 43

48 PI EFGen advanced topics 44 PI Event Frame Generator (PIEFGen) User Guide

49 Configuration tutorial for PI EFGen This tutorial contains several examples that show you how to configure PI EFGen to create event frames in PI AF. The examples include downtime events, temperature excursions, and hierarchical batch events. To generate event frames, PI EFGen requires trigger points to be defined in the PI Server. In the examples, simulation type points are used to create the necessary data. Verify that your interface node has the following software installed: PI Event Frames Generator (PI EFGen) x or later PI Event Frames Interface Manager Verify that your PI Server node has the following software installed: PI Server 2010 R2 or later PI Performance Equation Scheduler PI Ramp Soak Simulator PI AF 2010 R3 or later with event frames (can reside on a separate node) PI System Explorer (can reside on a separate node) PI System Management Tools (PI SMT) (can reside on a separate node) PI Tag Configurator add-in to Excel (can reside on a separate node) PI ProcessBook 2012 (optional, can reside on a separate node) The following files are included in the zip file PIEFGenSim.zip. Filename PIEFGenSim_TagConfig.xlsx PIEFGenSim_PIAFImport.xml PIEFGenSim_PBDisplay.pdi PIEFGenSim.ini PIEFGenSim.xml Description Points to export to the PI Server Example elements and event frame templates to import into PI AF Element-relative PI ProcessBook display file PI EFGen configuration file PI EFGen XML configuration file Topics in this section Set up PI data Configure event frames for the example Generate event frames for the example View event frames in PI System Explorer PI ProcessBook example PI Event Frame Generator (PIEFGen) User Guide 45

50 Configuration tutorial for PI EFGen Set up PI data The Pi point import file creates 18 simulation points for each of four reactors (RE100, RE200, RE300, and RE400), for a total of 72 points. For a simpler configuration, import the points for a single reactor, RE100. The PI point import file also defines 18 performance equation points that calculate different current time points that are used to assign unique IDs in the simulation. This simulation uses the PI Performance Equation Scheduler and PI Ramp Soak Interfaces to simulate PI points. To set up the data and PI AF structure required to run the examples, perform the following tasks: Procedure 1. Configure and verify the correct scan classes for PI Performance Equation Scheduler. 2. Create digital state sets for phases. 3. Configure simulation PI points. 4. Create a test PI AF database and import the AF element and template structure into PI AF. After you finish To generate event frames after setting up an example, see Generate event frames for the example. To view the resulting event frames in PI System Explorer, see View event frames in PI System Explorer Topics in this section Configure scan classes for PI Performance Equation Scheduler Create digital state set for phases Create simulation PI points Import the PI AF data structure Configure scan classes for PI Performance Equation Scheduler The examples require the following scan classes for the PI Performance Equation Scheduler: Scan class 1: 00:01:00 (no offset) Scan class 2: 00:02:00 (no offset) Scan class 3: 00:00:30 (no offset) Scan class 4: 00:00:01 (no offset) Use PI ICU or edit the PI\bin\pipeschd.bat file on your PI Server node to define the scan classes above, then stop and restart the PI Performance Equation Scheduler service. If you can t edit your current scan classes in pipeschd.bat due to other tag configurations on your system, set the Location4 attribute for all performance equation tags (point source C) to the appropriate scan class. 46 PI Event Frame Generator (PIEFGen) User Guide

51 Configuration tutorial for PI EFGen Create digital state set for phases Using PI System Management Tools, create a digital state set named EFGenSim Phases with the following states: Note: These phases are required by the examples. Do not change them. Create simulation PI points To create the required PI points, perform the following steps. Procedure 1. In Microsoft Excel, open the PIEFGenSim_TagConfig.xlsx spreadsheet and click the PISMT Tag EXPORT tab. 2. To select the simulation points that you want to create, enter an "x" in column A. By default, all points are selected. If you want to create only a subset, for example, only the points for Reactor 100, delete the "x" from the undesired entries. 3. Choose Addins > PI-SMT > Export Tag. The Export PI Tags window is displayed. 4. Verify that the correct PI Server is displayed and that Create mode is selected, then click OK. 5. To verify that the points have been created and are collecting data, connect to the PI Server using PI SMT, choose Data > Current Values, and search for "RE*" points. Import the PI AF data structure To import the required configuration into PI AF, perform the following steps: PI Event Frame Generator (PIEFGen) User Guide 47

52 Configuration tutorial for PI EFGen Procedure 1. Launch PI System Explorer, click the Database icon on the toolbar and create a database named "PIEFGenSim". 2. Choose File > Import. The Import window is displayed. 3. Browse to the PIEFGenSim_PIAFImport.xml file and click Open, then click OK. PI AF imports the file and creates the required elements. Ignore any errors resulting from duplicate units of measure. 4. To dismiss the dialog, click Close. 5. On the Library tab, verify that the following event frame templates are created (shown arranged by template reference): Note: If event frames are not created, verify that you are running a version of PI AF with event frames enabled. 6. On the Elements tab, verify that the following element structure was created: 48 PI Event Frame Generator (PIEFGen) User Guide

53 Configuration tutorial for PI EFGen 7. To verify that the element attributes for the reactors resolve to values for the simulation points, browse to one of the reactor elements and click its Attributes tab, as shown in the following figure: PI Event Frame Generator (PIEFGen) User Guide 49

54 Configuration tutorial for PI EFGen Configure event frames for the example If you prefer to import the configuration rather than configure it manually, copy PIEFGenSim.ini and PIEFGenSim.xml from the examples directory to the PIEFGen installation directory and load the configuration using the PI Event Frame Interface Manager. All examples require these two files. To best understand the contents of the events that are generated based on an example configuration, use PI System Explorer to view the event frame template that the example uses. Before configuring events, set up the interface using the PI Event Frame Interface Manager as follows: Procedure 1. On the Interface Selection tab, click Add Interface, browse to the directory where you installed the PIEFGen interface, choose the PIEFGEN.exe file and click OK. 2. On the File Selection tab, browse to the Examples directory in the PIEFGen installation directory and select the following files (unless you want to configure PIEFGen manually using the tutorial steps later in this section): Interface settings file: PIEFGenSim.ini Event Frames structure file: PIEFGenSim.xml 3. On the Server Information tab, configure settings for the PI server and AF system and database that you want to use. After you finish The following figure shows downtime events created using the example configuration described in the next section. Topics in this section Configure downtime events Configure temperature excursion events Configure batch events Configure batch events that span multiple reactors 50 PI Event Frame Generator (PIEFGen) User Guide

55 Configuration tutorial for PI EFGen Configure daily and hourly time events for Factory 1 Configure time events for Factory 2 Configure downtime events To generate the downtime events, launch the PI Event Frames Interface Manager and perform the following steps: Before you start The example uses the Downtime event frame template, which you can view by launching PI System Explorer and displaying the Library tab. Procedure 1. To populate the phase and reason code attributes, display the Event Frame Structure tab, right-click PIBAGen and choose Add New Procedure. The right pane displays the configuration pane. 2. In the Configuration Name field, enter RE100 Downtime. 3. Click Template and choose the Downtime event frame template. 4. In the Tagname field, enter RE100.Downtime.Active. 5. For the Behavior setting, choose Pulse. 6. In the Event Frame Name field, choose Use this PIPoint value and specify RE100.Downtime.Name. 7. In the Attribute Name table, configure the following attributes: Reason Code Set Configuration to PIPoint and Value to RE100.Downtime.ReasonCode. Phase Set Configuration to PIPoint and Value to RE100. The following figure shows the resulting configuration. PI Event Frame Generator (PIEFGen) User Guide 51

56 Configuration tutorial for PI EFGen 8. On the Other Settings tab, enter \\AFSRV1\PIEFGenSim\Creative Chemicals \Columbus\Factory 1\RE100 (or click PI AF Element Search and browse to this element). 9. In the Default Settings section, specify the following: Recovery Time: 1 day Evaluation Delay: 40 seconds The following figure shows the resulting configuration. Replace the server name (TBROWN6400 in the example) with the name of your AF server. 52 PI Event Frame Generator (PIEFGen) User Guide

57 Configuration tutorial for PI EFGen 10. Click Save Settings and save the configuration. 11. (Optional) To preview the results, go to the Test Configuration tab and click Run Test. 12. To start event frame generation, go to the Service Configuration tab, click Install Service. After installation completes, click Run Service. After you finish To view the resulting event frames, launch PI System Explorer and display the Event Frames pane. Right-click the top node (Event Frame Searches) and choose New Search. Search for events based on the Downtime template. Configure temperature excursion events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting RE100 Excursions Excursions.Temp RE100.Excursion.Temp.Active Pulse Choose Use this PIPoint value and enter RE100.Excursion.Name In the Attribute Names table, configure the following attributes: Attribute Name Configuration Value Type PIPoint RE100.Downtime.ReasonCode Phase PIPoint RE100.Phase PI Event Frame Generator (PIEFGen) User Guide 53

58 Configuration tutorial for PI EFGen Click the Other Settings tab and configure the path for the primary reference element to refer to RE100 using the PI AF Element Search button, as shown in the following figure. In the Default Settings section, check Enable and configure the following settings: Recovery Time: 1 day Evaluation Delay: 40 seconds. To save the configuration, click Save Settings. To generate events, start the interface. Configure batch events To generate hierarchical batch events using PIEFGen and the PI Event Frames Configuration Utility, configure three levels: Procedure, Unit Procedure, and Operation, as shown in the following figure: Configuring procedure-level batch events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting RE100 Batch Procedure EFSimProcedure RE100.Active Pulse Choose Use this PIPoint value and enter TIME.YEARMONTHDAYTIME In the Attribute Names table, configure the following attributes: Attribute Name Configuration Value Product PIPoint RE100.Product Recipe PIPoint RE100.Recipe Click the Other Settings tab. Omit the Primary Reference Element. In the Default Settings section, configure the following settings: 54 PI Event Frame Generator (PIEFGen) User Guide

59 Configuration tutorial for PI EFGen Recovery Time: 1 day Evaluation Delay: 10 seconds. To save the configuration, click Save Settings. Configuring unit procedure-level batch events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting RE100 Unit Procedure (add as child of RE100 Batch Procedure) EFSimUnitProcedure RE100.Active Pulse Choose Use this PIPoint value and enter TIME.YEARMONTHDAYTIME In the Attribute Names table, configure the following attributes: Attribute Name Configuration Value BatchID PIPoint TIME.YEARMONTHDAYTIME Procedure PIPoint RE100.Procedure Product PIPoint RE100.Product Click the Other Settings tab and add RE100 as the primary reference element. In the Default Settings section, check Enable and configure an evaluation delay of 10 seconds. To save the configuration, click Save Settings. Configuring operation-level batch events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting RE100 Operation (add as child of RE100 Unit Procedure) EFSimOperation RE100.Phase Step Choose ActivePoint value No attribute configuration is required. Click the Other Settings tab. Omit the primary reference element. In the Default Settings section, check Enable and configure an evaluation delay of 10 seconds. To save the configuration, click Save Settings. PI Event Frame Generator (PIEFGen) User Guide 55

60 Configuration tutorial for PI EFGen Configure batch events that span multiple reactors This configuration uses reactors RE200 and RE300, sharing the procedure-level Event Frame Name value of TIME.YEARMONTHDAYTIME, which changes value once per hour. As a result, any unit batches for RE200 or RE300 that occurred in the same hour are merged in a single procedure-level event frame. The following sections tell you how to configure reactor RE200. After configuring this hierarchy, repeat the steps for reactor RE300. The following figure shows the resulting hierarchy: Configuring procedure-level events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Setting RExxx Batch Procedure EFSimProcedure Check PIBaGen Compatibility Mode. No attribute configuration is required. Click the Other Settings tab. Omit the primary reference element. Check Enable. In the Default Settings section, configure recovery time of 1 day and an evaluation delay of 10 seconds. To save the configuration, click Save Settings. Configuring unit procedure-level batch events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting RE200 Unit Procedure (add as child of RExxx Batch Procedure) EFSimUnitProcedure RE200.Active Pulse Choose PIPoint value and enter TIME.YEARMONTHDAYTIME In the Unit Procedure Data Attribute Names table, configure the following attributes: Attribute Name Configuration Value BatchID PIPoint TIME.YEARMONTHDAYTIME Procedure PIPoint RE200.Procedure Product PIPoint RE200.Product In the Procedure Data Attribute Names table, configure the following attributes: 56 PI Event Frame Generator (PIEFGen) User Guide

61 Configuration tutorial for PI EFGen Attribute Name Configuration Value Procedure Event Frame Name PIPoint TIME.YEARMONTHDAYHOUR Recipe PIPoint RE200.Recipe Product PIPoint RE200.Product Click the Other Settings tab. For primary reference element, configure RE200. In the Default Settings section, check Enable and configure an evaluation delay of 10 seconds. To save the configuration, click Save Settings. Configuring operation-level batch events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting RE200 Operation (add as child of RE200 Unit Procedure) EFSimUnitOperation RE200.Phase Step Choose Use Active Point value No attribute configuration is required. Click the Other Settings tab. Omit primary reference element. In the Default Settings section, check Enable and configure an evaluation delay of 10 seconds. To save the configuration, click Save Settings. Configuring events for other reactors To create the batch events for RE300, follow the preceding steps, substituting the appropriate RE300 point names for each reactor, or copy and paste the configuration from RE200 and edit the point names for each reactor-specific configuration. In this configuration, the procedure event frame name is TIME.YEARMONTHDAYHOUR for both RE200 and RE300. With this simulation, PIEFGen creates a level 1 event frame for RE200 and RE300 batch events that start within the same hour. Configure daily and hourly time events for Factory 1 Configuring daily events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting Factory 1 TIME.Day Time.Day TIME.YEARMONTHDAY Step Choose Use Active Point value PI Event Frame Generator (PIEFGen) User Guide 57

62 Configuration tutorial for PI EFGen No attribute configuration is required. Attribute Name Configuration Value Day Type PIPoint TIME.DAY_TYPE Day of Week PIPoint TIME.DAY_TEXT Month PIPoint TIME.MONTH_TEXT Year PIPoint TIME.YEAR Day Date PIPoint TIME.DAY Click the Other Settings tab. For the primary reference element, configure Factory 1. In the Default Settings section, check Enable and configure a recovery time of 5 days and an evaluation delay of 10 seconds. To save the configuration, click Save Settings. Configuring hourly events Configure the settings for this event type as follows: Field Setting Configuration Name Factory 1 TIME.Hour (add as child of Factory 1 TIME.Day) Event Frame Template Active Point Name Active Point Behavior Event Frame Name Configure attributes as follows: TIME.Hour TIME.HOUR Step Choose Use Active Point value Attribute Name Configuration Value Peak Type PIPoint TIME.HOUR.PEAKTYPE Day Date PIPoint TIME.DAY Click the Other Settings tab. For the primary reference element, configure Factory 1. In the Default Settings section, check Enable and configure an evaluation delay of 10 seconds. To save the configuration, click Save Settings. Configuring peak events Configure the settings for this event type as follows: Field Configuration Name Event Frame Template Active Point Name Active Point Behavior Event Frame Name Setting Factory 1 TIME.PeakType (add as child of Factory 1 TIME.Day) TIME.PeakType TIME.HOUR.PEAKTYPE Step Choose Use Active Point value Configure attributes as follows: 58 PI Event Frame Generator (PIEFGen) User Guide

63 Configuration tutorial for PI EFGen Attribute Name Configuration Value Peak Type PIPoint TIME.HOUR.PEAKTYPE Day Date PIPoint TIME.DAY Click the Other Settings tab. For the primary reference element, configure Factory 1. In the Default Settings section, check Enable and configure an evaluation delay of 10 seconds. To save the configuration, click Save Settings. Configure time events for Factory 2 To generate time events for Factory 2, perform the following steps: Before you start Configure daily and hourly time events for Factory 1 to create the Factory 1 TIME.Day configuration. Procedure 1. Copy and paste the Factory 1 TIME.Day configuration and rename it to Factory Change the primary referenced element to Factory Save the configuration. Generate event frames for the example After you have configured one or more event frames in PI Event Frame Interface Manager, start the PIEFGen service to create the event frame specifications in the PI AF database and begin generating event frames. Procedure 1. On the Operational Settings tab, choose Realtime mode and set Interface ID to On the Service Configuration tab, click Install Service. 3. After installation completes, click Run Service. View event frames in PI System Explorer Before you start Use the procedures in Configure event frames for the example and Generate event frames for the example to create event frames. PI Event Frame Generator (PIEFGen) User Guide 59

64 Configuration tutorial for PI EFGen Procedure 1. In PI System Explorer, click Event Frames in the navigator panel to display Event Frames view. 2. Right-click the top node (Event Frame Searches) and choose New Search. The Event Frame Search Criteria window appears. 3. In the Name is field, enter the search criteria for the event frames you want to display and click OK. PI ProcessBook example The following figure shows the element-relative PI ProcessBook display file PIEFGenSim_PBDisplay.pdi. PI ProcessBook does not support PI event frames directly at this time, but it can be used to troubleshoot the configuration used in this simulation. 60 PI Event Frame Generator (PIEFGen) User Guide