POWERVISION Configuration Studio®

Version 2.9

Programming Reference Manual

00-02-1011
2017-03-06
Section 78
In order to consistently bring you the highest quality, full-featured products, we reserve the right to change our
specifications and designs at any time. The latest version of this manual can be found at
www.murphybyenovationcontrols.com.
Table of Contents

About the PowerVision Configuration Studio® Software .....................................................4

What’s New for PowerVision 2.9? ................................................................................4

Intended Use ................................................................................................................4
Programming in PowerVision Configuration Studio® Software..........................................5

State Machine Programming ........................................................................................5

Script Programming .....................................................................................................6
Activity Programming ...................................................................................................6
Walkthrough Activity Programming ..............................................................................8
Using the Programming Module ..............................................................................................9

Programming Items Tree..............................................................................................9

Variables ....................................................................................................................................10

Numeric Variables ......................................................................................................10

String Variables ..........................................................................................................13
Events ........................................................................................................................................14

Event Types ...............................................................................................................14

Scripting ....................................................................................................................................18

Adding and Editing Script Functions ..........................................................................18

Compiling Scripts .......................................................................................................19
Programming Lists ..................................................................................................................20

Types of Lists .............................................................................................................20

When to use Lists.......................................................................................................20
List Properties ............................................................................................................21
List Column Definition ................................................................................................22
List Tools in Scripting .................................................................................................22
Activity Programs ....................................................................................................................23

Activity Program Properties ........................................................................................24

Adding and Editing Shapes ........................................................................................24
Shape Toolbar............................................................................................................25
 Using the Navigator ....................................................................................................27
Creating Local Variables ............................................................................................27
Walkthrough Activity Programs.............................................................................................28

State Machines .........................................................................................................................28

State Machine Properties ...........................................................................................28

Editing the State Diagram ..........................................................................................29
Creating and Editing States........................................................................................29
Creating and Editing Transitions ................................................................................30
Expression Language .............................................................................................................31
THIS PAGE INTENTIONALLY LEFT BLANK
About the PowerVision Configuration Studio® Software

The PowerVision Configuration Studio® is a PC-based software program suite for configuring
the PowerViewTM Model PV3xx, PV4xx, PV7xx, HelmView® and MPC-xx display units. The
program is a member of the MurphyNet Software Suite of display configuration tools. The
software interface enables users to modify the display to their own specific needs. In addition,
the software interface allows the user to customize specific items such as:
• Display interface content look (types of inputs, rotary and bar gauges with customized
bezels and markings, uploaded logos and machine graphics, integrated video, on-
screen text and a variety of other user-defined parameters).
• Easily selectable multiple languages, day/night toggles.
• Control over the sequence of operation.
• Diagnostic codes and graphic alarms linked to bitmapped or other data.
• Active/inactive color schemes to signal inactive gauges instantly.
• Easy-to-save updates that enable the user to create and test multiple configurations.
The PowerVision Configuration Studio® generates configuration updates for the display units.
These updates can be transferred to the display unit by either a direct cable connection
between the PC and the display unit or by copying a configuration from the PC to a USB flash
drive and then connecting the USB flash drive to the display unit's USB port.

What’s New for PowerVision 2.9?

• Support internal message activity in color display.

Intended Use
This document is intended as a reference manual only.

Section 78 00-02-1011
2017-03-06 -4-
Programming in PowerVision Configuration Studio® Software

PowerVision Configuration Studio® Software includes an integrated programming environment

designed to allow users to accomplish complex tasks using a variety of programming models.
Now users can create advanced User Interface behaviors (such as animation and custom data
display) to manipulate data (such as combining and splitting data to create new values). In
addition, it provides a way to interact with the platform’s built-in applications.
The current version of PowerVision Configuration Studio® includes four distinct programming
paradigms. Each has advantages and disadvantages. In practice, it’s important to have an
understanding of all four methods of programming. These programming paradigms are:
• State Machine Programming
• Script Programming
• Activity Programming
• Walkthrough Activity Programming
State Machine Programming
State Machines keep track of a system status (called a state) and respond to the changes in
the system state by executing an action or set of actions. For example, it might be necessary
to create a state machine to keep track of the Day/Night status. The state machine would be
designed to execute the behaviors for the system in response to changes from Day to Night.
This could include such behaviors as:
• Turning down the brightness (when changing from Day to Night).
• Turning up the brightness (when changing from Night to Day).
A State Machine is a programming object that keeps track of the current status of a system
value. State Machines are made up of set of States each representing a single status value.
State Machines work best when they can be designed to manage a specific aspect of the
system or a single status type rather than combining different behaviors into a single state
machine.
NOTE: It’s preferable to create multiple smaller state machines rather than
one larger one.

State Machines in PowerVision Configuration® Studio Software are made up of the following
items which will be described in more detail in later sections:
• State objects: Within a state machine, they represent a possible status in which a
system could exist. For a given state machine, there is one and only one active state.
State objects are connected to each other via Transitions. State objects can execute
work when the state is Entered or Exited. The work executed by a state is called an
Action.
• Transition object: Connects two states together and represents a possible state
change. These state changes occur in response to Events.

