ASE2000 Version 2

Scripting
Document Version 1.0
April 19, 2016

Applied Systems Engineering, Inc.

1671 Dell Avenue, Suite 200
Campbell, California 95008
support@ase-systems.com
www.ase-systems.com
Ph: (408) 364-0500
Fax: (408) 364-0550
 Table of Contents

SCRIPTING FOR DNP3 AND IEC 60870-5.............................................................................................................3

SCRIPT EDITOR ..........................................................................................................................................................4
Basics ...................................................................................................................................................................4
Presentation .........................................................................................................................................................4
Script Header .......................................................................................................................................................5
CODING THE SCRIPT ..................................................................................................................................................7
Interface Elements................................................................................................................................................8
Control Elements..................................................................................................................................................9
DNP3 Transaction Elements .............................................................................................................................. 11
IEC 60870-5-101/104 Elements ......................................................................................................................... 18
SAVING AND ACTIVATING SCRIPTS ......................................................................................................................... 22
SCRIPT RESULTS ...................................................................................................................................................... 24
SCRIPT EXAMPLE ..................................................................................................................................................... 26
SCRIPT EXAMPLE RESULTS ...................................................................................................................................... 30
Scripting for DNP3 and IEC 60870-5
ASE2000 Version 2 release 17 (2.17) introduces the ability for users to write scripts to
implement custom scenarios for testing of DNP3 and IEC 60870-5 (101, 104) protocol
devices.

Scripting is supported by a script editor and script execution window, both embedded
within the ASE2000 V2.

Operation of the script editor portion of the ASE2000 V2 is free. ASE hardware is not
required.

Execution of user-written scripts is a licensed feature requiring installation of ASE

hardware (BCOM-USB device or USB dongle) with the scripting feature enabled.
Licensing information is shown by inserting the ASE hardware and selecting Help and
Licensing from the ASE2000 V2.

The scripting engine is also used for operation of DNP3 level 1 and level 2 conformance
test scripts delivered with the ASE2000. The delivered DNP3 conformance test scripts
are digitally signed, enabling them for operation without the script execution package
being explicitly licensing. Any modification to those scripts will invalidate the digital
signature and render them usable only on a script-licensed system.

This document describes operation of the script editor for DNP3 and IEC protocols. It is
assumed that the reader is familiar with operation and message structure of any protocol
being used.
Script Editor
The Script Editor is used to create and maintain user scripts.

Basics

The Script Editor is started from the View pull-down menu.

A script consists of a script header and a series of script Elements. Some Elements
perform specific actions, such as transmission or reception of a DNP3 message. Other
Elements are containers holding a set of Elements. A container Element may be simply
for organizational purposes, such as to contain all script Elements of a particular test
section. A container Element may also be functional, such as a Repeat Element that
causes its “contained” Elements to be repeated until a condition is met.

Elements are executed in the order coded except for steps within a Repeat element which,
as the name implies, can be repeated.

Each script Element either passes or fails. An Element with no implicit pass/fail
condition, such as a comment, automatically passes.

Presentation

Each element is shown within a tree type structure in the left portion of the script editing
window. Elements within a container Element are indented under the container.
Attributes for any selected element are shown and enterable at the right. There are four
attributes common to all items.

Page 4
 Common Attributes
Attribute Description
Number A step number, with optional embedded period, such as 1 or 2.1. The step, along
with its associated number, is shown in the test results summary. If the number
field is blank, then the test step is not shown in the test results. The step is still
executed, but not displayed. The usefulness of this feature may be apparent when a
test script is coded.
Title The test or step name, displayed during test execution and in the test results
summary
Enabled Enables or disables operation of element
Skip to Contains the number of a subsequent test step (not a prior test step). If the current
Test step passes, then the test process skips to the referenced test. If the current step
fails (or if this field is blank), the test process continues with the next coded step

Script Header

Attributes for the script header, the first entry in the script, are:

