exercises piace 2.4

Training Course – PI-ACE

The information contained in this guide is confidential and may be subject to revision. No part of this publication may be reproduced or transmitted, in any form or by any means without prior permission of OSI software.

All rights reserved, OSI software Inc. 2006

Table of Contents

Exercise 1 - Simple ACE calculation ............................................................................................................. 5

Objectives ......................................................................................................................................... 5 Introduction ....................................................................................................................................... 5 Exercise ............................................................................................................................................ 5 Step-by-step solution ........................................................................................................................ 8

Exercise 2 - Pump statistics – part one ....................................................................................................... 16

Objectives ....................................................................................................................................... 16 Introduction ..................................................................................................................................... 16 Exercise .......................................................................................................................................... 16 Step-by-step solution ...................................................................................................................... 19

Exercise 3 - Pump statistics – part two ....................................................................................................... 24


Exercise 4 - Using PI ACE Manager ........................................................................................................... 32


Exercise 5 - The PI Module DataBase ........................................................................................................ 41


Exercise 6 - The Power of Multiple Contexts -- part 1 ................................................................................. 52


Exercise 7 - The Power of Multiple Contexts -- part 2 ................................................................................. 62


Exercise 8 - Deploy an ACE module ........................................................................................................... 73





Exercise 9 - Module level variable and message Logging .......................................................................... 83





Introduction

The objective of these exercises is to allow the participant to become familiar with PI ACE.

Some of the exercises are cumulative. It is important to follow each step as described in this document for the final application to work.




Exercise 1 - Simple ACE calculation

Objectives

Create an simple ACE calculation with VB6 or VB .Net

Use the ACE wizard to build the code and register the calclulation

Validate the calculation results by displaying in PI ProcessBook

Introduction

This is a simple calculation to get familiar with the process of building ACE modules. Conceptually, this could compare to a switching valve that redirects two input flows towards the output depending upon the status of the valve.

Exercise

Part A

Open Visual Studio 6 or Visual Studio .Net and create a new calculation

PI server name: localhost

PI ACE Executable name: Class_Ex1

PI ACE Class Module name: Valve

Part B

Use the following tag as input and outputs

Tag ACE usage Description

BA:Active.1 Input Valve status

Flow1 Input Input flow number one

Flow2 Input Input flow number two

Flowout Output Ouput flow redirected by the valve




Part C

Use the following logic to write the appropriate code.

If BA:Active.1 is “Active”, flowout is equal to flow1

If BA:Active.1 is “Inactive”, flowout is equal to flow2

Else flowout is equal to “Bad Input”

Part D

Debug, test and register your calculation to run every 10 seconds with normal priority. Validate the result of your calculation with a graphical display in PI ProcessBook

Do not turn to the solution on the next page until

you have tried to do this using the instructions outline above.




Step-by-step solution

Part A

1. Open VB6 or VB .Net and select the New option in the PIACEWizard menu.

2. Define your calculation (PI server and name)




Part B

1. Select input and output tags

Part C

1. Write the code needed in VB .Net




2. Or in VB6

Part D

1. Debug your calculation in VB .Net (press F5 for step by step line processing in VB .Net 2003 or F10/F11 in VB .Net 2005).




This is a temporary screen showing the loading of the PIACEClassLibraryHost EXE used to run your VB .Net DLL.

2. Or debug in VB6 (press F8 for step by step line processing).




3. Test your module (VB. Net and VB6 will exhibit the same user interface)




4. Register your calculation

5. When the registration is completed, press Ok and Close.




6. Create a PI ProcessBook display showing the input data (Flow1 and Flow2) along with your output tag (Flowout) and the valve status (BA:Active.1)




Exercise 2 - Pump statistics – part one

Objectives

Use the PIACE methods to calculate an operating time and an average consumption

Use PIACE date and time functions

Introduction

The goal of this exercise is to calculate daily statistics about a pump. Given the instantaneous consumption and the state of the pump, we would like to derive its daily operating time in hours and its running cost. We also need to validate data quality to make sure our calculations make sense.

Exercise

Part A




PI ACE Class Module name: Runtime

Part B



Pump:Consumption Input Instantaneous Watts

Pump:Operation Input Pump status

Pump:Runtime Output Current uptime since 12:00AM

Pump:Costs Output Total cost since 12:00AM




Part C


The uptime is evaluated when the pump status is “Active” and accumulated

from 12:00AM to current time (Hint: use the .TimeEQ method)

The total cost from 12:00AM to current time can be estimated by multiplying the average consumption by the price of electricity, which is about