Section 78 00-02-1011
2017-03-06 -5-
 • Action objects: Represent a work item to be executed by an application. These actions
fire on the Enter or Exit of a state. The Enter actions execute on the next processing
cycle after an event has caused a transition to a state. The Exit actions execute when
an event has caused a transition away from the state.
When programming with state machines, keep in mind that all state machines are independent
of each other. This means that the current state of one state machine has no impact on the
state of another state machine. However, events (that cause transitions) are system wide so a
single event can cause a transition in two state machines.
Script Programming
Unlike State Machine programming, script programming in PowerVision Configuration® Studio
Software is optimized to handle scenarios where the user wants to execute a process flow
rather than keep track of the status of a specific system aspect. While state machines are
defined graphically, scripts are written in a text editor. This makes a script more appropriate for
advanced users. All scripting languages have a specific syntax which describes the keywords
and special character rules for the language. PowerVision Configuration Studio® Software
uses a syntax called AngelScript, which is similar to common languages such as C++ or C and
in this way can be learned quickly by most programmers.
Scripting is most appropriate for places where the user needs to create a difficult-to-describe
process flow; for example, to read data and conditionally execute one of many different
responses. A script would allow this to be done easily. Also, some advanced system behaviors
can only be implemented in scripting such as interacting with the file system (USB Stick for
example). Scripts are made up of the following structures:
• Script object: Text that describes a set of behaviors. Script text can include Functions
and EventFunctions. Script text also interacts with the system by calling API
Functions and accessing API Value lists.
• Function: A subset of a script that can be used repeatedly. These functions can be
called from any place in a script allowing the implementation of a functionality written
once instead of multiple times. For example, to create a script function to handle
creating a system time string for use in many places.
• EventFunction: A function whose name corresponds to a system event. These
functions behave exactly like normal functions except that they are fired automatically
when system events occur.
• API Function: A function provided by the system to execute a behavior. Similar to
actions in state machines, they tell the system to execute a prebuilt behavior. For
example, use an API function to read or write a variable.
• API Value: A value used in code to interact with configuration objects. For example, the
EventIDs object contains API values for each event in the system.

Activity Programming
Activity Programming is designed to allow a user that has a basic knowledge of simple flow
control to create complex orchestrations without the need to learn complex language
semantics such as C++ or Angel Script. Activity programs are capable of doing most

Section 78 00-02-1011
2017-03-06 -6-
processes common to structured programming languages such as loops, condition checks and
variable management, but these features are implemented using a simple visual language.
Activity Programs are a form of flowcharting, which is used to describe a system process as
opposed to describing it with structured text (i.e., code). This visual language is made up of a
set of shapes called activities which represent steps in the program. The steps are connected
with control flow lines to describe the transition between activities.

These programs begin with a Start Activity. Each activity is responsible for executing its work
before transitioning control to the next activity. Activities are executed one at a time until
control reaches a Stop Activity at which time the program ends. It will not start again until the
event which triggers the activity is received again OR another activity calls the activity directly.

Activity programs differ from state machines in that they run and complete in response to an
event rather than simply transitioning to a new state when an event occurs. This makes them
more useful for creating algorithms and managing event-driven processes. For users
transitioning from scripting, think of activities as functions or operations.

Advantages of Activity Programs

• High Performance – These programs have a performance similar to scripting. In most

cases, activities outperform state machines due to the decreased number of system
level events and waits necessary to manage states.
• Extendable – Advanced activities can be created which handle complex tasks with a
single activity shape.
• Easy to learn and understand.
• Allows you to combine conditional checking and variable get/set in a single visual
process.
• Supports recursion through the use of Activity->SubActivity calls.

Disadvantages of Activities Programs

• Activity programs are not appropriate for long-running processes. Because these tasks
must run to completion, they should not be used for long-running tasks. The same is
true for scripting. You should either break these into smaller activities that are called
based on time OR consider designing a state machine to flatten the load for the system.
• Not appropriate if you need to track a true State. If you are managing a true state such
as the status of a system feature (Day/Night for example), a state machine may be
more appropriate because it inherently responds to the events that cause the state
transition.
• If you need to perform complex data manipulation (parsing strings, translating byte
data), scripting’s full set of data manipulation functions may be more appropriate.

Section 78 00-02-1011
2017-03-06 -7-
Walkthrough Activity Programming
PowerVision Walkthrough Activity Programs are a special type of activity program that lets you
define a set of steps (like a wizard) to capture information inside of PowerVision configurations.
These programs do NOT run on the hardware but instead run in PowerVision desktop. They
are useful for times when you have a configuration that contains a large amount of functionality
that must be configured prior to use. For example, the MPC-20 hardware uses a walkthrough
to allow the establishment of variables for a number of engine and runtime environments.