Date, Level, and Version

Presented for documentation purposes only. Contents are listed in the script result.

SchemaVersion
Currently set to 1.1 and should not be changed.

Options
Options are selections the user can make at run-time. An option can be used to:

 Enable or disable operation of a test based on whether or not a device supports a specific
feature
 Provide a value for a test, such as an output point index to control

Page 5
Prior to running a script, all options are presented for user entry to specify context for
script execution.

Options are defined through an Options Editor created by selecting a target at the right
edge of the Options (Collection) line to produce:

Selecting the Add target creates a new option. It properties, shown to the right, are:

Category
Options are grouped and displayed by category.

Choices
Options can be free-form strings or one of a list of choices. An example of the latter is
one that can be either “true” or “false”, or one selected from a list of numbers, such as 1,
2, or 3.

The default is a free-form string. To define an option to be one choice from a list, select
the “Choices” target and enter all possible choices in the form supplied.

Page 6
Description
Text to appear in the help area when the option is selected.

Display Name
Name shown to the user in the option editing area.

Name
Option name used within the script to reference the value assigned to this option.

Coding the Script

The script process executes steps in the order coded. Each step is called an Element. An
Element is created by right-clicking on the node under which the new Element is to be
created. For example, clicking on the script header will place an Element at the outermost
level. Clicking on a container element, such as Section, will create a new Element within
that container.

New Elements are always added to the end of the relevant level. An Element can be
moved to another position by moving the mouse over the Element, holding down the left
mouse button, moving the Element to its new position, and releasing the Mouse button.

Page 7
To create a script:
 Add an element of the correct type
 Fill in the element properties
 Repeat

Each element has the four basic properties explained above (Number, Title, Enabled, and
Skip to Test,). Other properties are dependent and element type

There are three basic types of script elements, Interface, Control, and Transactional.

An Interface Element is one provided basically for interface between the script and the
user. These include questions and comments posed to the user, setting parameters,
and general information

A Control Element is one the controls the flow of the script, such as repeating a series of
steps

A Transactional Element is one that interacts with the protocol, either sending or
receiving a message. Only transactional elements differ based on the target
protocol

Interface Elements

The top level element to which all other elements are added. The editor creates this
element automatically. Properties have been previously discussed.

Page 8
Section
A container element used to hold a set of child elements. Sections allow the test author to
arrange tests in a hierarchical manner. A section may include any element, even other
sections. Each of the child elements in a section are executed in order. The significance
of a section is mostly organizational. For example, coding of the DNP3 Test Procedures
may use a section Element for each major test section.

The test set displays the hierarchical arrangement of the sections and the child elements
of a section.

Section Attributes
Name Type Description
Description String Collection User information
Remarks String Collection User information

Description and remarks are inserted into the script log.

Sequence
A container element that contains a set of child elements. Each of the child elements is
executed in order. A sequence may include any element. This is similar to a section but
the test set does not display the child elements of a sequence in the script view.

Comment
Provides a place to provide annotation, but otherwise performs no function.

Prompt
Prompts the user with a comment, direction, or question coded in the element title and
waits for acknowledgement. An example is to request some action, such as generate
events within a device being tested. The script waits for the user to resume after the
requested action (in this case, event generation) completes.

This element has one additional property, an option to close an IP connection to a device
being tested while the action is being performed.

Prompt Attributes
Name Type Description
Disconnect Boolean Disconnects to the DUT. Useful if the DUT is restarted
by the user as part of the requested action.

Control Elements
Control Elements control the flow of Script execution.

AnyOf
AnyOf is a container element with a set of child elements, each with pass/fail potential. If
any of the child Element tests passes then AnyOf passes. If all the child elements fail,
then AnyOf fails. The test set does not display the child Elements.

Page 9
An example is to send a request to a remote device that the device is expected to reject.
Rejection could be determined either if the remotes did not respond to the request, or
responded with a negative acknowledgement.