7.23cents/KWh, and by the total time elapsed since midnight (Hint: use the .Avg method and the time functions PIHour and PIMinute).

Our cost estimate will not be realistic if the data for the consumption is not good. Make sure that at least 95% of the data has good quality, otherwise

write a “Bad data” status to the cost (Hint: use the .PctGood method).

If using VB .Net, Import the OSIsoft.PI.ACE.PIACEBIFunctions component to limit the length of the string when using the time functions.

Part D

Debug, test and register your calculation to run every minute with normal priority. Validate the result of your calculation with a graphical display in PI ProcessBook







Part A






Part B


Part C

1. Write the code needed

Use “t” and “*” for your time reference

Divide the average consumption by 1000 to get KW

Use PIHour() and PIMinute() to get the total elapsed time (number of hours). We are rounding the uptime to the minute.




2. In VB6

3. Or in VB .Net




Part D

1. Debug your calculation and test your module





3. Create a PI ProcessBook display showing the input data (Pump:Operation and Pump:Consumption) along with your calculated output tags (Pump:Runtime and Pump:Costs).




Exercise 3 - Pump statistics – part two

Objectives

Use the PIACE methods to calculate the number of starts for that pump

Compare current and previous status

Use natural based scheduling

Introduction

Following the previous exercise, we would like to calculate the number of starts for this pump. A start is defined as the transition from the “Inactive” status to the “Active” status.

Exercise

Part A




PI ACE Class Module name: Starts

Part B



Pump:Operation Input Pump status

Pump:Starts Input Total # of starts since 12:00AM

Pump:Starts Output Total # of starts since 12:00AM




Part C


On new event for the pump status, you need to validate the previous status of the pump (Hint: use the .PrevVal method)

If the hour of the previous timestamp is greater than the hour of the current timestamp (trigger event), you need to reset the number of start to 0 because we have just crossed over midnight (Hint: use the .PrevEvent, PIHour and PIMinute methods)

Part D

Debug, test and register your calculation to run every minute with normal priority. Validate the result of your calculation with a graphical display in PI ProcessBook







Part A






Part B


Part C

1. Write the code needed

Use the .ExeTime property to compare the values and timestamp

Use .PrevVal to get the previous value and .PrevEvent to get the previous timestamp

If the number of start doesn’t need to be updated, make sure to force the value to be identical.

Do not forget to reset your counter just passed midnight




2. In VB6

3. Or in VB .Net




Part D






3. Create a PI ProcessBook display showing the input data (Pump:Operation and Pump:Consumption) along with your calculated output tags (Pump:Runtime and Pump:Cost).




Exercise 4 - Using PI ACE Manager

Objectives

View status for all PI ACE Executables, Modules and Contexts

Stop/Resume PI ACE Executables, Modules or Contexts

Change the scheduling information for a PI ACE Context

Select the level of message logging for a PI ACE Context

Introduction

The PI ACE Manager is a utility tool used for monitoring and modifying properties of any ACE Context, ACE Module or ACE Executable on any PI 3.3 Server. It can also allow the users to start and stop the calculation of any PI ACE components.

Exercise

Part A

Start PI ACE Manager and consult all PI ACE Statuses. Toggle between ACE 1.x or ACE 2.x depending upon the type of platform you used to develop your modules (VB6 or VB.Net).

Set the default display to the platform you use the most.

Part B

Stop/Resume MyACE (EXE or DLL)

Stop/Resume SimpleCalc (Module)

Stop/Resume localhost context for the module Units

Part C

Change the schedule of SimpleCalc to natural and choose High priority.

Change the Message Log Level for SimpleCalc to all types of messages and look for new messages in the PI server log file using PI SMT3.




Change the clamping settings for tag Pump:Consumption in module Runtime, executable/dll Class_Ex2 to "Both" and verify in PI ProcessBook that values never exceed the limit.







Part A

1. Start the PI ACE Manager by selecting PI ACE Manager from the Start /

Programs / PI System.

2. As the PI ACE Manager screen will appear, notice that the left pane is a tree view of all PI ACE Executables, Modules and Contexts stored on a given PI Server. Multiple PI Servers can be added for display.

Notice the structure:

First Level: PI Server (localhost)

Second Level: Executable (MyACE)

Third Level: Modules (SimpleCalc)

Fourth Level: Module Details (Input Tags, Output Tags and Contexts)

3. The right pane displays information for any selected item in the left pane. Explore items on the left pane and consult the information supplied on the




right pane. The status bar is a summary of the numbers of PI ACE Executables, Modules and Contexts running, stopped or in error.

Part B

1. From the PI ACE Manager, select MyCalc executable on the left pane.