Section 78 00-02-1011
2017-03-06 -8-
Using the Programming Module
The programming module is where to interact with the eight programming items. These items
are:
• Numeric Variables
• String Variables
• Events
• State Machines
• Scripts
• Activity Programs
• Walkthrough Activity
• Lists
Programming Items Tree
The programming items are organized into a tree structure displayed on
the left side of the programming module. This tree allows you to create,
delete, select and group the items. In addition, the context menus and
buttons can be used to copy, paste and search for the items in the tree.
Programming Items created by the system are automatically grouped
by the application that created them; however, these items can be
moved to other groups at any time.
When working on advanced configurations, it’s useful to use the
grouping system to keep related items together. For example, if items
(variables, state machines, etc.) used to manage the system backlight
have been created, they can be organized in a single folder called
Backlight rather than grouping them by the item type (the way in which
they were grouped in previous versions of PowerVision Configuration
Studio®).
The following can be accomplished using the tree:
• Selecting Items: Open the folder containing the item and select
it. The Editor for that item will display at the right of the
programming tree.
• Add Items: Click or right click anywhere
in the tree.
NOTE: When adding items they will be
added to the currently selected group.

• Remove Items: Click or right click on the item to be removed.

• Group Items by:
o Selecting the item and editing its group name value,
o Dragging (moving) any item to a different group, or
o Dragging one item onto another item to group them together.
• Search Items: Click to open a text field that searches items in the tree.
Section 78 00-02-1011
2017-03-06 -9-
 • Copy and Paste: Right click on any item in the tree to copy it, and paste it in any other
location in the tree.
• Unlink From Owner: Allows the unlinking of a variable from its owner (useful if you
want to delete its owner without deleting the variable).

Variables

Variables are values stored globally in the system. There are two types of variables available
in PowerVision Configuration Studio® Software. String Variables used to store text and
Numeric Variables used to store numbers. In general, these variables can be broken into three
categories.
• Built-In Variables: Many variables are automatically generated by the system based on
the applications defined in the hardware. For example, variables are auto-created for
things like Current Language, Backlight Level and Machine Hours. These variables
cannot be renamed or deleted.
• Auto-Created Mapping Variables: These variables are created during the mapping
process and can only be deleted at the point where they were created. Typically, these
variables are created as you map database data (J1939 PGNs for example) on a
specific device. Many places in the system rely on Auto-Created variables including I/O
Modules, Logging, FreeForm CAN messages and PDM.
• User-Created Variables: Variables created by the user for the sole purpose of holding
custom data. These variables are typically values used when programming or when
combining existing variables into new values.
Numeric Variables
Numeric variables are used to store global number values in the system. These variables are
managed by the database application and can be updated by programming or by the system
automatically in response to data received or created by the system.

Section 78 00-02-1011
2017-03-06 - 10 -
Section 78 00-02-1011
2017-03-06 - 11 -
Numeric Variables have the following properties that can be edited.
Field Description
Name This is the name of the variable that will be used in programming.
NOTE: Because certain characters are not
valid in programming this value is generated
automatically excluding invalid characters.

Group Name of the group in the programming tree where this item will be
displayed.
Identifier Description of variable or additional comments providing further
explanation of the variable’s purpose or characteristics.
NOTE: Built-In variables cannot be edited.

Include ID for Ensures that the item includes its readable name for use in
Programming programming/debugging.
Data Type Double, Float, Int32, Int16 or Int8.
Unit of Measure How the variable will be measured (i.e., psi, RPM, mL, etc.).
Description Name of the variable.
Type Unit of the variable (F,%, etc.).
Fire on change This is a system event that fires when the variable value changes.
From here an existing event can be fired or auto-created for use
elsewhere.
Allow Invalid Checking this will allow the variable to go invalid after the time
specified in the Invalidate After: field.
Default Value This is the initial value of the variable at startup. In addition, it can
be specified to be considered invalid until the system has written a
value to it.
Save Values If set, the current variable value is written to non-volatile memory
each specified period. If the period is zero, saving the value to non-
volatile memory must be managed manually by the user using
State Machine Programming.
Simulation Step Value for the variable to increment or decrement within Simulation
Min and Simulation Max range when the data simulation is
activated.
Simulation Min The smallest value simulated in the selected unit for this parameter
when data simulation is activated.
Simulation Max The largest value simulated in the unit for this parameter when
data simulation is activated.

Section 78 00-02-1011
2017-03-06 - 12 -
Calculation Events
Calculation Events are special events in the system that, when fired, will execute an
expression and update the variable with the result of the expression. These are useful in
updating variables with new values that are created by doing math or simple conditions on
other variables. Calculation Events use the PowerVision Expression Language which is
described in a later section.
Enumerations
Enumerations are predefined values which are valid for a given variable. For example, instead
of simply defining a Day/Night variable as a number, the enumeration list can describe the
value of Day=1 and Night=2. Enumerations are used primarily for documenting the valid
values for a variable, and they are also useful for showing a description of a value in scripting
and page setup.

Variables can share enumeration definitions via Override Enumerations. This is useful when
you have multiple variables that have the same values for use in Smart Gauges and Menus.
String Variables
String Variables are used to store global strings used in the system. These variables are
managed by the system and can be updated by programming or by the system automatically
in response to data received or data created by the system. String variables can be used in
scripting and are also used to drive Text and Keyboard widgets.

String Variables have the following properties that can be changed.

Field Description
Name Name of the variable
NOTE: Names for built-In variables can’t be
edited.

Group Name of the group in the programming tree

