PPCL Editor Overview

PPCL (Powers Process Control Language) is the programming language used to write field panel control programs for building control and energy management functions. PPCL consists of various types of statements, each performing a different task. Put together, these statements become ordered instructions called control programs that are executed at the field panel. These control programs instruct the field panel to perform calculations, evaluate control strategies, perform time-based actions, and command points.

PPCL provides the following types of operators:

• Arithmetic Operators that perform calculations using expressions
• Relational Operators that compare expressions
• Logical Operators that combine expressions. Parenthesis are used to group the expressions.

A total of 32 operators can be used in one PPCL statement. An expression adds one operator for each arithmetic operator, relational operator, logical operator, point reference, and value constant. Up to 16 operands can be used in one PPCL statement. Each additional point reference or value constant adds one operand.

Before writing program code, you should understand how the compiler uses order of precedence to evaluate statements which contain more than one operator. The order of precedence is the order in which operators (arithmetic, relational, and logical) and special functions are evaluated in a command statement. Operators that have a higher precedence are evaluated before operators which are at a lower precedence. If all the operators in the statement have equivalent precedence levels, then the operators are evaluated from left to right. Statements are evaluated according to the following table:

Examples

Order of precedence for arithmetic operators:

Multiplication has precedence over addition; so, in the statement

(10 - 5) + (2 * 3) = 11

the 2 * 3 = 6 is calculated first and the expression is then 10 - 5 + 6

All other remaining operators are at the same precedence level. Operators are then evaluated in a left to right order as follows:

10 - 5 = 5

5 + 6 = 11

The solution to this problem is 11.

Order of precedence for relational and logical operators:

The following statement compares values using relational operators (.EQ. and .NE.) and a logical operator (.AND.) and the result of the comparison can change the output of the statement.

If (value1 .EQ. value2 .AND. value1 .NE. value3) then...

For the purpose of this example, assume that both comparisons (condition1 and condition2) are true.

The .EQ. and .NE. relational operators have the highest precedence level in the formula. Since those two operators have the same precedence, they are evaluated from left to right:

value1 .EQ. value2 (condition1 = true)

value1 .NE. value3 (condition2 = true)

After the first level of operators have been evaluated, the problem now looks like this:

if (condition1 .AND. condition2) then...

The .AND. logical operator is then evaluated. Since .AND. requires both conditions to be true, the solution to this problem will also be true.

Parenthesis can be used to change the order in which the different parts of a statement are evaluated. Precedence is changed by placing parentheses around specific values or operations. The information contained within a set of parentheses is evaluated before the information outside of the parentheses. If all the operators in the parentheses have equivalent precedence levels, then the operators are evaluated from left to right.

When the computer evaluates multiple pairs of parentheses, each pair is evaluated according to how it is positioned in the formula. Multiple parentheses are evaluated as follows:

• For a pair of parentheses defined within another pair of parentheses, the computer always evaluates the innermost set first.
• For parentheses defined as individual pairs, each is evaluated from left to right.

Example

The following example uses two levels of precedence (Level 3 - multiplication and Level 4 - addition/subtraction).

10 - 5 + 2 * 3 = 11

The result of this statement is 11. The same values can produce a different solution when parentheses are included as follows:

(10 - 5 + 2) * 3 = 21

In the above statement, the expression within the parentheses is evaluated first. Since all the operators within the parentheses have the same precedence, the operators is the parenthesis are evaluated from left to right and the statement is then:

7 * 3 = 21

The result of this statement is 21. Even though the formula uses the same values, the use of parentheses in the second example changes the solution of the problem.

A special function is used to access a specific value that is unique to a point. The value of the point can then be tested or assigned to other points. Since special functions are maintained by the system, they cannot be manually commanded to a different value. Special functions cannot be used over the network.

A special function has a precedence level associated with it. Precedence levels represent the order at which expressions and functions are evaluated. For a complete discussion about precedence, see Order of Precedence for PPCL Operators and Special Functions. PPCL supports the following special functions:

• Alarm priority (ALMPRI)
• Totalized value (TOTAL)

Resident points are predefined logical points that permanently reside in the database in the field panel and provide time-based and system status information. These points may be referenced in PPCL programs to perform such functions as checking the current time or the day of the week. These points can also monitor alarms, modes of operation (DAY or NIGHT), and communications between nodes.

The value of the point can be tested or assigned to other points. Since each field panel maintains its own set of resident points, a resident point cannot be directly used across a network.

PPCL supports the following resident points:

• Alarm Count (ALMCNT)
• Alarm Count 2 (ALMCT2)
• Battery Status ($BATT)
• Decimal time (CRTIME)
• Day (DAY)
• Day of the Month (DAYOFM)
• Communications Link (LINK)
• Month (MONTH)
• Node Number (NODE0 through NODE99)
• Peak Demand Limiting ($PDL)
• Seconds Counter (SECNDS)
• Seconds Counters (SECND1 through SECND7)
• Military Time (TIME)

Local variables are locations within each field panel that are used to store values for PPCL programs. Local variables function like virtual points except that they require less memory, are predefined, and cannot be directly displayed. Local variables can contain analog or digital values.

Each set of local variables is designed for a specific task. Local variables are divided into two distinct categories: subroutine and global storage variables. PPCL supports the following local variables:

• $ARG1 through $ARG15
• $LOC1 through $LOC15

The @priority indicators are used to test if a point is at a specific priority or to command a point to a specific priority. A total of 16 parameters can be used in one PPCL statement.When using an @priority indicator with PPCL statements, the priority level you define in that statement occupies one of the parameters. PPCL supports the following @priority indicators:

• Emergency (@EMER)
• PPCL (@NONE)
• Operator (@OPER)
• Peak Demand Limiting (@PDL)
• Smoke (@SMOKE)

Point status indicators are used to monitor the current status of points. The point status indicators can be implemented to test if a point is at a specific status, so that the system can act accordingly. Since these points are related specifically to the functions of the device, you cannot directly use these points over the network. PPCL supports the following status indicators:

• Alarm (ALARM)
• Auto (AUTO)
• Day mode (DAYMOD)
• Battery status - charged (OK)
• Battery status - discharged (DEAD)
• Failed (FAILED)
• Fast (FAST)
• Manual override (HAND)
• Night mode (NGTMOD)
• Off (OFF)
• On (ON)
• Proof on (PRFON)
• Slow (SLOW)

The commands in your program are instructions to the field panel indicating an action to be taken. The PPCL commands are grouped on sub-menus based upon the type of control or function that the command performs.

You can use the Program Editor command assist feature to help you enter PPCL commands into your program. To use the assist feature, place the cursor in or above the program line where you want to insert the statement and select the Assist menu. Next, select the command from the appropriate sub-menu to display the assist dialog box for the command. Once you complete all the sections in the dialog box, you can view the completed statement before inserting the statement into the program.

The PPCL commands available on each sub-menu are listed below.

Program Control Commands

• ACT
• DEACT
• ENABLE
• DISABL
• EPHONE
• DPHONE
• GOSUB
• GOTO
• ONPWRT
• SAMPLE
• IF THEN ELSE

Point Control Commands

• ON
• OFF
• FAST
• SLOW
• AUTO
• SET
• INITTO
• WAIT
• STATE

Operational Control Commands

• ENALM
• DISALM
• ALARM
• NORMAL
• LLIMIT
• HLIMIT

Emergency Control Commands

• EMON
• EMOFF
• EMFAST
• EMSLOW
• EMAUTO
• EMSET
• RELEAS

Energy Management Commands

• DAY
• NIGHT
• DC
• DCR
• TOD
• TODMOD
• TODSET
• HOLIDA
• SSTO
• SSTOCO
• PDL
• PDLDAT
• PDLMTR
• PDLSET
• PDLDPG
• LOOP
• ADAPTM
• ADAPTS