This, in conjunction with the “skip to test” entry, controls flow of the test script.
Processing advances to the designated test step if the AnyOf Element passes.

AllOf
Similar to AnyOf, AllOf is a container element that passes if all child element tests pass.
If any child element fails, it fails. The test set does not display the child elements.

An example for a control operation would be if the device responded correctly (by the
script testing the response message) and if the relay operated (based on user input to a
verify elements, explained next).

This, in conjunction with the “skip to test” entry, controls flow of the test script.
Processing advances to the designated test step if the AllOf Element passes.

Verify
The Verify control element is similar to Prompt. Verify asks the user a question, but
waits for a pass or fail response, the result of which is entered into the script log. This is
used to determine success or failure that the test set cannot otherwise determine. For
example, send an analog or digital control to a device and verify that device processed it
correctly.

Verify Attributes
Name Type Description
Disconnect Boolean Disconnects to the DUT. Useful if the DUT is restarted
by the user as part of the requested action.

Wait
Delays script execution to allow an external action, such as a relay control, to complete.
The time, specified in milliseconds, can be entered as a constant or derived from an
option.

Wait Attributes
Name Type Description
Period Integer The wait period in milliseconds.
Option String Name of a certification option whose value is
added to the period.

Page 10
Repeat
Repeat contains a set of child elements that are repeated. The repetition can be set to
repeat as long as all elements are successful, or until all elements are successful, as
explained below.
 If Repeat Count is zero, termination occurs when all child elements are successful or
when the timeout period elapses
 If Repeat Count is non-zero, termination occurs when any child element fails, when the
repeat count is exhausted, or when the timeout period elapses

Repeat Attributes
Name Type Description
Repeat Count Integer Repeat count
Timeout Period Integer Timeout period beyond the test set response timeout in
milliseconds.

A repeat element is also useful in conjunction with a vectored Option. This is explained
in more detail later but, for example, an option called PointID could be coded as

[1, 2, 5, 4]

and referenced within a Repeat element. The PointID value the first time through the
Repeat sub-elements would be 1, 2 the 2nd time through, 5 the 3rd, and 4 the 4th.

DNP3 Transaction Elements

These elements are specific to DNP3 protocol.

SendDL
Causes a DNP3 Data Link messages to be transmitted.

SendDL Attributes
Name Type Description
DataLink Function String Data link function code

ReceiveDL
Causes analysis of an expected DNP3 Data Link message. The following verification on
the received message determines pass/fail status of the associated script step

 The DIR bit must be correct

 The PRM state must be correct
 The Data Link Function code must be correct
 Other components, such as CRC, which apply to all messages, must be correct

ReceiveDL Attributes
Name Type Description
DLFunction Enumeration Data link function code expected

Page 11
SendDNP3AP
Causes a DNP3 application layer messages to be transmitted. The user codes the data link
and application functions, selected from a pull-down list, and a set of application objects.

Familiarity with DNP is important at this point. The user must know what commands are
to be transmitted. As pertinent information is entered such as object group, qualifier,
variation, and point counts, corresponding DNP3 information will be automatically
solicited.

To start, the user can code:

 Application group types

 Qualifier codes
 Individual property values corresponding to prior entries. For example, if the user codes
an entry to control two points, two sets of entry fields will appear for the two points.

Page 12
Option Parameters
An important component of application layer commands is that certain parameters,
specifically those involving control operations, can be parametrized. For example, the
coder may wish to issue a control, but not know what point to control, or what value to
send, at the time the script is coded. These can be specified by option parameters
(described previously) so that the user can assign values just prior to initiating the script.

Page 13
The user supplied the value for PID at run time.

Receive DNP3 AP

Specifies expected reception of a DNP3 Application Layer message. It is coded much the
same way as sending an Application Layer message.

Page 14
Expected response components such as point ID and value can be coded from User
Options.