where this item will show.

Include ID for Ensures that the item includes its readable name for use in
Programming programming/debugging.
Length Number of characters this string can store. The minimum is 36 and
the maximum is 2048 (128 for small displays).
Section 78 00-02-1011
2017-03-06 - 13 -
Default Value Eliminates the need to initialize the values to empty or another
value when starting the system.
Fire on change This is a system event that fires when the string value changes.
From here an existing event can be fired or auto-created for use
elsewhere.

Events

Events in PowerVision Configuration Studio® Software are the primary method of causing the
system to respond to system processing. There are six event categories in the system, each of
which is created in different locations. However, all events can be used to cause responses in
any subsystem.
Also, events of one type can be mapped into other uses. For example, an event that was
originally created as an Event Condition in a state machine transition can be used to allow both
Update Variable and State transition behaviors to occur in response to a single trigger.
Event Types
Below are the Event Types:
• Built-In Events: Defined by applications in the system. These events are fired in
response to a system change to which a response is wanted. For example, the screen
application fires an event after it has drawn the screen (Screen.FrameComplete) and
the data logger fires an event when the log is full (DataLogger.FileFull).
• Script Events: Causes a scripting EventFunction to fire.
• Calculation Events: Causes an expression to be evaluated and the result written to a
variable. For example, a calculation event called Increment Brightness by 1 can be
created to update the brightness variable.
• Event Conditions: Created to conditionally fire its parent event based on the result of
an expression. For example, an event condition called Shutdown if Temperature > 250
degrees can be created that fires another event called Shutdown if the temperature gets
too hot.
• Transition Events: Created automatically in state machines when a transition is
dragged from one state to another. Firing these events causes the state machine to
transition from the transition’s origin state to its destination state.
• Custom Events: Created for use in the system. These events can then be attached
anywhere events are selected, i.e., keyboard widgets, page view transitions, etc.

Section 78 00-02-1011
2017-03-06 - 14 -
Field Description
Name Descriptive name for the event (Note that these can’t be edited on
built-In variables).
Group Name of the group in the programming tree where this item will
show.
Identifier This is the name of the event used in programming sections. The
identifier is the name of the variable without any invalid characters
such as spaces and other special characters which are not
compatible with programming modules.
Description Description of or more information about the event.
Data Data that corresponds to the Event.
Include ID for Ensures that the item includes its readable name for use in
Programming programming/debugging.
Continued on next page

Section 78 00-02-1011
2017-03-06 - 15 -
Field Description

Actions (tab) Event Actions are processes that system applications can execute.
They can be thought of as outgoing messages that are controlling
the behavior of the applications. Each application has a defined set
of actions it can receive. (For a list of applications and their actions
please refer the Applications Reference Manual.) Each state
contains two lists of actions:
• Entry Actions: The entry actions are executed sequentially
when an individual state is entered by a transition.
Applications in the system receive actions that are sent by
state machines to do work.
• Exit Actions: The exit actions are executed sequentially
when an individual state is exited by a transition.
Applications in the system receive actions that are sent by
state machines to do work.
By clicking [+], a window is displayed. This window shows three
columns: Application, Actions and Data. Clicking the Application
displays all actions that it can execute. Clicking the Action selects
the Data that is going to be passed to the action. When all three
are selected together, this describes the state’s action which will
occur. Once actions are added to a state, you can use drag and
drop to reorder the actions as well as move actions from entry to
exit.
Conditions (tab) Event Conditions are special events in the system that, when fired,
will evaluate the expression and fire its parent event or not based
on the result of the expression. These expressions must evaluate
to either a 0=don’t fire or non-0=fire to conditionally fire its parent
event. Conditional events are useful in conditionally triggering
behaviors such as over voltage or over temp conditions as well as
conditionally firing events to cause other optional behaviors.
Event Conditions use the PowerVision Expression Language
which is described in a later section.
Continued on next page

Section 78 00-02-1011
2017-03-06 - 16 -
Field Description

Timers (tab) Event Timers enable the user to fire an event based on a pre-
determined time interval. This time interval can be a single time
occurrence (one shot) or repeating time intervals (recurring).
Timers can be started with the CCM action Start Timer and
stopped with the CCM action Cancel Timer. One-shot timers must
be started with the CCM action and only send one event when they
expire until started again. Recurring timers start sending events at
each time interval upon power on but can be stopped with the CCM
action. Timers have a minimum duration of 50ms, but in practice
you should set timers to 100ms or greater for most scenarios.
NOTE: While timers typically should use long
intervals to prevent excessive system
processing, the system will also allow ONE
high-speed timer. This timer has a duration of
10ms. Please be aware that chaining complex
operations (scripting or user interface
interaction) to an event fired by a high-speed
timer is not advised. The high-speed timer is
meant for use in data interaction and
transmission scenarios only.

Timers can be adjusted on the fly by changing the timer’s

associated variable.

Section 78 00-02-1011
2017-03-06 - 17 -
Scripting