Special Function Commands

• MIN
• MAX
• DBSWIT
• TABLE
• TIMAVG
• OIP
• DEFINE
• LOCAL
• LSQDAT
• LSQ2

Arithmetic Function Commands

• ATN
• COM
• COS
• EXP
• LOG
• ROOT
• SIN
• SQRT
• TAN

If you open an existing program or create a new program and enable the statements in the PPCL Editor, the commands, numbers, and statement text display in the defined syntax styles. Disabled statements only display in one color—gray. Enabling statements in the PPCL Editor makes it easier to find commands, text, or numbers.

You can enable or disable a single statement or a range of statements within a program that is already downloaded to the field panel. You do not have to go to the field panel to perform these operations. Keep in mind, though, that enabling and disabling statements can affect the operation of your management platform.

An enabled statement allows the field panel to execute or evaluate the line of code. A disabled statement is not evaluated or executed by the field panel. Disabled statements are ignored by the system until they are enabled.

The PPCL Editor provides several ways to help troubleshoot your programs.

Enabling and Disabling Statements

You can disable one or more statements in your PPCL program, run it again, and then use the results to help debug the code.

Trace Bits

When you modify PPCL code, you should first clear trace bits from the previous PPCL code to ensure that the program runs properly. Clearing trace bits helps you follow the flow of PPCL execution. With trace bits cleared and PPCL code displayed, you can determine if certain statements are being executed or bypassed. This is a useful tool for debugging PPCL code. To clear trace bits, see Clearing Trace Bits.

Specifying points in the PPCL program depends on whether the points are P2 or BACnet points:

• APOGEE P2 Points - Reside in a device on an APOGEE Ethernet or APOGEE AEM network or are points that reside on FLNs serviced by an APOGEE Ethernet or P2 panel.
• BACnet Points – Reside on APOGEE BACnet panels or are in FLN devices serviced by APOGEE BACnet panels.

APOGEE P2 Point Referencing

For P2 point referencing, note that:

• You can specify the System Name, or System Name and Subpoint, in the form
  SystemName:SubpointName. For example “Device10APP2025:Day CLG STPT”
• You can drag-and-drop a P2 point from System Browser into the PPCL Editor on a P2 panel.
• Each FLN device is represented by an APOGEE P2 FLN device, where the subpoints of the FLN device are represented as properties of the device. Generally, the commandable subpoints of these devices are commanded via Cross Trunk.

BACnet Point Referencing

The following Object Types are supported for BACnet point referencing:

- Analog Input (AI)

- Analog Output (AO)

- Analog Value (AV)

- Binary Input (BI)

- Output (BO)

- Binary Value (BV)

- State Input (MI)

- Multi-State Output (MO)

- Multi-State Value (MV)

Referencing BACnet points

To reference a BACnet point consider the following:

• You can drag and drop a BACnet point into a PPCL program in a BACnet panel.
• You can drag and drop a BACnet point into a PPCL program in a P2 panel. Note the following BACnet point references in a P2 panel:
  Non-FLN Point – The system name is dropped from the point name.
  FLN Point – The point naming takes on the BACnet naming conventions.
• Use BACnet third-party form. Specify BAC_[device instance]_[object type]_[object instance]. For example, BAC_10_MO_1 where:
  10 = Device Instance of 10
  MO = Multi-State Output
  1 = Object Instance of 1
• Or, use the Management View CNS node name for a point.
• For a non-FLN device point, use the Management View name (not description) for a point, for Instance “FLOOR_1_DO1”. If this is not unique in the system, then precede the name with enough of the Management View path to make it unique, and place a colon (:) between the path and name. For instance “Device10.Local_IO:FLOOR_1_DO1”
• For FLN Subpoints, precede the Subpoint name with the FLN device name and a colon (:) This is because FLN device Subpoint names are the same for each instance of the FLN device, for example: “Dev201:DAY_CLG_STPT”