2. From the Executable Menu, choose the Take out of service option. In the right pane, the MyCalc executable is now Out of Service and color changed to gray. Also, the PI ACE Module SimpleCalc status is now at Off but its color is still green. Resume Calculation on the MyCalc executable by selecting it and by running the command from the Executable menu. In the right pane, the statuses for the executable and the module status should be On.

Note 1: Take out of Service and Resume calculation are also available in

the right click menu or on the toolbar

Note 2: Use the refresh server to update right pane.

Note 3: If an Executable has more then one module, they are all going to stop/start when the take out of service or resume calculation functions are used.

3. From the PI ACE Manager, select the SimpleCalc Module on the left pane. Choose the Take out of service option from the Module Menu. In the right pane, the SimpleCalc module is now Out of Service but MyACE executable is still on. Resume Calculation on the SimpleCalc module by selecting it and by running the command from the Module menu. In the right pane, the statuses for the executable and the module should be On.

Note 1: Take out of Service and Resume calculation are also available on


Note 2: Again, use the refresh server to update right pane.

4. From the PI ACE Manager, select in the left pane the context named localhost for the module Units under the executable Performance. From




the Context Menu, choose the Take out of service option. In the right pane, the localhost context is now Out of Service and the module is still On. Resume Calculation on localhost context by selecting it and running the command from the Context menu. In the right pane, the statuses for the executable and the module should be ON.

Note 1: Take out of Service and Resume calculation are also available on


Note 2: DO NOT FORGET to refresh to update right pane …

Note 3: Since a module can have more than one context, only the selected context selected will be stopped/started while the module is still running.

Part C

1. Select localhost context from SimpleCalc module. From Context Menu, select Edit Schedule and Priority command or right click on localhost and select Edit Schedule and Priority.

2. Change the priority of this calculation to High with the Priority combo box. Change the clock based calculation to a natural based calculation by




selecting the Natural radio button. Select the input tag DataSource. Confirm modification by clicking on the Save/Close button.

3. Again, using the localhost context, select from the Context menu or by right clicking the Message Log Level command to get the following window:




4. By default, error messages for PI ACE context are logged into the message log file. Choose to log related warnings, counter information, notification, calculation events and updates. User messages are generic messages that do not fit into any other categories. Click on Select All and Close. Use the PI SMT3 utility to consult the message log from the system status menu.

5. Select Pump:Consumption from Input tags. Through the tag menu or right click menu, select the Edit Tag Options.




6. Use the Clamping combo box and select Both to restrict the min and max values of the consumtion to the tag’s zero and (zero + span) respectively.




Exercise 5 - The PI Module DataBase

Objectives

Create modules, aliases and properties using PI ModuleDataBase Editor

Copy and link existing modules

Use the structure to dynamically display trends in PI ProcessBook

Introduction

The goal of this exercise is to create a structure in the PI ModuleDatabase with modules, aliases and properties that would represent a small chemical plant called Myplant.

This structure will be used in PI ProcessBook to dynamically update trends displaying flows attached to each unit and in Excel to generate context sensitive reports.




Exercise

Part A

Start the PI ModuleDataBase Editor and create the structures of modules, aliases and properties according to the following table.

PI module Parent Module Aliases Properties

Name Name Name Tag Name Type Value

MyPlant PI ModuleDB -- -- -- -- --

SectionA MyPlant

Unit11 SectionA Flow BA:LEVEL.1 Design Double 65

Part B

Import the existing structure with PI MDB builder and use it to create the others units and section.

PI module Parent Module Aliases Properties

Name Name Name Tag Name Type Value

Unit12 SectionA Flow SINUSOID Design Double 32

Unit66 SectionA Flow CDT158 Design Double 80

SectionB MyPlant

Unit34 SectionB Flow BA:CONC.1 Design Double 45

Unit37 SectionB Flow CDEP158 Design Double 12

Part C

Insert linked modules for Unit11 and Unit12 under module SectionB using the PI MduleDB Editor.

Part D

Open the ProcessBook PDI named Class_Ex5.PDI and select different unit in the tree view to update the trend with the tag linked to the corresponding alias.




Part E

Open the Excel report named Class_Ex5.xls and see how the data can be generically extracted depending upon the context used in the PI ModuleDB.







Part A

1. Open the PI Module DataBase Editor from the Start menu.

2. Expand and select the PI Module DB module and create a new module by right clicking and selecting New PIModule...

3. Enter the module name MyPlant and click Save and Close.

4. Create the module SectionA repeating steps 2 and 3 while module MyPlant is selected.