The PowerVision scripting environment provides a modern editing interface for creating Scripts
to define the behaviors and processes of the system. The Script Editor is broken into four
sections.
• Script Properties: Define the script name and its group in the programming tree.
• The Script Editor: Edit the script here.
• Function Reference: Quick reference guide to the API Functions available based on the
currently selected hardware.
NOTE: Because methods differ between hardware types and applications,
refer to the Application Reference Manual for details of each available
function.

• Scripting Syntax Reference: Reference guide to the scripting syntax used in PowerVision
Configuration Studio® Software. The system uses AngelScript (a third-party scripting
language) to define scripts. The full documentation of the version included with
PowerVision is included in this section.

Adding and Editing Script Functions

Scripts in PowerVision Configuration Studio® Software are typically made up of one or more
functions. Unlike in previous releases, a single script can include any number of functions and
event functions rather than being limited to a single event function. In addition, the system now
provides context sensitive type-ahead and auto-type features that help to correctly write the
syntax. To access the type-ahead feature press Ctrl-Space. The system shows valid syntax

Section 78 00-02-1011
2017-03-06 - 18 -
values based on the current cursor position. Syntax and Highlighting support is available for
the following items:

• Event Functions: void $NewEventName$ () – Event functions are identified by being

surrounded by $ characters. The text inside the $ $ must match an event name in the
system. When the matching event is fired, the scripting engine will automatically run the
script in this function. You can have more than one Event Function in a single script file.
To create new event functions, simply type the event function syntax (using an existing
event name such as $MyEvent$) or use the Add Event button to create a new Event
Function and Event at the same time.
• Standard Functions: void MyFunction() – Functions that are called from within the
code. They cannot be triggered from outside the scripting module.
NOTE: All functions in the system are global and can be called from any
other function even if the functions are not in the same script file.

• API Functions: Functions which are defined by the system and available to use in your
code to execute built-in processes.
• API Value Lists: API Value lists are objects which contain lists of values to be used in
scripting. The most common value lists are EventIDs which contain a list of event
handles you can fire and VariableIDs which contain a list of variable handles you can
read and write. Other lists are available depending on the applications included in your
selected hardware.
For additional information on Scripting Syntax Reference refer to the Scripting
Syntax Reference tab included in the tool.
Compiling Scripts
Because PowerVision does not include a compiler for AngelScript, scripts are not compiled in
the PowerVision tool directly. Instead the system relies on the connection to a hardware device
to compile the scripts. While compiling is not required to use the system (because scripts are
compiled when installed on the hardware), it’s often useful to compile them to find errors in
your script. When you hit the compile script button, the PowerVision tool will package all of
your scripts into a package and send them to the connected hardware. It will then display the
results of the compile in the PowerVision console. Double clicking an error or warning will
jump to the line of code where the error occurred.

Section 78 00-02-1011
2017-03-06 - 19 -
Programming Lists
PowerVision allows the configuration developer to manage arrays of data. Lists are analogous
to a table in a database or a sheet in Excel in that they have rows and columns. Lists are
defined in the programming tree by selecting New List in the context menu. Each list will have
a number of rows and columns defined statically. From this information along with the data
type of each column, a memory estimate is given. List size is limited by system RAM and
consumes RAM so you should create lists with the fewest number of rows and columns that
you need for a given task.

Types of Lists
There are two types of lists in PowerVision 2.8.
• Standard Lists – These are lists that are used by the system automatically. These
include DM1 and DM2 lists as well as lists required by other applications. When these
lists are present, they will automatically be populated by the application.
• Custom Lists – There are 10 slots reserved for creating your own custom lists. These
lists can contain number and string columns with any structure.

When to use Lists

Lists are useful for a number of things. Any time you need to manage an array of data or a list
of values, use a list. Also, lists can be directly bound to Text Gauges and Widgets so this
greatly simplifies managing a complex UI. For more information about binding and displaying
data for lists, see the Page Designer Manual.

Section 78 00-02-1011
2017-03-06 - 20 -
List Properties
List properties are located at the top of the screen and control the overall structure of the list.
Field Description
Name The name assigned to the program.

Group Name of the group in the programming tree where this item will
show.
Definition This is the type of list being used. This can be a system list (one
per type) or one of 10 predefined list slots.

Number of Columns The number of columns in the list.

Number of Rows Number of rows to be allocated in memory.

Memory Size The total size of the memory used by this table at run time.

Identifier The name of the list in scripting and other programming references.

Survives Upgrade The saved list won’t be deleted after firmware upgrade.

Section 78 00-02-1011
2017-03-06 - 21 -
List Column Definition
List Column allows you to store different data types in each row of the list.
Field Description
Name The name assigned to the column.

Type The data type of the list column.

Width The width in bytes of the column. For char columns, you can
change this value to control string size.

Offset (Informational) The location from the top of the row in bytes.

Hidden in Scripting For system-defined List Types, this column indicates if scripting will
expose the column.

List Tools in Scripting

Lists can be manipulated in Scripting using the following functions. The concept of working
with a list is much like any other programming system that works with Maps or Lists. One
thing to be aware of is that you should always Lock and Unlock a list when modifying data in
the list. This keeps other system features from accessing the list value while you are writing
the values in the list.

• ListManagerGetItem( uint ListManagerType, uint index, &ListStructure struct)