The message is checked for general and specific items. It passes if all checks passed.
Checks performed include:

Basic Checks
 Data Link tests must pass
 Application fragment size must be correct
 Application sequencing must be correct
 Application function must be correct
 Response objects may be tested for as coded by the user

Application Object Checks

In addition, if the user coded specific objects in the Application Objects collection, then
various validation tests will be performed against objects in the response message. The
user does not have to code all expected objects, only those to be validated. For example,
if the response is expected to contain many digital inputs, but only digital input index ‘1’
is to be validated, then only that index needs to be coded.

Page 15
  The group types must match.
 If the script variation is non-zero the variation must match (a script qualifier of 0x06 will
match any qualifier)
 If the script Qualifier Prefix Code is zero and the response Qualifier Prefix Code is zero
then the Qualifier Range Code must more or less match. For example, if the script range
start/stop values are not equal, then the response must match the values coded.
 If the script Qualifier Prefix Code is one or two, then the response Qualifier Prefix Code
must match. The range codes must also be consistent.

Input Point Value Checks

 If the Point Index is an ‘*’, then the PointID option parameter is examined. If a name is
provided there, the value of that option is used. If either are defined, the point ID must
match
 If the Point Value is an ‘*’, then the Value option parameter is examined. If a name is
provided there, the value of that option is used. If either are defined, the point value must
match
o Digital state values must match exactly
o Analog values must match within a user-entered deadband
 A timestamp, if provided, must be valid and later than any previously received timestamp

Control Point Configuration

Coding a relay output command requires specifying the:
 Point Index
 Value (Trip, Close, On, Off as appropriate)
 Type (“Breaker” or “Breaker Relay / Transformer Tap”, “Latching” or “Latching Relay”,
“Momentary” or “Momentary Relay”)
 On Time

Advanced Option Coding

Considering a common case of control outputs, each property, such a value and on-time,
can be hard-coded to send a specific value. Properties can also be referred back to an
option that the user can specify just prior to starting the script.

Page 16
Option values can be:
 Simple values such as 1, 2, and 3, or
 Vectored values enclosed in brackets and comma delimited, such as [1, 3, 5, 2]. A
vectored value is useful when a command appears within a Repeat element. The first
value from the vector is used for the first iteration, the second value for the second
iteration, and so on. When there are more iterations that entries in the list, selection
restarts from the beginning

For example:

The decision whether to use the value coded in the Application properties section of the
script element or to obtain a value at run-time from a user option entry is determined by
the value entered in the script element. Every script element property has a “wild card”
value that causes the option name to be used. For example, if the control point ID is
coded as ‘*’, then the option name is used as the source of the point ID at run time. If a
numeric value is coded, that value is used regardless of the option name value.

Page 17
 Application Option Description Use the Option Parameter if Otherwise
Property Parameter
Name Name
Point Index PointId Control Point ID Point Index is coded as * Enter numeric
point ID
Type Control Command type: Type is coded as “none”. User Select type
Type Latching, option entry MUST be one of: from
Momentary, or  Breaker pulldown list
Trip/Close  Breaker Relay / Transformer Tap
 Latching
 Latching Relay
 Momentary
 Momentary Relay
On Time Control On Relay on time in On Time is coded as 0 Specify any
Time milliseconds positive value
Value Value Command state Value is coded as Any. The user Select value
entered option value if 0 for trip from pull-
or latch off, or 1 for close or down list
latch on

Control Point Checks

Control group types require the creation Point Data. The validation process
 Checks response for matches on point ID, count, on time, off time, relay type and
command

IEC 60870-5-101/104 Elements

This section discussed script elements specific to IEC 60870-5-101 and IEC 60870-5-104
protocols. The reader is expected to be familiar with these protocols.

Send IEC Data Link

Used to send any of the set of IEC messages without application data

Page 18
  The “Datalink Function” property applies to IEC 60870-5-101 only and includes choices