5. Create the module Unit11 repeating steps 2 and 3 while module SectionA is selected.




6. Select module Unit11 and create a new alias by right clicking in the PI Aliases tab on the right hand side of PI Module DataBase Editor.

7. Enter the alias name ("Flow") and the corresponding tag name ("BA:LEVEL.1") and click Save and Close.

8. Create a new property by right clicking in the PI Properties tab on the right hand side of PI Module DataBase Editor.




9. Enter the property name ("Design"), its value (65) and select its type ("Double") and click Ok.

10. Here is what you should obtain (right-click to show alias & properties values)

Part B

1. Open MS Excel and go to the PI-SMT/MDBBuilder/Import Items… menu.




2. Select the module MyPlant in the tree view and check the following options

3. Click Ok to import the structure




4. Delete columns D to S included

5. Copy/Paste rows 4 to 6 and change Unit 11 for Unit 12

6. Change the AliasDataSource for the alias flow and PropertyValue for the property Design

7. Repeat steps 5-6 for Unit66, and then SectionB. Becareful, since SectionB has only two specifics sub modules. Do not forget to validate the path of the module after you copied it.

8. Use the export menu (select the module MyPlant) to update the structure.




Part C

1. Select module Unit11 and copy it.

2. Select module SectionB and paste a linked module by right clicking and choosing Insert Linked Module "Unit11"

3. Repeat steps 1 and 2 to insert a linked module Unit12 in SectionB.




Part D

Open the ProcessBook PDI named Class_Ex5.PDI and select different units in the tree view to update the trend with the tag linked to the corresponding alias.

Part E

Open the ProcessBook PDI named Class_Ex5.PDI and select different units in the tree view to update the trend with the tag linked to the corresponding alias.




Exercise 6 - The Power of Multiple Contexts -- part 1

Objectives

Use PI ACE Wizard to create and register a new calculation using aliases for inputs.

Use PI ACE Manager to add new contexts to an existing PI ACE Module

Introduction

In this exercise, we want to monitor the input flow for each unit we have created in exercise 5. We want to write an alarm status in a string whenever the rate of change of the flow over the last 10 minutes is greater than 25% of the average of the flow for the same period. The calculations are scheduled every 2 min. and offset by 15 sec. from each others.

Exercise

Part A




PI ACE Class Module name: Contexts

Part B

Use the following context \\localhost\MyPlant\SectionA\Unit11

Use the following items as input and outputs

Alias ACE usage Description

flow Input Feed flow for the unit





Flow_alarms Output String for storing the alarms

Part C


You need to evaluate the rate of change of the flow and compare it to the average (Hint: use the .Range and .Avg methods)

The text of the alarm is as follow: “High changes in flow name_of_tag” .You may declare a local string variable to build the text message (Hint: us the .Tag method)

Part D

Debug, test and register your calculation to run every 2 minute with normal priority. Add the others contexts using the ACE Manager to run your module against all units. Validate the result of your calculation with a graphical display in PI ProcessBook







Part A






Part B

1. Select the context

2. Select the input alias and output tag




Part C

1. Write the code In VB6

1. Or in VB .Net




Part D

1. Debug and test your calculation





3. Register the others context with the ACE Manager




4. A PI ProcessBook display showing the input data (alias flow) along with your calculated output string tag (Flow_Alarms). Noticed that we use the same tag to report alarms for all the flows. One alarm tag for each flow could have been used.




Exercise 7 - The Power of Multiple Contexts -- part 2

Objectives

Use PI ACE Wizard to create and register a new calculation using aliases for inputs and outputs.

Make use of the PI ModuleDB PIProperties in your calculation

Use PI ACE Manager to add new contexts to an existing PI ACE Module

Introduction

In this exercise, we want again to monitor the flow of each unit we have created in exercise 5. We want to set the questionable flag of the value to true if the value is smaller than the limit set by the corresponding property in the PI ModuleDB.

Exercise

Part A




PI ACE Class Module name: Property

Part B

Use the following context \\localhost\MyPlant\SectionA\Unit11


Alias ACE usage Description

flow Input & output Feed flow for the unit




Part C


Declare and set a PIModule variable to the module used as the current context (Hint: use the GetPIModuleFromPath function)

Retrieve the value of the PIProperty called Design (Hint: Use the .PIProperties() method of a PIModule variable)

Compare the current value to the design value and set the questionable flag

to true if the value is smaller (Hint: use the .IsQuestionable method)

In VB .Net, you will need to add a reference to the PISDK (COM reference) and import it.

Part D