o Gets data from a List
• ListManagerSetItem( uint ListManagerType, uint index, &ListStructure struct)
o Sets data into a List position
• ListManagerSetPosition( uint ListManagerType, uint index)
o Sets the position in a list to a random location
• ListManagerGetPosition( uint ListManagerType)
o Gets the current position in the list
• ListManagerGetCount( uint ListManagerType)
o Gets the count of items in the list
• ListManagerNext( uint ListManagerType, bool wrap)
o Moves the position of the list to the next item. If wrap then scrolls to top if you hit the last item
• ListManagerPrevious( uint ListManagerType, bool wrap)
o Moves the position of the list to the previous item. If wrap then scrolls to top if you hit the last item
• ListManagerMoveTo( uint ListManagerType, uint index)
o Moves the current item to the designated location of the list
• ListManagerAddItems( int ListManagerType, int count)
o Adds items to specified list, returns number of items added
• ListManagerAddItem( uint ListManagerType, &CustomListData struct)
o Adds Custom Data to a CustomList. If list is full returns -1
• ListManagerRemoveItem( uint ListManagerType, uint index)
o Removes item from a Custom List
• ListManagerExport( uint ListManagerType, string& filename )
o Exports a list as a tab-delimited text file.
• ListManagerImport ( uint ListManagerType, string& filename )
o Imports a list formatted as a tab-delimited text file.

Section 78 00-02-1011
2017-03-06 - 22 -
 • ListManagerFindItemByDouble ( uint ListManagerType, uint first, uint last, &CustomListColumn struct,
double& dataToMatch )
o Search the first matching item by a double data type column. Return item index number for success or
negative for error.
• ListManagerFindItemByFloat ( uint ListManagerType, uint first, uint last, &CustomListColumn struct,
float& dataToMatch )
o Search the first matching item by a float data type column. Return item index number for success or
negative for error.
• ListManagerFindItemByInt32( uint ListManagerType, uint first, uint last, &CustomListColumn struct,
int32& dataToMatch )
o Search the first matching item by a int32 data type column. Return item index number for success or
negative for error.
• ListManagerFindItemByInt16 ( uint ListManagerType, uint first, uint last, &CustomListColumn struct,
int16& dataToMatch )
o Search the first matching item by a int16 data type column. Return item index number for success or
negative for error.
• ListManagerFindItemByInt8 ( uint ListManagerType, uint first, uint last, &CustomListColumn struct,
int8& dataToMatch )
o Search the first matching item by an int8 data type column. Return item index number for success or
negative for error.
• ListManagerFindItemByBool ( uint ListManagerType, uint first, uint last, &CustomListColumn struct,
bool& dataToMatch )
o Search the first matching item by a bool data type column. Return item index number for success or
negative for error.
• ListManagerFindItemByString( uint ListManagerType, uint first, uint last, &CustomListColumn struct,uint
columnSize, string& dataToMatch )
o Search the first matching item by a char array column. Wildcard character \"*\" may be used in the text
matching pattern. Return item index number for success or negative for error.

Activity Programs

PowerVision Activity Programs provide a way to capture a program flow with shapes rather
than relying on the traditional script approach to programming. Because of this, Activity
programs are functionally and conceptually similar to scripts. Both scripts and activity
programs are fired by attaching a program/code to an Event. When the event is fired the
programming logic is executed starting at the Start shape and continues until the Stop shape.
If you’re familiar with script programming, this is similar to the start of a function and the return
of a function. If you are not familiar with scripting, don’t worry, Activity programs can do most
of what scripts can do and are much easier to use. In addition, due to their lighter use of
system resources, Activity Programs work on ALL PowerVision platforms.

The Activity Program user interface has these important sections:

• Activity Properties located at the top of the screen.
• Sequential Activity View which fills the middle of the screen.
• Shape Properties which is located to the right of the Sequential Activity View.
• Feature Toolbar located below the Sequential Activity View.
• Shape Toolbar located below the Sequential Activity View.
• Navigator located below the Shape Properties.

Section 78 00-02-1011
2017-03-06 - 23 -
Activity Program Properties
Activity properties are located at the top of the screen and allow various behaviors to be
captured related to the Activity. The following properties are available.
Field Description
Name The name assigned to the program.

Group Name of the group in the programming tree where this item will
show.
Event The event that causes this activity program to execute.

Adding and Editing Shapes

The Sequential Activity View section offers a visual view of the logic flow of the program. It is
made up of Shapes that are connected with Control Flow lines. Logic always starts at the Start
shape and executes any functionality defined by the shape. When the shape completes its
logic, the system immediately executes the next shape. This continues until the flow reaches a
Stop shape.
• Adding Shapes: To add a new shape, drag the Shape toolbar button onto the diagram
surface or right click on the diagram, and select New State Shape from the menu.

Section 78 00-02-1011
2017-03-06 - 24 -
 • Adding Control Flow: To add a new flow, select the control flow tool from the toolbar,