such as Reset Link
 The “Format Type” property applies to IEC 60870-5-104 only and includes choices such
as STARTDT

Receive IEC Data Link

Used to specify that a Data Link response message is expected. The received message is
verified for correctness as appropriate to the protocol and message being received

 The DIR bit is verified (101)

 The PRM bit is verified (101)
 The Data Link Function code is verified (101 and 104)

Send IEC AP

Used to send an IEC application message. Attributes common to all such messages
include:

Page 19
 Attributes

Name Type Description

DLFunction String Data link function code, used for IEC 60870-5-101 only
FormatType String Data link frame format type, used for IEC 60870-5-104
only
TypeId Numeric Type Identification, selectable from pull-down list
Common Numeric Common Address
Address
SQ Boolean Variable Structure Qualifier, sequential flag, true or false
Num Numeric Variable Structure Qualifier, Number of Elements
Cause of T (Test) Test bit, true or false
Transmission P/N Positive (false) or negative (true) confirm
Field Cause of Selectable from pull-down list
Transmission
COT Origin Cause of transmission origin
Application Collection Enter as appropriate for applications message (see
Objects discussion below)

To add objects, first select correct “Type” from the Type Identified pull-down list.

Page 20
Then add one or more elements using the Application Objects collection by entering the
correct number in the VSQ Number property variable structure qualifier).

Properties will be presented for entry appropriate to the object selected.

Options can be used to defer “Point ID” and “Point Value” to user entries at run-time

The user can fill in value for all fields to be transmitted in the application message.

If the Information Object Address is ‘*’, then the address is obtained from a user entry at
run-time. The name of the user-entry option is entered as shown. In this case it is called
UserPointId. An explicitly entered value takes precedence.

If the object value is “Any”, then the value is obtained from a user entry at run-time. The
name of the user-entry option is entered as shown. In this case it is called UserValue. An
explicitly entered value takes precedence.

Page 21
Receive IEC AP

Used to receive an IEC application layer message. The response is coded in a manner
similar to the request and causes the following validation checks on the message
received.

As appropriate, the ASE2000 will

 Check to insure timestamps are received in order, that is, a new timestamp is not older
that a prior timestamp
 Check to insure the appropriateness of quality codes
 Check to insure the appropriateness of data values:
o Control values are correctly echoed
o Digital points are in the desired state
o Analog values are within the deadband of the expected value

Saving and Activating Scripts

All Script activity is performed from Task Mode. A script resides in the ASE2000 in two
places:

 Within the editor and

 The active script

The script being edited is different from the script being run. This allows one copy of a
script being debugged while making changes to another copy.

To Load an Existing Script File into the Script Editor:

 Select View and Script Editor to open the Script Editor view, or (if the view is already
open) set focus to the Script Editor view.
 While focus is in that view, select file and open

To Create a New Script

 Select File and New from the Script Editing view

To Save a Script from the Script Editor

 Move focus to the script editor view
 Select File and Save or Save As

To Load a Script File for Execution

Page 22
Note that this option requires a license enabled for scripting. A script loaded for
execution appears in the script view, not in the script editor view.

To Use the Currently Edited Script as the Active Script

Set focus to the script editor view and copy the currently edited script to the active script
view.

Page 23
To Start (Activate) a Script
A script does not need to be started at the beginning. It can be started at any element
selected prior to the start of execution. The selected element and all (if any) sub-elements
are executed.

Script Results

Script results are shown in the active script window with details messages in the
Messages and Line Monitoring views. For example:

Page 24
 Test steps identified with a green check passed
 Test steps identified with a red X failed
 The test number is shown immediately after the time stamp for each message in the
messages view. Similar identification is contained in the Line Monitor view
 Moussing over a failed step identifies the failure reason.
 Test results can be saved to disk

Page 25
Script Example

Page 26
Page 27
Page 28
Page 29
Script Example Results

Page 30