Debug, test and register your calculation to run every minute with normal priority and an offset of 8 sec. Add the others contexts using the ACE Manager to run your module against all units. Validate the result of your calculation with a graphical display in PI ProcessBook







Part A



Part B




3. Select the context

4. Select the input alias and output tag




Part C

2. Write the code In VB6

2. Or in VB .Net (you need first to add the PISDK reference)




Part D

5. Debug and test your calculation





7. Register the others context with the ACE Manager




8. A PI ProcessBook display showing the flow for each along with the value of the design property and a questionable value for the flow.




Exercise 8 - Deploy an ACE module

Objectives

Create a PI connection to your neighbor’s computer

Develop a simple ACE module using your neighbor’s computer as the main PI server

Debug, test and deploy your module on your neighbor’s computer

Introduction

In this exercise, we want to simulate a development environment where the user is not working on the PI server. To do so, you will connect to another PI server and use it as your reference for developing the ACE module.

Exercise

Part A

Create a PI connection to your neighbor’s computer

Part B


PI server name: neighbor’s computer

PI ACE Executable name: student_firstname

PI ACE Class Module name: Deploy

Part C




Create an ouput in with the ACE Wizard named “aceout” using all the default attributes.



sinusoid Input Random value

aceout output --

Part D


Set the value of aceout to be equal to sinusoid

Part E

Debug and test your calculation. Deploy it on your neighbor’s computer and register it to run every minute with normal priority. Validate that your module runs correctly







Part A

1. Using PI SMT3 or PI SDK, create a new PI server connection.

Part B

1. Define your module server and name




Part C

1. Create a new output tag named aceout




2. Select your input and output tags

Part D

1. Write the code needed In VB6

Part D





Part E

1. Copy/paste the folder of your new module from your computer to your neighbor’s computer




2. On your neighbor’s computer, double-click on the EXE if you have developed with VB6.

3. Add your neighbor’s computer in your ACE manager and browse to your new module to register it

4. Start your module and validate that there are no error message and that the aceout tag has a value (you can use SMT3 to browse tag on a different server)




Exercise 9 - Module level variable and message

Logging

Objectives

Use a module level variable to keep last snapshot value for a trigger tag

Use the UserDefinedInitialization routine to log the process ID of your PIACEClassHostLibrary

Use the UserDefinedTermination routine to write a specific status and message when ACE stops

Introduction

In this exercise, we would like to compare the current snapshot of our trigger tag with the previous snapshot and write the result in a string tag.

We also want to write the state "ACE stopped" for our output tag when the calculation is stopped. At the same time, a message should be logged by the PI Message subsystem.

Exercise

Part A

Create a new string tag named SnapUpdate.

Create a new digital state named “ACE stopped" in the SYSTEM set for state 315.

Then create a new PI ACE Module with the following properties (using the PI

ACE Wizard in VB .Net):




ACE Executable name: Snapshot

ACE Module name: Deviation

Part B

For any new event of the tag DataSource, write in the tag SnapUpdate a string containing the date and time of the event, the previous and the current value of the snapshot of DataSource.

Hint 1: use a module level variable to store the snapshot value from calculation to calculation;

Hint 2: use the UserDefinedInitialization routine to first initialize the variable that will store the snapshot value from one calculation to the next.

Hint 3: you can include the PITimeServer library to help converting the execution time.

Part C

In the UserDefinedInitialization routine, write code to log the process ID of your calculation at startup.

Hint 1: you can include the System.Diagnostics library;

Hint 2: use the .ID property of the object process.

Part D

In the UserDefinedTermination routine, write code to force a value of “ACE stopped"in the output tag SnapUpdate and log the following User message: "ACE Calculation has been stopped"

Part E

Test and start/stop the module to see if the code performs as expected. Verify the PI system log with PI SMT3.





Part A

1. Using PI Point Builder or PI SMT, create a string tag named SnapUpdate.

2. Using PI Point Builder, add the state “ACE stopped” at state 315 in the SYSTEM table.




3. Open the wizard and create a new module.

4. Import input and output tags.




Part B

1. Declare a module level variable.

I

2. Initialize this variable to the current value of DataSource

3. Write the date, time, old and new values of the snapshot




Part C

1. Make sure you have added the System.Diagnostics reference. Then get the process ID and log a message to the PI message log

Part D

1. Add the code to the ModuleDependentTermination to write the “ACE stopped“ status and log a message in the PI server.




Part E

1. Validate in ProcessBook that the value change when the calculation is stopped

2. Verify the log file.

exercises piace 2.4

Documents

table of contents exercise

pi ace manager

pump statistics

training course piace

simple ace calculation