place the cursor over an output (blue or green square) on any shape and drag to
another shape which has an input (red square).
• Removing States and Transitions: To remove a shape or flow, select the item, and
use the delete key or select Delete Selected Item from the right-click menu.
• Undo: Reverses the last action taken.
• Print: Sends a copy of the diagram to a printer.
Shape Toolbar
When the user clicks on a shape, the Shape Properties box for that shape is displayed to the
right side of the screen. In addition to the name, each type of shape has a number of
properties that control how the shape behaves.

Section 78 00-02-1011
2017-03-06 - 25 -
The following shapes are available in the first release of Activity Programming:

• Start Activity – Each program requires a single start activity. This shape represents
the beginning of activity flow. There are no properties available to edit on this shape.
• Stop Activity - Each program must have one or more stop activities. This shape ends
the program and returns control to the parent program. There are no properties
available to edit on this shape.
• Decision Activity – This shape controls the control flow through a true or false
condition. This allows you to decide which path to use in the program based on
variables and conditions. This shape uses a PowerVision standard Expression editor to
allow you to define the direction of flow. In this editor, any expression that returns a
True or Positive Integer will pass/flow to the true output, and any other result such as
false or 0 will pass/flow to the false output.
• Multi-Decision Activity – Similar to a single Decision but allows you to specify multiple
possible outputs instead of a single True output.
• Fire Action Activity – Fires a set of actions when control flow enters this activity.
These actions are the same actions which are available in state machines. Please refer
to State Machine Programming for more information about which actions are available.
• Set Variable Activity – Sets a collection of variables (local or global) based on the
specified expressions. This shape allows you to add a list of Variables. For each of the
variables, you can define an expression which will be executed to determine a new
value for the variable. This tool also uses the standard Expression Editor.
• Call Activity – Calls another child activity program and waits for it to complete before
continuing. This shape allows you to pass data in and out of the sub program allowing
child programs to be reused. If you are familiar with script programming, this is directly
equivalent to calling a function.
o To call an activity, click the property Call Activity link to select the child activity
you wish to call.
o When calling another activity with the Call Activity shape, you can also pass data
from the parent activity. To do this, add an item to the Shared Variables section.
For each item you can MAP a variable from the parent activity to a variable in the
child activity. In addition, check the Copy on Call or Copy on Return to control if
the data is Sent Into or Out of the child activity.
• Internal Message – Generate an internal J1939 active diagnostic message to
diagnostic message list (Dm1ListType).
• Note Activity – This special activity does not have any inputs or outputs. It allows a
comment or note to be placed anywhere on the diagram to document how the logic
works.

Section 78 00-02-1011
2017-03-06 - 26 -
 • Add List Item Activity – Adds a row to a list using the current values of the mapped
variables. If auto-delete is enabled and the list is full, the first item in the list will be
deleted in order to make room for the new item.

NOTE: Hover over the connection points to see the help text for the
shape. For example, the True output of the Decision shape.

Using the Navigator

The Navigator and Feature toolbar allow you to navigate around large diagrams. The
navigator has a box you can drag to the desired area. Also the Zoom bar allows you to zoom
in and out of large complex sequential activities.

Creating Local Variables

In addition to interacting with the system variables in Activity Programming, it is often useful to
add local variables. A local variable is a variable that is not part of the system database.
Instead, local variables are created and given a default value at the start of the activity
program and are deleted at the end of the logic flow. They are useful for supporting temporary
values that you may need during logic flow, but do NOT need to be stored globally.

To add and remove Local Variables, click the toolbar icon to show and hide
the variable list. From here you can add, remove and assign a default value to the local
variable. In addition you can click the link to define other standard variable features such as
the variable name and enumeration values.

Section 78 00-02-1011
2017-03-06 - 27 -
Walkthrough Activity Programs

Walkthrough programs work exactly like normal activity programs but have one more shape.
This is the Display Panel shape. This shape allows you to capture a list of variables and
validations that will be displayed for the user.

State Machines

The Programming section of the PowerVision Configuration Studio® enables the user to use a
graphical user interface to create state machines which can control and create behaviors in the
system.
The State Machine editor is broken into three regions:
• State Machine properties.
• State Diagram.
• Property Editor.

State Machine Properties

State Machine properties are located at the top of the screen and allow properties to be set.
The following properties are available.
Field Description
Name The name assigned to the state machine.

Group Name of the group in the programming tree where this item will
appear.

Section 78 00-02-1011
2017-03-06 - 28 -
Field Description
Initial State The initial state when the unit is booted.
NOTE: This is the initial state only for a cold-
boot power on. If the ignition switch sleep
mode is being used, the state machines are
not reset to their initial states upon waking
from this mode.

Editing the State Diagram

The State Diagram section offers a visual view of the states and transitions. Interacting with
the states and transitions on the diagram is completed using the selection tool. When a state
or transition has been selected, its properties can be edited in the Property Editor on the right
side of the state diagram.
• Adding States: To add a new state, drag the state toolbar button onto the diagram
surface or right click on the diagram and select New State Shape from the menu.
• Adding Transitions: To add a new transition, select the transition tool from the toolbar,
place the cursor into the first state and drag to another. A transition from a state to itself
can be created by dragging from the state back to the same state. This is useful for
firing repetitive actions in response to an event.
• Removing States and Transitions: To remove a state or transition, select the item and
use the delete key or select Delete Selected Item from the right-click menu.
• Regenerate: Causes the system to automatically position the state machine objects in a
radial format to allow for easier viewing.
• Undo: Reverses the last action taken.
• Print: Sends a copy of the diagram to a printer.
Creating and Editing States
When the user clicks on a state, the Property Editor for that state is displayed to the right side
of the screen. In addition to the name, the user is then able to set the actions that execute
upon entering and exiting the state.
Actions are processes that system applications can execute. They can be thought of as
outgoing messages from a state machine that are controlling the behavior of the applications.
Each application has a defined set of actions it can receive. (For a list of applications and their
actions please refer the Applications Reference Manual.) Each state contains two lists of
actions:
• Entry Actions: The entry actions are executed sequentially when an individual state is
entered by a transition. Applications in the system receive actions that are sent by state
machines to do work.

Section 78 00-02-1011
2017-03-06 - 29 -
 • Exit Actions: The exit actions are executed sequentially when an individual state is
exited by a transition. Applications in the system receive actions that are sent by state
machines to do work.
By clicking [+] in either the Entry Actions or Exit Actions list to perform upon entering or exiting
the state, a window is displayed. This window shows three columns: Application, Actions and
Data. Clicking Application displays all the actions that it can execute. Clicking Action selects
the Data that is going to be passed to the action. When all three are selected together, this
describes the state’s action which will occur. Once actions are added to a state you can use
drag and drop to reorder the actions as well as move actions from entry to exit.

Creating and Editing Transitions

Remember that a transition is what causes a state machine to move from one state to another
state. These transitions occur in response to events (any type) that exist in the system.
When a transition is created, it will automatically have an event created for it. This is identified
by the Auto-Create checkbox. To keep this event leave the checkbox as it is. Rename the
event by using the name field. Connect the transition to an existing event by deselecting the
checkbox and selecting an event from the hyperlink. Doing this deletes the original event and
ties the transition to the newly selected event.
NOTE: To simplify using the system, the transition properties will also
display the properties of the connected event (auto-created or linked). This
means any timers and event conditions on this panel that are tied to the
event are NOT specific to the transition. Searching the same event in the
programming tree will also allow the same properties to be viewed or
edited.

Section 78 00-02-1011
2017-03-06 - 30 -
Expression Language

The PowerVision Configuration Studio® Software Expression Language is a simple syntax for
executing high performance calculations based on existing variables. The expression syntax
used is designed to be similar to syntax used in common applications such as Microsoft Excel.
Each expression has a name. This name represents the name of an event that is tied to the
calculation. To execute the expression the event must be fired. Writing expressions is done by
typing into the expression edit area. In addition, valid syntax sections can be dragged into the
area using the Variables and Functions tabs. Simple math operations can also be added by
clicking the toolbar buttons located just below the edit area.
To access the expression editor, click the event. The following screen is displayed.

Below is a list of the built-in functions that are available when working with expressions in the
expression language.
Function Parameters Description
AND AND (logical1, logical2) Returns 1 if both logical are true. Function can
take more than two logical arguments.
OR OR (logical1, logical2) Returns 1 if either logical is true. Function can
take more than two logical arguments.
NOT NOT(logical) Returns 0 or 1 that is opposite of logical.

IF IF(logical, true value, Returns true value if logical is true, false true if
false value) logical is false. Like Excel, all three parameters
must be specified.

Section 78 00-02-1011
2017-03-06 - 31 -
Function Parameters Description
MAX MAX(value1, value2) Returns the value that is greater of the two
values. Function can take more than two
logical arguments.
MIN MIN(value1, value2) Returns the value that is lesser of the two
values. Function can take more than two
logical arguments.
INT INT(number) Removes number after decimal to make a
whole number. (i.e. 11.9 = 11.0)
LOG10 LOG10(number) Returns the base-10 log of number.

LN LN(number) Returns the natural log of number.

XOR XOR (logical, logical)

Returns the result of executing an XOR
comparison between each bit of the variable
value and the number.
MOD MOD(number, divisor) Returns number mod divisor.

ISVALID ISVALID (variable Returns 1 if a variable is valid and 0 if it is not

name) valid.
BITWISEAND BITWISEAND (variable Returns the result of executing an AND
name, number) operation between each bit of the variable
value and the number.
BITWISENOT BITWISENOT (variable Enter a variable name and it performs a NOT
name, number) operation on each bit.
BITWISEOR BITWISEOR (variable Returns the result of executing an OR
name) comparison between each bit of the variable
value and the number.
BITWISESHIFTLEFT BITWISESHIFTLEFT Returns the variable value shifted left by the
(variable name, number of bits.
integer)
BITWISESHIFTRIGHT BITWISESHIFTRIGHT Returns the variable value shifted right by the
(variable name, number of bits.
integer)
BITWISEXOR BITWISEXOR (variable Returns the result of executing an XOR
name, number) operation between each bit of the variable
value and the number.

Section 78 00-02-1011
2017-03-06 - 32 -
THIS PAGE INTENTIONALLY LEFT BLANK
THIS PAGE INTENTIONALLY LEFT BLANK